IF Commons GitHub

Headless exit, style and consent

0008Draft

0008-exit-style-consent · owner if · domain commons

What a command can say

FR-001checkpassing

An outcome MUST carry the exit its command names, as a closed union (ok, pending, findings, environment, usage), or none; the status of a run MUST be that of the problems found where it names none or names ok, 4 where it names pending (unless something failed, which is findings), and 1, 3 or 2 where it names findings, environment or usage, however little else was found; the merge of two outcomes MUST keep the more severe name (usage, environment, findings, pending, ok); and the status and the JSON envelope MUST agree, the envelope carrying the status the run ends with and its name from the one table. Taken from: ergonex, which worked around the absence with a flag of its own mapped in its main.

Enforced (check): .github: cd commons/headless && bun run verify — suite/exit-style-consent.test.ts: a command names its exit and the run ends with it; the status and the envelope agree, and a failure is never hidden by a name of ok or pending

Proved by: headless/suite/exit-style-consent.test.ts

Tests: passed: suite/exit-style-consent.test.ts a command names its exit and the run ends with it; the status and the envelope agree, and

Cited by: governance/exits

How the marks look

FR-002checkpassing

The style of the marks MUST be an explicit decision, Io.marks (plain, emoji or auto, the default): plain is the ASCII marks and emoji the palette's emoji; auto MUST be plain unless the stream written to is a terminal that shows emoji and nothing asks for plain, and NO_COLOR set, --no-color given and the program's <PREFIX>_PLAIN each ask for plain; the program's <PREFIX>_EMOJI MUST turn emoji on where nothing asks for plain. So a run in CI, in a pipe, or with colour off MUST write the same plain text wherever it runs, and the locale alone MUST NOT turn emoji on where the stream is not a terminal. Taken from: ergonex's CI, where --no-color left the emoji on.

Enforced (check): .github: cd commons/headless && bun run verify — suite/exit-style-consent.test.ts: the marks are plain unless the stream is a terminal that shows emoji and nothing asks for plain; Io.marks decides explicitly

Proved by: headless/suite/exit-style-consent.test.ts

Tests: passed: suite/exit-style-consent.test.ts the marks are plain unless the stream is a terminal that shows emoji and nothing asks for

Cited by: surfaces/cli/run, Headless command line

What is redacted

FR-003checkpassing

The redactor MUST replace only what is a secret and MUST leave prose alone: the secret values the program holds (four characters or more), the password of a URL, a password= (or passwd=, pwd=) assignment, a token of a known shape (GitHub ghp_, gho_, ghu_, ghs_, ghr_ and github_pat_, GitLab glpat-, Slack xox, AWS AKIA, npm, sk-, a Bearer token of sixteen characters or more, a JWT, a private-key block), and the value of a key that the program declares secret (KEY=value, or "KEY": "value"); it MUST NOT replace the text after KEY: or KEY= for a key that was not declared, so that a sentence that names an environment variable (APP_GITHUB_TOKEN: the token is not set) is unchanged; redacting twice MUST be redacting once. Taken from: ergonex, whose message naming ERGONEX_GITHUB_TOKEN was turned into *** with the token unset.

Enforced (check): .github: cd commons/headless && bun run verify — suite/exit-style-consent.test.ts: the redactor replaces secrets and tokens of a known shape and declared keys, and leaves a sentence that names a variable alone

Proved by: headless/suite/exit-style-consent.test.ts

Tests: passed: suite/exit-style-consent.test.ts the redactor replaces secrets and tokens of a known shape and declared keys, and leaves a

Cited by: governance/redact, Headless, logical/credentials, Headless governance

FR-004checkpassing

The reach policy's confirmation class MUST include consent: the identifier of an approval a person gave earlier, passed as --consent <id> (an option the action has only where its class is consent and it changes something); for such an action the decision MUST be to proceed where a consent is given and the surface accepts it (acceptsConsent, the surface's flagConfirms where it does not say), to ask a person where there is one and no consent, and to refuse (consent-needed) otherwise; an action that only reads MUST NOT be of this class (reach/consent-on-read); a preview MUST need no consent; and a run that went on by a consent MUST record it in the run's log, the identifier written through the redactor. Taken from: ergonex, which needs a mutating action to run with no terminal on a consent given before.

Enforced (check): .github: cd commons/headless && bun run verify — suite/exit-style-consent.test.ts: an action of the class consent goes on with no terminal on a consent given before, asks a person where there is one, is refused otherwise, and records the consent in the log

Proved by: headless/suite/exit-style-consent.test.ts

Written in: headless/src/governance/action.ts

Tests: passed: suite/exit-style-consent.test.ts an action of the class consent goes on with no terminal on a consent given before, asks a

Cited by: governance/reach, The ergonex command

Acceptance scenarios

  1. Given a command whose outcome names usage, When its run ends, Then its status is 2 and the JSON envelope says status 2 named usage, per FR-001.
  2. Given an outcome that names ok and holds a failure, When its run ends, Then its status is 1, per FR-001.
  3. Given a pipe with a UTF-8 locale, When the marks are chosen, Then they are plain; given a terminal with a UTF-8 locale they are emoji, and --no-color or NO_COLOR makes them plain, per FR-002.
  4. Given the sentence APP_GITHUB_TOKEN: the token is not set, When it is redacted, Then it is unchanged, and APP_GITHUB_TOKEN=abc is *** only where the key is declared, per FR-003.
  5. Given a GitHub token in a message with nothing declared, When it is redacted, Then it is replaced by its shape, per FR-003.
  6. Given an action whose class is consent run with no terminal, When it is run with no consent, Then it is refused; with --consent c-1 it proceeds and the log records the consent, per FR-004.

Out of scope

  • How a consent is obtained or checked (a person's approval, its expiry): the program's, which gives the identifier; Headless carries it and records that it was used.

Edge cases

  • A named exit pending with a failure found: the status is 1, per FR-001.
  • A consent given to an action that only reads: no --consent option exists for it, per FR-004.
  • --dry-run with no consent: a preview, per FR-004.

Assumptions

  • A program that wants the old behaviour of the key pattern declares its keys; there is no setting to bring back the broad pattern.

Open questions

  • None.

Key entities

  • Run exit - the verdict a command names for its run.
  • Mark style - plain or emoji, decided once for a run.
  • Consent - the identifier of an approval given earlier, which stands for the answer of a person.

Success criteria

SC-001success criterion

A real program ends its runs with the right status, writes the same text in CI everywhere, never hides a sentence, and runs a changing action unattended on a consent.

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/exits, governance/reach, governance/redact, Headless, logical/credentials, surfaces/cli/run, The ergonex command, Headless governance, Headless command line

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