@jevitate/cli 0.28.0 → 0.29.0

package/dist/terminal-result.d.ts

@@ -0,0 +1,181 @@
+import { type MissionOutcome } from "@jevitate/domain";
+import { type EngineInfo } from "./engine.js";
+import { type RunMetadata } from "./run-metadata.js";
+/**
+ * The shared terminal result of a long-running command: however the command ends, it ends with a
+ * machine-readable result. A command registers once (`registerTerminalResult`), reports progress as
+ * it goes, and calls `complete()` when it has emitted its own result. If it ends any other way, this
+ * layer writes a redacted diagnostic artifact, prints one envelope and exits:
+ *
+ *  | trigger        | code                   | exit                                                  |
+ *  |----------------|------------------------|-------------------------------------------------------|
+ *  | signal         | E_TERMINAL_SIGNAL      | 129/130/143, by the kill switch (kill-signal.ts)      |
+ *  | parent gone    | E_TERMINAL_PARENT_GONE | 129, by the kill switch; no signal was sent           |
+ *  | inactivity     | E_TERMINAL_WATCHDOG    | 2 (inconclusive: it proves nothing)                   |
+ *  | `fail(err)`    | E_TERMINAL_INTERNAL    | 2 (crashed)                                           |
+ *  | uncaught error | E_TERMINAL_INTERNAL    | 2 (crashed; an unhandled rejection arrives this way)  |
+ *  | process exit   | E_TERMINAL_UNSETTLED   | 2 (a `process.exit` or a drained event loop, no result) |
+ *
+ * Exactly once: the first trigger wins and every later one is a no-op. An uncaught error after
+ * `complete()` is no trigger, since the result is already out: one redacted stderr report, then an
+ * exit that keeps the code the command set.
+ *
+ * What cannot be handled in process (SIGKILL, a caller's limit that kills the whole group) leaves
+ * only what was already printed, so each `progress()` also prints one short redacted line to stderr.
+ * stdout stays exactly one envelope. A stderr that stops accepting them only ends the printing.
+ *
+ * A broken output pipe never decides a result: see `installBrokenPipePolicy`.
+ *
+ * Inside an MCP tool call (`mcp-cli-runner.ts`) the process is the shared server and fd 1 is the MCP
+ * protocol channel, so this layer stays out: nothing is printed, nothing is armed, and nothing
+ * exits. The tool's result is still the command's own captured envelope. `fail` rethrows there, and
+ * the runner turns that into its own `E_CLI_INTERNAL` result.
+ *
+ * SYNCHRONOUS BY CONTRACT. Everything from a trigger to the exit runs in one turn and never yields
+ * the event loop, for the reason `onKillSignal` documents: Playwright's own signal handler closes
+ * the browsers, in-flight page operations start rejecting, and the command's own error handling can
+ * otherwise win the race to `process.exit` with another result. So artifact and output writes are
+ * `writeFileSync`/`writeSync` only. `process.stdout.write` is not safe here: on a pipe it can queue,
+ * and an exit in the same turn loses what is queued. The envelope therefore goes through
+ * `emitCommandResult` on a program whose writers are synchronous. `progress` and `addSecrets` are
+ * synchronous for the same reason: the trigger only reads what was already reported.
+ *
+ * Limit: the watchdog and the signal handler both run on the event loop, so a synchronous spin
+ * delays them until it returns.
+ */
+/**
+ * Where the command is now: what a progress line and a diagnostic name. All text is redacted before
+ * use. An update merges into what was reported, so pass `undefined` to clear a field that no longer
+ * applies (the mutation, once the replay under it has finished).
+ */
+export interface TerminalProgress {
+    readonly phase?: string | undefined;
+    readonly replay?: number | string | undefined;
+    readonly mutation?: string | undefined;
+    readonly step?: number | string | undefined;
+    /** Carried in the diagnostic only, never in a progress line. */
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+}
+export interface TerminalResultRegistration {
+    /** The command, named in the diagnostic and in a usage hint (e.g. `journey verify`, `verify-fix`). */
+    readonly command: string;
+    /** `--json` was passed: the envelope on stdout; otherwise the `error <CODE>: …` line on stderr. */
+    readonly json: boolean;
+    /** Values masked from all text, in each of their URL forms. Add later ones with `addSecrets`. */
+    readonly secrets: readonly string[];
+    /**
+     * The command's identity path. The result goes to `resultPathFor(artifactPath)` (`<stem>.result.json`),
+     * through `writeMissionResult`, and never to `artifactPath` itself, so a kill cannot replace an
+     * earlier proof stored there. Absent: the envelope is the only result.
+     */
+    readonly artifactPath?: string;
+    /**
+     * The longest the command may go without calling `progress()`, in milliseconds: a positive integer
+     * a timer can represent. Each `progress()` starts this limit again, so it does not bound the whole
+     * run: legal runs range from seconds to over 100 minutes (#778).
+     *
+     * Derive it from what one uninterrupted stretch can legally take, not from a typical run. If
+     * `progress()` is called per replay, it must cover the 300 s machine-slot admission bound
+     * (`DEFAULT_ADMISSION_TIMEOUT_MS`) plus the longest legal single replay of this command's plan,
+     * since both can fall between two calls.
+     */
+    readonly inactivityMs: number;
+    /** The progress known at registration. */
+    readonly progress?: TerminalProgress;
+}
+export interface TerminalResultHandle {
+    /**
+     * Merges what the command knows now into the progress a diagnostic reports, prints one redacted line
+     * to stderr, and starts `inactivityMs` again. A no-op once the command has settled. Synchronous;
+     * never throws.
+     */
+    progress(update: TerminalProgress): void;
+    /** Adds secrets learned during the run (a resolved auth token), so a later trigger masks them too. Synchronous; never throws. */
+    addSecrets(values: readonly string[]): void;
+    /**
+     * An internal error: reports it, then exits. A no-op once the command has settled. Inside an MCP
+     * tool call it throws the redacted error instead, so call it where a throw reaches the command's
+     * caller (a `catch` that ends the action).
+     */
+    fail(err: unknown): void;
+    /**
+     * The command has emitted its own result: nothing more is reported. Call it in the same synchronous
+     * turn as that emit, with no `await` between them. A command that never calls it reports
+     * E_TERMINAL_UNSETTLED at exit.
+     */
+    complete(): void;
+}
+/** The seams a test fakes. Every one of them must be synchronous (see this module's doc). */
+export interface TerminalResultDeps {
+    readonly exit: (code: number) => void;
+    /** Ends only the browsers this process launched (`terminateOwnBrowsersSync`), and nothing else. */
+    readonly terminateBrowsers: () => void;
+    readonly writeStdout: (text: string) => void;
+    readonly writeStderr: (text: string) => void;
+    readonly writeResult: (artifactPath: string, missionOutcome: MissionOutcome, exitCode: number, result: unknown, meta: RunMetadata | undefined) => string;
+    readonly engine: () => EngineInfo;
+    /** Listens for an uncaught error (and so an unhandled rejection). Returns the remover. */
+    readonly onFatalError: (listener: (err: unknown) => void) => () => void;
+    /** Listens for the process ending on any path. Returns the remover. */
+    readonly onProcessExit: (listener: () => void) => () => void;
+    readonly installKillSwitch: () => void;
+    /** True when this process is shared with other work and is not this command's to print on or end. */
+    readonly sharedProcess: () => boolean;
+}
+/**
+ * The one rule for text leaving a command: registered secrets first and whole, so no part of one is
+ * left for a later rule to half-mask, then URL parameters, named credentials and credential shapes.
+ * Text past `MAX_MASKED_TEXT` once the secrets' masks are in is withheld whole.
+ */
+export declare function redactSensitiveText(text: string, secrets: readonly string[]): string;
+/**
+ * A path this process wrote must still open: only a real secret is masked, never a shape (a video's
+ * file name is 32 hex digits) and never a short value (`--param dir=logs` is not `.jevitate/logs`).
+ */
+export declare function redactSensitivePath(path: string, secrets: readonly string[]): string;
+/** How a field keeps its value: `verbatim` (no secret can be there), or `path` (see `redactSensitivePath`). */
+export type RedactionFieldRule = (key: string) => "verbatim" | "path" | undefined;
+/**
+ * Every string VALUE in `value` through `redactSensitiveText`. A field named for a credential loses
+ * its whole value, whatever it looks like. `rule` exempts a caller's known fields. Keys are never
+ * touched: they are what a reader finds `exitCode` and `verdict` by, so a value that happens to equal
+ * one must not rename it. A map keyed by data has to reach here as text (see `buildDiagnostic`).
+ */
+export declare function redactSensitiveValue(value: unknown, secrets: readonly string[], rule?: RedactionFieldRule): unknown;
+/** `err` with its text redacted: the same object and class, so a caller's `instanceof` still decides. */
+export declare function redactThrown(err: unknown, secrets: readonly string[], depth?: number): unknown;
+/**
+ * Registers how a long-running command produces its terminal result. Call it before the command's
+ * first browser launch, and keep the returned handle for the run. See this module's doc for what ends
+ * a command, and for the synchronous contract everything reachable from a trigger keeps.
+ *
+ * Throws a `RangeError` on an unusable `inactivityMs`: a command never runs without its bound.
+ */
+export declare function registerTerminalResult(registration: TerminalResultRegistration, deps?: TerminalResultDeps): TerminalResultHandle;
+/**
+ * What an EPIPE on an output stream means. A closed reader is not a verdict, and exit 0 here once
+ * reported `still-reproduces` as a pass, so:
+ *
+ *  - stderr: nothing. It carries progress and diagnostics, and `2>&1 | head` must not end a proof.
+ *  - stdout, a registered command still running: nothing. It goes on to its real result and exit code.
+ *  - stdout otherwise: the process exits quietly (#213) with whatever `process.exitCode` the command
+ *    set, 0 when it set none. `emitEnvelope` writes before it sets the code, but a stream reports
+ *    the error on a later tick than the write, so the code is set by the time this runs. And a
+ *    registered command calls `complete()` in that same turn, so if the error ever came first, the
+ *    "still running" rule above would keep its code.
+ *
+ * `process.exit()` takes no code on purpose: it keeps the one the command set.
+ */
+export declare function installBrokenPipePolicy(streams?: {
+    readonly stdout: NodeJS.EventEmitter;
+    readonly stderr: NodeJS.EventEmitter;
+}, exit?: () => void): void;
+/**
+ * A command's promise rejected up to the entry point. With a command registered in this process the
+ * layer handles it, so its secrets are redacted: a running one gets the usual E_TERMINAL_INTERNAL
+ * ending, and a completed one (its result already out, so no second envelope) a redacted stderr line
+ * and exit 2. Returns false when nothing was registered: the caller reports it itself.
+ */
+export declare function reportCommandRejection(err: unknown, writeStderr?: (text: string) => void): boolean;
+/** Test seam: resets all module state (a real run never needs this: one process, one exit). */
+export declare function __resetTerminalResultForTests(): void;