IF Commons GitHub

surfaces/cli/run

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-headless-cli FR-011, 0004-headless-cli FR-003, 0004-headless-cli FR-004, 0004-headless-cli FR-012

The run boundary of the command line (commons headless 0004-headless-cli FR-011): run(program, argv, io) gives { code, out, err } and touches no process global, so a test, a REPL and a tool that embeds the program all call it the same way. It resolves the words to a command, parses the options (the model's standard ones included), decides whether to proceed, preview, ask or refuse (the governance's decide), runs the command, draws the closing block, and ends with the status of the one table of exits.

The result of a command (its report text, or the one JSON document) goes to out; what narrates the run (the phases, the closing block) goes to err, so that a report can be piped and a document is never mixed with prose. A failure before the command runs (an unknown word, a wrong option, a refusal) is a sentence on err and the status 2, in every mode: the one JSON document is the document of a run that ran.

import { run } from "./run.ts";
import { programOf } from "@intellectual-frontiers/headless/logical";
const io = { env: () => undefined, os: "linux", terminal: { stdin: false, stdout: false, stderr: false }, columns: undefined, now: () => 0, pid: 1, readLine: async () => undefined } as const;
(await run(programOf({ name: "tool", summary: "A tool.", version: "1.2.3", children: [] }), ["--version"], io)).out; // "tool 1.2.3\n"

Source: commons/headless/src/surfaces/cli/run.ts

2 of 2 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

lookOfRunfunction
function lookOfRun(program: Program, io: Io, colour: boolean): Look

The look of the error stream, where the narration goes (0008-exit-style-consent FR-002). The style of the marks is an explicit decision, Io.marks: plain (the ASCII marks), emoji, or auto, the default, which is plain unless the stream is a terminal that shows emoji and nothing asks for plain: not NO_COLOR, not --no-color, not the program's <PREFIX>_PLAIN. The program's <PREFIX>_EMOJI turns emoji on where nothing asks for plain. So a run in CI, in a pipe or with colour off is the same plain text everywhere.

Imported by 13 tests of the run (13 passed, 0 failed): the library's results

runfunction
function run(whole: Program, argv: readonly string[], io: Io): Promise<RunResult>

Runs a program's command line.

Imported by 85 tests of the run (85 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.