IF Commons GitHub

Headless output

0003Draft

0003-headless-output · owner if · domain commons

The command

FR-001checkpassing

A command MUST be one value: a verb of the terminal's declaration (its name, summary, options and operands, declared once), the traits of its action, and a function that takes its parsed arguments and a context and returns an outcome; a program MUST be a tree of branches and commands, and modelProblems MUST return every defect of the tree as a typed value: what the terminal finds in its names, what the governance finds in each action's facts, an option named like one of the model's standard options (model/reserved-option) or whose short letter is taken by one (model/reserved-short), a human-only option the command does not declare (model/human-only-unknown), and a command named like a word the surface answers itself (model/built-in-word). Taken from: erga 274-agora FR-006, erga 274-agora FR-035 (a domain is one typed value; the words resolved by the command tree) and ergonex's Report-returning commands.

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-model.test.ts: a program is a tree of branches and commands; each command has its path, its id and the facts of its action; suite/logical-model.test.ts: the defects of a tree are found: duplicate words, an action that contradicts itself, reserved options and shorts, an unknown human-only option, a built-in word; suite/logical-model.test.ts: what a command tells while it runs is a progress event, and the writer of a phase says each kind

Proved by: headless/suite/logical-model.test.ts

Written in: headless/src/logical/model.ts, headless/src/logical/program.ts

Tests: passed: suite/logical-model.test.ts what a command tells while it runs is a progress event, and the writer of a phase says eac; passed: suite/logical-model.test.ts a program is a tree of branches and commands; each command has its path, its id and the fa; passed: suite/logical-model.test.ts the defects of a tree are found: duplicate words, an action that contradicts itself, reser

Cited by: commands/program, Ergonex, Headless, logical/model

FR-002checkpassing

A command MUST return a typed outcome and MUST NOT print: the outcome holds the data, the text of a report, the problems found in the order found, the lines the run wants seen, the hints, the steps spelled out, the findings for SARIF, a title for the verdict, and whether the run was stopped; merging two outcomes MUST keep the first's data and text, put the problems, lines, steps and findings of the first before those of the second, and show a hint once. Taken from: ergonex (Report{text,data,findings}) and stolos 105-calm-output FR-005 (RunSummary).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-model.test.ts: an outcome is a value with empty defaults; merging keeps the first's data and text, orders the rest, and shows a hint once; suite/logical-model.test.ts: what a command tells while it runs is a progress event, and the writer of a phase says each kind

Proved by: headless/suite/logical-model.test.ts

Written in: headless/src/logical/outcome.ts

Tests: passed: suite/logical-model.test.ts what a command tells while it runs is a progress event, and the writer of a phase says eac; passed: suite/logical-model.test.ts an outcome is a value with empty defaults; merging keeps the first's data and text, orders

Cited by: Headless, logical/outcome

FR-003checkpassing

A run MUST be in one of four verbosities: calm (the default: quiet on success, loud and actionable on a problem), verbose (every item as it happens), quiet (the verdict alone) and json (nothing for a person but one document); --json MUST win over every other choice, --quiet with --verbose MUST be refused as opposite, and a table MUST say which kind of line each verbosity shows (calm shows no item, no line for a phase that went well and no log line; quiet only the verdict; verbose all; json none). Taken from: stolos 105-calm-output FR-002 and FR-003, 019-output FR-003.

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-model.test.ts: the flags choose a verbosity: json over all, quiet with verbose refused; a table says what each shows

Proved by: headless/suite/logical-model.test.ts

Written in: headless/src/logical/verbosity.ts

Tests: passed: suite/logical-model.test.ts the flags choose a verbosity: json over all, quiet with verbose refused; a table says what

Cited by: Headless, logical/verbosity

FR-004checkpassing

The closing block MUST be data (closingOf) in this order: the problems (the first failure is the verdict, so it is not listed twice; then the other failures, then the warnings), what is the person's to do, what is pending, the hints that are due, the steps the command spelled out; then the verdict; then ONE next command. A failure MUST be shown once, with its code. The verdict where nothing failed MUST say the title, then the counts of warnings, of what is for the person, of what is pending and of the optional features, in that order; the next command MUST be the failure's own, else the first step for the person, else the one the command suggested, and a failure whose fix holds no command MUST have none. Taken from: stolos 105-calm-output FR-004 (honest marks), FR-005 (one run, one summary), FR-006 (the order of the closing block), FR-007 (a failure is printed once).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-closing.test.ts: the closing block is in the order problems, your move, pending, hints, steps; the first failure is the verdict and is not listed twice; suite/logical-closing.test.ts: where nothing failed the verdict states counts and never 'all well'; the next command is the first step for the person, else the suggested one; suite/logical-closing.test.ts: pending is never a failure and shows its next step (the case of stolos 052); suite/logical-closing.test.ts: for any problems: the verdict and the counts agree, a failure is listed once, and there is at most one next command

Proved by: headless/suite/logical-closing.test.ts

Written in: headless/src/logical/closing.ts

Tests: passed: suite/logical-closing.test.ts for any problems: the verdict and the counts agree, a failure is listed once, and there is; passed: suite/logical-closing.test.ts pending is never a failure and shows its next step (the case of stolos 052); passed: suite/logical-closing.test.ts the closing block is in the order problems, your move, pending, hints, steps; the first fa; passed: suite/logical-closing.test.ts where nothing failed the verdict states counts and never 'all well'; the next command is t

Cited by: Headless, logical/closing

FR-005checkpassing

A fix text MUST be split into the one command in it and the words around it, so that a fix:, run: or next: line holds only the command; the programs whose commands may begin a fix, and the program's own commands that may stand inside a sentence, MUST be the program's to give. Taken from: stolos 105-calm-output FR-011 (splitFix).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-closing.test.ts: a fix is split into its one command and the words around it (the golden cases of stolos)

Proved by: headless/suite/logical-closing.test.ts

Written in: headless/src/logical/fix.ts

Tests: passed: suite/logical-closing.test.ts a fix is split into its one command and the words around it (the golden cases of stolos)

Cited by: Headless, logical/fix

What is told

FR-006checkpassing

A run in json verbosity MUST end with ONE JSON document and nothing else for a person: the schema (headless.envelope/1), the program, its version, the command as typed, whether nothing failed, the status with its name, the counts of each level, the problems, the lines, the hints, the steps and the data, in that order of keys; it MUST hold no colour, no mark and no width, and a value JSON cannot say (undefined, a bigint, a Date, a number that is not finite) MUST be made one it can, never thrown on. Taken from: erga 274-agora (--json is one document), ergonex (--json) and stolos 019-output FR-003.

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-told.test.ts: an envelope is one document with a fixed order of keys, whose status, counts and data agree with the run; suite/logical-told.test.ts: toJson never throws and gives what JSON can say, for any value

Proved by: headless/suite/logical-told.test.ts

Written in: headless/src/logical/envelope.ts

Tests: passed: suite/logical-told.test.ts an envelope is one document with a fixed order of keys, whose status, counts and data agre; passed: suite/logical-told.test.ts toJson never throws and gives what JSON can say, for any value

Cited by: Headless, logical/envelope

FR-007checkpassing

A report asked for as SARIF MUST be a SARIF 2.1.0 log of the findings it returned, or, where it returned none, of its failures and warnings (the code of a problem its rule), each with its level, its message and its file and line where it has them. Taken from: ergonex (--sarif).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-told.test.ts: SARIF 2.1.0 holds the findings returned, else those of the failures and warnings, with rules, levels and locations

Proved by: headless/suite/logical-told.test.ts

Written in: headless/src/logical/envelope.ts

Tests: passed: suite/logical-told.test.ts SARIF 2.1.0 holds the findings returned, else those of the failures and warnings, with rul

Cited by: Headless, logical/envelope

FR-008checkpassing

A problem shown with a code MUST be explainable by that code: a catalogue (the program's own data) maps a code to a title, what happened, the likely cause, the fix and, where it has one, a guide; explainText MUST give one explanation for a code written in either case, the list of every code where no code is given, and for a code that is not there say so and name the nearest. WHEN a raw error of another tool matches a pattern of the program, translate MUST give its code and fix, the first pattern that matches winning, and a raw error that matches none MUST be shown as it is. A catalogue MUST be checked: every key a stable code, no field blank, every pattern naming a code the catalogue explains. Taken from: stolos 052-self-describing FR-004 and FR-005, 105-calm-output FR-009 and stolos 052-self-describing FR-013.

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-told.test.ts: a raw error of another tool is given its code and fix by the first pattern that matches, and an unknown one is left as it is; suite/logical-told.test.ts: explain gives one explanation for a code in either case, the list without one, and names the nearest for one that is not there; suite/logical-told.test.ts: a catalogue is checked: stable codes, no blank field, patterns that name a code explained

Proved by: headless/suite/logical-told.test.ts

Written in: headless/src/logical/explain.ts, headless/src/logical/program.ts

Tests: passed: suite/logical-told.test.ts a catalogue is checked: stable codes, no blank field, patterns that name a code explained; passed: suite/logical-told.test.ts a raw error of another tool is given its code and fix by the first pattern that matches, a; passed: suite/logical-told.test.ts explain gives one explanation for a code in either case, the list without one, and names t

Cited by: governance/problems, AnyFS command line, commands/catalogue, Ergonex, Headless, logical/explain, governance/problems, Repoctl

FR-009checkpassing

A hint (an optional feature that is merely off) MUST be due when it was never shown or was shown seven days ago or more, each hint at most once in a run, and the memory of when each was shown MUST be the one given with the due hints set to the time now, and the same where none is due. Taken from: stolos 105-calm-output FR-008.

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-told.test.ts: a hint is due when never shown or shown seven days ago, once for each id, and the memory changes only where one is due

Proved by: headless/suite/logical-told.test.ts

Written in: headless/src/logical/hints.ts

Tests: passed: suite/logical-told.test.ts a hint is due when never shown or shown seven days ago, once for each id, and the memory c

Cited by: Headless, logical/hints

FR-010checkpassing

A run nested in another MUST NOT draw a header, a phase or a closing block: it MUST hand what it found to its parent as a summary (the counts, every problem in order, the lines), read back by a decoder and never trusted, and the parent MUST merge it so that every problem appears once. The names of the variables that say a run is nested and where the summary goes MUST come from the program's prefix. Taken from: stolos 105-calm-output FR-005 (STOLOS_NESTED, STOLOS_SUMMARY).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-told.test.ts: a nested run hands its summary to its parent, which reads it back by a decoder and merges it so that every problem is there once

Proved by: headless/suite/logical-told.test.ts

Written in: headless/src/logical/nested.ts, headless/src/logical/program.ts

Tests: passed: suite/logical-told.test.ts a nested run hands its summary to its parent, which reads it back by a decoder and merges

Cited by: Headless, logical/nested, Headless reach and targets

FR-011checkpassing

Before anything is drawn, logged or returned, every text of an outcome (every message, fix, raw error, line, step, hint and finding, the report's text, and every string of its data however deep) and of what a command tells while it runs MUST pass through the program's redactor; redacting an outcome twice MUST be redacting it once. Taken from: arcactl 0046-arcactl FR-009 and stolos's secrets reminder (105-calm-output FR-017).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-told.test.ts: every text of an outcome and of its progress passes through the redactor, however deep, and doing it twice is doing it once

Proved by: headless/suite/logical-told.test.ts

Written in: headless/src/logical/redaction.ts

Tests: passed: suite/logical-told.test.ts every text of an outcome and of its progress passes through the redactor, however deep, an

Cited by: Headless, logical/redaction

FR-012checkpassing

Every command MUST take the options of the model by its effect, and no program MAY redeclare them: --json, --quiet (-q), --verbose (-v), --color and --no-color, --non-interactive; --sarif for a report; --dry-run where the action can preview; --check where it can check; --yes (-y) where it destroys. Taken from: ergonex (--json, --sarif, --no-color), arcactl (--non-interactive) and stolos 105-calm-output FR-002 (--verbose, --quiet).

Enforced (check): .github: cd commons/headless && bun run verify — suite/logical-model.test.ts: every command takes the standard options by its effect, and the key of each is a long option

Proved by: headless/suite/logical-model.test.ts

Written in: headless/src/logical/model.ts

Tests: passed: suite/logical-model.test.ts every command takes the standard options by its effect, and the key of each is a long opti

Acceptance scenarios

  1. Given a tree with a duplicate word, an option named json and a destructive action with no preview, When modelProblems runs, Then each is found, per FR-001.
  2. Given two outcomes with a hint of the same id, When they are merged, Then the hint is shown once, per FR-002.
  3. Given --json --quiet, When the verbosity is chosen, Then it is json; given --quiet --verbose, Then it is refused, per FR-003.
  4. Given an outcome with two failures, a warning, a step for the person and a pending item, When its closing block is made, Then the lines are in the order of FR-004, the first failure is the verdict, and there is one next command, per FR-004.
  5. Given the fix mytool sync (pull first), When it is split, Then the command is mytool sync and the instruction is Pull first, per FR-005.
  6. Given an outcome with a bigint in its data, When its envelope is written, Then it is one parseable document with no other output, per FR-006.
  7. Given a raw Could not resolve host, When it is translated by a catalogue that has the pattern, Then its code and fix are given, per FR-008.
  8. Given a hint shown six days ago, When the due hints are taken, Then it is not due; seven days ago, it is, per FR-009.
  9. Given a child that wrote its summary, When the parent merges it, Then each problem is in the parent's block once, per FR-010.
  10. Given a secret token in a message, a fix and the data, When the outcome is redacted, Then it is in none of them, per FR-011.

Out of scope

  • Marks, colours, widths, the spinner, prompts and the files of the run log: the surface (0004-headless-cli).
  • The catalogue of a program's explanations, its guides, the commands of its fixes, and the secrets panel: the program's own data and code, given to these mechanisms.

Edge cases

  • A failure whose fix is only a sentence: the sentence is shown, and there is no next command, per FR-004.
  • An outcome with no problem, no hint and no step: the verdict alone, per FR-004.
  • A hint of the same id raised twice in a run: shown once, per FR-009.
  • A summary file that is not what a summary is: refused with why, never trusted, per FR-010.

Assumptions

  • A command's data can be told as JSON once toJson has made it so.

Open questions

  • None.

Key entities

  • Command - a verb, the traits of its action, and what it does.
  • Outcome - what a command returns: data, text, problems, lines, hints, steps, findings.
  • Closing block - the lines, the verdict and the one next command of a run, as data.
  • Envelope - the one JSON document of a run.

Success criteria

SC-001success criterion

Every program that uses this layer ends a run with the same block, the same document and the same explanations.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

governance/problems, AnyFS command line, physical/program, physical/verbs/common, commands/catalogue, commands/define, commands/program, Ergonex, surfaces/headless/mod, Headless, logical/closing, logical/envelope, logical/explain, logical/fix, logical/hints, logical/mod, logical/model, logical/nested, logical/outcome, logical/program, logical/redaction, logical/verbosity, Planning, physical/planctl, governance/problems, Repoctl, physical/define, physical/program, Intellectual Frontiers Commons, Headless governance, Headless reach and targets, GRC headless verbs

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