# runner The engine: the contract an executor or generator is written against, the resolution of the package that provides one, and the running of one task, of many in order, and of the tasks a change affects. ## Writing an executor A target names an executor as `:`. The package is the workspace project whose manifest carries that name, else the package of that name among the installed packages; its manifest names an `executors.json`, which names each module and schema, looked for beside the manifest and then under `src/`. A module written in TypeScript loads from source. ```json { "executors": { "hello": { "implementation": "./src/hello", "schema": "./src/hello.json", "description": "Says hello" } } } ``` ```ts import type { Executor } from '@hyperfrontend/workspace' interface Options { name: string } const hello: Executor = (options, context) => { process.stdout.write(`hello ${options.name} from ${context.projectName}\n`) return { success: true } } export default hello ``` The executor is called in the same process with the defaults of its schema and an [`ExecutorContext`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-ExecutorContext): the root, the project and target names, the target as configured, and every project of the workspace. An option given on the command line is read as the type the schema declares. An option the schema lists under [`required`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-ExecutorSchema-prop-required) that neither the target nor the command line gives is refused before the executor runs, naming the option and the executor. A generator is a function of a [`Tree`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-Tree) and its options, listed in a `generators.json` the manifest names under [`generators`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-GeneratorsManifest-prop-generators), each entry naming its module under [`factory`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-GeneratorEntry-prop-factory) rather than [`implementation`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-ExecutorEntry-prop-implementation): ```json { "generators": { "note": { "factory": "./src/note/generator", "schema": "./src/note/schema.json", "description": "Writes a note" } } } ``` The manifest's `package.json` points at both files: `"executors": "./executors.json"` and `"generators": "./generators.json"`. The tree records every change and writes nothing until the run ends, which is what a dry run prints. A bare generator name goes to the one workspace project that lists it, then to this package; two workspace projects offering the same name are refused until the package is named. ## Running tasks [`runTask`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-runTask) merges the target of the project's `project.json` with the defaults in `hf.json` and runs exactly that task; nothing it depends on runs first. A shell target (`@hyperfrontend/workspace:run-commands`, or a bare command) runs through the platform shell with `node_modules/.bin` on the path. Configurations are refused. [`planMany`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-planMany) orders the tasks of a selection by their prerequisites, and [`runPlanned`](https://www.hyperfrontend.dev/docs/libraries/workspace/runner/#api-runPlanned) runs them in that order, each in a process of its own, skipping the dependents of a failure. The affected run selects its tasks through the graph first and then runs them the same way. ## API Reference ### Functions #### generatorNames ```typescript function generatorNames(root: string, projects: ReadonlyMap): string[] ``` Every generator a name could mean, as `:`. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `projects` | `ReadonlyMap` | The workspace's projects by name | **Returns** `string[]`: The generators of the workspace's projects, then the engine's own **Example: Listing what `npx hf generate` can run** ```typescript import { discoverProjects, listFiles } from '@hyperfrontend/workspace/graph' import { generatorNames } from '@hyperfrontend/workspace/runner' generatorNames(root, discoverProjects(root, listFiles(root))) // => ['@acme/tooling:component', '@hyperfrontend/workspace:workspace', '@hyperfrontend/workspace:library', ...] ``` #### loadExecutor ```typescript function loadExecutor(source: ExecutorSource, importModule: ImportModule, executor: string): Promise ``` Imports the module implementing an executor and finds its default export. **Parameters** | Name | Type | Description | | --- | --- | --- | | `source` | `ExecutorSource` | Where the executor lives | | `importModule` | `ImportModule` | Imports a module from its path | | `executor` | `string` | The executor, for the error | **Returns** `Promise`: The executor function **Example: Calling an executor outside a task** ```typescript import { pathToFileURL } from 'node:url' import { loadExecutor, locateExecutor, withDefaults } from '@hyperfrontend/workspace/runner' const source = locateExecutor(root, projects, '@acme/tooling:lint') const lint = await loadExecutor(source, (file) => import(pathToFileURL(file).href), '@acme/tooling:lint') const result = await lint(withDefaults({ fix: true }, source.schema), context) // => whatever the executor answers, { success: true } when it passed ``` #### loadGenerator ```typescript function loadGenerator(source: GeneratorSource, importModule: ImportModule, written: string): Promise ``` The generator a located module implements. **Parameters** | Name | Type | Description | | --- | --- | --- | | `source` | `GeneratorSource` | Where the generator lives | | `importModule` | `ImportModule` | Imports a module from its absolute path | | `written` | `string` | The generator as the command line names it, for the refusal | **Returns** `Promise`: The module's default export **Example: Loading a generator the runner located** ```typescript import { pathToFileURL } from 'node:url' import { loadGenerator, locateGenerator } from '@hyperfrontend/workspace/runner' const generate = await loadGenerator(locateGenerator(root, projects, 'library'), (file) => import(pathToFileURL(file).href), 'library') await generate(tree, { name: 'data-utils' }) ``` #### locateExecutor ```typescript function locateExecutor(root: string, projects: ReadonlyMap, executor: string): ExecutorSource ``` Where the executor a target names lives. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `projects` | `ReadonlyMap` | The workspace's projects by name | | `executor` | `string` | The executor, `:` | **Returns** `ExecutorSource`: The module and the options schema **Example: Finding a packaged executor** ```typescript import { discoverProjects, listFiles } from '@hyperfrontend/workspace/graph' import { locateExecutor } from '@hyperfrontend/workspace/runner' const projects = discoverProjects(root, listFiles(root)) locateExecutor(root, projects, '@hyperfrontend/workspace:typecheck') // => { file: '/repo/node_modules/@hyperfrontend/workspace/executors/typecheck/index.js', schema: { properties: { tsConfig: { type: 'string' }, ... } } } ``` **Example: A workspace project stands in front of the installed package of the same name** ```typescript locateExecutor(root, projects, '@acme/tooling:lint') // => { file: '/repo/tools/tooling/src/executors/lint/index.ts', schema: { ... } } while tools/tooling carries @acme/tooling ``` #### locateGenerator ```typescript function locateGenerator(root: string, projects: ReadonlyMap, written: string): GeneratorSource ``` Where the generator a name means lives. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `projects` | `ReadonlyMap` | The workspace's projects by name | | `written` | `string` | The generator as the command line names it, `` or `:` | **Returns** `GeneratorSource`: The module and the options schema **Example: A bare name prefers the workspace's own generator** ```typescript locateGenerator(root, projects, 'library') // => the library generator of a workspace project that lists one, else { file: '/repo/node_modules/@hyperfrontend/workspace/generators/library/index.js', schema: { ... } } ``` **Example: Naming the package settles it** ```typescript locateGenerator(root, projects, '@hyperfrontend/workspace:library') // => the engine's own, whatever the workspace lists under that name ``` #### main ```typescript function main(argv: unknown, host: RunHost): Promise ``` The command line: runs the task it names and reports why it could not, when it could not. **Parameters** | Name | Type | Description | | --- | --- | --- | | `argv` | `unknown` | The arguments after the entry, `run : [--name=value ...]` | | `host` | `RunHost` | Where the task runs and what it runs with | **Returns** `Promise`: The exit code: 0 when the task succeeded, 1 otherwise **Example: Reporting a refusal instead of throwing** ```typescript await main(['run', 'lib-core:build:production'], host) // => 1, after writing "hf run lib-core:build:production: lib-core:build:production names the configuration production; targets run without configurations" ``` #### manySummary ```typescript function manySummary(outcomes: unknown): string[] ``` The summary of a run: one line per task and a count of each ending. **Parameters** | Name | Type | Description | | --- | --- | --- | | `outcomes` | `unknown` | How each task ended | **Returns** `string[]`: The lines **Example: The lines a run ends with** ```typescript manySummary([ { id: 'lib-core:build', status: 'succeeded', durationMs: 1840 }, { id: 'app-shell:build', status: 'skipped', durationMs: 0 }, ]) // => [' succeeded lib-core:build (1.8 s)', ' skipped app-shell:build (0.0 s)', '1 succeeded, 0 failed, 1 skipped'] ``` #### parseAffectedArgs ```typescript function parseAffectedArgs(argv: unknown): AffectedRequest ``` Reads the command line of `affected`. **Parameters** | Name | Type | Description | | --- | --- | --- | | `argv` | `unknown` | The arguments after `affected` | **Returns** `AffectedRequest`: The request **Example: The working tree against `origin/main` unless told otherwise** ```typescript parseAffectedArgs(['-t', 'test']) // => { targets: ['test'], base: 'origin/main', head: null, args: [] } parseAffectedArgs(['-t', 'test', '--base=v1.2.0', '--head', 'HEAD']) // => { targets: ['test'], base: 'v1.2.0', head: 'HEAD', args: [] } ``` #### parseManyArgs ```typescript function parseManyArgs(argv: unknown): ManyRequest ``` Reads the command line of `run-many`. **Parameters** | Name | Type | Description | | --- | --- | --- | | `argv` | `unknown` | The arguments after `run-many` | **Returns** `ManyRequest`: The request **Example: Everything after the selection reaches the tasks** ```typescript parseManyArgs(['-t', 'build,test', '-p', 'lib-*', '--verbose']) // => { targets: ['build', 'test'], projects: ['lib-*'], args: ['--verbose'] } parseManyArgs(['-t', 'build', '--all']) // => { targets: ['build'], projects: null, args: [] } ``` #### planMany ```typescript function planMany(graph: WorkspaceGraph, request: ManyRequest): PlannedTask[] ``` Every task to run for a request, each after its prerequisites; a cycle is refused with its path. **Parameters** | Name | Type | Description | | --- | --- | --- | | `graph` | `WorkspaceGraph` | The workspace graph | | `request` | `ManyRequest` | The targets and projects asked for | **Returns** `PlannedTask[]`: The tasks in the order they run **Example: The prerequisites come first, unrequested** ```typescript import { workspaceGraph } from '@hyperfrontend/workspace/graph' import { planMany } from '@hyperfrontend/workspace/runner' planMany(workspaceGraph(root), { targets: ['build'], projects: ['app-shell'], args: [] }) // => [ // { id: 'lib-core:build', requested: false, after: [] }, // { id: 'app-shell:build', requested: true, after: ['lib-core:build'] }, // ] ``` #### planTasks ```typescript function planTasks(graph: WorkspaceGraph, tasks: unknown): PlannedTask[] ``` The given tasks and every task their `dependsOn` reaches, each after its prerequisites, in the order given otherwise; a cycle is refused with its path. **Parameters** | Name | Type | Description | | --- | --- | --- | | `graph` | `WorkspaceGraph` | The workspace graph | | `tasks` | `unknown` | The tasks asked for, each of a project of the graph | **Returns** `PlannedTask[]`: The tasks in the order they run **Example: Planning tasks chosen some other way than by name** ```typescript planTasks(graph, [{ project: 'app-shell', target: 'e2e' }]) // => [ // { id: 'lib-core:build', requested: false, after: [] }, // { id: 'app-shell:build', requested: false, after: ['lib-core:build'] }, // { id: 'app-shell:e2e', requested: true, after: ['app-shell:build'] }, // ] ``` #### runGenerator ```typescript function runGenerator(tree: Tree, written: string, options: Record, importModule: ImportModule): Promise ``` Runs the generator a name means over a tree, so a generator composes another by name: a workspace's own generator of that name, else the engine's. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tree` | `Tree` | The tree the generator edits, rooted at the workspace | | `written` | `string` | The generator as the command line names it, `` or `:` | | `options` | `Record` | The options the generator is called with | | `importModule` | `ImportModule` | Imports a module from its absolute path; the process's own import when omitted (default: `...`) | **Returns** `Promise`: Resolves when the generator has run **Example: A workspace generator composing the packaged `library` generator** ```typescript import type { Generator } from '@hyperfrontend/workspace/generators' import { runGenerator } from '@hyperfrontend/workspace/generators' const featureLibrary: Generator<{ name: string }> = async (tree, options) => { await runGenerator(tree, 'library', { name: options.name, tags: ['type:feature'], skipFormat: true }) tree.write(`libs/${options.name}/src/feature.ts`, 'export const feature = true\n') } export default featureLibrary ``` #### runPlanned ```typescript function runPlanned(tasks: unknown, args: unknown, host: ManyHost): Promise ``` Runs planned tasks one at a time, skipping any whose prerequisite did not succeed. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tasks` | `unknown` | The tasks in order | | `args` | `unknown` | The arguments every requested task receives | | `host` | `ManyHost` | How a task runs, the clock and the output | **Returns** `Promise`: How each task ended, in order **Example: Running the plan in children of this command line** ```typescript import { spawn } from 'node:child_process' import { runPlanned, selfCommand } from '@hyperfrontend/workspace/runner' const outcomes = await runPlanned(tasks, ['--verbose'], { runChild: (id, args) => new Promise((resolve) => { const command = selfCommand(process, ['run', id, ...args]) spawn(command[0] as string, command.slice(1), { stdio: 'inherit' }).on('close', (code) => resolve(code ?? 1)) }), now: Date.now, write: (line) => process.stderr.write(`${line}\n`), }) // => [{ id: 'lib-core:build', status: 'failed', durationMs: 1840 }, { id: 'app-shell:build', status: 'skipped', durationMs: 0 }] ``` #### runTask ```typescript function runTask(id: string, args: unknown, host: RunHost): Promise ``` Runs one task. **Parameters** | Name | Type | Description | | --- | --- | --- | | `id` | `string` | The task, `:` | | `args` | `unknown` | The arguments after the task, `--name=value` or `--name` | | `host` | `RunHost` | Where the task runs and what it runs with | **Returns** `Promise`: True when the task succeeded **Example: Running one task in this process** ```typescript import { spawn } from 'node:child_process' import { pathToFileURL } from 'node:url' import { runTask } from '@hyperfrontend/workspace/runner' const succeeded = await runTask('lib-core:build', ['--clean=false'], { root, cwd: process.cwd(), env: process.env, platform: process.platform, execPath: process.execPath, spawn: (line, options) => spawn(line, options), write: (line) => process.stderr.write(`${line}\n`), importModule: (file) => import(pathToFileURL(file).href), }) // => true when the build executor answered { success: true }; lib-core's dependsOn did not run first ``` #### selfCommand ```typescript function selfCommand(started: StartedAs, args: unknown): string[] ``` The argument vector that starts this command line again with other arguments. **Parameters** | Name | Type | Description | | --- | --- | --- | | `started` | `StartedAs` | The running process | | `args` | `unknown` | The arguments of the new run | **Returns** `string[]`: The executable, its flags, the entry module and the arguments **Example: Starting a task in a child the way this process was started** ```typescript import { spawn } from 'node:child_process' import { selfCommand } from '@hyperfrontend/workspace/runner' const [program, ...args] = selfCommand(process, ['run', 'lib-core:build']) // => ['/usr/bin/node', '--import=tsx', '/repo/node_modules/@hyperfrontend/workspace/bin/hf.mjs', 'run', 'lib-core:build'] spawn(program as string, args, { stdio: 'inherit' }) ``` #### withDefaults ```typescript function withDefaults(options: Readonly>, schema: ExecutorSchema): Record ``` Options with the defaults of their schema filled in where they are unset. **Parameters** | Name | Type | Description | | --- | --- | --- | | `options` | `Readonly>` | The options of the target and the command line | | `schema` | `ExecutorSchema` | The executor's options schema | **Returns** `Record`: A copy of the options with the defaults applied **Example: Filling the options a target left unset** ```typescript withDefaults({ tsConfig: 'libs/core/tsconfig.lib.json' }, { properties: { tsConfig: { type: 'string' }, strict: { type: 'boolean', default: true } } }) // => { tsConfig: 'libs/core/tsconfig.lib.json', strict: true } ``` ### Interfaces #### AffectedRequest The targets asked for over a change, and the arguments every requested task receives. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly targets` | `unknown` | The targets. | | `readonly base` | `string` | The base revision, `origin/main` when none is named. | | `readonly head` | `string` | The head revision, or null for the working tree. | | `readonly args` | `unknown` | The arguments after the selection, passed to each requested task. | #### ExecutorContext What an executor is called with besides its options. **Properties** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute. | | `cwd` | `string` | The directory the command line started in. | | `projectName` | `string` | The project the task runs on. | | `targetName` | `string` | The target the task runs. | | `target` | `TargetConfiguration` | The target, merged with its defaults and its tokens replaced. | | `projects` | `Record` | Every project's configuration by name, targets resolved. | | `configuration` | `WorkspaceConfiguration` | The workspace configuration. | #### ExecutorEntry One executor of an executors manifest. **Properties** | Name | Type | Description | | --- | --- | --- | | `implementation` | `string` | The module whose default export implements it, relative to the manifest. | | `schema` | `string` | The schema of its options, relative to the manifest. | | `description?` | `string` | What it does. | #### ExecutorResult What an executor answers. **Properties** | Name | Type | Description | | --- | --- | --- | | `success` | `boolean` | Whether the task succeeded. | #### ExecutorSchema An executor's options schema, as far as the runner reads it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly properties?` | `Readonly>` | The options. | | `readonly required?` | `unknown` | The options a run must give, from the target or the command line. | #### ExecutorsManifest A package's `executors.json`. **Properties** | Name | Type | Description | | --- | --- | --- | | `executors?` | `Record` | The executors by name. | #### ExecutorSource Where an executor lives. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly file` | `string` | The module implementing it, absolute. | | `readonly schema` | `ExecutorSchema` | The schema of its options. | #### GeneratorEntry One generator of a generators manifest. **Properties** | Name | Type | Description | | --- | --- | --- | | `factory` | `string` | The module whose default export implements it, relative to the manifest. | | `schema` | `string` | The schema of its options, relative to the manifest. | | `description?` | `string` | What it does. | #### GeneratorsManifest A package's `generators.json`. **Properties** | Name | Type | Description | | --- | --- | --- | | `generators?` | `Record` | The generators by name. | #### GeneratorSource Where a generator lives. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly file` | `string` | The module implementing it, absolute. | | `readonly schema` | `GeneratorSchema` | The schema of its options. | #### LintSettings The settings of the `lint` target the workspace infers for its projects. **Properties** | Name | Type | Description | | --- | --- | --- | | `command?` | `string` | The command the inferred target runs from a project's root; `{workspaceRoot}` in it is the path from there to the workspace root. Defaults to `hf-lint .`. | | `exclude?` | `string[]` | The project files whose projects get no inferred target, as globs. | #### ManyHost What running the tasks needs. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly runChild` | `(id: string, args: unknown) => Promise` | Runs one task in a child, with the arguments after it; resolves to the exit code. | | `readonly now` | `() => number` | The current time in milliseconds. | | `readonly write` | `(line: string) => void` | Writes a line to standard error. | #### ManyRequest The tasks asked for and the arguments every requested task receives. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly targets` | `unknown` | The targets. | | `readonly projects` | `unknown` | The project names and globs, or null for every project. | | `readonly args` | `unknown` | The arguments after the selection, passed to each requested task. | #### PlannedTask One task to run, in order. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | `:`. | | `readonly requested` | `boolean` | Whether the task was asked for, rather than reached through `dependsOn`. | | `readonly after` | `unknown` | The tasks it runs after. | #### ProjectConfiguration A project's configuration, as an executor reads it. **Properties** | Name | Type | Description | | --- | --- | --- | | `name?` | `string` | The project's name. | | `root` | `string` | The project's root, workspace-relative and POSIX. | | `sourceRoot?` | `string` | The source root. | | `projectType?` | `"application" \| "library"` | `application` or `library`. | | `tags?` | `string[]` | The tags. | | `implicitDependencies?` | `string[]` | The projects this one depends on without importing them. | | `targets?` | `Record` | The targets by name. | | `metadata?` | `Readonly>` | Free-form metadata. | #### RunHost Where a task runs and what it runs with. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly cwd` | `string` | The directory the command line started in. | | `readonly importModule` | `ImportModule` | Imports an executor's module. | | `readonly root` | `string` | The workspace root, absolute. | | `readonly env` | `Environment` | The environment the commands start from. | | `readonly platform` | `string` | The platform, which decides how the search path is written. | | `readonly execPath` | `string` | The running Node.js executable, whose directory joins the search path. | | `readonly spawn` | `ShellSpawn` | Starts a command. | | `readonly write` | `(line: string) => void` | Writes a line of the runner's own: the command about to run, or why one failed. | #### SchemaProperty One option of an executor's schema, as far as the runner reads it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly type?` | `string` | The JSON type. | | `readonly default?` | `unknown` | The value the option takes when a run leaves it unset. | #### StartedAs What of a running process names the command line it was started as. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly execPath` | `string` | The Node.js executable. | | `readonly execArgv` | `unknown` | The flags Node.js itself was given. | | `readonly argv` | `unknown` | The argument vector: the executable, the entry module, then the arguments. | #### TargetConfiguration A target, as `project.json` and the `targetDefaults` of `hf.json` write it. **Properties** | Name | Type | Description | | --- | --- | --- | | `executor?` | `string` | The executor, `:`. | | `command?` | `string` | A shell command, the short form of a `run-commands` target. | | `options?` | `Options` | The options the executor is called with. | | `inputs?` | `unknown` | The inputs whose change selects the target. | | `dependsOn?` | `unknown` | The tasks the target runs after. | | `metadata?` | `Readonly>` | Free-form metadata. | #### TaskOutcome How one task ended. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | `:`. | | `readonly status` | `"succeeded" \| "failed" \| "skipped"` | Whether it ran and succeeded, ran and failed, or was skipped after a failed prerequisite. | | `readonly durationMs` | `number` | How long it ran, in milliseconds; 0 when skipped. | #### TaskRef A task named by its project and target. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly project` | `string` | The project's name. | | `readonly target` | `string` | The target. | #### Tree A virtual file tree: reads fall through to the files, writes are recorded until committed. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly root` | `string` | The directory every path is relative to, absolute. | ##### children ```typescript children(path: string): string[] ``` The names directly under a directory. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | ##### delete ```typescript delete(path: string): void ``` Records a file's deletion. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | ##### exists ```typescript exists(path: string): boolean ``` Whether a file or directory is there. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | ##### isFile ```typescript isFile(path: string): boolean ``` Whether the path names a file. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | ##### listChanges ```typescript listChanges(): TreeChange[] ``` Every change recorded so far. ##### read ```typescript read(path: string): Buffer ``` The content of a file, or null when there is none. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | ```typescript read(path: string, encoding: "utf-8"): string ``` The text of a file, or null when there is none. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | | `encoding` | `"utf-8"` | | ##### write ```typescript write(path: string, content: string | Buffer): void ``` Records a file's content. **Parameters** | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | | `content` | `string \| Buffer` | | #### TreeChange One change a tree has recorded since it was opened. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly path` | `string` | The path, relative to the tree's root, POSIX. | | `readonly type` | `"CREATE" \| "UPDATE" \| "DELETE"` | What happened to the file. | | `readonly content?` | `Buffer` | The content written, or nothing for a deletion. | #### WorkspaceConfiguration The workspace configuration, as `hf.json` writes it. **Properties** | Name | Type | Description | | --- | --- | --- | | `targetDefaults?` | `Record` | The defaults of each target, by executor or by target name. | | `namedInputs?` | `Record` | The named inputs. | | `lint?` | `LintSettings` | The inferred `lint` target's settings. | ### Types #### Executor An executor: the default export of the module an executors manifest names. ```typescript type Executor = (options: Options, context: ExecutorContext) => Promise | ExecutorResult ``` #### ExecutorFunction An executor: called with the options and the context, it answers a promise of its result. ```typescript type ExecutorFunction = (options: Record, context: ExecutorContext) => unknown ``` #### ExecutorModule A module as the runner reads it: its exports by name. ```typescript type ExecutorModule = Readonly> ``` #### Generator A generator: the default export of the module a generators manifest names. ```typescript type Generator = (tree: Tree, options: Options) => unknown ``` #### ImportModule Imports a module from its absolute path. ```typescript type ImportModule = (file: string) => Promise ``` ### Variables #### ENGINE_PACKAGE The package whose generators answer to a bare name when no workspace project offers it. ```typescript const ENGINE_PACKAGE: "@hyperfrontend/workspace" ``` **Value** `'@hyperfrontend/workspace'` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/runner/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/runner.md Documentation index: https://www.hyperfrontend.dev/llms.txt