@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/graph/query.test.ts

@@ -0,0 +1,156 @@
+/**
+ * `graph query` — the raw SPARQL escape hatch over the canonical fixture graph.
+ *
+ * Exercises SELECT / ASK / CONSTRUCT with deterministic results (4 canonical
+ * `ds:Component`s, COUNT=4), the syntax-error → INVALID_INPUT + `ontology_list`
+ * recovery, the `needsStore` boot, and CLI-json ≡ MCP `graph_query` parity.
+ * Closes the PARITY_GAP `graph-query-deferred`.
+ */
+
+import type { QueryResult } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { graphModule } from "./index.js";
+
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+const FLAGS_JSON: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+
+const queryVerb = graphModule.verbs.find(
+  (v) => v.path[1] === "query",
+) as VerbSpec;
+
+let fixture: FixtureGraph;
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({
+    ttl: CANONICAL_TTL,
+    config: ALL_VISIBLE_CONFIG,
+  });
+});
+afterAll(async () => {
+  await fixture.dispose();
+});
+
+describe("graph query — SELECT / ASK / CONSTRUCT", () => {
+  it("SELECT resolves the 4 canonical components, ordered by name", async () => {
+    const result = (await queryVerb.run(
+      {
+        sparql:
+          "SELECT ?name WHERE { ?c a ds:Component ; ds:name ?name } ORDER BY ?name",
+      },
+      fixture.runtime,
+    )) as QueryResult;
+    expect(result.type).toBe("select");
+    const names =
+      result.type === "select" ? result.bindings.map((b) => b.name) : [];
+    expect(names).toEqual(["Beta Widget", "Button", "LXD Panel", "Modal"]);
+  });
+
+  it("SELECT COUNT(*) over ds:Component is 4", async () => {
+    const result = (await queryVerb.run(
+      { sparql: "SELECT (COUNT(*) AS ?c) WHERE { ?comp a ds:Component }" },
+      fixture.runtime,
+    )) as QueryResult;
+    const count =
+      result.type === "select" ? Number(result.bindings[0]?.c ?? 0) : 0;
+    expect(count).toBe(4);
+  });
+
+  it("ASK returns a boolean", async () => {
+    const yes = (await queryVerb.run(
+      { sparql: "ASK { ?c a ds:Component }" },
+      fixture.runtime,
+    )) as QueryResult;
+    expect(yes).toMatchObject({ type: "ask", result: true });
+
+    const no = (await queryVerb.run(
+      { sparql: "ASK { ds:nonesuch a ds:Component }" },
+      fixture.runtime,
+    )) as QueryResult;
+    expect(no).toMatchObject({ type: "ask", result: false });
+  });
+
+  it("CONSTRUCT returns triples", async () => {
+    const result = (await queryVerb.run(
+      {
+        sparql: "CONSTRUCT { ?c a ds:Component } WHERE { ?c a ds:Component }",
+      },
+      fixture.runtime,
+    )) as QueryResult;
+    expect(result.type).toBe("construct");
+    const triples = result.type === "construct" ? result.triples : [];
+    expect(triples).toHaveLength(4);
+  });
+});
+
+describe("graph query — errors & boot", () => {
+  it("a syntax error is INVALID_INPUT with an ontology_list recovery", async () => {
+    let caught: unknown;
+    try {
+      await queryVerb.run(
+        { sparql: "SELECT ?x WHERE { this is not valid sparql" },
+        fixture.runtime,
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "INVALID_INPUT" });
+    expect(
+      (caught as { recovery?: { mcp?: { tool: string } } }).recovery?.mcp,
+    ).toMatchObject({ tool: "ontology_list" });
+  });
+
+  it("needsStore boots the store before the query runs", async () => {
+    const fresh = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: ALL_VISIBLE_CONFIG,
+    });
+    expect(fresh.runtime.store.booted).toBe(false);
+    const outcome = await executeVerb(
+      queryVerb,
+      { sparql: "SELECT (COUNT(*) AS ?c) WHERE { ?comp a ds:Component }" },
+      NO_MUT,
+      fresh.runtime,
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(fresh.runtime.store.booted).toBe(true);
+    await fresh.dispose();
+  });
+});
+
+describe("graph query — CLI-json ≡ MCP graph_query (PROTECTED)", () => {
+  it("both surfaces return the same envelope over the same graph", async () => {
+    const sparql =
+      "SELECT ?name WHERE { ?c a ds:Component ; ds:name ?name } ORDER BY ?name";
+    const cli = await executeVerb(
+      queryVerb,
+      { sparql },
+      NO_MUT,
+      bootRuntime(FLAGS_JSON, fixture.cwd),
+    );
+    const cliEnvelope = JSON.parse(cli.stdout as string);
+
+    const mcp = await projectMcp([graphModule], fixture.cwd);
+    const mcpEnvelope = await mcp.callTool("graph_query", { sparql });
+    await mcp.cleanup();
+
+    expect(cliEnvelope).toEqual(mcpEnvelope);
+    expect(cliEnvelope.ok).toBe(true);
+  });
+});

package/src/capabilities/graph/query.verb.ts

@@ -0,0 +1,58 @@
+/**
+ * `graph query <sparql>` — the raw SPARQL escape hatch (the twin of `graph
+ * inspect`'s single-entity read). Store-backed and read-only: the dispatcher
+ * boots the store before `run`, and `rt.query.sparql` auto-prefixes the query
+ * from the pack's prefix map, so `ds:Component` resolves without a PREFIX line.
+ *
+ * Injection-safe by construction: the whole query IS the user's text — there is
+ * no interpolation into a template — so there is nothing to escape. A malformed
+ * query surfaces as INVALID_INPUT with a recovery pointer to `ontology list`.
+ */
+
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { queryFormatters } from "./query.render.js";
+
+// Inline `import("…")` type (no `from`) so the ke types stay OFF the static
+// graph — the lazy-dispatch probe forbids a static ke import on any file
+// reachable from capabilities/index, keeping the WASM runtime off the fast path.
+type QueryResult = import("@canonical/ke").QueryResult;
+
+const queryVerb: VerbSpec<Record<string, unknown>, QueryResult> = {
+  path: ["graph", "query"],
+  summary: "Run a raw SPARQL query against the loaded graph.",
+  doc: "Executes an arbitrary SPARQL query (SELECT / ASK / CONSTRUCT) against the store. Prefixes are applied automatically from the pack's namespace map; list the ontology namespaces to discover the available prefixes.",
+  params: [
+    {
+      kind: "string",
+      name: "sparql",
+      doc: "The SPARQL query text (SELECT, ASK, or CONSTRUCT).",
+      positional: true,
+      required: true,
+    },
+  ],
+  output: { formatters: queryFormatters },
+  examples: [
+    {
+      cmd: 'pragma graph query "SELECT ?s WHERE { ?s a ds:Component }"',
+      note: "list every component subject",
+    },
+    {
+      cmd: 'pragma graph query "ASK { ds:button a ds:Component }" --format json',
+    },
+  ],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
+    import("./runQuery.js").then((m) => m.runQuery(rt, String(params.sparql))),
+};
+
+/** The `graph query` verb. */
+export const graphQueryVerb = asVerb(queryVerb);

package/src/capabilities/graph/runQuery.ts

@@ -0,0 +1,49 @@
+/**
+ * The `graph query` run body (lazily imported, off the fast path).
+ *
+ * Delegates to the `rt.query.sparql` facade (which the dispatcher has already
+ * booted the store for) and translates a query failure into the v2 error
+ * kernel. The old shell raised `STORE_ERROR`; v2 has no such code, so a SPARQL
+ * syntax/execution failure becomes INVALID_INPUT (exit 2) with a recovery
+ * pointer to the loaded namespaces. A `PragmaError` that already carries a
+ * precise code (e.g. STORE_UNAVAILABLE from a cold boot) is re-thrown unchanged.
+ */
+
+import type { QueryResult } from "@canonical/ke";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+
+/**
+ * Execute a raw SPARQL query against the booted store.
+ *
+ * @param rt - The per-invocation runtime (its store is booted by the dispatcher).
+ * @param sparql - The raw SPARQL query text.
+ * @returns The select bindings / ask boolean / construct triples.
+ * @throws PragmaError INVALID_INPUT on a query failure (with a recovery hint).
+ */
+export async function runQuery(
+  rt: PragmaRuntime,
+  sparql: string,
+): Promise<QueryResult> {
+  try {
+    return await rt.query.sparql(sparql);
+  } catch (error) {
+    if (error instanceof PragmaError) throw error;
+    // Keep the parser's own message — the WHY (bad token, line/column, an
+    // unknown prefix) — instead of an opaque "(query)" placeholder.
+    const detail = (
+      error instanceof Error ? error.message : String(error)
+    ).trim();
+    throw new PragmaError({
+      code: "INVALID_INPUT",
+      message: detail
+        ? `Invalid SPARQL query: ${detail}`
+        : "Invalid SPARQL query.",
+      recovery: {
+        message: "Check your SPARQL syntax and the loaded namespaces.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+}

package/src/capabilities/index.ts

@@ -0,0 +1,54 @@
+/**
+ * The capability registry: the literal array of every capability module the
+ * projectors consume (D8 — test-only fixtures are never listed here).
+ *
+ * The order is the authoring order; projectors sort where they need to. PR1
+ * ships `info` + `config show` as real verbs and the hidden `meta` verbs
+ * (`__complete`, `mcp`). Importing this barrel pulls only spec + formatter
+ * modules — every run body is behind a lazy dynamic import — so the
+ * `--help`/`__complete` fast paths stay free of the config reader and zod.
+ */
+
+import type { CapabilityModule } from "../kernel/spec/types.js";
+import { blockModule } from "./block/index.js";
+import { capabilitiesModule } from "./capabilities/index.js";
+import { colophonModule } from "./colophon/index.js";
+import { configModule } from "./config/index.js";
+import { createModule } from "./create/index.js";
+import { doctorModule } from "./doctor/index.js";
+import { graphModule } from "./graph/index.js";
+import { infoModule } from "./info/index.js";
+import { metaModule } from "./meta/index.js";
+import { modifierModule } from "./modifier/index.js";
+import { ontologyModule } from "./ontology/index.js";
+import { promptModule } from "./prompt/index.js";
+import { setupModule } from "./setup/index.js";
+import { skillModule } from "./skill/index.js";
+import { sourcesModule } from "./sources/index.js";
+import { standardModule } from "./standard/index.js";
+import { tierModule } from "./tier/index.js";
+import { tokenModule } from "./token/index.js";
+import { upgradeModule } from "./upgrade/index.js";
+
+/** Every capability module, in authoring order. */
+export const capabilities: readonly CapabilityModule[] = [
+  infoModule,
+  configModule,
+  createModule,
+  sourcesModule,
+  standardModule,
+  tierModule,
+  modifierModule,
+  tokenModule,
+  blockModule,
+  ontologyModule,
+  skillModule,
+  graphModule,
+  promptModule,
+  doctorModule,
+  upgradeModule,
+  setupModule,
+  capabilitiesModule,
+  colophonModule,
+  metaModule,
+];

package/src/capabilities/info/collectInfo.ts

@@ -0,0 +1,76 @@
+/**
+ * Collect the `info` payload — the verb's run body (lazily imported).
+ *
+ * STORELESS but network-aware (PR6): reads the layered config, reports the
+ * version and install source, then enriches with (a) an update-check against
+ * the npm registry — this deliberately REVERSES PR1's networkless-D11 stance for
+ * `info` (the reversal IS the enrichment), unconditional because the covenant
+ * `info` verb carries no flag, 3s timeout, silent-fail — and (b) a storeless
+ * entity total from the pack index (`readPackIndex`, the same reader `sources
+ * status` uses). Neither enrichment boots the store, so the storeless-guarantee
+ * spy still sees `store.booted === false`. Kept out of the spec module so
+ * building the command tree never pulls it onto the `--help` fast path.
+ */
+
+import {
+  entityTotal,
+  readPackIndex,
+} from "../../kernel/completion/entitySource.js";
+import { readConfig } from "../../kernel/config/readConfig.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import {
+  detectInstallSource,
+  pmUpdateCommand,
+} from "../shared/packageManager.js";
+import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { InfoData, InfoUpdate } from "./types.js";
+
+/**
+ * Assemble the `info` data for the current runtime.
+ *
+ * @param runtime - The per-invocation runtime.
+ * @returns The storeless (network-aware) info payload.
+ * @note Impure — reads the config layers + pack index from disk and checks the
+ *   registry (never boots the store).
+ */
+export async function collectInfo(runtime: PragmaRuntime): Promise<InfoData> {
+  const layers = await readConfig(runtime.cwd);
+  const { config } = layers;
+  const install = detectInstallSource();
+
+  // Update-check: unconditional (no flag exists), 3s timeout, silent-fail.
+  const registry = await checkRegistryVersion(PRAGMA_PACKAGE, config.channel);
+  const update: InfoUpdate | undefined =
+    registry && registry.latest !== runtime.version
+      ? {
+          current: runtime.version,
+          latest: registry.latest,
+          command: pmUpdateCommand(install.pm, PRAGMA_PACKAGE),
+        }
+      : undefined;
+  const updateSkipped = registry === undefined;
+
+  // Entity total: storeless — the same pack-index reader `sources status` uses.
+  const index = readPackIndex(runtime.cwd);
+  const entities = index ? entityTotal(index) : undefined;
+
+  return {
+    version: runtime.version,
+    installSource: install.label,
+    ...(update ? { update } : {}),
+    updateSkipped,
+    ...(entities !== undefined ? { entities } : {}),
+    config: {
+      ...(config.tier !== undefined ? { tier: config.tier } : {}),
+      channel: config.channel,
+      ...(config.detail !== undefined ? { detail: config.detail } : {}),
+      origins: layers.origins,
+      ...(layers.project.path
+        ? { projectConfigPath: layers.project.path }
+        : {}),
+      globalConfigPath: layers.global.path,
+      projectExists: layers.project.exists,
+      globalExists: layers.global.exists,
+    },
+  };
+}

package/src/capabilities/info/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `info` capability barrel.
+ */
+
+export { infoModule } from "./info.verb.js";
+export type { InfoConfig, InfoData, InfoUpdate } from "./types.js";

package/src/capabilities/info/info.render.ts

@@ -0,0 +1,72 @@
+/**
+ * Formatters for `pragma info` — plain, llm, json (no ink).
+ */
+
+import type { ConfigOrigin } from "../../kernel/config/types.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { InfoData } from "./types.js";
+
+/** A `[layer]` marker for values a config file supplied (blank for defaults). */
+function originMarker(origin: ConfigOrigin): string {
+  return origin === "default" ? "" : ` [${origin}]`;
+}
+
+export const infoFormatters: Formatters<InfoData> = {
+  plain(data) {
+    const { config } = data;
+    const lines = [
+      `pragma v${data.version}`,
+      `  Installed via: ${data.installSource}`,
+      `  tier: ${config.tier ?? "(none)"}${originMarker(config.origins.tier)}`,
+      `  channel: ${config.channel}${originMarker(config.origins.channel)}`,
+      `  detail: ${config.detail ?? "standard"}${originMarker(config.origins.detail)}`,
+    ];
+    if (data.entities !== undefined) {
+      lines.push(`  entities: ${data.entities.toLocaleString()}`);
+    }
+    lines.push(
+      "",
+      "Config files:",
+      `  global:  ${config.globalConfigPath}${config.globalExists ? "" : " (not found)"}`,
+      `  project: ${config.projectConfigPath ?? "(none)"}${
+        config.projectConfigPath && !config.projectExists ? " (not found)" : ""
+      }`,
+    );
+    if (data.update) {
+      lines.push(
+        "",
+        `Update available: ${data.update.current} → ${data.update.latest}`,
+        `  Run: ${data.update.command}`,
+      );
+    }
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const { config } = data;
+    const lines = [
+      `# pragma v${data.version}`,
+      `- Installed via: ${data.installSource}`,
+      `- Tier: ${config.tier ?? "(none)"}${originMarker(config.origins.tier)}`,
+      `- Channel: ${config.channel}${originMarker(config.origins.channel)}`,
+      `- Detail: ${config.detail ?? "standard"}${originMarker(config.origins.detail)}`,
+      `- Global config: ${config.globalConfigPath}`,
+    ];
+    if (config.projectConfigPath) {
+      lines.push(`- Project config: ${config.projectConfigPath}`);
+    }
+    if (data.entities !== undefined) {
+      lines.push(`- Entities: ${data.entities.toLocaleString()}`);
+    }
+    if (data.update) {
+      lines.push(
+        `- Update available: ${data.update.current} → ${data.update.latest} (\`${data.update.command}\`)`,
+      );
+    }
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/info/info.test.ts

@@ -0,0 +1,127 @@
+/**
+ * `pragma info` — the PR6 network + entity-count enrichment.
+ *
+ * Mocks the registry (behind / offline / up-to-date) so the update-check is
+ * deterministic, asserts the storeless invariant (info NEVER boots the store),
+ * and pins CLI-json ≡ MCP `info` parity. The pack-index entity total is
+ * storeless (embedded fallback), so it is always present here.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { VERSION } from "../../constants.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { infoModule } from "./index.js";
+import type { InfoData } from "./types.js";
+
+const infoVerb = infoModule.verbs[0] as VerbSpec;
+const FLAGS_JSON: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+
+const roots: string[] = [];
+const tmpCwd = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-info-"));
+  roots.push(dir);
+  return dir;
+};
+
+/** Stub the global fetch: return a registry doc with `latest`, or fail (offline). */
+function stubRegistry(latest: string | "offline"): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => {
+      if (latest === "offline") throw new Error("network down");
+      return {
+        ok: true,
+        json: async () => ({ "dist-tags": { latest } }),
+      } as unknown as Response;
+    }),
+  );
+}
+
+let prevXdg: string | undefined;
+beforeEach(() => {
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = tmpCwd();
+});
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  vi.unstubAllGlobals();
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+async function collect(rt: PragmaRuntime): Promise<InfoData> {
+  const outcome = await executeVerb(infoVerb, {}, NO_MUT, rt);
+  return JSON.parse(outcome.stdout as string).data as InfoData;
+}
+
+describe("info — update-check enrichment", () => {
+  it("sets `update` when a newer release is published", async () => {
+    stubRegistry("99.0.0");
+    const rt = bootRuntime(FLAGS_JSON, tmpCwd());
+    const data = await collect(rt);
+
+    expect(data.update).toMatchObject({ current: VERSION, latest: "99.0.0" });
+    expect(data.update?.command).toContain("@canonical/pragma-cli");
+    expect(data.updateSkipped).toBe(false);
+    // The storeless invariant: the enrichment must NOT boot the store.
+    expect(rt.store.booted).toBe(false);
+  });
+
+  it("marks `updateSkipped` when the registry is unreachable", async () => {
+    stubRegistry("offline");
+    const data = await collect(bootRuntime(FLAGS_JSON, tmpCwd()));
+    expect(data.update).toBeUndefined();
+    expect(data.updateSkipped).toBe(true);
+  });
+
+  it("reports no update when already at the latest version", async () => {
+    stubRegistry(VERSION);
+    const data = await collect(bootRuntime(FLAGS_JSON, tmpCwd()));
+    expect(data.update).toBeUndefined();
+    expect(data.updateSkipped).toBe(false);
+  });
+});
+
+describe("info — storeless entity total", () => {
+  it("carries a numeric entity total from the storeless pack index", async () => {
+    stubRegistry(VERSION);
+    const rt = bootRuntime(FLAGS_JSON, tmpCwd());
+    const data = await collect(rt);
+    expect(typeof data.entities).toBe("number");
+    expect(rt.store.booted).toBe(false);
+  });
+});
+
+describe("info — CLI-json ≡ MCP info (PROTECTED)", () => {
+  it("both surfaces return the same enriched envelope", async () => {
+    stubRegistry(VERSION);
+    const cwd = tmpCwd();
+    const cli = await executeVerb(
+      infoVerb,
+      {},
+      NO_MUT,
+      bootRuntime(FLAGS_JSON, cwd),
+    );
+    const cliEnvelope = JSON.parse(cli.stdout as string);
+
+    const mcp = await projectMcp([infoModule], cwd);
+    const mcpEnvelope = await mcp.callTool("info");
+    await mcp.cleanup();
+
+    expect(cliEnvelope).toEqual(mcpEnvelope);
+    expect(cliEnvelope.ok).toBe(true);
+  });
+});

package/src/capabilities/info/info.verb.ts

@@ -0,0 +1,46 @@
+/**
+ * The `info` verb spec (noun `info`, self-verb).
+ *
+ * `run` is a lazy thunk: it dynamic-imports the collector, so building the
+ * command tree (help, completion, surface emit) reads this spec without pulling
+ * the config reader or zod onto the fast path.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { infoFormatters } from "./info.render.js";
+import type { InfoData } from "./types.js";
+
+const infoVerb: VerbSpec<Record<string, unknown>, InfoData> = {
+  path: ["info"],
+  summary: "Show version, resolved config, provenance, and update status.",
+  doc: "Storeless — reports the CLI version, how it was installed, the layered config with per-field origins, an entity total from the pack index, and (network, silent-fail) whether a newer release is available.",
+  params: [],
+  output: { formatters: infoFormatters },
+  examples: [
+    { cmd: "pragma info", note: "human-readable summary" },
+    {
+      cmd: "pragma info --format json",
+      note: "the full {ok,data,meta} envelope",
+    },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    // Network-aware (PR6 enrichment): the update-check reads the registry. This
+    // does NOT affect the emitted surface — `emitVerb` ignores `needsNetwork`.
+    needsNetwork: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./collectInfo.js").then((m) => m.collectInfo(runtime)),
+};
+
+/** The `info` capability module. */
+export const infoModule: CapabilityModule = {
+  name: "info",
+  verbs: [asVerb(infoVerb)],
+};