@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { errorEnvelope, successEnvelope } from "../render/envelope.js";
+import { PragmaError } from "./PragmaError.js";
+import { cliRecovery } from "./recovery.js";
+import { serializeError } from "./serialize.js";
+
+describe("PragmaError factories", () => {
+  it("notFound carries entity, suggestions, and code", () => {
+    const error = PragmaError.notFound("block", "Buton", {
+      suggestions: ["Button"],
+    });
+    expect(error.code).toBe("ENTITY_NOT_FOUND");
+    expect(error.entity).toEqual({ type: "block", name: "Buton" });
+    expect(error.suggestions).toEqual(["Button"]);
+    expect(error.message).toBe('block "Buton" not found.');
+  });
+
+  it("emptyResults defaults its message and keeps filters", () => {
+    const error = PragmaError.emptyResults("token", {
+      filters: { channel: "stable" },
+    });
+    expect(error.code).toBe("EMPTY_RESULTS");
+    expect(error.message).toBe("No tokens found.");
+    expect(error.filters).toEqual({ channel: "stable" });
+  });
+
+  it("invalidInput enumerates valid options", () => {
+    const error = PragmaError.invalidInput("format", "yaml", {
+      validOptions: ["plain", "json"],
+    });
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.validOptions).toEqual(["plain", "json"]);
+  });
+
+  it("unknownVerb names the token", () => {
+    const error = PragmaError.unknownVerb("frobnicate");
+    expect(error.code).toBe("UNKNOWN_VERB");
+    expect(error.message).toBe('Unknown command "frobnicate".');
+  });
+
+  it("storeUnavailable takes its own class", () => {
+    const error = PragmaError.storeUnavailable("connection refused");
+    expect(error.code).toBe("STORE_UNAVAILABLE");
+    expect(error.message).toContain("connection refused");
+  });
+
+  it("configError passes the reason through verbatim", () => {
+    const error = PragmaError.configError("bad channel", {
+      validOptions: ["normal"],
+    });
+    expect(error.code).toBe("CONFIG_ERROR");
+    expect(error.message).toBe("bad channel");
+    expect(error.validOptions).toEqual(["normal"]);
+  });
+
+  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." });
+  });
+});
+
+describe("serializeError", () => {
+  it("omits empty and absent optional fields", () => {
+    const error = PragmaError.internalError("boom");
+    expect(serializeError(error)).toEqual({
+      code: "INTERNAL_ERROR",
+      message: "Internal error: boom",
+      recovery: { message: "Please report this issue." },
+    });
+  });
+
+  it("includes suggestions, recovery, validOptions, and filters when present", () => {
+    const error = PragmaError.notFound("block", "Buton", {
+      suggestions: ["Button"],
+      recovery: cliRecovery("pragma block list", "List blocks."),
+    });
+    expect(serializeError(error)).toEqual({
+      code: "ENTITY_NOT_FOUND",
+      message: 'block "Buton" not found.',
+      suggestions: ["Button"],
+      recovery: { cli: "pragma block list", message: "List blocks." },
+    });
+  });
+});
+
+describe("envelope builders", () => {
+  it("wraps success data with default empty meta", () => {
+    expect(successEnvelope({ made: true })).toEqual({
+      ok: true,
+      data: { made: true },
+      meta: {},
+    });
+  });
+
+  it("carries plan-first meta through", () => {
+    expect(
+      successEnvelope({ plan: [] }, { planOnly: true, confirmRequired: true }),
+    ).toEqual({
+      ok: true,
+      data: { plan: [] },
+      meta: { planOnly: true, confirmRequired: true },
+    });
+  });
+
+  it("wraps an error into the failure envelope", () => {
+    const error = PragmaError.invalidInput("format", "yaml", {
+      validOptions: ["plain", "json"],
+    });
+    expect(errorEnvelope(error)).toEqual({
+      ok: false,
+      error: {
+        code: "INVALID_INPUT",
+        message: 'Invalid format "yaml".',
+        validOptions: ["plain", "json"],
+      },
+    });
+  });
+});

package/src/kernel/error/PragmaError.ts

@@ -0,0 +1,182 @@
+import type { ErrorCode, PragmaErrorData, Recovery } from "./types.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. */
+  readonly code: ErrorCode;
+  /** Entity that triggered the error (type + name), if applicable. */
+  readonly entity: PragmaErrorData["entity"];
+  /** Fuzzy-matched alternative names the user may have intended. */
+  readonly suggestions: string[];
+  /** Structured recovery hint with optional CLI command or MCP tool call. */
+  readonly recovery: Recovery | undefined;
+  /** Active filters at the time of the error, for diagnostic context. */
+  readonly filters: Record<string, string> | undefined;
+  /** Enumerated valid options when input was rejected. */
+  readonly validOptions: string[] | undefined;
+
+  /**
+   * @param data - Structured error payload.
+   */
+  constructor(data: PragmaErrorData) {
+    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: string,
+    entityName: string,
+    opts: { suggestions?: string[]; recovery?: Recovery } = {},
+  ): PragmaError {
+    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: string,
+    opts: {
+      message?: string;
+      filters?: Record<string, string>;
+      recovery?: Recovery;
+      validOptions?: string[];
+    } = {},
+  ): PragmaError {
+    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: string,
+    value: string,
+    opts: { validOptions?: string[]; recovery?: Recovery } = {},
+  ): PragmaError {
+    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: string,
+    opts: { suggestions?: string[]; recovery?: Recovery } = {},
+  ): PragmaError {
+    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: string,
+    opts: { recovery?: Recovery } = {},
+  ): PragmaError {
+    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: string,
+    opts: { validOptions?: string[]; recovery?: Recovery } = {},
+  ): PragmaError {
+    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 "please report" hint.
+   */
+  static internalError(reason: string): PragmaError {
+    return new PragmaError({
+      code: "INTERNAL_ERROR",
+      message: `Internal error: ${reason}`,
+      recovery: { message: "Please report this issue." },
+    });
+  }
+}
+
+export { PragmaError };

package/src/kernel/error/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 "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
+  // 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",
+] as const;
+
+export { ERROR_CODES };

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

@@ -0,0 +1,83 @@
+import { TaskExecutionError } from "@canonical/task";
+import { describe, expect, it } from "vitest";
+import {
+  asPragmaError,
+  CANCELLED_MESSAGE,
+  isCancellation,
+  isInterruption,
+} from "./fromTaskError.js";
+import { PragmaError } from "./PragmaError.js";
+
+describe("fromTaskError bridge", () => {
+  it("recognises a declined confirm gate as a cancellation", () => {
+    const err = new TaskExecutionError({
+      code: "GENERATOR_CANCELLED",
+      message: "Cancelled.",
+    });
+    expect(isCancellation(err)).toBe(true);
+    expect(CANCELLED_MESSAGE).toBe("Cancelled.");
+  });
+
+  it("does not treat other failures as cancellations", () => {
+    expect(isCancellation(new Error("boom"))).toBe(false);
+    expect(
+      isCancellation(
+        new TaskExecutionError({ code: "INTERNAL", message: "boom" }),
+      ),
+    ).toBe(false);
+    expect(isCancellation("nope")).toBe(false);
+    expect(isCancellation(null)).toBe(false);
+    // An interrupt is NOT a cancellation (different exit code).
+    expect(
+      isCancellation(
+        new TaskExecutionError({ code: "TASK_INTERRUPTED", message: "x" }),
+      ),
+    ).toBe(false);
+  });
+
+  it("recognises an interpreter interrupt (SIGINT / in-wizard Ctrl-C mid-run)", () => {
+    const err = new TaskExecutionError({
+      code: "TASK_INTERRUPTED",
+      message: "Task interrupted",
+    });
+    expect(isInterruption(err)).toBe(true);
+    // A decline is not an interruption, and vice-versa — they exit differently.
+    expect(
+      isInterruption(
+        new TaskExecutionError({
+          code: "GENERATOR_CANCELLED",
+          message: "Cancelled.",
+        }),
+      ),
+    ).toBe(false);
+    expect(isInterruption(new Error("boom"))).toBe(false);
+    expect(isInterruption(null)).toBe(false);
+  });
+
+  it("maps absent/invalid answer codes to a usage error (INVALID_INPUT)", () => {
+    for (const code of [
+      "MISSING_REQUIRED_ANSWER",
+      "GENERATOR_INVALID_ANSWER",
+    ]) {
+      const mapped = asPragmaError(
+        new TaskExecutionError({ code, message: "bad answer" }),
+      );
+      expect(mapped).toBeInstanceOf(PragmaError);
+      expect(mapped.code).toBe("INVALID_INPUT");
+      expect(mapped.message).toBe("bad answer");
+    }
+  });
+
+  it("passes a PragmaError through unchanged", () => {
+    const original = PragmaError.notFound("thing", "x");
+    expect(asPragmaError(original)).toBe(original);
+  });
+
+  it("keeps an unknown failure as an internal error (with a report hint)", () => {
+    const mapped = asPragmaError(new Error("kaboom"));
+    expect(mapped.code).toBe("INTERNAL_ERROR");
+    expect(mapped.message).toContain("kaboom");
+    // Genuine bugs still say "report this issue"; a cancel never reaches here.
+    expect(mapped.recovery?.message).toMatch(/report this issue/i);
+  });
+});

package/src/kernel/error/fromTaskError.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 + "please 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<string>([
+  "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: unknown): string | undefined {
+  if (error && typeof error === "object" && "code" in error) {
+    const { code } = error as { code: unknown };
+    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: unknown): boolean {
+  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: unknown): boolean {
+  return taskErrorCode(error) === TASK_INTERRUPTED;
+}
+
+/**
+ * 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.
+ */
+export function asPragmaError(error: unknown): PragmaError {
+  if (error instanceof PragmaError) return error;
+  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);
+}

package/src/kernel/error/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { assertRecoveryCli, cliRecovery } from "./recovery.js";
+export {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "./renderError.js";
+export { serializeError } from "./serialize.js";
+export type {
+  ErrorCode,
+  ErrorPayload,
+  PragmaErrorData,
+  Recovery,
+} from "./types.js";

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
+import { PragmaError } from "./PragmaError.js";
+import { assertRecoveryCli, 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.
+    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({
+      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."),
+      }),
+    ];
+    for (const error of errors) {
+      if (error.recovery?.cli) {
+        expect(() =>
+          assertRecoveryCli(error.recovery.cli as string),
+        ).not.toThrow();
+      }
+    }
+  });
+});

package/src/kernel/error/recovery.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+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.
+ *
+ * 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 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 `.
+ */
+export function cliRecovery(
+  cli: string,
+  message: string,
+  mcp?: Recovery["mcp"],
+): Recovery {
+  assertRecoveryCli(cli);
+  return { message, cli, ...(mcp ? { mcp } : {}) };
+}