approval-md 0.0.1 → 0.2.0

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

@@ -0,0 +1,202 @@
+/**
+ * The execution verbs of SPEC.md §10.1: `approval run`, `approval wait`,
+ * `approval status`, and `approval queue`.
+ *
+ * As everywhere else in this CLI, **no logic lives here.** Authorization,
+ * budgets, loop safety, and the appends are `core/execute.ts`; state derivation
+ * is `core/gate.ts`; chain verification is `core/verify.ts`. This file splits
+ * argv, resolves paths and identity, spawns the child, chooses an exit code, and
+ * formats output.
+ *
+ * Four choices are load-bearing enough to state plainly.
+ *
+ * **`approval run` is transparent.** Its own exit code is the CHILD's exit code
+ * — a wrapper that swallowed it would break every `make`, every CI step, and
+ * every `&&` that ever wrapped a command. run's own refusals are the only thing
+ * that can produce a different code, and they all happen *before* the child is
+ * spawned: 5 when no valid token was presented, 2 for a usage error, 4 for a
+ * filesystem fact, 3 for a torn tail, 1 for any other gate refusal.
+ *
+ * **Exit 5 is new, and it is only here.** The human-settled design (2026-08-06)
+ * asked for a distinct code when `run` refuses for want of a token, and
+ * `exit-codes.ts` defines it as an addition to the frozen table rather than a
+ * redefinition of anything in it. `approval wait` likewise adds 6 for timeout.
+ * No other command emits either.
+ *
+ * **The child owns stdout.** `run` inherits stdio, so the child's output is not
+ * captured, buffered, or interleaved with ours. That leaves `--json` nowhere
+ * safe to print on stdout, so run's own JSON summary goes to **stderr** — the
+ * one place we can write without corrupting a stream the child is entitled to.
+ * This is stated in `--help` because it is the single place this CLI departs
+ * from "one JSON object on stdout".
+ *
+ * **`run` and the adapter contract are two callers of one core path.** A command
+ * is an adapter whose `act` is a spawn, whose payload is SPEC.md §6.2's `{argv,
+ * cwd}`, and whose credentials are the ambient environment.
+ * `src/adapters/contract.ts` wraps the same `startExecution` / `finishExecution`
+ * pair for adapters that are objects rather than processes; `run` calls the core
+ * verbs directly because its stdio inheritance, exit-code transparency, and `--`
+ * argv split are CLI concerns with nothing to do with adapters. What both must
+ * obey belongs in `core/execute.ts`, where both already read it; a rule added to
+ * the adapter contract alone protects adapters and not this verb.
+ *
+ * **`status` and `queue` answer different questions.** `queue` is the pending
+ * decision inbox and nothing else: requests awaiting a human, inside their TTL.
+ * `status` is system health: attestation, dangling executions, budget headroom,
+ * the latest verification, loop escalations. A dangling execution appears in
+ * `status` and never in `queue` — nobody is being asked to decide it, and
+ * putting operational debris in a human's approval inbox is how inboxes get
+ * ignored.
+ */
+import { type ExecuteRefusal } from "../core/execute.js";
+import { type Prompter } from "./prompt.js";
+import type { Streams } from "./main.js";
+import { type Style } from "./style.js";
+/**
+ * Map an execution refusal onto the exit table.
+ *
+ * `token-required` is the one addition: exit 5, and only `run` can produce it.
+ * Everything else follows the split the gate and token verbs already draw —
+ * filesystem facts are 4, a crashed write is 3, and every decision the runtime
+ * itself made is 1.
+ *
+ * Exported because `approval adapter` (APRV-69) is the second caller of the core
+ * execution path and must map its refusals identically. Two copies of this
+ * switch would drift the first time a code was added, and an agent's retry logic
+ * keys on the difference between 5 and 1.
+ */
+export declare function executeRefusalExitCode(refusal: ExecuteRefusal): number;
+/**
+ * Where the child's stdio goes.
+ *
+ * The default is the CLI's own behaviour and the one the module header
+ * describes: `inherit`, so the child owns the terminal and `run` is transparent.
+ * It is an option only because a caller can exist whose own stdout is not a
+ * terminal but a protocol — the MCP wrapper of SPEC.md §10.5 speaks JSON-RPC on
+ * fd 1, and a child that inherited it would write into the wire. Such a caller
+ * pipes instead and receives what the child said through {@link onOutput}.
+ *
+ * This is a seam, not a second implementation: everything before and after the
+ * spawn — the identity check, the payload binding, `execution.started`, the exit
+ * code, `execution.completed` / `execution.failed` — is the one path, and no
+ * caller can reach it without going through all of it.
+ */
+export interface RunChildIo {
+    /** Passed straight to `spawnSync`. Default `"inherit"`. */
+    readonly stdio: "inherit" | ["ignore", "pipe", "pipe"];
+    /** Called with the child's captured output when {@link stdio} pipes it. */
+    readonly onOutput?: (captured: {
+        stdout: string;
+        stderr: string;
+    }) => void;
+}
+export declare function commandRun(argv: string[], streams: Streams, cwd: string, childIo?: RunChildIo): number;
+interface WaitedAction {
+    action_key: string;
+    state: string;
+    seq: number | null;
+    /**
+     * The raw execution token, when sealed delivery put one within this process's
+     * reach (APRV-105). Present ONLY in `--json`: the human render is a terminal,
+     * and a token printed there is the paste this feature exists to remove.
+     * Absent under the default `token_delivery: manual`, absent on a machine that
+     * did not open the request, and absent once the token has been spent.
+     */
+    token?: string;
+}
+/**
+ * `approval wait`'s human answer: the verdict, then one aligned row per action.
+ *
+ * Action keys are copyable, so the left column opts out of `key` styling
+ * (`plainLeft`) and the state beside it carries the colour instead.
+ */
+export declare function renderWaitHuman(task: string, status: string, actions: readonly WaitedAction[], st?: Style): string;
+export declare function commandWait(argv: string[], streams: Streams, cwd: string): number;
+interface QueueEntry {
+    action_key: string;
+    task: string | null;
+    class: string | null;
+    /** Canonical decimal USD string (APRV-121), as the record spells it. */
+    est_cost_usd: string | null;
+    requested_ts: string | null;
+    seq: number | null;
+    /** Milliseconds until the TTL lapses, or `null` when the policy sets none. */
+    ttl_remaining_ms: number | null;
+}
+/**
+ * The live inbox as an aligned table (APRV-91 #9).
+ *
+ * The old shape was tab-separated, which lines up only when every field happens
+ * to be the same width, and a queue's fields never are. The alignment is
+ * `style.table`'s (APRV-102 replaced a hand-rolled copy of it here), so widths
+ * are measured on the UNDRESSED cells and the coloured render is the plain one
+ * with escapes inserted.
+ *
+ * The TTL is the only dressed cell. The request timestamp was `muted` until
+ * APRV-102 and is not any more: a timestamp is a value an operator copies into
+ * a `grep` or a bug report, and rule 3 of `style.ts` does not have a "but this
+ * one is only dim" exception.
+ */
+export declare function renderQueueHuman(pending: readonly QueueEntry[], ttlMs: number | null, st?: Style): string;
+export declare function commandQueue(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandStatus(argv: string[], streams: Streams, cwd: string): number;
+/**
+ * Injected seams for `execution resolve`. `prompter` is the terminal, exactly
+ * as `gate open`'s is: a test passes a scripted one and asserts on what was
+ * asked as well as on what was done, and passing `null` is how "there is no
+ * terminal" becomes a test rather than a claim.
+ */
+export interface ResolveDeps {
+    prompter?: Prompter | null;
+}
+/**
+ * `approval execution resolve <action-key> --outcome completed|failed --note …`
+ *
+ * The human recovery verb for a dangling execution: the runtime died between
+ * `execution.started` and its outcome, `approval status` has been reporting the
+ * gap ever since, and a person went and looked. This records what they saw.
+ *
+ * Three rules, enforced here as usage errors before core is called at all, so
+ * the log is untouched by a malformed invocation:
+ *
+ * - `--outcome` is `completed` or `failed`. Nothing is inferred.
+ * - `--note` is MANDATORY and non-empty. The event's whole value is the
+ *   observation behind it.
+ * - The actor must be a human (`--as human:<id>` or `APPROVAL_HUMAN`). An agent
+ *   closing its own dangling execution is the executing party reporting on
+ *   itself.
+ *
+ * No attestation is required, and the help text says why: resolve records a
+ * fact a human observed; it exercises no policy authority, so it does not
+ * require an attested policy.
+ *
+ * `--dangling` is the bulk form of the same verb ({@link resolveDangling}): the
+ * whole list, one confirmation, one record per key the checkout can prove.
+ */
+export declare function commandResolve(argv: string[], streams: Streams, cwd: string, deps?: ResolveDeps): number;
+/**
+ * `approval execution reconcile <action-key> --resolution executed|not-executed
+ * --note …`
+ *
+ * The human resolution of an INDETERMINATE execution (APRV-120): the side
+ * effect was attempted, the runtime could not tell whether it committed, and a
+ * person went and looked at the far side.
+ *
+ * It is a separate verb from `resolve` rather than a third `--outcome` value,
+ * because the two answer different questions from different evidence. `resolve`
+ * asks "what did our runtime do?" and is answered from this machine. This asks
+ * "did the provider commit?" and is answered from the provider's own console,
+ * inbox or ledger. An operator who reached for the wrong one is told so
+ * (`not-indeterminate`, `already-finished`) rather than quietly writing the
+ * wrong record into an append-only log.
+ *
+ * The same three rules `resolve` enforces, enforced here before core is called:
+ * the resolution is one of two closed values and nothing is inferred, the note
+ * is mandatory and non-empty because it is the evidence, and the actor must be
+ * a human — the daemon never auto-resolves, and an agent reconciling its own
+ * unknown outcome is the executing party reporting on itself.
+ */
+export declare function commandReconcile(argv: string[], streams: Streams, cwd: string): number;
+/** `approval execution <subcommand>`: `resolve` and `reconcile`. */
+export declare function commandExecution(argv: string[], streams: Streams, cwd: string, deps?: ResolveDeps): number;
+export {};