approval-md 0.1.0 → 0.2.0

package/dist/src/cli/setup.d.ts

@@ -0,0 +1,202 @@
+/**
+ * `approval setup` — the interactive configuration family (SPEC.md §5.2, §10.1).
+ *
+ * APRV-73 gave `.approval/env` a format and `approval env` a reader. This verb
+ * is the writer, and it is the only one: it establishes the things an operator
+ * must have before any gate operation works — a declared human identity, a
+ * vault passphrase, a sampling secret, a live Telegram bot and chat, and an
+ * adapter's credentials — by putting each VALUE where that kind of value
+ * belongs and each SOURCE in `.approval/env`.
+ *
+ * ## Who lives where
+ *
+ * This file holds the three subcommands whose subject is a value this runtime
+ * MINTS or a name it records, plus the dispatch:
+ *
+ * ```
+ * setup identity                 # APPROVAL_HUMAN, in this file
+ * setup vault                    # the vault passphrase, in this file
+ * setup sampling                 # the audit sampling secret, in this file
+ * setup checkpoint               # cli/setup-checkpoint.ts (the vault + a print)
+ * setup channel <name>           # cli/setup-channel.ts  (keystore + .approval/env)
+ * setup adapter <name>           # cli/setup-adapter.ts  (the vault)
+ * setup service                  # cli/setup-service.ts  (a launchd/systemd unit)
+ * ```
+ *
+ * The last two are **two nouns and not one list**, and the split is SPEC.md
+ * §4's: a CHANNEL surfaces requests and collects decisions and holds no state,
+ * so its setup fills the keystore and `.approval/env`; an ADAPTER executes side
+ * effects and holds credentials, so its setup fills the vault.
+ * An older build spelled the Telegram one without the `channel` noun, and that
+ * form is gone (APRV-79): the dispatch answers it with the new one and exits 2
+ * rather than aliasing it, because an alias would leave two spellings of a
+ * distinction the SPEC draws on purpose.
+ *
+ * Everything the three files share — the dependency bag, the keystore seam, the
+ * front matter, the human-only gate, the service names, the plaintext-literal
+ * offer — is `cli/setup-common.ts`, which imports from none of them. The
+ * conversation `setup channel|adapter` both run is `cli/setup-flow.ts`.
+ *
+ * ## The order these run in
+ *
+ * Nothing enforced it and nothing said it, which APRV-76 noticed the hard way.
+ * It is:
+ *
+ * ```
+ * approval init                       # the directory and the .gitignore
+ * (write APPROVAL.md)                 # the policy NAMES every variable below
+ * approval setup identity             # APPROVAL_HUMAN
+ * approval setup vault                # the passphrase, into the keystore
+ * eval "$(approval env)"              # the ONLY thing that puts them in a shell
+ * approval setup adapter <name>       # the adapter's credentials, into the vault
+ * ```
+ *
+ * The policy comes before every `setup`, because each of them reads variable
+ * NAMES out of it. The `eval` comes before `setup adapter`, because that
+ * subcommand needs the passphrase's VALUE in the environment and will not read
+ * `.approval/env` to get it (§11.1 invariant 7). `setup sampling` and
+ * `setup channel telegram` slot in anywhere after the policy.
+ *
+ * ## What this verb is not allowed to do
+ *
+ * **It never appends to the log, never attests, and never edits `APPROVAL.md`.**
+ * Configuration is not an authorized action, and the log is the record of
+ * authorized actions; a "telegram configured" event would be a line in the one
+ * file this project promises never to rewrite, saying something the log has no
+ * business knowing. `tests/cli-setup.test.ts` byte-compares `events.jsonl`
+ * across a complete run of every subcommand to keep that true by assertion.
+ * When a policy line is needed (the sampling secret's name), this verb PRINTS
+ * the `approval policy amend` invocation and stops: an amendment is a human
+ * ceremony with an attestation at the end of it, and a setup wizard that
+ * silently edited an attested policy would be forging the sign-off.
+ *
+ * It writes exactly three things: lines in `.approval/env`, through a writer
+ * that preserves every other line and comment (`core/env-file.ts`), items in
+ * the OS keystore, and entries in the vault (`setup adapter` only).
+ *
+ * ## Interactive or nothing
+ *
+ * Every subcommand refuses when stdin is not a terminal, or when `--json` was
+ * given, and exits 2 printing THE EXACT NON-INTERACTIVE ALTERNATIVE — the
+ * `security add-generic-password` line to run, or the `.approval/env` line to
+ * add, or the `export` to put in a shell profile. This is not a wizard being
+ * precious about its terminal. A `setup` that could be driven from a pipe would
+ * be a way for a CI job or an agent to write `APPROVAL_HUMAN` and a keystore
+ * item, which is precisely the boundary §11 draws: identity is config-declared,
+ * so establishing it must be an act of the human at the machine. The refusal
+ * text is the documented scripted path, so nobody has to reverse-engineer one.
+ *
+ * `setup identity` is EXEMPT from the human-only `--as` gate that every other
+ * subcommand carries, and the exemption is not a hole: identity is what that
+ * gate reads. A verb that demanded `APPROVAL_HUMAN` before it would let you set
+ * `APPROVAL_HUMAN` could only ever be run by someone who did not need it. The
+ * control on this path is the terminal itself.
+ *
+ * ## Answers, and answering again (APRV-90)
+ *
+ * Every typed question in this family runs through `prompt.ts`'s `askUntil`: a
+ * wrong answer is one line saying what was wrong and the same question again,
+ * never an exit code with a help page under it. `setup identity` also
+ * NORMALISES what it is given — `carter` is recorded as `human:carter`, and
+ * `human:carter` is taken as it stands ({@link identityFromAnswer}). The prompt
+ * still prints the `human:` prefix, because the prefix is what distinguishes
+ * the actor kinds the human-only verbs refuse, but nobody has to retype a
+ * prefix the question already showed them. `agent:` and `system:` are refused
+ * with the sentence that names why, as a reason to answer again.
+ *
+ * ## Where a secret goes, and how it gets there
+ *
+ * Three service names, one per secret, documented so an operator can find them
+ * with `security find-generic-password` or `secret-tool lookup` by hand:
+ * `approval-tg-token`, `approval-vault-passphrase`, `approval-sampling-secret`.
+ *
+ * - **macOS** (`darwin` and `security` on PATH) → `keychain:<service>`;
+ * - **Linux with `secret-tool`** → `secret-service:<service>` (the same string
+ *   is the label, so the two platforms name one secret one way);
+ * - **neither** → the operator is OFFERED a plaintext literal in
+ *   `.approval/env`, and must type `yes` in full to take it, having been shown
+ *   the same warning `approval env --check` will print at them forever after.
+ *   §5.2 permits literals for a stated reason, and refusing here would only
+ *   move the value into a shell profile where nothing can see it to report it.
+ *
+ * **A value the operator already holds is never handled by this process.** The
+ * Telegram token on macOS is collected by `security`'s OWN no-echo prompt: we
+ * spawn `security add-generic-password … -w` WITH NO VALUE and with inherited
+ * stdio, Apple's prompt reads it from the terminal, and the token reaches this
+ * runtime only afterwards, on the stdout of a `find-generic-password -w` read
+ * that puts nothing in an argv either. Off macOS it comes through
+ * `Prompter.readSecret`, which at least keeps it off the screen.
+ *
+ * **A value we generate ourselves is a different question**, and it is the one
+ * place this family makes a trade rather than following a rule. The vault
+ * passphrase and the sampling secret are `randomBytes(32)`, minted in this
+ * process, so they are already in this process and there is nobody to prompt.
+ * They reach the keystore by STDIN first: `security add-generic-password -w`
+ * with the value written to its stdin twice (the prompt asks for confirmation),
+ * and `secret-tool store`, which documents stdin as its input. Only if the
+ * stdin form FAILS does the fallback put the value in an argv (`-w <value>`),
+ * and then the outcome says so out loud. That residual exposure is a value
+ * minted one millisecond earlier, never used, visible in `ps` to the same user
+ * who is running the command and to root — which is the boundary §11 already
+ * declares undefended. It is accepted for generated values and for nothing
+ * else: no path in this family ever puts an operator's own token in an argv.
+ *
+ * **And there is one standing exception to the rule above, which
+ * `setup adapter <name>` takes.** A credential bound for the VAULT must pass
+ * through this process, because the vault is not a helper with a prompt: it is
+ * a file this runtime encrypts, so `setCredential` needs the bytes. There is
+ * nothing to delegate the typing to and no third party to hold the value. The
+ * secret is read with `Prompter.readSecret` (no echo), handed straight to the
+ * cipher, and never printed, logged, or placed in an argv — which is exactly
+ * what `approval vault set` already does when a human pastes a credential onto
+ * its stdin. The rule is "never handle a value someone else can hold for you";
+ * for the vault nobody can, so it is stated here rather than left to look like
+ * an oversight.
+ *
+ * ## Seams
+ *
+ * The prompter, the keystore, and `fetch` are injected. The alternative is a
+ * test suite that needs a terminal, writes to the developer's real Keychain,
+ * and talks to the real Bot API — and the third of those would put a real bot
+ * token in a test run. `tests/cli-setup.test.ts` drives all three through fakes
+ * and the mock Bot API on loopback, and the spawned-CLI cases never get past
+ * the terminal check, so nothing under `npm test` can reach a keystore at all.
+ */
+import { type SetupDeps } from "./setup-common.js";
+import type { Streams } from "./main.js";
+/**
+ * One typed answer to `human identity (human:<id>):`, as an identity (APRV-90).
+ *
+ * **A bare id is accepted and normalised.** The prompt prints the `human:`
+ * prefix because the prefix is load-bearing — actors are `human:`, `agent:` or
+ * `system:`, and the human-only verbs refuse the other two — so an operator who
+ * has never read SPEC.md §11 learns the shape from the question itself. Making
+ * them retype a prefix the prompt just printed adds a failure path and teaches
+ * nothing further, so `carter` becomes `human:carter` and `human:carter` is
+ * taken as it stands.
+ *
+ * An answer with a colon in it is taken as a FULL actor and validated as one,
+ * which is what makes `agent:claude` a refusal rather than `human:agent:claude`.
+ * That refusal is a reason handed back to {@link askUntil}, so the operator is
+ * asked again rather than dropped out of the verb.
+ */
+export declare function identityFromAnswer(answer: string): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * `approval setup identity` — declare who the human is.
+ *
+ * EXEMPT from the human-only gate, and the module doc says why: this is the
+ * verb that creates the thing the gate reads.
+ */
+export declare function commandSetupIdentity(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): number;
+/** `approval setup vault` — mint and store the vault passphrase. HUMAN-ONLY. */
+export declare function commandSetupVault(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): number;
+/** `approval setup sampling` — mint and store the audit sampling secret. HUMAN-ONLY. */
+export declare function commandSetupSampling(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): number;
+/** `approval setup <identity|vault|sampling|channel <name>|adapter <name>>`. */
+export declare function commandSetup(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): number | Promise<number>;

package/dist/src/cli/style.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Terminal presentation: colour, glyphs, headings, tables (APRV-91, APRV-93).
+ *
+ * The observation behind this file was a real `examples/email-demo.md` run and
+ * a `policy amend --dry-run` the operator called dense: two 64-hex hashes on one
+ * line, the same absolute path three times, every line the same visual weight,
+ * no colour anywhere. Nothing was WRONG; nothing was scannable either.
+ *
+ * The design rules, from APRV-91's brief:
+ *
+ *   1. ROLES, NOT COLOURS. Callers ask for `ok` or `key`, never for green or
+ *      bold, so a theme is one table and a colour-blind reader loses nothing.
+ *   2. COLOUR IS REDUNDANT, ALWAYS. Every coloured thing is also carried by a
+ *      glyph or a word, so the plain-text degradation is lossless. That is not
+ *      politeness: piped output IS the tested output, and a pipe gets no colour.
+ *   3. NEVER COLOUR A COPYABLE VALUE. Hashes, tokens, paths and commands are
+ *      printed raw so a triple-click yields clean bytes. Colour the LABEL.
+ *   4. DECIDED ONCE. {@link style} memoizes the process-wide answer; tests build
+ *      their own with {@link makeStyle} rather than mutating the environment.
+ *
+ * NO NEW DEPENDENCY, deliberately: a colour library is thousands of lines to
+ * buy the eleven escape sequences below, and this repo justifies every package.
+ *
+ * `--json` IS AN ABSOLUTE VETO here, above even FORCE_COLOR. The brief lists
+ * `--json` alongside the other conditions, but the machine-readable shapes are
+ * frozen public API; one escape byte in a JSON stream is a parse error, not a
+ * cosmetic regression. So a caller that passes `json: true` cannot get colour by
+ * any combination of environment variables.
+ */
+/** The presentation roles. A theme is this list mapped to SGR parameters. */
+export type Role = "brand" | "ok" | "warn" | "fail" | "key" | "value" | "muted" | "rule" | "secret";
+/** The glyph vocabulary, and its ASCII degradation. */
+declare const GLYPHS: {
+    readonly ok: readonly ["✓", "[ok]"];
+    readonly fail: readonly ["✗", "[x]"];
+    readonly skip: readonly ["–", "[-]"];
+    readonly point: readonly ["▸", ">"];
+    readonly bar: readonly ["│", "|"];
+    readonly rule: readonly ["─", "-"];
+};
+export type Glyph = keyof typeof GLYPHS;
+/** How many characters of a 64-hex digest a human is shown. */
+export declare const SHORT_HASH_LENGTH = 12;
+export interface StyleInput {
+    /**
+     * Whether stdout is a terminal. Omitted means "ask this process".
+     *
+     * Tests pass an explicit `true` to render coloured output into a captured
+     * string, which is the only way to assert BOTH modes without a pty.
+     */
+    tty?: boolean;
+    /** Environment to read. Omitted means `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Whether this invocation is answering in JSON. An absolute veto on colour. */
+    json?: boolean;
+    /** The `--no-color` flag. An explicit off, above FORCE_COLOR. */
+    noColor?: boolean;
+}
+export interface Style {
+    /** Whether escape sequences are emitted at all. */
+    readonly enabled: boolean;
+    /** Whether glyphs degrade to their ASCII spellings. */
+    readonly ascii: boolean;
+    /** Wrap `text` in `role`. A no-op when colour is off, or when text is empty. */
+    paint(role: Role, text: string): string;
+    brand(text: string): string;
+    ok(text: string): string;
+    warn(text: string): string;
+    fail(text: string): string;
+    key(text: string): string;
+    /** Identity by contract: a value is never dressed. Here so call sites can say so. */
+    value(text: string): string;
+    muted(text: string): string;
+    secret(text: string): string;
+    /** One glyph, already coloured by its natural role where it has one. */
+    glyph(name: Glyph): string;
+    /** The bare glyph, uncoloured. */
+    rawGlyph(name: Glyph): string;
+    /** A section heading: the label in `key`, nothing else. */
+    heading(text: string): string;
+    /** A horizontal rule of `width` characters, in `rule`. */
+    rule(width?: number): string;
+    /** Aligned two-column rows. Column one in `key` unless the row says otherwise. */
+    table(rows: readonly TableRow[], options?: TableOptions): string;
+}
+/**
+ * One row of a two-column table.
+ *
+ * `left` is the label column and `right` the detail. `glyph` puts a coloured
+ * status mark ahead of the label (doctor's column), and `plainLeft` opts a row
+ * out of `key` styling for a left cell that is itself a copyable value.
+ */
+export interface TableRow {
+    left: string;
+    right?: string;
+    glyph?: Glyph;
+    /** Role for the glyph and, when set, nothing else. Defaults by glyph name. */
+    role?: Role;
+    plainLeft?: boolean;
+    /** Extra lines printed under the row, indented to the detail column. */
+    under?: readonly string[];
+}
+export interface TableOptions {
+    /** Spaces before every row. Default 0. */
+    indent?: number;
+    /** Spaces between the columns. Default 2. */
+    gap?: number;
+}
+/**
+ * One cell. A bare string is an UNDRESSED cell, which is the common case and
+ * the safe default: rule 3 above says a value is never painted, so a caller has
+ * to ask for a role before anything is.
+ */
+export interface Cell {
+    text: string;
+    role?: Role;
+}
+export type GridCell = string | Cell;
+/** A row, with the lines that hang beneath it when it has any. */
+export interface GridRow {
+    cells: readonly GridCell[];
+    under?: readonly string[];
+}
+export type GridInput = readonly GridCell[] | GridRow;
+export interface GridOptions {
+    /** A header row, rendered in `key` unless a cell asks for its own role. */
+    header?: readonly GridCell[];
+    /** Per-column alignment; missing entries are `left`. */
+    align?: readonly ("left" | "right")[];
+    /** Spaces before every row. Default 0. */
+    indent?: number;
+    /** Spaces between columns: one number for all, or one per boundary. */
+    gap?: number;
+    gaps?: readonly number[];
+    /** Spaces (after `indent`) before an `under` line. Default 2. */
+    underHang?: number;
+}
+/**
+ * The one aligned-columns renderer in this CLI (APRV-102).
+ *
+ * Three hand-rolled versions of this arithmetic existed — `style.table`,
+ * `execute.ts`'s queue and `hook.ts`'s classify — and they had already drifted
+ * on the question that matters: WIDTH IS MEASURED ON THE UNDRESSED TEXT.
+ * Escape sequences occupy no terminal columns, so padding computed after
+ * painting is wrong by exactly the length of the escapes and the table lines up
+ * only in a pipe. Here the cell text is padded and painted separately, so the
+ * coloured render is the plain one with escapes inserted and nothing else.
+ *
+ * Every line is `trimEnd`ed: trailing spaces are invisible in review and very
+ * visible in the diff of a pinned transcript.
+ *
+ * Returned with no trailing newline; the caller owns the stream.
+ */
+export declare function table(st: Style, rows: readonly GridInput[], options?: GridOptions): string;
+/**
+ * The one shape a refusal is printed in (APRV-91 #8/#13).
+ *
+ *     ✗ payload-mismatch  message.json does not hash to the registered hash
+ *       fix: approval payload hash message.json
+ *
+ * Glyph and machine-readable code in `fail`, message plain, and an optional
+ * repair on a second line. NEVER followed by a help page: the operator did not
+ * mistype anything, so the flags are not the answer and printing them buries
+ * the one line that is.
+ *
+ * The `fix:` LABEL is dressed and the command after it is not, which departs
+ * from the brief's "the command in `key`" on purpose. A fix line exists to be
+ * copied and run, and rule 3 (never dress a copyable value) is the rule that
+ * makes the whole palette safe to trust. The label alone carries the emphasis.
+ *
+ * Returned as text with no trailing newline, so callers keep control of the
+ * stream and of whether a blank line follows.
+ */
+export declare function refusal(style: Style, code: string, message: string, fix?: string): string;
+/**
+ * The one shape a legitimate skip is printed in (APRV-153).
+ *
+ *     – web-port  this policy declares no channels.web.port, so no queue page is served
+ *       to enable: approval policy amend
+ *
+ * The counterpart of {@link refusal} for a part that is not wrong. The fact it
+ * reports is doctor's fact (an optional part, absent by configuration), so it
+ * borrows doctor's vocabulary: the skip glyph, the check name in `warn`, the
+ * detail plain. `approval up` used to print these through {@link refusal}, and
+ * the red ✗ taught an operator that a healthy startup had failed; this shape
+ * exists to prevent that mis-reading.
+ *
+ * The second line is labelled `to enable:` rather than `fix:` because nothing
+ * is broken and there is nothing to repair; it is the path to turning the part
+ * on. Like a fix line it exists to be copied and run, so the label is dressed
+ * and the command after it is not (rule 3).
+ *
+ * Returned as text with no trailing newline, like {@link refusal}.
+ */
+export declare function skipNotice(style: Style, check: string, detail: string, enable?: string): string;
+/**
+ * The notice under a printed execution token, on a surface that is not Telegram.
+ *
+ * Three facts and an instruction, in the order a reader needs them: it works
+ * once, nothing anywhere can give it back, so the copy has to happen now.
+ */
+export declare const TOKEN_NOTICE = "single-use \u00B7 stored nowhere \u00B7 copy it now";
+/** The same, for the Telegram listener, where the extra clause is load-bearing. */
+export declare const TOKEN_NOTICE_TELEGRAM = "single-use \u00B7 stored nowhere \u00B7 not sent to Telegram \u00B7 copy it now";
+/**
+ * The execution token, in a rule-boxed panel (APRV-91's brief, APRV-102).
+ *
+ *     ─────────────────────────────────────────────────────────────
+ *       execution token   task-042:chaser
+ *       729a25b06567ccc0aed356f3423e39bf12b6252056b7890acde455603010fb11
+ *       single-use · stored nowhere · copy it now
+ *     ─────────────────────────────────────────────────────────────
+ *
+ * Trust surfaces look different from chatter: this is the one value in the whole
+ * CLI that exists for exactly as long as the terminal keeps it, so it gets a box
+ * and whitespace rather than a prefix on a line of prose.
+ *
+ * THE TOKEN LINE IS UNCOLOURED AND ALONE. Rule 3 in the header is not a
+ * preference here: a triple-click on the token must yield the token, and an
+ * escape sequence in the middle of it yields something that cannot be spent.
+ * The label carries the emphasis, the notice wears `secret` (bold yellow, never
+ * red: red is failure and this is a success), and the rules wear `rule`.
+ *
+ * One helper rather than one per surface, because `grant`, the Telegram listener
+ * and the CLI channel each print this and three copies is three chances for the
+ * one that matters to lose its warning.
+ */
+export declare function tokenPanel(st: Style, actionKey: string, token: string, notice?: string): string;
+/** Build a style. Tests use this; the CLI uses {@link style}. */
+export declare function makeStyle(input?: StyleInput): Style;
+/**
+ * The process-wide style, decided once.
+ *
+ * `json` and `noColor` are known only after a command line is parsed, so the
+ * first caller passes them and later callers get that same answer. A verb that
+ * answers in JSON therefore has to ask FIRST, which every JSON branch does by
+ * construction: it asks for the style before it prints.
+ */
+export declare function style(input?: StyleInput): Style;
+/** Forget the memoized answer. For tests, and for nothing else. */
+export declare function resetStyle(): void;
+/**
+ * The first 12 characters of a digest, for human output only.
+ *
+ * 12 hex characters is 48 bits: ample to tell two hashes in one report apart,
+ * which is the entire job here, and short enough that two of them fit on a line
+ * with their labels. The FULL value stays in `--json`, which is what anything
+ * comparing hashes should be reading. Anything that is not a 64-hex digest is
+ * returned untouched, so this is safe to apply to a field that may be null or
+ * already short.
+ */
+export declare function shortHash(hash: string): string;
+/**
+ * `path` relative to `cwd` when it is inside it, absolute otherwise.
+ *
+ * The dense-output complaint was largely this: the same 70-character absolute
+ * path three times in one report. A path INSIDE the working directory is
+ * printed relative because that is how the operator would type it. A path
+ * outside stays absolute, because `../../../etc/approval/APPROVAL.md` is worse
+ * than the truth in every way.
+ */
+export declare function relPath(path: string, cwd: string): string;
+/** One numbered step of a {@link runbook}: a command, and at most a comment. */
+export interface RunbookStep {
+    /** The runnable command, printed raw so a triple-click yields clean bytes. */
+    command: string;
+    /** A short trailing comment. Rendered after the command as `# …`. */
+    note?: string;
+}
+/** The body of a {@link runbook}, in the order a reader needs it. */
+export interface RunbookInput {
+    /**
+     * Verbatim output from whatever refused (git, gh), indented under the
+     * headline. It goes here rather than inline in the headline because a
+     * remote's four-line rejection swallowed into a sentence is the exact
+     * failure APRV-129 exists to undo.
+     */
+    quote?: readonly string[];
+    /** YOUR STATE: three or four short lines, one fact each, no commands. */
+    state: readonly string[];
+    /** NEXT STEPS: numbered, ONE runnable command per line. */
+    steps: readonly RunbookStep[];
+    /** Closing pointers: one line each, rationale compressed, no commands. */
+    footer?: readonly string[];
+}
+/**
+ * A refusal the operator has to READ AND ACT ON, rendered as a runbook
+ * (APRV-129).
+ *
+ *     ✗ push-rejected  the remote refused the push
+ *         ! [remote rejected] main -> main (protected branch hook declined)
+ *
+ *       YOUR STATE
+ *         attestation appended at seq 2
+ *         committed LOCALLY on main, NOT on origin
+ *
+ *       NEXT STEPS
+ *         1. git branch policy-amend-2
+ *         2. git push -u origin policy-amend-2
+ *
+ *       why a merge commit: … see docs/cli-reference.md
+ *
+ * The shape comes from the first live `push-rejected`, which said all of this
+ * correctly as one paragraph and was read as the single word REJECTED. The
+ * register already existed in this file (the token panel, doctor's
+ * line-per-check), and this is that register applied to recovery.
+ *
+ * ONE RUNNABLE COMMAND PER LINE is the load-bearing rule. A step is a command
+ * and at most a trailing comment, so the reader can copy down the list without
+ * parsing prose for the part that is typed. Rationale is not deleted: it is
+ * compressed into `footer` as one line plus a documentation pointer.
+ *
+ * Structure survives with styling stripped: the headings are their own words,
+ * the numbers are literal digits, and the indentation is spaces. NO_COLOR and
+ * ASCII mode lose the colour and the glyph spelling, nothing else.
+ *
+ * Returned as text with no trailing newline, like {@link refusal}.
+ */
+export declare function runbook(st: Style, code: string, headline: string, input: RunbookInput): string;
+export {};

package/dist/src/cli/token.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The token verbs: `approval token` (status) and `approval consume` (plumbing).
+ *
+ * As everywhere else in this CLI, **no logic lives here.** Minting, verification,
+ * the death conditions, and the append are all `core/token.ts`; this file
+ * resolves paths and identity, chooses an exit code, and formats output.
+ *
+ * ## `approval token` reports status; it does not print the token
+ *
+ * SPEC.md §10.1 lists `approval token <action-key>  # print single-use execution
+ * token if granted`. Under the settled hash-only design (2026-08-06) the log
+ * carries `sha256(token)` and the raw token is returned by the grant call and
+ * kept nowhere else — so there is nothing for this verb to fetch. It would have
+ * to *store* the secret to print it, which is precisely the property the design
+ * exists to avoid.
+ *
+ * The honest reading, and the one implemented here: the token is printed **by
+ * `approval grant`**, once; `approval token` answers "is a live, unspent token
+ * outstanding for this action, and what is its digest?". That interpretation is
+ * flagged in the task notes for human review — it is a reading of the spec, not
+ * a silent amendment of it, and §10.4's normative sentence (adapters MUST
+ * require a valid, unexpired, single-use token bound to the idempotency key) is
+ * unaffected either way.
+ *
+ * ## `approval consume` is internal
+ *
+ * It is the seam APRV-18's `approval run` will wrap: verify, append
+ * `execution.started`, hand control to the command. It ships now so the token
+ * boundary is testable end to end and so an adapter integration can be driven by
+ * hand, and its help text says INTERNAL in the first line.
+ *
+ * Exit codes are the frozen table, mapped exactly as the gate verbs map them: a
+ * refusal ("that token will not execute") is 1, because the command was
+ * well-formed and the answer is no; only filesystem facts are 4 and only a
+ * crashed write is 3.
+ */
+import type { Streams } from "./main.js";
+export declare function commandToken(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandConsume(argv: string[], streams: Streams, cwd: string): number;