@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/error/PragmaError.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { ISSUES_URL } from "../../constants.js";
 import { errorEnvelope, successEnvelope } from "../render/envelope.js";
 import { PragmaError } from "./PragmaError.js";
 import { cliRecovery } from "./recovery.js";
@@ -56,7 +57,9 @@ describe("PragmaError factories", () => {
   it("internalError attaches a report hint", () => {
     const error = PragmaError.internalError("boom");
     expect(error.code).toBe("INTERNAL_ERROR");
-    expect(error.recovery).toEqual({ message: "Please report this issue." });
+    expect(error.recovery).toEqual({
+      message: `Report this issue at ${ISSUES_URL}.`,
+    });
   });
 });
 
@@ -66,14 +69,14 @@ describe("serializeError", () => {
     expect(serializeError(error)).toEqual({
       code: "INTERNAL_ERROR",
       message: "Internal error: boom",
-      recovery: { message: "Please report this issue." },
+      recovery: { message: `Report this issue at ${ISSUES_URL}.` },
     });
   });
 
   it("includes suggestions, recovery, validOptions, and filters when present", () => {
     const error = PragmaError.notFound("block", "Buton", {
       suggestions: ["Button"],
-      recovery: cliRecovery("pragma block list", "List blocks."),
+      recovery: cliRecovery("block list", "List blocks."),
     });
     expect(serializeError(error)).toEqual({
       code: "ENTITY_NOT_FOUND",

package/src/kernel/error/PragmaError.ts

@@ -1,3 +1,4 @@
+import { ISSUES_URL } from "../../constants.js";
 import type { ErrorCode, PragmaErrorData, Recovery } from "./types.js";
 
 /**
@@ -168,13 +169,14 @@ class PragmaError extends Error {
    * Factory: unexpected internal failure (a bug).
    *
    * @param reason - Description of the internal error.
-   * @returns PragmaError with code `INTERNAL_ERROR` and a "please report" hint.
+   * @returns PragmaError with code `INTERNAL_ERROR` and a report-this hint
+   *   naming the issue tracker.
    */
   static internalError(reason: string): PragmaError {
     return new PragmaError({
       code: "INTERNAL_ERROR",
       message: `Internal error: ${reason}`,
-      recovery: { message: "Please report this issue." },
+      recovery: { message: `Report this issue at ${ISSUES_URL}.` },
     });
   }
 }

package/src/kernel/error/constants.ts

@@ -25,10 +25,13 @@ const ERROR_CODES = [
   "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 "please report this issue": a capability
-  // genuinely unavailable in this build/environment (`create package` /
-  // `create application` in the compiled binary, whose generator assets are not
-  // embedded — `create component` is embedded and runs), OR an external command
+  // 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.

package/src/kernel/error/fromTaskError.ts

@@ -6,7 +6,7 @@
  * `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 + "please report this issue" — telling a
+ * 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
@@ -62,15 +62,37 @@ export function isInterruption(error: unknown): boolean {
   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: unknown): PragmaError | undefined {
+  let current: unknown = error;
+  for (let depth = 0; depth < 4 && current !== undefined; depth += 1) {
+    if (current instanceof PragmaError) return current;
+    const record = current as { taskError?: unknown; cause?: unknown } | null;
+    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: absent/invalid non-interactive answers
- * become INVALID_INPUT (a usage error, exit 2); a `PragmaError` passes through
- * unchanged; everything else stays INTERNAL_ERROR. Cancellation is handled
- * separately by {@link isCancellation} as a clean, non-error outcome.
+ * 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: unknown): PragmaError {
-  if (error instanceof PragmaError) return 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)) {

package/src/kernel/error/index.ts

@@ -8,7 +8,7 @@
 
 export { ERROR_CODES } from "./constants.js";
 export { PragmaError } from "./PragmaError.js";
-export { assertRecoveryCli, cliRecovery } from "./recovery.js";
+export { cliRecovery } from "./recovery.js";
 export {
   renderErrorJson,
   renderErrorLlm,

package/src/kernel/error/recovery.test.ts

@@ -1,60 +1,37 @@
 import { describe, expect, it } from "vitest";
 import { RECOVERY_CLI_PREFIX } from "../../constants.js";
-import { PragmaError } from "./PragmaError.js";
-import { assertRecoveryCli, cliRecovery } from "./recovery.js";
+import { cliRecovery } from "./recovery.js";
 
 describe("recovery.cli invariant (D5)", () => {
-  it("keeps the recovery prefix literal as `pragma `", () => {
-    // Recovery hints quote the stable, documented command name via the fixed
-    // `pragma ` prefix, so they never drift from the published command.
+  it("carries the shipped distribution's recovery prefix", () => {
+    // The prefix is DERIVED from the distribution's `name` (pragma.conf.ts), so
+    // recovery hints quote a command the installed binary actually answers to.
+    // This pins the value THIS distribution ships; `src/identity.test.ts` proves
+    // the derivation by varying the config.
     expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
   });
 
-  it("accepts a command carrying the canonical prefix", () => {
-    expect(() => assertRecoveryCli("pragma info")).not.toThrow();
-    expect(() => assertRecoveryCli("pragma config show")).not.toThrow();
-  });
-
-  it("rejects a command missing the prefix", () => {
-    expect(() => assertRecoveryCli("info")).toThrow(/must start with/);
-    expect(() => assertRecoveryCli("pragmatic info")).toThrow(
-      /must start with/,
-    );
-    expect(() => assertRecoveryCli("pragmainfo")).toThrow(/must start with/);
-  });
-
-  it("builds a validated recovery whose cli carries the prefix", () => {
-    const recovery = cliRecovery(
-      "pragma config show",
-      "See the resolved config.",
-    );
-    expect(recovery).toEqual({
+  it("prepends the distribution's prefix to the command it is given", () => {
+    // The caller passes the SUFFIX, so a hint naming the wrong binary is
+    // unwritable rather than merely asserted against. What replaced the deleted
+    // `assertRecoveryCli` is `kernel/copy.test.ts`'s position rule, which sees
+    // the raw `cli:` literals that never reached this function at all — the only
+    // place a wrong prefix was ever actually written.
+    expect(cliRecovery("config show", "See the resolved config.")).toEqual({
       cli: "pragma config show",
       message: "See the resolved config.",
     });
-    expect(recovery.cli?.startsWith(RECOVERY_CLI_PREFIX)).toBe(true);
   });
 
-  it("refuses to build a recovery from an unprefixed command", () => {
-    expect(() => cliRecovery("config show", "nope")).toThrow(/must start with/);
-  });
-
-  it("every PragmaError.recovery.cli in the kernel carries the prefix", () => {
-    // The factories that ship a recovery hint must honour the invariant. Only
-    // internalError seeds one today (message-only, no cli), so assert the
-    // guard holds for any cli that is present.
-    const errors = [
-      PragmaError.internalError("boom"),
-      PragmaError.notFound("block", "Nope", {
-        recovery: cliRecovery("pragma block list", "List blocks."),
+  it("carries an MCP tool alongside the command when one is given", () => {
+    expect(
+      cliRecovery("sources update", "Build the store.", {
+        tool: "sources_update",
       }),
-    ];
-    for (const error of errors) {
-      if (error.recovery?.cli) {
-        expect(() =>
-          assertRecoveryCli(error.recovery.cli as string),
-        ).not.toThrow();
-      }
-    }
+    ).toEqual({
+      cli: "pragma sources update",
+      message: "Build the store.",
+      mcp: { tool: "sources_update" },
+    });
   });
 });

package/src/kernel/error/recovery.ts

@@ -1,49 +1,58 @@
 /**
  * The recovery-string invariant (D5).
  *
- * Every `recovery.cli` hint quotes the stable, documented command name, so it
- * must begin with the literal `pragma ` prefix, matching the installed `pragma`
- * binary. Recovery hints are authored through {@link cliRecovery}
- * so the prefix can never drift; {@link assertRecoveryCli} is the single guard,
- * exercised by the invariant test.
+ * 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";
 import type { Recovery } from "./types.js";
 
 /**
- * Assert that a `recovery.cli` string starts with the canonical prefix.
- *
- * @param cli - The candidate CLI recovery command.
- * @throws Error when the command does not begin with `pragma `.
- */
-export function assertRecoveryCli(cli: string): void {
-  if (!cli.startsWith(RECOVERY_CLI_PREFIX)) {
-    throw new Error(
-      `recovery.cli must start with "${RECOVERY_CLI_PREFIX}" (D5); got "${cli}"`,
-    );
-  }
-}
-
-/**
- * Build a {@link Recovery} whose `cli` command is guaranteed to carry the
- * canonical prefix, optionally pairing it with an MCP tool an agent can call.
+ * 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 cli - The full recovery command, including the `pragma ` prefix.
+ * @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 validated recovery hint.
- * @throws Error when `cli` does not begin with `pragma `.
+ * @returns A recovery hint whose `cli` names this distribution's binary.
  */
 export function cliRecovery(
-  cli: string,
+  command: string,
   message: string,
   mcp?: Recovery["mcp"],
 ): Recovery {
-  assertRecoveryCli(cli);
-  return { message, cli, ...(mcp ? { mcp } : {}) };
+  return {
+    message,
+    cli: `${RECOVERY_CLI_PREFIX}${command}`,
+    ...(mcp ? { mcp } : {}),
+  };
 }

package/src/kernel/error/renderError.ts

@@ -7,6 +7,7 @@
  * whichever transport they use.
  */
 
+import type { OutputFormat } from "../../constants.js";
 import type { PragmaError } from "./PragmaError.js";
 import { serializeError } from "./serialize.js";
 
@@ -98,4 +99,44 @@ function renderErrorJson(error: PragmaError): string {
   return JSON.stringify({ ok: false, error: serializeError(error) });
 }
 
-export { renderErrorJson, renderErrorLlm, renderErrorPlain };
+/**
+ * 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: PragmaError,
+  format: OutputFormat,
+): string | undefined {
+  if (format === "json") return renderErrorJson(error);
+  if (format === "llm") return renderErrorLlm(error);
+  return undefined;
+}
+
+export {
+  renderErrorForFormat,
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+};

package/src/kernel/error/types.ts

@@ -14,14 +14,18 @@ type ErrorCode = (typeof ERROR_CODES)[number];
 /**
  * Structured recovery hint attached to a {@link PragmaError}.
  *
- * `cli` — when present — is the exact command the user can run to recover; it
- * always begins with the literal `pragma ` prefix (D5), enforced by
- * {@link assertRecoveryCli}.
+ * `cli` — when present — is the command as a user would type it: this
+ * distribution's own bin name (`RECOVERY_CLI_PREFIX`) plus a grammar path (D5).
+ * `cliRecovery` takes the path alone and prepends the prefix, so there is no
+ * assertion to make; the one COMPUTED producer (the create mount) derives
+ * the prefix from the program's own name, pinned by a test expectation
+ * COMPOSED from `RECOVERY_CLI_PREFIX` — the routes are enumerated in the
+ * docblock on `error/recovery.ts`.
  */
 interface Recovery {
   /** Human-readable recovery guidance. */
   message: string;
-  /** CLI command the user can run to recover (starts with `pragma `). */
+  /** CLI command the user can run to recover, bin name included. */
   cli?: string;
   /** MCP tool invocation an agent can call to recover. */
   mcp?: { tool: string; params?: Record<string, unknown> };
@@ -53,6 +57,23 @@ interface PragmaErrorData {
 interface ErrorPayload {
   readonly code: ErrorCode;
   readonly message: string;
+  /**
+   * Fuzzy-matched alternative names — BARE candidate tokens the caller can
+   * substitute for the one token it typed (a verb, a tree segment), never
+   * full invocations. The FUZZY tiers serialize this one convention:
+   * bin.ts's unknown-command tier emits the candidate name (`block`) and
+   * the create mount's unknown-segment tier the candidate segment
+   * (`react`); the corrected full command line, when one is shown, lives
+   * in the default prose did-you-mean rendering, not in this field. An
+   * excess positional is NOT a fuzzy match — its matched operand may be
+   * the very token its message calls unexpected, or one the message never
+   * names — so that producer omits this field entirely and instead ships
+   * the runnable corrected command as `recovery.cli` WHEN an operand
+   * names a sibling or child segment resolving to a declared runnable
+   * leaf (the prose did-you-mean condition, narrowed to runnable — a
+   * matched namespace keeps the prose hint but ships no recovery); with
+   * no runnable match the envelope carries neither optional field.
+   */
   readonly suggestions?: readonly string[];
   readonly recovery?: Recovery;
   readonly validOptions?: readonly string[];

package/src/kernel/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 — 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 type { DeclaredVocabulary } from "./vocabulary.js";
+export { VOCABULARY } from "./vocabulary.js";