approval-md 0.0.1 → 0.2.0

package/dist/src/cli/style.js

@@ -0,0 +1,469 @@
+/**
+ * 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 single escape byte every sequence below starts with. */
+const ESC = "\u001b";
+/**
+ * Role to SGR parameters. `value` is empty on purpose: the role exists so a
+ * caller can SAY "this is a value" at the call site, and the answer is that a
+ * value is never dressed (rule 3 above).
+ */
+const SGR = {
+    brand: "1;38;5;111",
+    ok: "32",
+    warn: "33",
+    fail: "1;31",
+    key: "1",
+    value: "",
+    muted: "2",
+    rule: "2",
+    secret: "1;33",
+};
+/** The glyph vocabulary, and its ASCII degradation. */
+const GLYPHS = {
+    ok: ["✓", "[ok]"],
+    fail: ["✗", "[x]"],
+    skip: ["–", "[-]"],
+    point: ["▸", ">"],
+    bar: ["│", "|"],
+    rule: ["─", "-"],
+};
+/** How many characters of a 64-hex digest a human is shown. */
+export const SHORT_HASH_LENGTH = 12;
+/** The natural role of each glyph, so `glyph("ok")` is green without asking. */
+const GLYPH_ROLE = {
+    ok: "ok",
+    fail: "fail",
+    skip: "warn",
+    point: "secret",
+    bar: "rule",
+    rule: "rule",
+};
+/**
+ * The enable matrix, in precedence order.
+ *
+ * `json` first because it is frozen API (see the header). Then the explicit
+ * flag, then FORCE_COLOR (the escape hatch for CI that renders ANSI), then
+ * NO_COLOR and TERM=dumb, and only then the question of what stdout is.
+ */
+function colourEnabled(input, env) {
+    if (input.json === true)
+        return false;
+    if (input.noColor === true)
+        return false;
+    if (forcedColour(env))
+        return true;
+    const noColor = env["NO_COLOR"];
+    if (noColor !== undefined && noColor !== "")
+        return false;
+    if (env["TERM"] === "dumb")
+        return false;
+    return input.tty ?? process.stdout.isTTY === true;
+}
+/**
+ * Whether FORCE_COLOR says yes (APRV-102).
+ *
+ * The convention every other tool honours is that FORCE_COLOR is a LEVEL, not a
+ * boolean: `1`, `2` and `3` all mean "colour, at this depth", `true` is common
+ * in CI configuration, and only `0` (and, in some tools, `false`) means off. The
+ * literal `=== "1"` this replaced meant `FORCE_COLOR=2` in a CI job silently
+ * fell through to the TTY question and produced a plain log, which is precisely
+ * the case the escape hatch exists for. Depth itself is not modelled: this
+ * palette is one 256-colour parameter and eight basic ones.
+ */
+function forcedColour(env) {
+    const forced = env["FORCE_COLOR"];
+    if (forced === undefined || forced === "")
+        return false;
+    const normalized = forced.toLowerCase();
+    return normalized !== "0" && normalized !== "false";
+}
+/**
+ * Whether glyphs degrade to ASCII.
+ *
+ * An UNSET locale is treated as UTF-8 capable. That is the deliberate choice:
+ * a bare `env -i node cli.js` and every test runner would otherwise flip the
+ * glyph column to `[ok]`, changing bytes that are pinned all over the suite for
+ * a terminal that is almost certainly fine. Degrade when the locale is SET and
+ * says something other than UTF-8, or when asked directly.
+ */
+function asciiOnly(env) {
+    if (env["APPROVAL_ASCII"] === "1")
+        return true;
+    const locale = env["LC_ALL"] ?? env["LANG"];
+    if (locale === undefined || locale === "")
+        return false;
+    return !/utf-?8/iu.test(locale);
+}
+class TerminalStyle {
+    enabled;
+    ascii;
+    constructor(enabled, ascii) {
+        this.enabled = enabled;
+        this.ascii = ascii;
+    }
+    paint(role, text) {
+        const code = SGR[role];
+        if (!this.enabled || code === "" || text === "")
+            return text;
+        return `${ESC}[${code}m${text}${ESC}[0m`;
+    }
+    brand(text) {
+        return this.paint("brand", text);
+    }
+    ok(text) {
+        return this.paint("ok", text);
+    }
+    warn(text) {
+        return this.paint("warn", text);
+    }
+    fail(text) {
+        return this.paint("fail", text);
+    }
+    key(text) {
+        return this.paint("key", text);
+    }
+    value(text) {
+        return text;
+    }
+    muted(text) {
+        return this.paint("muted", text);
+    }
+    secret(text) {
+        return this.paint("secret", text);
+    }
+    rawGlyph(name) {
+        return GLYPHS[name][this.ascii ? 1 : 0];
+    }
+    glyph(name) {
+        return this.paint(GLYPH_ROLE[name], this.rawGlyph(name));
+    }
+    heading(text) {
+        return this.key(text);
+    }
+    rule(width = 61) {
+        return this.paint("rule", this.rawGlyph("rule").repeat(Math.max(0, width)));
+    }
+    table(rows, options = {}) {
+        // The two-column shape is the n-column one with a glyph column in front:
+        // one alignment engine, so a change to how width is measured cannot reach
+        // only half of the CLI's tables (APRV-102).
+        const glyphed = rows.some((row) => row.glyph !== undefined);
+        const gap = options.gap ?? 2;
+        const markWidth = Math.max(0, ...rows.map((row) => (row.glyph === undefined ? 0 : this.rawGlyph(row.glyph).length)));
+        const grid = rows.map((row) => ({
+            cells: [
+                ...(glyphed
+                    ? [
+                        row.glyph === undefined
+                            ? ""
+                            : { text: this.rawGlyph(row.glyph), role: row.role ?? GLYPH_ROLE[row.glyph] },
+                    ]
+                    : []),
+                row.plainLeft === true ? row.left : { text: row.left, role: "key" },
+                row.right ?? "",
+            ],
+            ...(row.under === undefined ? {} : { under: row.under }),
+        }));
+        return table(this, grid, {
+            indent: options.indent ?? 0,
+            // A single space after the glyph, `gap` after the label: the glyph is a
+            // mark ON the row rather than a column of its own.
+            gaps: glyphed ? [1, gap] : [gap],
+            underHang: glyphed ? markWidth + 3 : 2,
+        });
+    }
+}
+function cellOf(cell) {
+    return typeof cell === "string" ? { text: cell } : cell;
+}
+function rowOf(row) {
+    return Array.isArray(row) ? { cells: row } : row;
+}
+/**
+ * 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 function table(st, rows, options = {}) {
+    const indent = " ".repeat(options.indent ?? 0);
+    const defaultGap = options.gap ?? 2;
+    const gapAt = (boundary) => " ".repeat(options.gaps?.[boundary] ?? defaultGap);
+    const header = options.header === undefined
+        ? null
+        : options.header.map((cell) => {
+            const normalized = cellOf(cell);
+            return { text: normalized.text, role: normalized.role ?? "key" };
+        });
+    const body = rows.map(rowOf);
+    const all = [...(header === null ? [] : [{ cells: header }]), ...body];
+    const columns = Math.max(0, ...all.map((row) => row.cells.length));
+    const widths = [];
+    for (let column = 0; column < columns; column += 1) {
+        widths.push(Math.max(0, ...all.map((row) => cellOf(row.cells[column] ?? "").text.length)));
+    }
+    const renderRow = (cells) => {
+        let line = indent;
+        for (let column = 0; column < columns; column += 1) {
+            const { text, role } = cellOf(cells[column] ?? "");
+            const pad = " ".repeat(Math.max(0, (widths[column] ?? 0) - text.length));
+            const painted = role === undefined ? text : st.paint(role, text);
+            const right = (options.align?.[column] ?? "left") === "right";
+            line += right ? `${pad}${painted}` : `${painted}${pad}`;
+            if (column < columns - 1)
+                line += gapAt(column);
+        }
+        return line.trimEnd();
+    };
+    const out = [];
+    if (header !== null)
+        out.push(renderRow(header));
+    const hang = " ".repeat(options.underHang ?? 2);
+    for (const row of body) {
+        out.push(renderRow(row.cells));
+        for (const extra of row.under ?? [])
+            out.push(`${indent}${hang}${extra}`.trimEnd());
+    }
+    return out.join("\n");
+}
+/**
+ * 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 function refusal(style, code, message, fix) {
+    const head = `${style.glyph("fail")} ${style.fail(code)}  ${message}`;
+    return fix === undefined ? head : `${head}\n  ${style.key("fix:")} ${fix}`;
+}
+/**
+ * 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 function skipNotice(style, check, detail, enable) {
+    const head = `${style.glyph("skip")} ${style.warn(check)}  ${detail}`;
+    return enable === undefined ? head : `${head}\n  ${style.key("to enable:")} ${enable}`;
+}
+/**
+ * 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 const TOKEN_NOTICE = "single-use · stored nowhere · copy it now";
+/** The same, for the Telegram listener, where the extra clause is load-bearing. */
+export const TOKEN_NOTICE_TELEGRAM = "single-use · stored nowhere · not sent to Telegram · copy it now";
+/** How wide the rules around a token panel are drawn. */
+const PANEL_WIDTH = 61;
+/**
+ * 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 function tokenPanel(st, actionKey, token, notice = TOKEN_NOTICE) {
+    const bar = st.rule(PANEL_WIDTH);
+    return [
+        bar,
+        `  ${st.key("execution token")}   ${actionKey}`,
+        `  ${token}`,
+        `  ${st.secret(notice)}`,
+        bar,
+    ].join("\n");
+}
+/** Build a style. Tests use this; the CLI uses {@link style}. */
+export function makeStyle(input = {}) {
+    const env = input.env ?? process.env;
+    return new TerminalStyle(colourEnabled(input, env), asciiOnly(env));
+}
+let processStyle = null;
+/**
+ * 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 function style(input = {}) {
+    processStyle ??= makeStyle(input);
+    return processStyle;
+}
+/** Forget the memoized answer. For tests, and for nothing else. */
+export function resetStyle() {
+    processStyle = null;
+}
+/**
+ * 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 function shortHash(hash) {
+    return /^[0-9a-f]{64}$/iu.test(hash) ? hash.slice(0, SHORT_HASH_LENGTH) : hash;
+}
+/**
+ * `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 function relPath(path, cwd) {
+    if (path === "" || cwd === "")
+        return path;
+    const base = cwd.endsWith("/") ? cwd : `${cwd}/`;
+    if (path === cwd)
+        return ".";
+    return path.startsWith(base) ? path.slice(base.length) : path;
+}
+/** How far the body of a runbook is indented under its headline. */
+const RUNBOOK_INDENT = "    ";
+/**
+ * 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 function runbook(st, code, headline, input) {
+    const out = [`${st.glyph("fail")} ${st.fail(code)}  ${headline}`];
+    for (const line of input.quote ?? [])
+        out.push(`${RUNBOOK_INDENT}${st.muted(line)}`);
+    const block = (heading, lines) => {
+        if (lines.length === 0)
+            return;
+        out.push("", `  ${st.key(heading)}`);
+        for (const line of lines)
+            out.push(`${RUNBOOK_INDENT}${line}`);
+    };
+    block("YOUR STATE", input.state);
+    block("NEXT STEPS", input.steps.map((step, index) => {
+        // The command is never dressed (rule 3): it is what gets copied.
+        const note = step.note === undefined ? "" : `  ${st.muted(`# ${step.note}`)}`;
+        return `${index + 1}. ${step.command}${note}`;
+    }));
+    const footer = input.footer ?? [];
+    if (footer.length > 0) {
+        out.push("");
+        for (const line of footer)
+            out.push(`  ${line}`);
+    }
+    return out.join("\n");
+}
+//# sourceMappingURL=style.js.map

package/dist/src/cli/style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.js","sourceRoot":"","sources":["../../../src/cli/style.ts"],"names":[],"mappings":"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"}

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;