@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/kernel/error/PragmaError.js

@@ -0,0 +1,149 @@
+import { ISSUES_URL } from "../../constants.js";
+/**
+ * Structured error for all pragma operations.
+ *
+ * Carries a machine-readable {@link ErrorCode}, optional recovery hints, and
+ * contextual metadata (suggestions, valid options, active filters) so the CLI
+ * and MCP projectors can render one actionable diagnostic from one throw. The
+ * effect seam reads throw these directly; mutations surface `TaskError`s that
+ * the dispatcher wraps.
+ */
+class PragmaError extends Error {
+    /** Machine-readable error classification. */
+    code;
+    /** Entity that triggered the error (type + name), if applicable. */
+    entity;
+    /** Fuzzy-matched alternative names the user may have intended. */
+    suggestions;
+    /** Structured recovery hint with optional CLI command or MCP tool call. */
+    recovery;
+    /** Active filters at the time of the error, for diagnostic context. */
+    filters;
+    /** Enumerated valid options when input was rejected. */
+    validOptions;
+    /**
+     * @param data - Structured error payload.
+     */
+    constructor(data) {
+        super(data.message);
+        this.name = "PragmaError";
+        this.code = data.code;
+        this.entity = data.entity;
+        this.suggestions = data.suggestions ?? [];
+        this.recovery = data.recovery;
+        this.filters = data.filters;
+        this.validOptions = data.validOptions;
+    }
+    /**
+     * Factory: entity not found by name.
+     *
+     * @param entityType - Kind of entity (e.g. `"block"`, `"token"`).
+     * @param entityName - Name the user supplied.
+     * @param opts - Optional suggestions and recovery hint.
+     * @returns PragmaError with code `ENTITY_NOT_FOUND`.
+     */
+    static notFound(entityType, entityName, opts = {}) {
+        return new PragmaError({
+            code: "ENTITY_NOT_FOUND",
+            message: `${entityType} "${entityName}" not found.`,
+            entity: { type: entityType, name: entityName },
+            suggestions: opts.suggestions,
+            recovery: opts.recovery,
+        });
+    }
+    /**
+     * Factory: query returned zero results.
+     *
+     * @param entityType - Kind of entity being listed.
+     * @param opts - Optional message, active filters, and recovery hint.
+     * @returns PragmaError with code `EMPTY_RESULTS`.
+     */
+    static emptyResults(entityType, opts = {}) {
+        return new PragmaError({
+            code: "EMPTY_RESULTS",
+            message: opts.message ?? `No ${entityType}s found.`,
+            filters: opts.filters,
+            recovery: opts.recovery,
+            validOptions: opts.validOptions,
+        });
+    }
+    /**
+     * Factory: user-supplied input is invalid.
+     *
+     * @param field - Name of the invalid field or argument.
+     * @param value - The rejected value.
+     * @param opts - Optional valid alternatives and recovery hint.
+     * @returns PragmaError with code `INVALID_INPUT`.
+     */
+    static invalidInput(field, value, opts = {}) {
+        return new PragmaError({
+            code: "INVALID_INPUT",
+            message: `Invalid ${field} "${value}".`,
+            validOptions: opts.validOptions,
+            recovery: opts.recovery,
+        });
+    }
+    /**
+     * Factory: an unknown noun/verb was entered.
+     *
+     * @param verb - The unrecognized command token.
+     * @param opts - Optional suggestions and recovery hint.
+     * @returns PragmaError with code `UNKNOWN_VERB`.
+     */
+    static unknownVerb(verb, opts = {}) {
+        return new PragmaError({
+            code: "UNKNOWN_VERB",
+            message: `Unknown command "${verb}".`,
+            suggestions: opts.suggestions,
+            recovery: opts.recovery,
+        });
+    }
+    /**
+     * Factory: the knowledge-engine store could not be reached.
+     *
+     * Its own exit code (3) so scripts can distinguish an unavailable store from
+     * an ordinary runtime failure.
+     *
+     * @param reason - Human-readable failure description.
+     * @param opts - Optional recovery hint.
+     * @returns PragmaError with code `STORE_UNAVAILABLE`.
+     */
+    static storeUnavailable(reason, opts = {}) {
+        return new PragmaError({
+            code: "STORE_UNAVAILABLE",
+            message: `Store unavailable. ${reason}`,
+            recovery: opts.recovery,
+        });
+    }
+    /**
+     * Factory: configuration file is invalid or contains bad values.
+     *
+     * @param reason - Human-readable description of the config problem.
+     * @param opts - Optional valid alternatives and recovery hint.
+     * @returns PragmaError with code `CONFIG_ERROR`.
+     */
+    static configError(reason, opts = {}) {
+        return new PragmaError({
+            code: "CONFIG_ERROR",
+            message: reason,
+            validOptions: opts.validOptions,
+            recovery: opts.recovery,
+        });
+    }
+    /**
+     * Factory: unexpected internal failure (a bug).
+     *
+     * @param reason - Description of the internal error.
+     * @returns PragmaError with code `INTERNAL_ERROR` and a report-this hint
+     *   naming the issue tracker.
+     */
+    static internalError(reason) {
+        return new PragmaError({
+            code: "INTERNAL_ERROR",
+            message: `Internal error: ${reason}`,
+            recovery: { message: `Report this issue at ${ISSUES_URL}.` },
+        });
+    }
+}
+export { PragmaError };
+//# sourceMappingURL=PragmaError.js.map

package/dist/src/kernel/error/PragmaError.js.map

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

package/dist/src/kernel/error/constants.js

@@ -0,0 +1,40 @@
+/**
+ * The closed set of pragma error codes.
+ *
+ * Every {@link PragmaError} carries one of these; the CLI projector maps each
+ * to a process exit code and the covenant freezes the exit-code table. Ported
+ * from the v1 error kernel with two additions for the v2 exit model:
+ * `STORE_UNAVAILABLE` (its own exit code, D2) and `UNKNOWN_VERB` (the usage
+ * class the unknown-command suggester resolves to). A store failure is either
+ * `STORE_UNAVAILABLE` (can't reach it) or a plain `INTERNAL_ERROR`, so no
+ * distinct `STORE_ERROR` code is carried.
+ */
+/** All recognized pragma error codes as a const tuple. */
+const ERROR_CODES = [
+    "ENTITY_NOT_FOUND",
+    "EMPTY_RESULTS",
+    "INVALID_INPUT",
+    // RESERVED: declared and exit-mapped (usage, exit 2) for forward-compat and
+    // advertised in the covenant, but not yet raised by any site. Reserved for a
+    // future ambiguous glob/lookup match (a name resolving to several entities);
+    // until then no factory exists, so it cannot be raised by accident.
+    "AMBIGUOUS_INPUT",
+    "UNKNOWN_VERB",
+    "STORE_UNAVAILABLE",
+    "CONFIG_ERROR",
+    "INTERNAL_ERROR",
+    // A runtime condition that is NOT a bug and NOT a usage mistake, so it must
+    // NOT collapse to INTERNAL_ERROR's "report this issue": a capability
+    // genuinely unavailable in this environment (`create` refusing when its
+    // lazily-imported generator runtime cannot be loaded at all — the
+    // module-not-found backstop in `capabilities/create/create.verb.ts`, which
+    // means the `@canonical/summon-*` dependencies could not be resolved, i.e. a
+    // broken or pruned install; every declared generator otherwise runs
+    // everywhere), OR an external command
+    // that RAN and failed for a fixable environment reason (a denied global
+    // `npm i -g`, a network/registry failure — see `shared/assertExecOk`). Both
+    // carry an actionable recovery and map to the generic runtime exit 1.
+    "UNSUPPORTED",
+];
+export { ERROR_CODES };
+//# sourceMappingURL=constants.js.map

package/dist/src/kernel/error/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/kernel/error/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,GAAG;IAClB,kBAAkB;IAClB,eAAe;IACf,eAAe;IACf,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,oEAAoE;IACpE,iBAAiB;IACjB,cAAc;IACd,mBAAmB;IACnB,cAAc;IACd,gBAAgB;IAChB,4EAA4E;IAC5E,qEAAqE;IACrE,wEAAwE;IACxE,kEAAkE;IAClE,2EAA2E;IAC3E,6EAA6E;IAC7E,oEAAoE;IACpE,sCAAsC;IACtC,wEAAwE;IACxE,4EAA4E;IAC5E,sEAAsE;IACtE,aAAa;CACL,CAAC;AAEX,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/src/kernel/error/fromTaskError.js

@@ -0,0 +1,96 @@
+/**
+ * Bridge task-interpreter / summon-core error codes to the pragma boundary.
+ *
+ * A mutating verb's Task can fail with a code raised by summon-core's `execute`:
+ * `GENERATOR_CANCELLED` when an attended-TTY user DECLINES the confirm gate, and
+ * `MISSING_REQUIRED_ANSWER` / `GENERATOR_INVALID_ANSWER` for absent or invalid
+ * non-interactive answers. `runTask` rethrows these as a `TaskExecutionError`
+ * carrying `.code`. Without a bridge the CLI/MCP boundary collapses every
+ * non-`PragmaError` to INTERNAL_ERROR + "report this issue" — telling a
+ * user to file a bug for cancelling their own scaffold.
+ *
+ * The codes are matched as STRING LITERALS, never imported from summon-core, so
+ * the kernel keeps summon-core out of its static import graph (the lazy-React /
+ * lazy-summon discipline that is the whole reason `create` dynamic-imports it).
+ */
+import { PragmaError } from "./PragmaError.js";
+/** summon-core's task-error code for a run declined at the confirm gate. */
+const GENERATOR_CANCELLED = "GENERATOR_CANCELLED";
+/** The interpreter's task-error code for a run aborted mid-flight (SIGINT). */
+const TASK_INTERRUPTED = "TASK_INTERRUPTED";
+/** summon-core task-error codes for absent/invalid non-interactive answers. */
+const ANSWER_USAGE_CODES = new Set([
+    "MISSING_REQUIRED_ANSWER",
+    "GENERATOR_INVALID_ANSWER",
+]);
+/** The clean, non-scary line shown when a user cancels at the confirm gate. */
+export const CANCELLED_MESSAGE = "Cancelled.";
+/** Read a task-interpreter error code off a thrown value, if it carries one. */
+function taskErrorCode(error) {
+    if (error && typeof error === "object" && "code" in error) {
+        const { code } = error;
+        if (typeof code === "string")
+            return code;
+    }
+    return undefined;
+}
+/**
+ * True when the throw is an attended user DECLINING the interactive confirm
+ * gate — a deliberate choice, not a failure. The boundary renders this as a
+ * clean cancellation (a plain message, success exit), never INTERNAL_ERROR.
+ */
+export function isCancellation(error) {
+    return taskErrorCode(error) === GENERATOR_CANCELLED;
+}
+/**
+ * True when the throw is the interpreter aborting a run mid-flight — a SIGINT
+ * on a `--yes`/CI run, or an in-wizard Ctrl-C DURING execution (which aborts
+ * the run's controller). Distinct from {@link isCancellation}: a cancel is a
+ * clean user decline (exit 0), an interruption stopped work already underway
+ * (exit 130, UNIX 128+SIGINT). The boundary renders both with the same clean
+ * "Cancelled." line — neither is a bug to report — but with different exit
+ * codes.
+ */
+export function isInterruption(error) {
+    return taskErrorCode(error) === TASK_INTERRUPTED;
+}
+/**
+ * The {@link PragmaError} a task failure CARRIES, if any. A task-layer failure
+ * raised through the failure channel (`failPragma` — so an enclosing `recover`
+ * such as setup's per-step isolation can catch it, which a synchronous throw
+ * bypasses) stores the original PragmaError as the TaskError's `cause`;
+ * `runTask` then wraps that TaskError in a `TaskExecutionError` whose
+ * `taskError` carries it. Walk both wrappers (bounded — the shapes nest at
+ * most a few levels) so the boundary recovers the ORIGINAL error with its
+ * code, message, and recovery intact.
+ */
+function carriedPragmaError(error) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current !== undefined; depth += 1) {
+        if (current instanceof PragmaError)
+            return current;
+        const record = current;
+        current = record?.taskError ?? record?.cause;
+    }
+    return undefined;
+}
+/**
+ * Coerce a thrown value into a {@link PragmaError} for the CLI/MCP boundary,
+ * bridging summon-core task-error codes: a `PragmaError` (direct, or carried
+ * through the task failure channel as a TaskError `cause`) passes through
+ * unchanged; absent/invalid non-interactive answers become INVALID_INPUT (a
+ * usage error, exit 2); everything else stays INTERNAL_ERROR. Cancellation is
+ * handled separately by {@link isCancellation} as a clean, non-error outcome.
+ */
+export function asPragmaError(error) {
+    const carried = carriedPragmaError(error);
+    if (carried !== undefined)
+        return carried;
+    const message = error instanceof Error ? error.message : String(error);
+    const code = taskErrorCode(error);
+    if (code !== undefined && ANSWER_USAGE_CODES.has(code)) {
+        return new PragmaError({ code: "INVALID_INPUT", message });
+    }
+    return PragmaError.internalError(message);
+}
+//# sourceMappingURL=fromTaskError.js.map

package/dist/src/kernel/error/fromTaskError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromTaskError.js","sourceRoot":"","sources":["../../../../src/kernel/error/fromTaskError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAElD,+EAA+E;AAC/E,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IACzC,yBAAyB;IACzB,0BAA0B;CAC3B,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAE9C,gFAAgF;AAChF,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1D,MAAM,EAAE,IAAI,EAAE,GAAG,KAA0B,CAAC;QAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,aAAa,CAAC,KAAK,CAAC,KAAK,mBAAmB,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,aAAa,CAAC,KAAK,CAAC,KAAK,gBAAgB,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,OAAO,KAAK,SAAS,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACnE,IAAI,OAAO,YAAY,WAAW;YAAE,OAAO,OAAO,CAAC;QACnD,MAAM,MAAM,GAAG,OAA0D,CAAC;QAC1E,OAAO,GAAG,MAAM,EAAE,SAAS,IAAI,MAAM,EAAE,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC1C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,OAAO,IAAI,WAAW,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,WAAW,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/src/kernel/error/index.js

@@ -0,0 +1,13 @@
+/**
+ * Error kernel barrel — the structured error model and its renderers.
+ *
+ * The projectors import `PragmaError` and the renderers from here; the
+ * recovery invariant and the serializer are exported for the seams that build
+ * and marshal errors.
+ */
+export { ERROR_CODES } from "./constants.js";
+export { PragmaError } from "./PragmaError.js";
+export { cliRecovery } from "./recovery.js";
+export { renderErrorJson, renderErrorLlm, renderErrorPlain, } from "./renderError.js";
+export { serializeError } from "./serialize.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/error/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/kernel/error/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/kernel/error/recovery.js

@@ -0,0 +1,52 @@
+/**
+ * The recovery-string invariant (D5).
+ *
+ * A `recovery.cli` hint quotes a command the installed binary answers to, so it
+ * must begin with {@link RECOVERY_CLI_PREFIX} — the distribution's own `name`
+ * plus a space. {@link cliRecovery} takes the command SUFFIX and prepends the
+ * prefix itself, so a hint that names the wrong binary is unwritable rather
+ * than merely detected. That is why there is no assertion here: an assertion
+ * over a string the caller composed from the prefix cannot fail, and the hints
+ * that were actually wrong were raw `cli:` object literals that never reached
+ * this function at all. `kernel/copy.test.ts` covers those, at the position.
+ *
+ * A THIRD authoring route is also legal and reached by NEITHER guard: a `cli`
+ * DERIVED from the program's own name at the call site. One site does this —
+ * the create mount (`capabilities/create/mount.ts`,
+ * `[...detail.chain, suggestion].join(" ")`), whose `chain[0]` is the root
+ * Commander program's name, `BIN_NAME` by wiring. It bypasses
+ * {@link cliRecovery}, and the position rule is structurally blind to it (it
+ * flags QUOTED literals containing the distribution's name, never a computed
+ * expression) — so D5 holds there by derivation, and the derivation is pinned
+ * where the value surfaces: `createGrammar.test.ts` COMPOSES its expected
+ * `cli` from {@link RECOVERY_CLI_PREFIX}, so a renamed root program reddens
+ * the cell naming the constant. (A separate `startsWith` assertion cannot
+ * pin it — behind an exact pin of the same value it has no reachable
+ * failing input.)
+ *
+ * `kernel/packs/schema.ts` holds a user-authored pack's `emptyRecovery.cli` to
+ * the same shape from the other side — it must NOT carry a prefix, because the
+ * consuming distribution's renderer supplies one.
+ */
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
+/**
+ * Build a {@link Recovery} whose `cli` command carries the distribution's own
+ * prefix, optionally pairing it with an MCP tool an agent can call.
+ *
+ * A recovery may need to speak to BOTH surfaces: the `cli` string guides a human,
+ * while `mcp` names the tool an agent invokes (an agent cannot run a shell
+ * command). The single human `message` is shared by both.
+ *
+ * @param command - The recovery command WITHOUT the binary name (`sources update`).
+ * @param message - Human-readable guidance shown alongside the command.
+ * @param mcp - The MCP tool (and optional params) an agent calls to recover.
+ * @returns A recovery hint whose `cli` names this distribution's binary.
+ */
+export function cliRecovery(command, message, mcp) {
+    return {
+        message,
+        cli: `${RECOVERY_CLI_PREFIX}${command}`,
+        ...(mcp ? { mcp } : {}),
+    };
+}
+//# sourceMappingURL=recovery.js.map

package/dist/src/kernel/error/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../../../src/kernel/error/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,OAAe,EACf,GAAqB;IAErB,OAAO;QACL,OAAO;QACP,GAAG,EAAE,GAAG,mBAAmB,GAAG,OAAO,EAAE;QACvC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxB,CAAC;AACJ,CAAC"}

package/dist/src/kernel/error/renderError.js

@@ -0,0 +1,115 @@
+/**
+ * Render a {@link PragmaError} for each output surface.
+ *
+ * Plain text targets a human terminal (stderr), condensed Markdown targets an
+ * agent reading `--format llm`, and JSON emits the `{ ok: false, error }` envelope —
+ * the same failure shape the MCP projector returns, so agents see one contract
+ * whichever transport they use.
+ */
+import { serializeError } from "./serialize.js";
+/**
+ * Render a {@link PragmaError} as human-readable plain text for the terminal.
+ *
+ * @param error - The structured error to render.
+ * @returns Multi-line plain text string.
+ */
+function renderErrorPlain(error) {
+    const lines = [`Error: ${error.message}`];
+    if (error.suggestions.length > 0) {
+        lines.push("", "Did you mean?");
+        for (const suggestion of error.suggestions) {
+            lines.push(`  - ${suggestion}`);
+        }
+    }
+    if (error.filters) {
+        lines.push("", "Active filters:");
+        for (const [key, value] of Object.entries(error.filters)) {
+            lines.push(`  ${key}: ${value}`);
+        }
+    }
+    if (error.validOptions && error.validOptions.length > 0) {
+        lines.push("", `Valid options: ${error.validOptions.join(", ")}`);
+    }
+    if (error.recovery) {
+        lines.push("");
+        // Keep the human guidance AND the runnable command — dropping the message
+        // when a `cli` is present loses the WHY (e.g. "Build the local store …").
+        lines.push(error.recovery.cli
+            ? `${error.recovery.message} Run \`${error.recovery.cli}\``
+            : error.recovery.message);
+    }
+    return lines.join("\n");
+}
+/**
+ * Render a {@link PragmaError} as condensed Markdown for agent consumption.
+ *
+ * @param error - The structured error to render.
+ * @returns Markdown-formatted string.
+ */
+function renderErrorLlm(error) {
+    const lines = [`## Error: ${error.code}`, error.message];
+    if (error.suggestions.length > 0) {
+        lines.push(`Suggestions: ${error.suggestions.join(", ")}`);
+    }
+    if (error.filters) {
+        const filterParts = Object.entries(error.filters)
+            .map(([key, value]) => `${key}=${value}`)
+            .join(", ");
+        lines.push(`Filters: ${filterParts}`);
+    }
+    if (error.validOptions && error.validOptions.length > 0) {
+        lines.push(`Valid options: ${error.validOptions.join(", ")}`);
+    }
+    if (error.recovery) {
+        // Keep both the guidance and the runnable command (message was dropped when
+        // a `cli` was present).
+        lines.push(error.recovery.cli
+            ? `Recovery: ${error.recovery.message} \`${error.recovery.cli}\``
+            : `Recovery: ${error.recovery.message}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Render a {@link PragmaError} as the `{ ok: false, error }` JSON envelope.
+ *
+ * @param error - The structured error to render.
+ * @returns Serialized failure envelope, identical to the MCP error envelope.
+ */
+function renderErrorJson(error) {
+    return JSON.stringify({ ok: false, error: serializeError(error) });
+}
+/**
+ * Render an error for an EXPLICITLY requested machine format, or decline.
+ *
+ * The ONE machine-format envelope decision for the usage-error surfaces —
+ * `handleProgramError`'s Commander parse failures (the unknown-command arm
+ * included), the create mount's projection usage-error writer, and
+ * `writeRefusal`: an explicit `--format json` renders the failure envelope,
+ * an explicit `--format llm` the condensed Markdown form, and anything else
+ * returns `undefined` so the caller keeps its raw default bytes.
+ * Auto-detected llm is excluded by construction — `parseGlobalFlags` leaves
+ * `format` at `"plain"` under auto-detection and records `autoLlm`
+ * separately — so an inferred output mode can never move the default
+ * (cross-CLI parity) bytes. Hoisted so the gate and the renderer pick exist
+ * ONCE instead of drifting per call site (they had already split: sites
+ * gated on json only vs json|llm, and `--format llm` enveloped some members
+ * of the usage-error class while siblings stayed raw). Deliberately NOT
+ * routed through here: the always-render sites with no raw arm to arbitrate
+ * — `renderStartupError`, bin.ts's bad-`--format` rejection,
+ * `handleProgramError`'s non-Commander fallthrough, and dispatch's
+ * `renderError` (which deliberately includes autoLlm for run errors) — each
+ * picks a PragmaError renderer directly.
+ *
+ * @param error - The structured error to render.
+ * @param format - The parsed global `--format` value.
+ * @returns The rendered string for `json`/`llm`; `undefined` for `plain`.
+ */
+function renderErrorForFormat(error, format) {
+    if (format === "json")
+        return renderErrorJson(error);
+    if (format === "llm")
+        return renderErrorLlm(error);
+    return undefined;
+}
+export { renderErrorForFormat, renderErrorJson, renderErrorLlm, renderErrorPlain, };
+//# sourceMappingURL=renderError.js.map

package/dist/src/kernel/error/renderError.js.map

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

package/dist/src/kernel/error/serialize.js

@@ -0,0 +1,25 @@
+/**
+ * Serialize a {@link PragmaError} into the covenant's error payload.
+ *
+ * The payload is the `error` field of the `{ ok: false, error }` envelope and
+ * is shared verbatim by the CLI (`--format json`) and MCP projectors, so both
+ * emit byte-identical error output. Optional fields are omitted rather than set
+ * to `undefined`, keeping the JSON minimal and stable.
+ */
+/**
+ * Project a {@link PragmaError} onto the frozen {@link ErrorPayload} shape.
+ *
+ * @param error - The structured error to serialize.
+ * @returns The payload embedded under `error` in the failure envelope.
+ */
+export function serializeError(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        ...(error.suggestions.length > 0 && { suggestions: error.suggestions }),
+        ...(error.recovery && { recovery: error.recovery }),
+        ...(error.validOptions && { validOptions: error.validOptions }),
+        ...(error.filters && { filters: error.filters }),
+    };
+}
+//# sourceMappingURL=serialize.js.map

package/dist/src/kernel/error/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../../../src/kernel/error/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;QACvE,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnD,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;QAC/D,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;KACjD,CAAC;AACJ,CAAC"}

package/dist/src/kernel/error/types.js

@@ -0,0 +1,9 @@
+/**
+ * Error type definitions for the pragma error system.
+ *
+ * Separated from the {@link PragmaError} class so consumers that only need the
+ * shapes (renderers, the MCP envelope, the exit-code mapper) can import types
+ * without pulling in the class or its factories.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/kernel/error/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/kernel/error/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/src/kernel/index.js

@@ -0,0 +1,34 @@
+/**
+ * The kernel's own top-level declarations — the small set of facts that belong
+ * to no sub-domain because every sub-domain may need them.
+ *
+ * This is NOT a facade over the kernel. `kernel/` is a namespace of domains,
+ * each of which keeps its own barrel (`config/`, `render/`, `runtime/`,
+ * `packs/`, `error/`, `spec/`, `completion/`, `project/…`); a consumer wanting
+ * one of those imports that domain's barrel, not this one. What lives here is
+ * only what sits directly in `kernel/`, and the bar for putting a file there
+ * is high: it must be a declaration the kernel makes about itself rather than
+ * a step in any one pipeline.
+ *
+ * Today that is the declared vocabulary and the interactivity vocabulary. The
+ * latter (`interactivity.ts`) names the questions about attended streams — is
+ * stdout captured, may we prompt, may we color (that third one lives with the
+ * styler, for the dependency reason its docblock records) — which render,
+ * dispatch and flag parsing each used to answer with their own inline probe.
+ * They are different questions over different streams, and the names are what
+ * keeps them from being flattened into one flag.
+ *
+ * The declared vocabulary is the distribution's mapping from the roles the
+ * CLI knows (a prompt, a resource) onto the RDF terms that actually
+ * carry them in the active graph. It is parsed once at module load and read
+ * from the prompt capability, the MCP prompt source, and the pack index
+ * builder, none of which owns it and any of which would otherwise hardcode
+ * someone else's IRIs.
+ *
+ * The copy-gate rule table (`copy.ts`) deliberately stays off this barrel. It
+ * is reviewed data consumed by its own test and by nothing else at runtime;
+ * exporting it here would advertise a runtime API the gate does not have.
+ */
+export { canPrompt, stdoutIsCaptured } from "./interactivity.js";
+export { VOCABULARY } from "./vocabulary.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/kernel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/src/kernel/interactivity.js

@@ -0,0 +1,68 @@
+/**
+ * The interactivity vocabulary — three named questions over three streams.
+ *
+ * Every one of these used to be spelled inline as a bare `process.<stream>
+ * .isTTY === true` at the site that needed it, in four places, and the
+ * spellings did not agree — because they are NOT the same question. Naming them
+ * is the point: the names are what stop the next reader from "simplifying"
+ * three probes into one flag.
+ *
+ * - {@link stdoutIsCaptured} reads **stdout**. It governs OUTPUT SHAPE: whether
+ *   a consumer is piping the data stream somewhere (the shape an agent
+ *   captures), which is what AUTO-INFERS the condensed `llm` default. Capture
+ *   is the inference, not the gate: what drops the root-help wordmark is the
+ *   resulting shape — `llm` or `json` — so an explicit `--format plain` through
+ *   a pipe is captured and keeps the art, while `--format llm` on an attended
+ *   terminal is not captured and drops it. Explicit format beats inference, in
+ *   both directions.
+ * - {@link canPrompt} reads **stdin AND stderr** — never stdout. The step
+ *   sequence renders to stderr and reads stdin, so `<verb> 2>/dev/null` is
+ *   non-interactive while `<verb> | cat` is not. Gating this one on stdout
+ *   would mount an invisible render that then blocks on stdin.
+ * - `canColor` (`render/style.ts`) reads **stdout** plus chalk's own color
+ *   level, so piped, redirected and MCP output stays byte-stable even where
+ *   `supports-color` fires off a TTY. It is the one question of the three that
+ *   lives with the styler rather than here, because it needs `chalk` and this
+ *   module is imported by global-flag parsing — which runs before `--version`
+ *   answers, on a path that must load nothing it does not use. It still asks
+ *   its stdout half through {@link stdoutIsCaptured}, so the three stay one
+ *   vocabulary.
+ *
+ * The distinction is not academic: an agent running a mutating verb with its
+ * stdout captured but a terminal still attached is CAPTURED and PROMPTABLE at
+ * the same time. Answering either question with the other's probe would either
+ * hang a pipeline or refuse a human.
+ *
+ * These are the only sanctioned readers of `process.*.isTTY` outside a test.
+ * Each is a plain function rather than a module-load constant because a test
+ * assigns the streams' `isTTY` per case, and a constant would freeze the first
+ * value the process ever saw.
+ */
+/**
+ * Whether stdout is going somewhere other than an attended terminal — piped,
+ * redirected, or read by a parent process.
+ *
+ * The OUTPUT-SHAPE question, and stdout's alone: it says nothing about whether
+ * a human is available to answer a prompt (see {@link canPrompt}).
+ *
+ * @returns True when stdout is not a TTY.
+ * @note Impure — reads `process.stdout.isTTY`.
+ */
+export function stdoutIsCaptured() {
+    return process.stdout.isTTY !== true;
+}
+/**
+ * Whether this invocation may ask the user a question: stdin AND stderr are
+ * both attended terminals.
+ *
+ * THE interactivity gate (H3). One exported fact, so the kernel's interaction
+ * context and a mounted subtree's own decision can never disagree about what
+ * "a TTY" means. Deliberately blind to stdout — see the module docblock.
+ *
+ * @returns True when a prompt can be both drawn and answered.
+ * @note Impure — reads `process.stdin.isTTY` and `process.stderr.isTTY`.
+ */
+export function canPrompt() {
+    return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+//# sourceMappingURL=interactivity.js.map