approval-md 0.0.1 → 0.2.0

package/dist/src/cli/gate-window.js

@@ -0,0 +1,294 @@
+/**
+ * `approval gate open|close|status` — the open window's CLI (APRV-214, amended
+ * SPEC.md §5.2).
+ *
+ * As everywhere else in this CLI, no logic lives here. Deriving the window,
+ * checking the actor, the cap and the window state, and every append are
+ * `core/gate-window.ts`; this file resolves paths and identity, runs the
+ * ceremony, chooses an exit code, and formats output.
+ *
+ * ## The ceremony, and why it is shaped like this
+ *
+ * `open` suspends the harness gate's policy for every tool call under the root.
+ * Three locks stand between an agent and that, and they are independent:
+ *
+ *  1. **The class.** `approval gate open` classifies `policy.core`
+ *     (`core/command-class.ts`), which APPROVAL.md holds human-only, so the
+ *     harness hook denies the command before it ever runs.
+ *  2. **The terminal.** `createPrompter` returns `null` unless `process.stdin`
+ *     is a TTY, and a harness shell tool has no TTY. `--json` refuses for the
+ *     same reason: a machine-readable answer implies a machine asking.
+ *  3. **The word.** One line is read and only exactly `understood` proceeds.
+ *     There is deliberately NO `--yes` and no `--force`: a flag that answers
+ *     the question is a way for something that cannot type to type.
+ *
+ * `close` has none of it beyond the human actor, because closing only ever
+ * tightens, and a ceremony guarding the safe direction is one people learn to
+ * type past. `status` decides nothing and writes nothing.
+ */
+import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
+import { closeWindow, DEFAULT_WINDOW, MAX_WINDOW_MS, openGateWindow, openWindow, remainingMs, } from "../core/gate-window.js";
+import { parseDuration } from "../core/policy-load.js";
+import { readVerifiedRecords } from "../core/state.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE, } from "./exit-codes.js";
+import { GATE_WINDOW_HELP } from "./help.js";
+import { DEFAULT_LOG_PATH, resolvePath } from "./paths.js";
+import { createPrompter } from "./prompt.js";
+import { refusal as renderRefusal, style } from "./style.js";
+import { usageErrorText } from "./usage.js";
+/** The one answer that opens a window. Trimmed, never case-folded. */
+const CONFIRMATION = "understood";
+const FLAGS = {
+    "--for": "string",
+    "--reason": "string",
+    "--note": "string",
+    "--as": "string",
+    "--log": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+function usageError(streams, json, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, GATE_WINDOW_HELP));
+    return EXIT_USAGE;
+}
+/**
+ * Map a refusal onto the frozen exit table.
+ *
+ * Everything this verb DECIDED is {@link EXIT_INTEGRITY} — the command was
+ * well-formed, the runtime understood it, and the answer is no. Only facts
+ * about the filesystem are {@link EXIT_IO}, and only a crashed write is
+ * {@link EXIT_TORN_TAIL}: the same split every other verb draws.
+ */
+function refusalExitCode(refusal) {
+    switch (refusal.code) {
+        case "log-unreadable":
+            return EXIT_IO;
+        case "log-torn-tail":
+            return EXIT_TORN_TAIL;
+        case "append-failed":
+            switch (refusal.append?.code) {
+                case "corrupt-tail":
+                    return EXIT_TORN_TAIL;
+                case "io":
+                case "lock-timeout":
+                    return EXIT_IO;
+                default:
+                    return EXIT_INTEGRITY;
+            }
+        default:
+            return EXIT_INTEGRITY;
+    }
+}
+function emitRefusal(streams, json, refusal) {
+    if (json) {
+        const error = { code: refusal.code, message: refusal.message };
+        if (refusal.append !== undefined)
+            error["append"] = refusal.append.code;
+        streams.err(`${JSON.stringify({ ok: false, error })}\n`);
+    }
+    else {
+        streams.err(`${renderRefusal(style({ json }), refusal.code, refusal.message)}\n`);
+    }
+    return refusalExitCode(refusal);
+}
+function emitJson(streams, value) {
+    streams.out(`${JSON.stringify(value)}\n`);
+}
+/** A refusal built here rather than in core, in core's own shape. */
+function refuse(code, message) {
+    return { ok: false, code, message };
+}
+/** How a window is reported, in text and in `--json`, from one place. */
+function windowJson(window, now) {
+    return {
+        seq: window.seq,
+        opened_at: window.openedAt,
+        opened_by: window.openedBy,
+        reason: window.reason,
+        expires_at: window.expiresAt,
+        remaining_ms: remainingMs(window, now),
+        bypassed: window.bypassCount,
+        scope: "hook",
+    };
+}
+/** `1h 05m`, `4m 12s`: enough for a person to decide whether to close it. */
+function humanRemaining(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1_000));
+    const hours = Math.floor(seconds / 3_600);
+    const minutes = Math.floor((seconds % 3_600) / 60);
+    if (hours > 0)
+        return `${String(hours)}h ${String(minutes).padStart(2, "0")}m`;
+    return `${String(minutes)}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+// ---------------------------------------------------------------------------
+// The statement a person reads before typing
+// ---------------------------------------------------------------------------
+/**
+ * What is about to happen, in plain sentences, before one word is read.
+ *
+ * It states the consequences AND the limits, because a person who believes the
+ * window is narrower than it is will open one carelessly, and a person who
+ * believes it is wider than it is will hand-edit the hook out of the harness
+ * instead — which is the ungated, unrecorded session this whole verb exists to
+ * replace.
+ */
+function statement(root, durationText, expiresAt, reason, actor) {
+    return [
+        "approval gate open — a human-only ceremony (SPEC.md §5.2, \"The open window\")",
+        "",
+        `You are about to open the harness gate in ${root} for ${durationText}, until ${expiresAt}.`,
+        "Until it closes:",
+        "  - every hook-gated shell command and file edit an agent makes under that root is",
+        "    ALLOWED without approval, whatever APPROVAL.md says about it;",
+        "  - each one appends a `gate.bypassed` record (tool, classes, summary);",
+        "  - nothing is charged to a budget and nothing enters the retrospective sample;",
+        "  - `approval status` reports UNHEALTHY while the window is open;",
+        "  - what STAYS denied: writes aimed at .approval/log/ (`log.mutate`), every",
+        "    `human-only` class, and any command the classifier cannot read;",
+        "  - a log the hook cannot read or verify still denies.",
+        "",
+        `  reason:    ${reason}`,
+        `  opened by: ${actor}`,
+        "",
+        "Close it early with `approval gate close`. It lapses at the time above; nothing",
+        "is appended then.",
+        "",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// approval gate
+// ---------------------------------------------------------------------------
+export function commandGate(argv, streams, cwd, deps = {}) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, FLAGS);
+    if (!parsed.ok)
+        return usageError(streams, json, parsed.message);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${GATE_WINDOW_HELP}\n`);
+        return EXIT_OK;
+    }
+    const sub = parsed.positionals[0];
+    if (sub === undefined) {
+        return usageError(streams, json, "missing subcommand: open, close or status");
+    }
+    const extra = parsed.positionals[1];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`);
+    }
+    const logPath = resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, cwd);
+    switch (sub) {
+        case "open":
+            return gateOpen(parsed.flags, streams, cwd, logPath, json, deps);
+        case "close":
+            return gateClose(parsed.flags, streams, logPath, json);
+        case "status":
+            return gateStatus(streams, logPath, json);
+        default:
+            return usageError(streams, json, `unknown subcommand ${JSON.stringify(sub)}: expected open, close or status`);
+    }
+}
+function gateOpen(flags, streams, cwd, logPath, json, deps) {
+    // 1. Usage first, so a typo costs nothing and reaches no ceremony.
+    const durationText = stringFlag(flags, "--for") ?? DEFAULT_WINDOW;
+    const durationMs = parseDuration(durationText);
+    if (durationMs === null) {
+        return usageError(streams, json, `--for expects a duration like 5m, 30m, 2h, got ${JSON.stringify(durationText)}`);
+    }
+    const reasonFlag = stringFlag(flags, "--reason");
+    if (reasonFlag === null) {
+        return usageError(streams, json, "--reason is required: a bypass nobody stated a reason for is a bypass nobody can review");
+    }
+    // 2. The refusals the verb decides, in the order SPEC.md §11.2 lists them.
+    if (reasonFlag.trim().length === 0) {
+        return emitRefusal(streams, json, refuse("gate-reason-required", "--reason was empty; say what the window is for"));
+    }
+    if (durationMs > MAX_WINDOW_MS) {
+        return emitRefusal(streams, json, refuse("gate-duration-too-long", `--for ${JSON.stringify(durationText)} is longer than the 24h cap: a bypass that outlives the attention of the person who opened it is a bypass nobody is watching`));
+    }
+    const asFlag = stringFlag(flags, "--as");
+    const actor = resolveHumanActor(asFlag === null ? {} : { actor: asFlag });
+    if (actor === null) {
+        return emitRefusal(streams, json, refuse("actor-not-human", `opening the gate requires a human identity: pass --as human:<id> or set ${HUMAN_ACTOR_ENV}. This is the one act that suspends the policy, so an agent identity is refused here as well as in the log's own schema`));
+    }
+    // 3. The terminal. `--json` is refused for the same reason a pipe is: an
+    //    answer shaped for a machine implies a machine asking the question, and
+    //    what this asks for is a person's assent.
+    if (json) {
+        return emitRefusal(streams, json, refuse("gate-stdin-not-tty", "`gate open` has no --json form: it is a ceremony a person performs at a terminal, and a machine-readable answer would imply a machine asking. Run it in a terminal with no --json"));
+    }
+    const prompter = deps.prompter === undefined ? createPrompter(streams) : deps.prompter;
+    if (prompter === null) {
+        return emitRefusal(streams, json, refuse("gate-stdin-not-tty", "stdin is not a terminal, so nobody can be asked. There is deliberately no --yes and no --force: a flag that answers this question is a way for something that cannot type to type. Run it from a terminal"));
+    }
+    const expiresAt = new Date(Date.now() + durationMs).toISOString();
+    streams.out(statement(cwd, durationText, expiresAt, reasonFlag.trim(), actor));
+    const answer = prompter.readLine(`Type \`${CONFIRMATION}\` to open the window, anything else to abort: `);
+    // `null` is EOF (Ctrl-D, or the terminal going away), and it aborts like any
+    // other answer that is not the word.
+    if (answer === null || answer.trim() !== CONFIRMATION) {
+        return emitRefusal(streams, json, refuse("gate-confirmation-mismatch", `the window was not opened: the answer must be exactly \`${CONFIRMATION}\`. Nothing was appended`));
+    }
+    const result = openWindow(logPath, { durationText, durationMs, reason: reasonFlag.trim() }, actor, {});
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    streams.out(`gate OPEN at seq ${String(result.record.seq)} until ${result.window.expiresAt} (${durationText}), opened by ${actor}\n` +
+        "every gated tool call under this root is now allowed without approval and recorded as gate.bypassed;\n" +
+        "`approval status` reports unhealthy until it closes. Close it with `approval gate close`.\n");
+    return EXIT_OK;
+}
+function gateClose(flags, streams, logPath, json) {
+    const asFlag = stringFlag(flags, "--as");
+    const actor = resolveHumanActor(asFlag === null ? {} : { actor: asFlag });
+    if (actor === null) {
+        return emitRefusal(streams, json, refuse("actor-not-human", `closing the gate requires a human identity: pass --as human:<id> or set ${HUMAN_ACTOR_ENV}. The pair is one ceremony and both halves are the human's`));
+    }
+    const note = stringFlag(flags, "--note");
+    const result = closeWindow(logPath, actor, note === null ? {} : { note });
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            seq: result.record.seq,
+            opened_seq: result.closed.seq,
+            actor,
+            bypassed: result.closed.bypassCount,
+        });
+    }
+    else {
+        streams.out(`gate CLOSED at seq ${String(result.record.seq)}: the window opened at seq ${String(result.closed.seq)} by ${result.closed.openedBy} is over, after ${String(result.closed.bypassCount)} bypassed call(s)\n`);
+    }
+    return EXIT_OK;
+}
+function gateStatus(streams, logPath, json) {
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok)
+        return emitRefusal(streams, json, refuse(read.code, read.message));
+    const now = Date.now();
+    const window = openGateWindow(read.records, now);
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            open: window !== null,
+            window: window === null ? null : windowJson(window, now),
+        });
+        return EXIT_OK;
+    }
+    const st = style({ json });
+    if (window === null) {
+        streams.out(`gate: ${st.ok("closed")} — the policy decides every gated tool call\n`);
+        return EXIT_OK;
+    }
+    streams.out(`gate: ${st.warn("OPEN")} until ${window.expiresAt} (${humanRemaining(remainingMs(window, now))} left)\n` +
+        `  opened by ${window.openedBy} at seq ${String(window.seq)} (${window.openedAt})\n` +
+        `  reason:   ${window.reason}\n` +
+        `  bypassed: ${String(window.bypassCount)} call(s) so far\n` +
+        "  close it with `approval gate close`\n");
+    return EXIT_OK;
+}
+//# sourceMappingURL=gate-window.js.map

package/dist/src/cli/gate-window.js.map

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

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

@@ -0,0 +1,68 @@
+/**
+ * The gate verbs of SPEC.md §10.1: `approval register`, `approval request`,
+ * `approval grant|reject|revoke`, and `approval expire`.
+ *
+ * As everywhere else in this CLI, **no logic lives here.** State derivation,
+ * transition legality, TTL arithmetic, attestation, and budgets are all
+ * `core/gate.ts`; frontmatter reading is `core/frontmatter.ts`; the append is
+ * `core/log.ts`. This file resolves paths and identity, chooses an exit code,
+ * and formats output.
+ *
+ * Four choices are load-bearing enough to state plainly.
+ *
+ * **A gate refusal is exit 1, not exit 2.** "You may not do that" is not a
+ * usage error — the command was well-formed, the runtime understood it, and the
+ * answer is no. Grouping refusals with typos would train agents to retry with
+ * different flags when the correct response is to ask a human. Exit 2 stays what
+ * it has always been: an unknown flag, a missing argument, an unresolvable
+ * identity. The frozen `error.code` inside `--json` is what a caller branches on
+ * to tell *which* refusal it was.
+ *
+ * **The log supplies the action's declaration, not flags.** `approval request
+ * <task> --action <key>` reads the action's class, cost, reversibility and
+ * summary from the `task.registered` record in the log — the same record
+ * `approval register` wrote from the envelope. There are no `--class` /
+ * `--cost` flags, deliberately: an agent that could name its own class at
+ * request time could declare `read.web` for an action registered as
+ * `financial.spend`, and SPEC.md §7's "class MUST be declared before a token can
+ * be requested" would mean nothing. Register once from the file; request against
+ * what was registered. A task file edited after registration is `envelope.drift`
+ * (M5), not a silent re-declaration.
+ *
+ * **`register` reads task files but never writes them.** Unknown frontmatter
+ * keys are preserved trivially here because nothing is rewritten at all;
+ * round-trip rewriting is M6.
+ *
+ * **grant / reject / revoke are human-only**, via `resolveHumanActor` — `--as
+ * human:<id>` or `APPROVAL_HUMAN`, refused at exit 2 when absent or when it
+ * names an agent. `expire` takes no identity at all: it is the system verb, and
+ * `core/gate.ts` stamps `system:gate`.
+ *
+ * **This layer no longer reads the clock.** It used to pass `new Date()` into
+ * every gate call; under amended SPEC.md §8 (A2) a gate-typed event's `ts` is
+ * assigned inside core at the write boundary, and there is no parameter here to
+ * pass one through. Nothing about determinism is lost — core reads an injected
+ * clock — and one caller-supplied-timestamp seam is gone.
+ */
+import { type Decision } from "../core/gate.js";
+import type { Streams } from "./main.js";
+export declare function commandRegister(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandRequest(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandDecide(decision: Decision, argv: string[], streams: Streams, cwd: string): number;
+/**
+ * `approval withdraw <task> --action <key>` — the requester takes its own
+ * pending request back (APRV-106).
+ *
+ * Agent-facing, unlike every other terminal verb here: the whole point is that
+ * the party who asked can stop asking, and the party who asks is usually an
+ * agent. Identity resolves through {@link resolvePrincipalActor}, and the gate
+ * then checks it against the actor on the `approval.requested` record — so
+ * passing `--as` does not let a caller withdraw someone else's request, it only
+ * lets the caller say who it is.
+ *
+ * The task id is positional and the action key is a flag, matching
+ * `approval request` exactly: the two verbs are the open and the close of one
+ * gesture, and an agent that can spell one can spell the other.
+ */
+export declare function commandWithdraw(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandExpire(argv: string[], streams: Streams, cwd: string): number;