@hyperfrontend/workspace/cli

cli

The command line behind npx hf, as a function: runWorkspaceCli takes the arguments, the directory the command ran in and two streams, and resolves to the exit code.

import { runWorkspaceCli } from '@hyperfrontend/workspace/cli'

const code = await runWorkspaceCli({
  argv: process.argv.slice(2),
  cwd: process.cwd(),
  stdout: process.stdout,
  stderr: process.stderr,
})

Commands

CommandWhat it does
run <project>:<target> [--name=value ...]Runs that one task alone, without the tasks it depends on
run-many -t <targets> (-p <names> | --all)Runs the tasks and their prerequisites in order, skipping the dependents of a failure
affected -t <targets> [--base=<ref>] [--head=<ref>]Runs the tasks the change selects, from the merge base with the default branch unless a base is given
format --check|--write [--all | --files=<list>]Runs prettier on the changed files, every file, or the files named
generate <generator> [--option=value ...]Runs a generator of the workspace or of an installed package, by bare name or as <package>:<name>
show projects [--with-target=<target>] [--json]Lists the project names
graph <command>Prints, verifies and explains the workspace graph (runGraph)

Every command finds the workspace root from any directory below it; generate also runs where no hf.json exists yet, taking the working directory as the root. A task's option is given after it as --name=value, read as the type the executor's schema declares, or --name alone for true; after a shell target the arguments reach the command. The command line's own messages go to standard error, and the exit code is 0 when the command succeeded and 1 otherwise.

One name, two packages

@hyperfrontend/features publishes an executable of the same name for its own commands. With both packages installed, either executable answers every command: a word it does not own is handed to the other package's command line, and --help prints both usages.

API Reference§

ƒ Functions

§function

handOver(invocation: Invocation, host: HandoverHost): Promise<number>

Passes a run on to the features command line, when @hyperfrontend/features is installed where the command was run.
Parameters
NameTypeDescription
§invocation
InvocationThe run, passed on as it was received
§host
HandoverHostHow the features command line is found and loaded
Returns
Promise<number>
The exit code of the features command line, or null when the package is not installed
Example

Letting the other command line answer a command this one does not own

import { handOver, processHost } from '@hyperfrontend/workspace/cli'

const code = await handOver({ argv: ['pack', '.'], cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr }, processHost())
// => the features exit code, or null when @hyperfrontend/features is not installed where the command was run
§function

isOwnCommand(word: string): boolean

Whether a word is a command this command line owns.
Parameters
NameTypeDescription
§word
stringThe first argument
Returns
boolean
True for run and every command of the table
Example

Deciding which command line answers

isOwnCommand('run-many') // true
isOwnCommand('pack') // false: the features command line is asked, when it is installed
§function

processHost(entry: string): HandoverHost

The handover host of the running process: the features command line is resolved from the directory the command was run in, the way Node resolves any installed package.
Parameters
NameTypeDescription
§entry
stringThe package entry that holds the command line(default: FEATURES_CLI)
Returns
HandoverHost
How this process resolves and loads that entry
Example

Resolving the features command line from where the command was run

const host = processHost()
host.resolve('/repo/apps/shell') // => '/repo/node_modules/@hyperfrontend/features/cli/index.js', or null when the package is not installed
§function

runGraph(argv: unknown, root: string, output: GraphOutput): number

Runs the graph command.
Parameters
NameTypeDescription
§argv
unknownThe arguments after graph
§root
stringThe workspace root, absolute
§output
GraphOutputWhere the command writes
Returns
number
The exit code: 1 when verify finds a difference, 0 otherwise
Examples

The tasks a change selects, explained

import { runGraph } from '@hyperfrontend/workspace/cli'

const output = { say: (line: string) => process.stdout.write(`${line}\n`), note: (line: string) => process.stderr.write(`${line}\n`) }
runGraph(['affected', '--target', 'build', '--base', 'origin/main', '--explain'], root, output)
// => 0; each selected build and the file that selected it went to `say`, the state build report to `note`

Checking the persisted graph state in CI

runGraph(['verify'], root, output) // => 1 when a cold build disagrees with the state on disk
§function

runWorkspaceCli(options: Invocation, host: HandoverHost): Promise<number>

Runs the workspace's command line. The hf name is shared with @hyperfrontend/features: where that package is installed, a command this one does not own is passed on to its command line, and the usage is followed by its usage.
Parameters
NameTypeDescription
§options
InvocationThe arguments, the starting directory and where to write
§host
HandoverHostHow the features command line is found and loaded(default: ...)
Returns
Promise<number>
The exit code: 0 when the command succeeded, 1 otherwise
Examples

The command line as a function

import { runWorkspaceCli } from '@hyperfrontend/workspace/cli'

const code = await runWorkspaceCli({
  argv: ['run-many', '-t', 'build', '-p', 'lib-*'],
  cwd: process.cwd(),
  stdout: process.stdout,
  stderr: process.stderr,
})
// => 0 when every task succeeded, 1 otherwise

Another `hf` command line passing a command on

const code = await runWorkspaceCli({ argv, cwd, stdout, stderr, handedOver: true })
// => the exit code; an unknown command is reported here rather than passed back

◈ Interfaces

§interface

FeaturesCli

The features package's command line, as far as this one calls it.
Properties
§readonly runFeaturesCli:(invocation: Invocation) => Promise<number>Runs the features command line and resolves to its exit code.
§interface

GraphOutput

Where the command writes.
Properties
§readonly say:(line: string) => voidWrites a line of the result, to standard output.
§readonly note:(line: string) => voidWrites a line about what the command did on the way, to standard error.
§interface

HandoverHost

How the other command line is found and loaded.
Properties
§readonly resolve:(cwd: string) => stringThe file of the features command line as a directory resolves it, or null when the package is not installed.
§readonly load:(file: string) => Promise<FeaturesCli>Loads the features command line from its file.
§interface

Invocation

One run of a command line, as both packages take it.
Properties
§readonly argv:unknownThe arguments after the executable's name.
§readonly cwd:stringThe directory the command line was started in.
§readonly stdout:TextSinkWhere results go.
§readonly stderr:TextSinkWhere the command line's own lines go.
§readonly handedOver?:booleanSet by the command line that passed this run on, so it is not passed back.
§interface

TextSink

Somewhere text is written.
Methods
§write(text: string): unknown
Writes text.

Parameters

NameTypeDescription
§text
string

◆ Types

§type

WorkspaceCliOptions

What a run of the command line is given.
type WorkspaceCliOptions = Invocation

● Variables

§type

FEATURES_CLI

The entry of the features package that runs its command line.
§type

GRAPH_USAGE

What the command expects.
§type

USAGE

What the command line prints about itself.
§type

WORKSPACE_FILE

The file that marks a workspace root.