@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/tier/lookup.verb.ts

@@ -0,0 +1,44 @@
+/**
+ * `tier lookup <name>` — the covenant `tier_lookup` tool.
+ *
+ * Bespoke store-backed lookup with a SINGLE `<name>` positional (a pack lookup
+ * would emit the variadic `<name...>`), so it emits
+ * `{ v: "lookup", args: ["<name>"], needsStore: true, mcp: "tier_lookup" }`.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { type TierLookupData, tierLookupFormatters } from "./lookup.render.js";
+
+const tierLookupSpec: VerbSpec<Record<string, unknown>, TierLookupData> = {
+  path: ["tier", "lookup"],
+  summary: "Show one tier by name, with the blocks scoped to it.",
+  doc: "Look up a single tier by its name (e.g. apps/lxd) and list the blocks scoped directly to it.",
+  params: [
+    {
+      kind: "string",
+      name: "name",
+      doc: "The tier name (e.g. apps/lxd).",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "tiers" } },
+    },
+  ],
+  output: { formatters: tierLookupFormatters },
+  examples: [{ cmd: "pragma tier lookup apps/lxd" }],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (params, rt) =>
+    import("./runLookup.js").then((m) =>
+      m.runTierLookup(rt, String(params.name)),
+    ),
+};
+
+/** The `tier lookup` verb, widened for registry composition. */
+export const tierLookupVerb = asVerb(tierLookupSpec);

package/src/capabilities/tier/pack.ts

@@ -0,0 +1,28 @@
+/**
+ * The bundled `tier` pack — a flat, name-ordered list story.
+ *
+ * Tier hierarchy is encoded in the slash-separated path string (`apps/lxd`), not
+ * in graph edges, so `tier list` is a flat list; the ordered-inheritance logic
+ * lives in the block list's tier chain. SPARQL-sourced (a flat-ordered list).
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+export const tierPack: PackDefinition = {
+  noun: "tier",
+  description: "List all tiers in the design system ontology.",
+  toolDescription:
+    "List all tiers in the design-system ontology. Use when understanding the tier hierarchy before setting a tier filter. Example: tier_list {}.",
+  list: {
+    query: [
+      "SELECT ?uri ?name WHERE {",
+      "  ?uri a ds:Tier ;",
+      "       ds:name ?name .",
+      "} ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+    ],
+  },
+};

package/src/capabilities/tier/runLookup.ts

@@ -0,0 +1,87 @@
+/**
+ * The `tier lookup` run body (lazily imported, off the fast path).
+ *
+ * Bespoke (not a pack lookup): the covenant freezes `tier_lookup` with a SINGLE
+ * `<name>` positional, whereas a pack lookup emits the variadic `<name...>`.
+ * Resolves the tier by its `ds:name` and returns the blocks scoped directly to
+ * it (a joined OPTIONAL, so a tier with no direct members still resolves).
+ */
+
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { runSelect } from "../../kernel/packs/sparql/runSelect.js";
+import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
+import { compactUri } from "../../kernel/render/compactUri.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { TierLookupData } from "./lookup.render.js";
+
+/**
+ * Read every tier name in the store (its `ds:name`), ordered.
+ *
+ * The bespoke lookup already holds the machinery to reach the store, so a
+ * name-not-found can rank "did you mean?" candidates the same way every other
+ * entity lookup does — the tier list is a single cheap SELECT away.
+ *
+ * @param rt - The runtime (its store is booted by the projector for needsStore).
+ * @returns The tier names, ordered.
+ * @note Impure — queries the store through `runSelect`.
+ */
+async function selectTierNames(rt: PragmaRuntime): Promise<string[]> {
+  const rows = await runSelect(
+    rt,
+    "SELECT ?name WHERE { ?tier a ds:Tier ; ds:name ?name } ORDER BY ?name",
+    "tier",
+  );
+  return rows
+    .map((row) => row.name as string | undefined)
+    .filter((name): name is string => Boolean(name));
+}
+
+/**
+ * Look up one tier by name.
+ *
+ * @param rt - The runtime (its store is booted by the projector for needsStore).
+ * @param name - The tier name (its `ds:name`, e.g. `apps/lxd`).
+ * @returns The tier's IRI, name, and directly-scoped block names.
+ * @throws PragmaError ENTITY_NOT_FOUND when no tier has that name;
+ *   STORE_UNAVAILABLE (exit 3) when the store is unseeded for this project.
+ */
+export async function runTierLookup(
+  rt: PragmaRuntime,
+  name: string,
+): Promise<TierLookupData> {
+  const query = [
+    "SELECT ?uri ?blockName WHERE {",
+    "  ?uri a ds:Tier ; ds:name ?tierName .",
+    `  FILTER(STR(?tierName) = ${JSON.stringify(name)})`,
+    "  OPTIONAL { ?block ds:tier ?uri ; ds:name ?blockName }",
+    "}",
+    "ORDER BY ?blockName",
+  ].join("\n");
+
+  // Route through `runSelect` (not `rt.query.sparql` directly) so a cold/unseeded
+  // store — a generated `ds:` query hitting an unknown prefix — is remapped to an
+  // actionable STORE_UNAVAILABLE with `pragma sources update` recovery, instead of
+  // a raw "Prefix not found" collapsing to INTERNAL_ERROR at the boundary.
+  const rows = await runSelect(rt, query, "tier");
+  const uri = rows[0]?.uri;
+  if (!uri) {
+    // Rank "did you mean?" candidates from the full tier list — the only entity
+    // lookup that used to omit suggestions, though (like the others) it has the
+    // names in hand. The suggestion query runs only on this cold, not-found path.
+    const suggestions = suggestNames(name, await selectTierNames(rt));
+    throw PragmaError.notFound("tier", name, {
+      suggestions,
+      recovery: {
+        message: "List available tiers.",
+        cli: "pragma tier list",
+        mcp: { tool: "tier_list" },
+      },
+    });
+  }
+  const blocks = rows
+    // `blockName` rides an OPTIONAL, so the key is absent for a memberless tier.
+    .map((row) => row.blockName as string | undefined)
+    .filter((block): block is string => Boolean(block));
+  return { uri: compactUri(uri, DEFAULT_PREFIX_MAP), name, blocks };
+}

package/src/capabilities/token/addConfig.render.ts

@@ -0,0 +1,27 @@
+/**
+ * Formatters for `token add-config` — plain, llm, json.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { AddConfigResult } from "./runAddConfig.js";
+
+export const addConfigFormatters: Formatters<AddConfigResult> = {
+  plain(data) {
+    const lines = [
+      `${data.alreadyExisted ? "Updated" : "Wrote"} ${data.path}`,
+      `  ${data.tokenCount} token${data.tokenCount === 1 ? "" : "s"} in the active graph`,
+      `  sources: ${data.sources.join(", ")}`,
+    ];
+    return lines.join("\n");
+  },
+  llm(data) {
+    return [
+      `${data.alreadyExisted ? "Updated" : "Wrote"} \`${data.path}\` for the terrazzo token pipeline.`,
+      `- ${data.tokenCount} token(s) in the active graph`,
+      `- sources: ${data.sources.map((source) => `\`${source}\``).join(", ")}`,
+    ].join("\n");
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/token/addConfig.test.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import type { McpHarness } from "../../testing/helpers/projectMcp.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
+
+let fixture: FixtureGraph;
+let mcp: McpHarness;
+let configPath: string;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+  configPath = join(fixture.cwd, "tokens.config.mjs");
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+beforeEach(() => {
+  rmSync(configPath, { force: true });
+});
+
+describe("token_add-config — plan-first mutation (PROTECTED)", () => {
+  it("without confirm, returns a plan and writes NOTHING", async () => {
+    const result = await mcp.callTool("token_add-config");
+    expect(result.ok).toBe(true);
+    const meta = result.meta as {
+      planOnly?: boolean;
+      confirmRequired?: boolean;
+    };
+    expect(meta.planOnly).toBe(true);
+    expect(meta.confirmRequired).toBe(true);
+    const data = result.data as { plan: string[] };
+    expect(data.plan.join("\n")).toMatch(/tokens\.config\.mjs/);
+    expect(existsSync(configPath)).toBe(false);
+  });
+
+  it("with confirm, writes a terrazzo config reflecting the store token count", async () => {
+    const result = await mcp.callTool("token_add-config", { confirm: true });
+    expect(result.ok).toBe(true);
+    const data = result.data as {
+      path: string;
+      tokenCount: number;
+      sources: string[];
+    };
+    expect(existsSync(configPath)).toBe(true);
+    // The canonical fixture holds 2 ds:Token entities.
+    expect(data.tokenCount).toBe(2);
+    const written = readFileSync(configPath, "utf-8");
+    expect(written).toContain("defineConfig");
+    expect(written).toContain("@canonical/terrazzo");
+  });
+});

package/src/capabilities/token/addConfig.verb.ts

@@ -0,0 +1,40 @@
+/**
+ * `token add-config` — generate a terrazzo `tokens.config.mjs` (the one `token`
+ * mutation). Store-backed (needsStore, per covenant) so it can report the token
+ * count; plan-first through the uniform mutation seam (a tool call without
+ * `confirm` returns the write plan; `--dry-run`/`--yes` on the CLI). No params —
+ * the covenant emits `{ v: "add-config", mutates: true, needsStore: true }`.
+ */
+
+import type { Task } from "@canonical/task";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { addConfigFormatters } from "./addConfig.render.js";
+import type { AddConfigResult } from "./runAddConfig.js";
+
+const addConfigVerb: VerbSpec<Record<string, unknown>, AddConfigResult> = {
+  path: ["token", "add-config"],
+  summary: "Generate a tokens.config.mjs for the terrazzo token pipeline.",
+  doc: "Writes a terrazzo `defineConfig` at the project root, sourcing token JSON from the configured design-system packages. Store-backed so it reports how many tokens the active graph holds. Plan-first: returns the write plan until you confirm.",
+  params: [],
+  output: { formatters: addConfigFormatters },
+  examples: [
+    { cmd: "pragma token add-config --dry-run", note: "preview the write" },
+    { cmd: "pragma token add-config --yes", note: "write the config" },
+  ],
+  capability: {
+    needsStore: true,
+    mutates: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+  },
+  run: (_params, rt) =>
+    import("./runAddConfig.js").then((m) =>
+      m.runAddConfig(rt),
+    ) as unknown as Task<AddConfigResult>,
+};
+
+/** The `token add-config` verb, widened for registry composition. */
+export const tokenAddConfigVerb = asVerb(addConfigVerb);

package/src/capabilities/token/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The `token` capability module — the bundled SPARQL pack compiled to verbs.
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { tokenAddConfigVerb } from "./addConfig.verb.js";
+import { tokenPack } from "./pack.js";
+
+/** The `token` capability module — the bundled read pack plus the `add-config`
+ * mutation (hand-written; the pack compiler emits reads only). */
+export const tokenModule: CapabilityModule = {
+  name: "token",
+  verbs: [
+    ...compilePack(tokenPack, "bundled:token", DEFAULT_PREFIX_MAP),
+    tokenAddConfigVerb,
+  ],
+};

package/src/capabilities/token/pack.ts

@@ -0,0 +1,58 @@
+/**
+ * The bundled `token` pack — design tokens as data.
+ *
+ * SPARQL-sourced on both verbs: there is no `ds:Token` GraphQL type to project
+ * against when the graph ships no tokens, and the lookup reads a property path
+ * (`ds:tokenType/rdfs:label`) only SPARQL can express. `token add-config` (a
+ * mutation) is out of PR3; the `emptyRecovery` install hint is the story users
+ * see on an empty store.
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+export const tokenPack: PackDefinition = {
+  noun: "token",
+  description: "List all design tokens.",
+  toolDescription:
+    "List all design tokens with their type. Use when browsing which tokens exist under the active scope. Example: token_list {}.",
+  list: {
+    query: [
+      "SELECT ?uri ?name ?category WHERE {",
+      "  ?uri a ds:Token ;",
+      "       ds:tokenId ?name .",
+      "  OPTIONAL {",
+      "    ?uri ds:tokenType ?type .",
+      "    ?type rdfs:label ?category .",
+      "  }",
+      "}",
+      "ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+      { field: "category", label: "Type" },
+    ],
+    emptyRecovery: {
+      message:
+        "No tokens in the store. Build it from the configured design-system packages.",
+      cli: "pragma sources update",
+    },
+  },
+  lookup: {
+    source: "sparql",
+    by: "ds:tokenId",
+    type: "ds:Token",
+    toolDescription:
+      'Get type and theme values for one or more design tokens by name. Use when resolving specific tokens\' light/dark values. Example: token_lookup { names: ["color.primary"] }.',
+    fields: [
+      { name: "category", property: "ds:tokenType/rdfs:label", label: "Type" },
+      { name: "valueLight", property: "ds:valueLight", label: "Light value" },
+      { name: "valueDark", property: "ds:valueDark", label: "Dark value" },
+    ],
+    sample: {
+      fixedCount: true,
+      toolDescription:
+        "Return randomly selected complete design tokens (with theme values) as exemplars. Use BEFORE writing queries to see actual data shapes.",
+    },
+  },
+};

package/src/capabilities/token/runAddConfig.ts

@@ -0,0 +1,95 @@
+/**
+ * The `token add-config` write body (lazily imported, off the fast path).
+ *
+ * A store-backed mutation: it counts the design tokens in the active graph (so
+ * the plan reports how many tokens the config will cover) and derives the
+ * terrazzo token-source globs from the configured design-system packages, then
+ * returns a Task that writes `tokens.config.mjs`. The store read happens in the
+ * async setup; the file write is the Task's single `WriteFile` effect, so a
+ * plan-only preview (`mutation.preview`) describes the write without performing
+ * it. Ported from the old shell's `token add-config` (terrazzo `defineConfig`).
+ */
+
+import { resolve } from "node:path";
+import { $, exists, gen, type Task, writeFile } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+
+/** The default token source when no design-system packages are configured. */
+const DEFAULT_TOKEN_SOURCE =
+  "node_modules/@canonical/ds-global/tokens/**/*.json";
+
+/** The result of generating a terrazzo tokens config. */
+export interface AddConfigResult {
+  /** The absolute path written. */
+  readonly path: string;
+  /** How many `ds:Token` entities the active graph holds. */
+  readonly tokenCount: number;
+  /** The token-source globs written into the config. */
+  readonly sources: readonly string[];
+  /** Whether a `tokens.config.mjs` already existed (it is overwritten). */
+  readonly alreadyExisted: boolean;
+}
+
+/** Count the `ds:Token` entities in the booted store (best-effort). */
+async function countTokens(rt: PragmaRuntime): Promise<number> {
+  try {
+    const result = (await rt.query.sparql(
+      "SELECT (COUNT(DISTINCT ?token) AS ?count) WHERE { ?token a ds:Token }",
+    )) as { type?: string; bindings?: { count?: string }[] };
+    const raw = result.bindings?.[0]?.count;
+    return raw ? Number(raw) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Derive the terrazzo token-source globs from the configured packages. */
+async function resolveSources(rt: PragmaRuntime): Promise<string[]> {
+  const { config } = await rt.loadConfig();
+  const packages = config.packages ?? [];
+  if (packages.length === 0) return [DEFAULT_TOKEN_SOURCE];
+  return packages.map((pkg) => {
+    const name = typeof pkg === "string" ? pkg : pkg.name;
+    return `node_modules/${name}/tokens/**/*.json`;
+  });
+}
+
+/** Render the terrazzo `tokens.config.mjs` content. */
+function generateConfig(sources: readonly string[]): string {
+  const sourceList = sources
+    .map((source) => `    ${JSON.stringify(source)}`)
+    .join(",\n");
+  return `// tokens.config.mjs — generated by \`pragma token add-config\`
+import { defineConfig } from "@canonical/terrazzo";
+
+export default defineConfig({
+  tokens: [
+${sourceList},
+  ],
+  outDir: "./tokens/",
+  plugins: [],
+});
+`;
+}
+
+/**
+ * Build the Task that writes `tokens.config.mjs` for the terrazzo pipeline.
+ *
+ * @param rt - The runtime (its store is booted by the projector for needsStore).
+ * @returns A Task yielding the write outcome.
+ * @note Impure — reads the store + config; the write is the Task's effect.
+ */
+export async function runAddConfig(
+  rt: PragmaRuntime,
+): Promise<Task<AddConfigResult>> {
+  const tokenCount = await countTokens(rt);
+  const sources = await resolveSources(rt);
+  const path = resolve(rt.cwd, "tokens.config.mjs");
+  const content = generateConfig(sources);
+
+  return gen(function* () {
+    const alreadyExisted = yield* $(exists(path));
+    yield* $(writeFile(path, content));
+    return { path, tokenCount, sources, alreadyExisted };
+  });
+}

package/src/capabilities/upgrade/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `upgrade` capability barrel.
+ */
+
+export type { UpgradeData } from "./types.js";
+export { upgradeModule } from "./upgrade.verb.js";

package/src/capabilities/upgrade/runUpgrade.ts

@@ -0,0 +1,119 @@
+/**
+ * Build the `upgrade` Task (lazily imported, off the fast path).
+ *
+ * Async-setup then compose: read the channel, detect the install source, and
+ * check the registry (a preview-safe READ — no side effect), then return a Task
+ * shaped by the outcome. The `exec` effect is the SOLE mutation, so the effect
+ * seam does the rest for free:
+ *
+ * - `--dry-run` (dispatcher `dryRun`) MOCKS the exec and describes the plan —
+ *   both the `Log` version-delta line AND the `Execute: <command>` line show,
+ *   and nothing runs.
+ * - `--yes` / MCP `confirm` runs the exec for real; a nonzero exit is surfaced
+ *   by `assertExecOk` as an actionable UNSUPPORTED (exit 1) — the interpreter
+ *   RESOLVES on a nonzero exit, so the check is the consumer's job.
+ * - offline / already-latest carry NO exec — a real run just returns the status.
+ *
+ * The whole registry read is preview-safe, so no `mutation.preview` gating is
+ * needed here (unlike `sources update`, whose heavy resolve must be gated).
+ * `run` returns `Promise<Task<R>>`, presented through the `Task<R>` arm by the
+ * honest cast at the verb (the `update.verb.ts` precedent).
+ */
+
+import { $, exec, gen, info, type Task, warn } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { assertExecOk, guardMissingBinary } from "../shared/assertExecOk.js";
+import {
+  detectInstallSource,
+  pmUpdateCommand,
+} from "../shared/packageManager.js";
+import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { UpgradeData } from "./types.js";
+
+/**
+ * Resolve the upgrade state and compose the corresponding Task.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns A Task yielding the upgrade outcome (its exec runs only on a real,
+ *   update-needed execution).
+ * @note Impure — reads the config + the registry (the exec is the only mutation,
+ *   and it runs only under a real, update-needed execution).
+ */
+export async function runUpgrade(
+  rt: PragmaRuntime,
+): Promise<Task<UpgradeData>> {
+  const { channel } = (await rt.loadConfig()).config;
+  const install = detectInstallSource();
+  const command = pmUpdateCommand(install.pm, PRAGMA_PACKAGE);
+  const pm = install.label;
+  const current = rt.version;
+
+  const registry = await checkRegistryVersion(PRAGMA_PACKAGE, channel);
+
+  if (registry === undefined) {
+    const data: UpgradeData = {
+      pm,
+      current,
+      latest: undefined,
+      command,
+      offline: true,
+      alreadyLatest: false,
+      executed: false,
+    };
+    return gen(function* () {
+      yield* $(
+        warn("Could not reach the registry — skipped the update check."),
+      );
+      return data;
+    });
+  }
+
+  if (registry.latest === current) {
+    const data: UpgradeData = {
+      pm,
+      current,
+      latest: registry.latest,
+      command,
+      offline: false,
+      alreadyLatest: true,
+      executed: false,
+    };
+    return gen(function* () {
+      yield* $(info(`Already at the latest version (${current}).`));
+      return data;
+    });
+  }
+
+  const data: UpgradeData = {
+    pm,
+    current,
+    latest: registry.latest,
+    command,
+    offline: false,
+    alreadyLatest: false,
+    executed: true,
+  };
+  const parts = command.split(" ");
+  const bin = parts[0] ?? "npm";
+  const args = parts.slice(1);
+  // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
+  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("please report
+  // this issue"). Surface it as a named "`<pm>` not found on PATH" instead.
+  return guardMissingBinary(
+    bin,
+    {
+      message: `Install ${pm} (or your package manager) and ensure it is on your PATH, then try again.`,
+    },
+    gen(function* () {
+      // The version-delta rides a Log effect, so `--dry-run` describes it too.
+      yield* $(info(`${current} → ${registry.latest}`));
+      // The one mutation — mocked under dry-run, run for real under --yes/confirm.
+      // The interpreter RESOLVES on a nonzero exit (only a spawn error rejects),
+      // so inspect the result: a failed install (e.g. EACCES on a global
+      // `npm i -g`) must fail loudly, not report a silent success.
+      const result = yield* $(exec(bin, args, rt.cwd));
+      assertExecOk(command, result);
+      return data;
+    }),
+  );
+}

package/src/capabilities/upgrade/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Data shape for `pragma upgrade`.
+ */
+
+/** The outcome of an upgrade run (or its plan). */
+export interface UpgradeData {
+  /** The install-source label (e.g. `bun (global)`). */
+  readonly pm: string;
+  /** The currently-installed version. */
+  readonly current: string;
+  /** The latest published version, or `undefined` when offline. */
+  readonly latest: string | undefined;
+  /** The package-manager command that applies the update. */
+  readonly command: string;
+  /** True when the registry could not be reached. */
+  readonly offline: boolean;
+  /** True when the installed version is already the latest. */
+  readonly alreadyLatest: boolean;
+  /** True when the update command was actually executed (a real run). */
+  readonly executed: boolean;
+}

package/src/capabilities/upgrade/upgrade.render.ts

@@ -0,0 +1,55 @@
+/**
+ * Formatters for `pragma upgrade` — plain (chalk), llm, json.
+ *
+ * Renders the REAL-run outcome (the `--dry-run` plan is rendered by the
+ * dispatcher's plan renderer, not here), so there is no "would run" branch: a
+ * needed run always carries `executed: true`.
+ */
+
+import chalk from "chalk";
+import type { Formatters } from "../../kernel/spec/types.js";
+import { PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { UpgradeData } from "./types.js";
+
+export const upgradeFormatters: Formatters<UpgradeData> = {
+  plain(data) {
+    const lines = [`Installed via: ${data.pm}`];
+    if (data.offline) {
+      lines.push("Could not reach the registry — try again later.");
+      return lines.join("\n");
+    }
+    if (data.alreadyLatest) {
+      lines.push(`Already at the latest version (${data.current}).`);
+      return lines.join("\n");
+    }
+    lines.push(
+      "",
+      `${PRAGMA_PACKAGE}  ${data.current} → ${chalk.green(String(data.latest))}`,
+      "",
+    );
+    if (data.executed) {
+      lines.push(
+        `Ran: ${chalk.cyan(data.command)}`,
+        "",
+        `Updated to ${data.latest}.`,
+      );
+    } else {
+      lines.push(`Run: ${chalk.cyan(data.command)}`);
+    }
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    if (data.offline)
+      return "Upgrade check failed: could not reach the registry.";
+    if (data.alreadyLatest) {
+      return `Already at the latest version (${data.current}).`;
+    }
+    if (data.executed) return `Upgraded: ${data.current} → ${data.latest}`;
+    return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};