approval-md 0.0.1 → 0.2.0

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 {};