@canonical/pragma-cli 0.33.0 → 0.35.0

package/dist/src/kernel/project/cli/dispatch.js

@@ -0,0 +1,420 @@
+/**
+ * The CLI dispatcher: from parsed argv to rendered output.
+ *
+ * Coerces raw string args into typed params by {@link ParamSpec.kind} (no zod
+ * on this path), boots the runtime, runs the verb across the effect seam, and
+ * renders. The seam is the discriminator `capability.mutates`: a read is a
+ * plain `Promise` rendered directly; a mutation is a `Task` interpreted under
+ * the node interpreter (`--yes`), the dry-run interpreter (`--dry-run`), or the
+ * undo interpreter (`--undo`). `--format json` wraps output in the full
+ * `{ ok, data, meta }` envelope (D3); errors render to stderr with a mapped
+ * exit code.
+ */
+import { describeEffect } from "@canonical/task";
+import { runPreview, runTask, runUndo } from "@canonical/task/node";
+import { asPragmaError, CANCELLED_MESSAGE, isCancellation, isInterruption, } from "../../error/fromTaskError.js";
+import { PragmaError, renderErrorJson, renderErrorLlm, renderErrorPlain, } from "../../error/index.js";
+import { successEnvelope, writeStdout } from "../../render/index.js";
+import { bootRuntime } from "../../runtime/index.js";
+import { EXIT, mapExitCode } from "./exitCodes.js";
+/**
+ * THE CLI interactivity gate (H3): stdin AND stderr are TTYs. The Ink wizard
+ * renders to stderr and reads stdin, so `<verb> 2>/dev/null` must be
+ * non-interactive — gating on stdout would mount an invisible render that
+ * blocks on stdin. One exported fact: the kernel's interaction context and a
+ * mounted subtree's own decision both read it here, so the two callers can
+ * never disagree about what "a TTY" means.
+ */
+export function cliIsTTY() {
+    return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+/**
+ * Route a Task's log effects to stderr. The interpreter otherwise falls back to
+ * `console.log` (stdout), which would corrupt the `--format json` / MCP stdio
+ * data stream; diagnostics belong on stderr.
+ */
+const logToStderr = (_level, message) => {
+    process.stderr.write(`${message}\n`);
+};
+/** A silenced log sink — `--quiet` drops progress; errors render elsewhere. */
+const logNowhere = (_level, _message) => { };
+/**
+ * The interpreter log sink for this invocation: stderr, or — under `--quiet`
+ * — nothing. Progress/stage lines are success-path output; error rendering
+ * never routes through this sink, so muting it cannot hide a failure.
+ */
+function logSink(flags) {
+    return flags.quiet === true ? logNowhere : logToStderr;
+}
+/** Coerce one raw arg into the type its {@link ParamSpec} declares. */
+function coerceParam(param, raw) {
+    // A repeatable flag's collector hands over an array of occurrences; coerce
+    // each element so an enum still validates every value.
+    if (Array.isArray(raw) &&
+        (param.kind === "string" || param.kind === "enum") &&
+        param.repeatable === true) {
+        return raw.map((value) => coerceParam(param, value));
+    }
+    switch (param.kind) {
+        case "number": {
+            const value = typeof raw === "number" ? raw : Number(raw);
+            if (Number.isNaN(value)) {
+                throw PragmaError.invalidInput(param.name, String(raw));
+            }
+            return value;
+        }
+        case "boolean":
+            return typeof raw === "boolean" ? raw : raw === "true";
+        case "enum": {
+            const value = String(raw);
+            if (!param.values.includes(value)) {
+                throw PragmaError.invalidInput(param.name, value, {
+                    validOptions: [...param.values],
+                });
+            }
+            return value;
+        }
+        default:
+            return raw;
+    }
+}
+/**
+ * Build the typed param bag from Commander's positional args and options.
+ *
+ * Flag options arrive keyed by their camelCase param name (Commander derives
+ * `withHistory` from `--with-history`); positionals map in declared order, with
+ * a trailing `string[]` param absorbing the remainder.
+ *
+ * @param params - The verb's parameter specs.
+ * @param positionals - Positional args in order.
+ * @param opts - Commander's parsed option values.
+ * @returns The coerced param bag passed to `run`.
+ */
+export function extractParams(params, positionals, opts) {
+    const result = {};
+    for (const param of params) {
+        if (param.positional)
+            continue;
+        const raw = opts[param.name];
+        if (raw !== undefined) {
+            result[param.name] = coerceParam(param, raw);
+        }
+        else if ("default" in param && param.default !== undefined) {
+            result[param.name] = param.default;
+        }
+    }
+    const positional = params.filter((p) => p.positional);
+    for (let i = 0; i < positional.length && i < positionals.length; i++) {
+        const param = positional[i];
+        if (param.kind === "string[]" && i === positional.length - 1) {
+            result[param.name] = positionals.slice(i);
+            break;
+        }
+        result[param.name] = coerceParam(param, positionals[i]);
+    }
+    return result;
+}
+/**
+ * Render a read/execute result through the verb's formatters.
+ *
+ * The plain branch owns two ROUTING decisions (the rendering itself stays in
+ * the formatters): it threads the presentation context (`--no-headers`,
+ * stdout's TTY-ness) into the plain formatter, and it routes a declared
+ * empty-state notice to STDERR with exit 0 — a zero-record result is a calm
+ * success, and stdout (the data stream) must not carry a human sentence a
+ * pipe would read as a record. `llm` and `json` keep their own empty shapes
+ * on stdout: both are machine contracts whose consumers read one stream.
+ *
+ * @note Impure — reads `process.stdout.isTTY` for the render context.
+ */
+function renderData(verb, flags, data, meta) {
+    if (flags.format === "json") {
+        const projection = JSON.parse(verb.output.formatters.json(data));
+        return {
+            stdout: `${JSON.stringify(successEnvelope(projection, meta))}\n`,
+            exitCode: 0,
+        };
+    }
+    if (flags.llm) {
+        const text = verb.output.formatters.llm(data);
+        return { stdout: text ? `${text}\n` : "", exitCode: 0 };
+    }
+    const context = {
+        headers: flags.noHeaders !== true,
+        stdoutIsTty: process.stdout.isTTY === true,
+    };
+    const text = verb.output.formatters.plain(data, context);
+    // The calm zero-record notice is success-path guidance — `--quiet` mutes it.
+    const notice = flags.quiet === true
+        ? undefined
+        : verb.output.formatters.emptyNotice?.(data);
+    return {
+        stdout: text ? `${text}\n` : "",
+        ...(notice ? { stderr: `${notice}\n` } : {}),
+        exitCode: 0,
+    };
+}
+/**
+ * Render a dry-run plan.
+ *
+ * The default render is the effect dump — one described effect per line — which
+ * is what every verb without a plan of its own gets, byte for byte as before.
+ * A verb that declares `output.formatPlan` renders that instead: the dump is
+ * debug material (interpreter log effects, a repeated absolute path prefix on
+ * every line), and a preview is something a user is meant to read.
+ *
+ * The JSON envelope is decided by the STASHED DATA, not by the seam: `plan` is
+ * the same string array it always was, and `targets` appears only for a verb
+ * that stashed a structured plan beside it. So a verb whose renderer works off
+ * the effects alone leaves the machine-readable shape exactly as it found it.
+ *
+ * @param flags - The global flags (format selection, verbosity).
+ * @param plan - The described effects the mutation would perform.
+ * @param effects - Those same effects, unformatted, for the verb's renderer.
+ * @param seam - The verb's plan renderer + whatever it stashed, when it has one.
+ * @returns The dispatch outcome.
+ */
+async function renderPlan(flags, plan, effects, seam) {
+    if (flags.format === "json") {
+        const body = seam?.planData === undefined
+            ? { plan }
+            : { plan, targets: seam.planData };
+        return {
+            stdout: `${JSON.stringify(successEnvelope(body, { dryRun: true }))}\n`,
+            exitCode: 0,
+        };
+    }
+    if (seam !== undefined) {
+        // Awaited: the seam MAY be async, so a renderer can load formatting rules
+        // that live in another package behind a dynamic `import()` instead of
+        // charging every `--help` spawn for them (see `VerbSpec.output.formatPlan`).
+        const rendered = await seam.format(seam.planData, effects, flags.verbose === true);
+        return { stdout: `${rendered}\n`, exitCode: 0 };
+    }
+    const body = plan.length > 0
+        ? `Dry run — planned effects:\n${plan.map((p) => `  - ${p}`).join("\n")}`
+        : "Dry run — no effects.";
+    return { stdout: `${body}\n`, exitCode: 0 };
+}
+/** Render the outcome of an undo. */
+function renderUndo(flags, undone) {
+    if (flags.format === "json") {
+        return {
+            stdout: `${JSON.stringify(successEnvelope({ undone }, { undo: true }))}\n`,
+            exitCode: 0,
+        };
+    }
+    return { stdout: `Undid ${undone} step(s).\n`, exitCode: 0 };
+}
+/** Render a caught error to stderr with a mapped exit code. */
+function renderError(error, flags) {
+    const rendered = flags.format === "json"
+        ? renderErrorJson(error)
+        : flags.llm
+            ? renderErrorLlm(error)
+            : renderErrorPlain(error);
+    return { stderr: `${rendered}\n`, exitCode: mapExitCode(error.code) };
+}
+/**
+ * Run a verb across the effect seam and produce its output.
+ *
+ * The testable core of {@link dispatch}: pure of process I/O, it returns what
+ * to write rather than writing it, so tests (and the envelope-parity check)
+ * can assert on the outcome directly.
+ *
+ * @param verb - The verb to run.
+ * @param params - The coerced param bag.
+ * @param mutation - The mutation flags (ignored for reads).
+ * @param runtime - The booted runtime.
+ * @returns The dispatch outcome.
+ * @note Impure — a mutation's node/undo interpreter touches the filesystem.
+ */
+export async function executeVerb(verb, params, mutation, runtime) {
+    const flags = runtime.globalFlags;
+    // The lazy-store seam: boot the store (once, memoized) only for verbs that
+    // declare they need it. A storeless verb never reaches the store factory, so
+    // the storeless guarantee holds by construction (no STORE_SKIP triage).
+    if (verb.capability.needsStore) {
+        await runtime.store.get();
+    }
+    if (verb.capability.mutates) {
+        // Tell the verb whether this is a plan-only preview (`--dry-run`) or a real
+        // execution, so a network-touching mutation can stay offline for the plan.
+        // Also hand it the interaction context so an interactive verb can pick its
+        // prompt strategy. The verb's `run` sets `mutationRuntime.exec` (the runner
+        // options) as its last act; the projector reads it back on the real-run
+        // branch AND on the dry-run branch, which takes `cwd` (so the preview reads
+        // the tree the run would write into) and `onEffectStart` (so the stamping
+        // transform runs, and planned byte counts match written ones). It never
+        // takes the prompt handler: a preview auto-answers prompts and so can never
+        // block on input. `--undo` stays handler-free and untouched by this seam.
+        const controller = new AbortController();
+        const interaction = {
+            // The shared H3 gate (see cliIsTTY): stderr, never stdout.
+            isTTY: cliIsTTY(),
+            transport: "cli",
+            yes: mutation.yes,
+            signal: controller.signal,
+            // Let an interactive verb's wizard abort the run on an in-Ink Ctrl-C (H2):
+            // raw mode swallows SIGINT, so the keypress can't reach the SIGINT handler
+            // below — the wizard drives this instead. `abort()` is idempotent.
+            abort: () => controller.abort(),
+        };
+        const mutationRuntime = {
+            ...runtime,
+            mutation: { preview: mutation.dryRun, undo: mutation.undo },
+            interaction,
+            // Progress seam (U7): a long mutation's eager resolve/build runs before its
+            // Task is returned, so `onLog` can't reach it — stream stage lines straight
+            // to stderr instead, keeping stdout (the JSON/data stream) clean.
+            report: flags.quiet === true
+                ? () => { }
+                : (message) => process.stderr.write(`${message}\n`),
+        };
+        const task = await Promise.resolve(verb.run(params, mutationRuntime));
+        if (mutation.dryRun) {
+            // The HONEST preview (PR7): reads hit the real filesystem, writes are
+            // recorded and never executed. A mutation whose real run would die on its
+            // first template read now fails HERE too, so `--dry-run` exits nonzero
+            // exactly when the run would — the plan is a prediction, not a wish.
+            // `exec.cwd` is the same write root the real run resolves paths against,
+            // and `exec.onEffectStart` carries summon's stamping transform, so the
+            // planned byte counts are the bytes the run would actually write.
+            //
+            // NO `onLog`, deliberately. A preview that PERFORMS an effect is not a
+            // preview of that effect: routing the recorded `Log`s to stderr printed
+            // the generator's whole commentary on the way through, and the plan then
+            // listed the very same lines as rows. The interpreter prints nothing of
+            // its own when `onLog` is absent, so a log is now planned once and
+            // performed never.
+            const previewExec = mutationRuntime.exec ?? {};
+            try {
+                const { effects } = await runPreview(task, {
+                    cwd: previewExec.cwd,
+                    onEffectStart: previewExec.onEffectStart,
+                });
+                // A plan is the effects a mutation WOULD apply — a `Prompt` is not one,
+                // so the interactive confirm gate / answer prompts never clutter it.
+                const planned = effects.filter((effect) => effect._tag !== "Prompt");
+                // The DESCRIBED plan — what `--format json` carries and what a verb
+                // with no renderer of its own is dumped as — passes the same
+                // visibility filter the MCP payload and the human preview use. It is
+                // the filter, not the row format, that this seam shares: `plan` is
+                // structured description, so it stays `describeEffect` strings rather
+                // than terminal rows, and the two surfaces can be compared string for
+                // string (`testing/behavioral/parity.test.ts`, A6).
+                //
+                // Loaded lazily from the LIGHT `/format` subpath. A dry run is already
+                // several filesystem reads deep here; a `--help` spawn never reaches
+                // this branch, and the kernel keeps summon-core off its static graph.
+                const { visiblePlanEffects } = await import("@canonical/summon-core/format");
+                const format = verb.output.formatPlan;
+                return await renderPlan(flags, visiblePlanEffects(planned, flags.verbose === true).map(describeEffect), planned, format === undefined
+                    ? undefined
+                    : { format, planData: mutationRuntime.planData });
+            }
+            finally {
+                // A verb that mounted an interactive session before returning its Task
+                // must be torn down on this branch too, exactly as on the real run.
+                await previewExec.dispose?.();
+            }
+        }
+        if (mutation.undo) {
+            const { undoCount } = await runUndo(task, { onLog: logSink(flags) });
+            return renderUndo(flags, undoCount);
+        }
+        // Real execution: spread the verb's runner options into the node
+        // interpreter (prompt handler, stamping/progress callbacks, log routing,
+        // signal). Teardown (e.g. unmount an Ink render) runs in `finally`.
+        const exec = mutationRuntime.exec ?? {};
+        const onSigint = () => controller.abort();
+        process.once("SIGINT", onSigint);
+        try {
+            const value = await runTask(task, { onLog: logSink(flags), ...exec });
+            return renderData(verb, flags, value, {});
+        }
+        finally {
+            process.removeListener("SIGINT", onSigint);
+            await exec.dispose?.();
+        }
+    }
+    const data = await Promise.resolve(verb.run(params, runtime));
+    return renderData(verb, flags, data, {});
+}
+/**
+ * Run a verb whose params are already prepared, then perform the output I/O —
+ * the shared tail of {@link dispatch} and of a mounted subtree's own
+ * dispatcher, which extracts its params by its own rules but reuses every
+ * piece of the kernel machinery from here down: dry-run/undo/real-run
+ * interpretation, error rendering, exit codes, SIGINT.
+ *
+ * @param verb - The verb spec to run.
+ * @param getParams - Produces the coerced param bag (may throw a usage error;
+ *   it is rendered exactly like a run error).
+ * @param mutation - The mutation flags.
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+async function runPrepared(verb, getParams, mutation, globalFlags) {
+    const runtime = bootRuntime(globalFlags);
+    let outcome;
+    try {
+        outcome = await executeVerb(verb, getParams(), mutation, runtime);
+    }
+    catch (error) {
+        // Two clean, non-bug outcomes print the same "Cancelled." line but exit
+        // differently — both set DIRECTLY here, out-of-band from `mapExitCode`'s
+        // frozen {0,1,2,3} (see exitCodes.ts):
+        //   - a DECLINE (confirm gate / at-prompt Ctrl-C) is a deliberate user
+        //     choice, not a failure → success exit 0; and
+        //   - an INTERRUPT (SIGINT on --yes/CI, or an in-wizard Ctrl-C mid-run) is
+        //     an abort of work already underway → UNIX 128+SIGINT exit 130.
+        // Everything else maps through the shared task-error bridge (which turns a
+        // bad/absent non-interactive answer into a usage error, not an internal bug).
+        outcome = isCancellation(error)
+            ? { stderr: `${CANCELLED_MESSAGE}\n`, exitCode: EXIT.OK }
+            : isInterruption(error)
+                ? { stderr: `${CANCELLED_MESSAGE}\n`, exitCode: EXIT.INTERRUPTED }
+                : renderError(asPragmaError(error), globalFlags);
+    }
+    if (outcome.stdout)
+        writeStdout(outcome.stdout);
+    if (outcome.stderr)
+        process.stderr.write(outcome.stderr);
+    if (outcome.exitCode !== 0)
+        process.exitCode = outcome.exitCode;
+}
+/**
+ * Dispatch a matched verb: coerce, run, and perform the output I/O.
+ *
+ * @param verb - The matched verb spec.
+ * @param positionals - Positional args from Commander.
+ * @param opts - Commander's parsed option values (incl. mutation flags).
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+export async function dispatch(verb, positionals, opts, globalFlags) {
+    const mutation = {
+        dryRun: opts.dryRun === true,
+        undo: opts.undo === true,
+        yes: opts.yes === true,
+    };
+    await runPrepared(verb, () => extractParams(verb.params, positionals, opts), mutation, globalFlags);
+}
+/**
+ * Dispatch a verb whose params were ALREADY extracted by the caller — the
+ * seam a mounted subtree drives: its leaf specs carry no Commander defaults
+ * (explicit stays distinguishable from default), so the mount extracts the
+ * explicit answers itself and hands them here, reusing the whole kernel tail
+ * (interpreters, rendering, exit codes, SIGINT) byte-for-byte.
+ *
+ * @param verb - The (possibly synthesized) verb spec to run.
+ * @param params - The prepared param bag.
+ * @param mutation - The mutation flags.
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+export async function dispatchPrepared(verb, params, mutation, globalFlags) {
+    await runPrepared(verb, () => params, mutation, globalFlags);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/src/kernel/project/cli/dispatch.js.map

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

package/dist/src/kernel/project/cli/exitCodes.js

@@ -0,0 +1,66 @@
+/**
+ * Process exit codes for the CLI projector (D2).
+ *
+ * The covenant freezes exactly four ERROR-CLASSIFICATION codes: success, a
+ * generic runtime failure, a usage failure, and an unavailable store.
+ * {@link mapExitCode} routes every {@link ErrorCode} into one of them — usage
+ * errors the shell can fix, a store that is not reachable, and everything else
+ * as a runtime failure.
+ *
+ * COVENANT NOTE — out-of-band codes bypass {@link mapExitCode} by design. The
+ * dispatch catch sets two codes DIRECTLY, never through the map, so the frozen
+ * `{0,1,2,3}` classification set is untouched:
+ *   - a deliberate cancel (declining the confirm gate / an at-prompt Ctrl-C)
+ *     exits {@link EXIT.OK} (0) — a user choice, not a failure; and
+ *   - an interrupt ({@link EXIT.INTERRUPTED}, 130) — a run aborted by SIGINT or
+ *     an in-wizard Ctrl-C mid-execution, following the UNIX 128+SIGINT
+ *     convention. It is intentionally out-of-band from the four error codes and
+ *     is NOT produced by `mapExitCode`.
+ */
+/**
+ * The process exit codes. The first four are the covenant's frozen
+ * error-classification set (produced by {@link mapExitCode}); `INTERRUPTED` is
+ * the out-of-band UNIX interrupt code set directly at the dispatch catch (see
+ * the module doc), never routed through the map.
+ */
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Generic runtime failure (entity-not-found, empty, config, internal). */
+    RUNTIME: 1,
+    /** Usage failure (invalid/ambiguous input, unknown verb). */
+    USAGE: 2,
+    /** The knowledge-engine store could not be reached. */
+    STORE_UNAVAILABLE: 3,
+    /**
+     * Interrupted by SIGINT / an in-wizard Ctrl-C during execution (UNIX
+     * 128+SIGINT). Out-of-band from the four classification codes above: set
+     * directly at the dispatch catch, NOT via {@link mapExitCode}.
+     */
+    INTERRUPTED: 130,
+};
+/** Error codes that signal a usage mistake the caller can correct. */
+const USAGE_CODES = new Set([
+    "INVALID_INPUT",
+    "AMBIGUOUS_INPUT",
+    "UNKNOWN_VERB",
+]);
+/**
+ * Map a {@link PragmaError} code to its numeric process exit code.
+ *
+ * Usage codes map to {@link EXIT.USAGE}, an unavailable store to
+ * {@link EXIT.STORE_UNAVAILABLE}, and every other code — entity-not-found,
+ * empty results, config error, internal error — to the generic
+ * {@link EXIT.RUNTIME}.
+ *
+ * @param code - The error code to map.
+ * @returns The corresponding process exit code.
+ */
+export function mapExitCode(code) {
+    if (code === "STORE_UNAVAILABLE")
+        return EXIT.STORE_UNAVAILABLE;
+    if (USAGE_CODES.has(code))
+        return EXIT.USAGE;
+    return EXIT.RUNTIME;
+}
+//# sourceMappingURL=exitCodes.js.map

package/dist/src/kernel/project/cli/exitCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exitCodes.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/exitCodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,2EAA2E;IAC3E,OAAO,EAAE,CAAC;IACV,6DAA6D;IAC7D,KAAK,EAAE,CAAC;IACR,uDAAuD;IACvD,iBAAiB,EAAE,CAAC;IACpB;;;;OAIG;IACH,WAAW,EAAE,GAAG;CACR,CAAC;AAEX,sEAAsE;AACtE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAY;IACrC,eAAe;IACf,iBAAiB;IACjB,cAAc;CACf,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,IAAI,IAAI,KAAK,mBAAmB;QAAE,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAChE,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC;IAC7C,OAAO,IAAI,CAAC,OAAO,CAAC;AACtB,CAAC"}