The command model (commons headless 0003-headless-outputFR-001): a program is a tree of branches and commands; a command is a verb of the terminal's declaration (its name, summary, options and operands, declared once) with the facts of its action (commons headless 0002-headless-governance) and the function that runs it, which returns a typed outcome and prints nothing. A surface draws the tree: the command line as words and options, a tool server as tools, a REST interface as routes.
The options every command takes by its effect (--json, --quiet, --verbose, --no-color, --non-interactive; --dry-run where it can preview, --check where it can check, --yes where it destroys) are the model's (standardOptions), so that no program redeclares them and none can declare a different meaning for their names.
typeActionTraits=Omit<ActionDefinition, "id"|"summary"> & {
/** Where it may be reached from and run (commons headless 0005-reach-and-targets): required of every action by the conformance rule `model/no-reach-policy`. */readonlyreach?:ReachPolicy;
};
What a command is as an action, besides its identity (the path of its words and its summary are the tree's).
type Context = {
readonly program: string;
/** The words of the command as typed (`work build`). */
readonly comma…(969 characters)
typeContext= {
readonlyprogram:string;
/** The words of the command as typed (`work build`). */readonlycommand:string;
readonlyfacts:ActionFacts;
readonlymode:Mode;
readonlyverbosity:Verbosity;
/** Whether the person can be asked a question now. */readonlyinteractive:boolean;
/** Where the command tells what it is doing, as it does it. */readonlyprogress:Progress;
/** A question to the person; each answers `undefined` where there is no one to ask. */readonlyprompt:Prompt;
/** The credentials of this one command (0011-credential-prompt): asked once each, held in memory until the command ends, refused where there is no person, never logged. */readonlycredentials:Credentials;
/** The environment, as a function. */readonlyenv: (name:string) =>string|undefined;
/** Aborted when the person stops the run (SIGINT, SIGTERM): a command that can stop early listens. */readonlysignal:AbortSignal;
};
typePrompt= {
readonlyask: (question:string) =>Promise<string|undefined>;
/** `undefined` where there is no person to ask: the decision is then the governance's (`decide`), never a guess. */readonlyconfirm: (question:string) =>Promise<boolean|undefined>;
};
The words of the program's own place that the surface answers itself (help, explain, completions, man): a program's tree may not use them for a command.
The options every command takes, and those its action's facts add: --dry-run where it can preview, --check where it can check, --yes where it destroys.
Everything wrong with a program's tree: what the terminal finds in its names (a duplicate, a bad name), what the governance finds in each action's facts, an option of a command named as one of the model's standard options, and a human-only option the command does not declare.
typeActionTraits=Omit<ActionDefinition, "id"|"summary"> & {
/** Where it may be reached from and run (commons headless 0005-reach-and-targets): required of every action by the conformance rule `model/no-reach-policy`. */readonlyreach?:ReachPolicy;
};
What a command is as an action, besides its identity (the path of its words and its summary are the tree's).
type Context = {
readonly program: string;
/** The words of the command as typed (`work build`). */
readonly comma…(969 characters)
typeContext= {
readonlyprogram:string;
/** The words of the command as typed (`work build`). */readonlycommand:string;
readonlyfacts:ActionFacts;
readonlymode:Mode;
readonlyverbosity:Verbosity;
/** Whether the person can be asked a question now. */readonlyinteractive:boolean;
/** Where the command tells what it is doing, as it does it. */readonlyprogress:Progress;
/** A question to the person; each answers `undefined` where there is no one to ask. */readonlyprompt:Prompt;
/** The credentials of this one command (0011-credential-prompt): asked once each, held in memory until the command ends, refused where there is no person, never logged. */readonlycredentials:Credentials;
/** The environment, as a function. */readonlyenv: (name:string) =>string|undefined;
/** Aborted when the person stops the run (SIGINT, SIGTERM): a command that can stop early listens. */readonlysignal:AbortSignal;
};
typePrompt= {
readonlyask: (question:string) =>Promise<string|undefined>;
/** `undefined` where there is no person to ask: the decision is then the governance's (`decide`), never a guess. */readonlyconfirm: (question:string) =>Promise<boolean|undefined>;
};
The words of the program's own place that the surface answers itself (help, explain, completions, man): a program's tree may not use them for a command.
The options every command takes, and those its action's facts add: --dry-run where it can preview, --check where it can check, --yes where it destroys.
Everything wrong with a program's tree: what the terminal finds in its names (a duplicate, a bad name), what the governance finds in each action's facts, an option of a command named as one of the model's standard options, and a human-only option the command does not declare.