approval-md 0.0.1 → 0.2.0

package/dist/src/cli/long-help.js

@@ -0,0 +1,148 @@
+/**
+ * `--help --long`: the short help plus the reasoning behind it (APRV-91 #16).
+ *
+ * APRV-91 split every per-verb help in two. What is left in `src/cli/help.ts`
+ * is the SHORT form, capped at 25 lines: usage, one paragraph of intent, the
+ * flags, a footer. The prose that used to sit under it — the threat models, the
+ * design points that surprise people, the alternatives that were rejected — was
+ * MOVED to `docs/cli-reference.md`, and every short help ends with the anchor it
+ * was moved to. This module is the other half of that bargain: `--long` follows
+ * the anchor and prints the section inline, so the reader who wants the
+ * reasoning never has to leave the terminal to find it.
+ *
+ * WHERE THE LONG FORM COMES FROM, and why it is not a constant.
+ *
+ * The alternatives were to keep a `*_LONG_HELP` constant beside every short one,
+ * to generate an embedded module from the docs at build time, or to read the
+ * docs file at runtime. Constants lose immediately: the same prose would exist
+ * twice, in the help module and in the reference a `why:` footer points at, and
+ * two copies of grandfathered prose drift the first time someone edits one.
+ * Build-time embedding fixes the drift but buys a generated file, a codegen
+ * step and a staleness guard to protect a file the package already ships.
+ *
+ * So: read `docs/cli-reference.md` at runtime, and SHIP IT. `package.json`
+ * `files` now names it, and the path below resolves the same way in the repo
+ * (`dist/src/cli/` to the root) and in an installed package, because the
+ * published layout keeps that relationship. There is exactly one copy of the
+ * prose and it is the one a reader on GitHub sees.
+ *
+ * The failure mode is handled rather than thrown: a missing or unreadable
+ * reference makes `--long` print the short help and a plain line saying where
+ * the prose should have been. `--long` is a documentation flag, and a
+ * documentation flag that exits non-zero because a doc file moved would be a
+ * worse bug than the missing prose.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as help from "./help.js";
+import { style as processStyle } from "./style.js";
+import { verbOf } from "./usage.js";
+/** The shipped reference, relative to this module's compiled location. */
+const REFERENCE_PATH = fileURLToPath(new URL("../../../docs/cli-reference.md", import.meta.url));
+/** Every exported help constant, in declaration order. */
+function helpConstants() {
+    return Object.entries(help).filter((entry) => typeof entry[1] === "string" && entry[0].endsWith("_HELP"));
+}
+/**
+ * The help text for a command line, by longest matching title line.
+ *
+ * The mapping is DERIVED rather than declared: every help constant opens with
+ * `approval <verb path> — …`, which `verbOf` already parses for the usage-error
+ * pointer. Longest match wins, so `log tail` finds TAIL_HELP rather than
+ * LOG_HELP. A declared table would be a second list of verbs to forget to
+ * update; this one cannot fall out of step with the constants it indexes.
+ */
+export function helpFor(words) {
+    const line = ["approval", ...words].join(" ");
+    let best = null;
+    let bestLength = -1;
+    for (const [, text] of helpConstants()) {
+        const verb = verbOf(text);
+        // The root's own title is the bare word `approval`, which prefix-matches
+        // every command line there is. It is the caller's explicit fallback, never
+        // a match, or `approval frobnicate --help --long` would answer confidently.
+        if (verb === "approval")
+            continue;
+        if (verb.length <= bestLength)
+            continue;
+        if (line === verb || line.startsWith(`${verb} `)) {
+            best = text;
+            bestLength = verb.length;
+        }
+    }
+    return best;
+}
+/** The `why: docs/cli-reference.md#anchor` footer's anchor, when there is one. */
+export function anchorOf(helpText) {
+    const match = /why: docs\/cli-reference\.md#([a-z0-9-]+)/u.exec(helpText);
+    return match?.[1] ?? null;
+}
+/** GitHub's anchor rule: lowercase, drop punctuation, spaces to dashes. */
+function anchorize(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^a-z0-9 -]/gu, "")
+        .replace(/ /gu, "-");
+}
+/**
+ * The body of the section `anchor` names, headings included, trimmed.
+ *
+ * A section runs to the next heading AT THE SAME LEVEL OR SHALLOWER, so a `##`
+ * section keeps its own `###` subsections and a `###` section stops at its
+ * sibling. That is what makes one anchor able to carry a whole verb family.
+ */
+export function referenceSection(anchor, markdown) {
+    const lines = markdown.split("\n");
+    let start = -1;
+    let depth = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = /^(#{2,})\s+(.+?)\s*$/u.exec(lines[index] ?? "");
+        if (match === null)
+            continue;
+        if (start === -1) {
+            if (anchorize(match[2] ?? "") !== anchor)
+                continue;
+            start = index;
+            depth = (match[1] ?? "").length;
+            continue;
+        }
+        if ((match[1] ?? "").length <= depth) {
+            return lines.slice(start, index).join("\n").trim();
+        }
+    }
+    return start === -1 ? null : lines.slice(start).join("\n").trim();
+}
+/** Read the shipped reference, or null when it is not there. */
+export function readReference(path = REFERENCE_PATH) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The whole `--help --long` output: the short help, a rule, and the reasoning.
+ *
+ * The short form is printed VERBATIM and first. `--long` is additive by
+ * definition: an operator who has learned to read the short help must not have
+ * to re-find their bearings in a different layout because they asked for more.
+ */
+export function longHelp(helpText, options = {}) {
+    const style = options.style ?? processStyle();
+    const anchor = anchorOf(helpText);
+    const markdown = options.reference === undefined ? readReference() : options.reference;
+    if (anchor === null) {
+        return `${helpText}\n\n${style.muted("(no extended reference for this command)")}`;
+    }
+    const where = `docs/cli-reference.md#${anchor}`;
+    if (markdown === null) {
+        return `${helpText}\n\n${style.muted(`(the reference is not installed; see ${where})`)}`;
+    }
+    const section = referenceSection(anchor, markdown);
+    if (section === null) {
+        return `${helpText}\n\n${style.muted(`(no section ${where})`)}`;
+    }
+    return [helpText, "", style.rule(), style.heading(`Why — ${where}`), "", section].join("\n");
+}
+//# sourceMappingURL=long-help.js.map

package/dist/src/cli/long-help.js.map

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

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

@@ -0,0 +1,77 @@
+/**
+ * `approval` CLI entry point — the commands of SPEC.md §10.1: the log-facing
+ * `approval log verify | tail | export` and `approval reindex`, the policy
+ * verbs, and the gate verbs `register`, `request`, `grant`, `reject`, `revoke`,
+ * and `expire`.
+ *
+ * **The CLI holds no logic.** Chain verification lives in `core/verify.ts`, the
+ * projection in `core/reindex.ts`, and appends in `core/log.ts`. Everything
+ * here is argument parsing, path resolution, output formatting, and the mapping
+ * from a core result to an exit code. That boundary is deliberate: the rules
+ * about what counts as a clean log must have exactly one implementation, and it
+ * is not this one.
+ *
+ * **Two things are frozen public API**, because agents depend on them
+ * mechanically: the exit codes (see `exit-codes.ts`) and the `--json` shapes
+ * (documented in every `--help`). Both are pinned by tests.
+ *
+ * **I/O is not integrity.** `verify()` cannot tell an unreadable log from a
+ * broken one, so this layer stats and access-checks the path *first* and
+ * reports filesystem problems as {@link EXIT_IO} with a message that never uses
+ * the word "corrupt". Absent files are exempt: an empty log is clean.
+ *
+ * Nothing in this file writes to the log, and no command repairs a torn tail.
+ * The gate verbs do append — through `core/gate.ts`, which appends through
+ * `core/log.ts` — and their exit-code mapping lives in `gate.ts` beside them: a
+ * gate refusal is {@link EXIT_INTEGRITY}, because the command was well-formed
+ * and the runtime's answer was no.
+ */
+import { type Style } from "./style.js";
+/** Output sinks, injectable so the command layer stays testable in-process. */
+export interface Streams {
+    out(text: string): void;
+    err(text: string): void;
+}
+export interface MainOptions {
+    cwd?: string;
+    streams?: Streams;
+}
+/**
+ * `approval log tail`'s human rendering (APRV-91 #9, APRV-102).
+ *
+ * TWO SHAPES, DELIBERATELY, and the piped one is unchanged.
+ *
+ * In a pipe (and under `NO_COLOR`) this is exactly what it always was:
+ * tab-separated fields, one record per line. That shape is pinned by
+ * `tests/cli.test.ts`, printed in three `examples/*.md` transcripts, and — the
+ * reason that matters more than either — it is what `cut -f2` reads. An aligned
+ * table is a nicer thing to look at and a worse thing to pipe, because the
+ * separator stops being a character and starts being "however many spaces this
+ * particular log needed". A log tail is the surface most likely to be on the
+ * left of a pipe, so the plain bytes win there.
+ *
+ * On a terminal, where nothing is parsing the output, the columns are aligned
+ * and the brief's roles apply: the seq right-aligned so the digits line up,
+ * the event name in `key`, and the actor coloured by kind (human `ok`, agent
+ * undressed, system `muted`). Colour is redundant with the actor prefix printed
+ * beside it, as everywhere. The TIMESTAMP is left undressed against the brief's
+ * `muted`: APRV-102's rule that a copyable value is never painted outranks it,
+ * and this is the surface an operator lifts timestamps out of.
+ *
+ * Both shapes carry the same fields in the same order, so this is a change of
+ * spacing and dressing, never of content.
+ */
+export declare function renderTailHuman(records: readonly unknown[], st?: Style): string;
+/**
+ * Run the CLI. Resolves to the process exit code rather than calling
+ * `process.exit`, so buffered stdout is flushed by the normal exit path — a
+ * truncated JSON object would be worse than no output at all.
+ *
+ * ASYNCHRONOUS since APRV-209, and for one reason: every verb is loaded by
+ * `await import()` inside the switch below, and ESM has no synchronous dynamic
+ * import. The awaits do not make any verb concurrent — exactly one runs per
+ * invocation, the preamble still decides presentation once before any of them
+ * can print, and the long-lived verbs (`channel`, `daemon`, `up`, `mcp`) report
+ * their eventual code through `process.exitCode` exactly as they did.
+ */
+export declare function main(argv: string[], options?: MainOptions): Promise<number>;