@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/kernel/runtime/storeReadiness.ts

@@ -0,0 +1,62 @@
+/**
+ * The STORELESS store-readiness check — the ONE source of the cold-store
+ * `STORE_UNAVAILABLE` error (its message AND its `pragma sources update` /
+ * `sources_update` recovery), shared by the lazy store boot ({@link
+ * loadStoreSession}) and the native MCP discovery surfaces (the `prompts/*`
+ * provider, the `pragma:{+uri}` resource browser).
+ *
+ * A cold store must present the SAME diagnostic on every surface: an agent that
+ * lists prompts over the `prompt_list` tool (store-backed, so its `needsStore`
+ * pre-check throws) and one that lists them over native `prompts/list` must see
+ * the identical `STORE_UNAVAILABLE` + `sources_update` recovery, not one error
+ * and one silently-empty list. Centralizing the construction here is what keeps
+ * those surfaces from drifting apart.
+ *
+ * It reaches only {@link resolveSources} (a pointer + config probe — no store,
+ * no ke), so a caller on the storeless fast path can pre-check availability
+ * without ever booting the store.
+ */
+
+import type { ConfigLayers } from "../config/types.js";
+import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
+import { resolveSources } from "./resolveSources.js";
+
+/**
+ * Build the canonical cold-store `STORE_UNAVAILABLE` error: the reason plus the
+ * single `pragma sources update` recovery that also names the `sources_update`
+ * tool an agent calls (then retries — PR9's C1 cold-store retry succeeds).
+ *
+ * @param reason - The boot decision's reason (e.g. "the built pack is missing
+ *   from the cache").
+ * @returns The structured STORE_UNAVAILABLE error.
+ */
+export function storeUnavailable(reason: string): PragmaError {
+  return PragmaError.storeUnavailable(`${reason}.`, {
+    recovery: cliRecovery(
+      "sources update",
+      "Build the local store from the configured packs.",
+      { tool: "sources_update" },
+    ),
+  });
+}
+
+/**
+ * The STORE_UNAVAILABLE error to surface when the store cannot boot from the
+ * current config and active-pack pointer, or `undefined` when a store read may
+ * proceed. STORELESS —
+ * probes the decision table only, never constructs the store.
+ *
+ * @param layers - The resolved config layers.
+ * @param cwd - The project directory the boot resolves against.
+ * @returns The error to surface cold, or `undefined` when the store is available.
+ */
+export function checkStoreAvailable(
+  layers: ConfigLayers,
+  cwd: string,
+): PragmaError | undefined {
+  const decision = resolveSources(layers, cwd);
+  return decision.kind === "unavailable"
+    ? storeUnavailable(decision.reason)
+    : undefined;
+}

package/src/kernel/runtime/storeless.test.ts

@@ -58,7 +58,7 @@ describe("storeless guarantee — the store never boots for storeless verbs (PRO
     expect(runtime.store.booted).toBe(false);
   });
 
-  it("sources status does not construct the store (reports a cold store)", async () => {
+  it("sources status does not construct the store", async () => {
     const runtime = bootRuntime(FLAGS, freshCwd());
     const outcome = await executeVerb(sourcesStatusVerb, {}, NO_MUT, runtime);
     expect(outcome.exitCode).toBe(0);

package/src/kernel/runtime/types.ts

@@ -17,7 +17,7 @@ import type { ConfigLayers } from "../config/types.js";
  * separately so inferred mode can shape output without switching behaviour.
  */
 export interface GlobalFlags {
-  /** Condensed Markdown output for LLM/agent consumption. */
+  /** Condensed Markdown output, from `--format llm` or auto-detection. */
   readonly llm: boolean;
   /** True when `llm` was inferred from a non-interactive stdout, not requested. */
   readonly autoLlm?: boolean;

package/src/kernel/runtime/wasmEmbed.test.ts

@@ -1,15 +1,10 @@
 import { spawnSync } from "node:child_process";
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { embeddedManifest } from "./graphpack/embedded.js";
 
 /**
  * The store-boot path only fully lives in the standalone binary: this is the
@@ -74,8 +69,11 @@ describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)
       triples: string;
     };
     expect(out.ok).toBe(true);
-    expect(out.entities).toBe(6);
-    expect(Number(out.triples)).toBeGreaterThan(0);
+    // The compiled binary is the only place this is worth asserting: the store
+    // it booted from the inlined `data.nq` must hold exactly what the committed
+    // `manifest.json` claims was built into it.
+    expect(Number(out.triples)).toBe(embeddedManifest().tripleCount);
+    expect(out.entities).toBeGreaterThan(0);
   });
 
   it("dist binary runs storeless sources status", () => {
@@ -83,18 +81,17 @@ describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)
     expect(run.status, run.stderr).toBe(0);
     const envelope = JSON.parse(run.stdout.trim()) as {
       ok: boolean;
-      data: { lockPresent: boolean; cached: boolean };
+      data: { store: string };
     };
     expect(envelope.ok).toBe(true);
-    // A fresh install: no lock, store not yet built.
-    expect(envelope.data.lockPresent).toBe(false);
-    expect(envelope.data.cached).toBe(false);
+    // A fresh install: nothing built here, so the embedded pack answers reads.
+    expect(envelope.data.store).toBe("embedded");
   });
 
   // Regression guard: `sources update` walks a package's TTL directories. The
   // compiled binary's node:fs globSync mishandles `**` (returns bogus paths),
   // which the in-process suite could not catch — so exercise the real binary.
-  it("dist binary runs sources update end-to-end (build + lock + status)", () => {
+  it("dist binary runs sources update end-to-end (build + point + status)", () => {
     const pkg = join(workdir, "pkg");
     const proj = join(workdir, "proj");
     mkdirSync(join(pkg, "definitions"), { recursive: true });
@@ -110,7 +107,7 @@ ex:one a ex:Widget ; rdfs:label "One" .
     );
     writeFileSync(
       join(proj, "pragma.config.ts"),
-      `export default { packages: [{ name: "pkg-a", source: "file://${pkg}" }] };\n`,
+      `export default { packs: [{ name: "pkg-a", source: "file://${pkg}" }] };\n`,
     );
 
     const env = {
@@ -129,14 +126,22 @@ ex:one a ex:Widget ; rdfs:label "One" .
 
     const update = inProj(["sources", "update", "--yes", "--format", "json"]);
     expect(update.status, update.stderr).toBe(0);
-    expect(existsSync(join(proj, "pragma.lock.json"))).toBe(true);
+    const built = (
+      JSON.parse(update.stdout.trim()) as {
+        data: { contentHash: string };
+      }
+    ).data.contentHash;
+    expect(built).toMatch(/^[0-9a-f]{64}$/);
 
     const status = inProj(["sources", "status", "--format", "json"]);
     const envelope = JSON.parse(status.stdout.trim()) as {
-      data: { lockPresent: boolean; cached: boolean; entityCount: number };
+      data: { store: string; contentHash: string; entityCount: number };
     };
-    expect(envelope.data.lockPresent).toBe(true);
-    expect(envelope.data.cached).toBe(true);
-    expect(envelope.data.entityCount).toBe(2);
+    // The project now reads its OWN pack — the one the update just built.
+    expect(envelope.data.store).toBe("built");
+    expect(envelope.data.contentHash).toBe(built);
+    // Distinct abox subjects: the one individual (ex:one). The ex:Widget class
+    // is tbox schema, not an entity — the raw entity count would double this (A1).
+    expect(envelope.data.entityCount).toBe(1);
   });
 });

package/src/kernel/spec/emitReference.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import {
+  fixtureModule,
+  fixtureReferenceModule,
+} from "../../testing/fixtures/fixtureCapability.js";
+import { ERROR_CODES } from "../error/constants.js";
+import { emitReference } from "./emitReference.js";
+
+/** The five pages every reference doc set carries. */
+const PAGES = ["index.md", "commands.md", "tools.md", "errors.md", "config.md"];
+
+describe("emitReference", () => {
+  const docs = emitReference([fixtureReferenceModule]);
+  const index = docs.get("index.md") ?? "";
+  const commands = docs.get("commands.md") ?? "";
+  const tools = docs.get("tools.md") ?? "";
+  const errors = docs.get("errors.md") ?? "";
+
+  it("emits exactly the five reference pages", () => {
+    expect([...docs.keys()].sort()).toEqual([...PAGES].sort());
+  });
+
+  it("ends every page in exactly one trailing newline", () => {
+    for (const content of docs.values()) {
+      expect(content.endsWith("\n")).toBe(true);
+      expect(content.endsWith("\n\n")).toBe(false);
+    }
+  });
+
+  it("is deterministic — the same catalog yields byte-identical pages", () => {
+    const again = emitReference([fixtureReferenceModule]);
+    for (const page of PAGES) {
+      expect(again.get(page)).toBe(docs.get(page));
+    }
+  });
+
+  describe("index.md", () => {
+    it("reports counts derived from the live grammar", () => {
+      // gizmo + ping = 2 nouns; local/scan/tidy/wipe/ping = 5 commands (hidden
+      // dropped); scan/tidy/wipe/ping = 4 tools (local withheld); 1 resource
+      // template (the module's `mcpResources` surface).
+      expect(index).toContain("**2** command nouns");
+      expect(index).toContain("**5** CLI commands");
+      expect(index).toContain("**4** MCP tools");
+      expect(index).toContain("**1** resource template(s)");
+    });
+
+    it("links the three sibling pages with relative paths", () => {
+      expect(index).toContain("(./commands.md)");
+      expect(index).toContain("(./tools.md)");
+      expect(index).toContain("(./errors.md)");
+    });
+  });
+
+  describe("commands.md", () => {
+    it("groups verbs under noun headings, sorted, hidden excluded", () => {
+      expect(commands).toContain("## gizmo");
+      expect(commands).toContain("## ping");
+      expect(commands.indexOf("## gizmo")).toBeLessThan(
+        commands.indexOf("## ping"),
+      );
+      expect(commands).not.toContain("hidden");
+    });
+
+    it("renders a read verb's usage, args, flags, attributes, and examples", () => {
+      expect(commands).toContain("### pragma gizmo scan");
+      expect(commands).toContain("pragma gizmo scan [targets...] [options]");
+      // Optional variadic positional token.
+      expect(commands).toContain("| `[targets...]` | no |");
+      // Enum flag: escaped pipe token, enum values, and default in the description.
+      expect(commands).toContain("| `--mode` | `<fast\\|slow>` |");
+      expect(commands).toContain("(one of: fast, slow) (default: fast)");
+      // Each flag kind renders its value placeholder.
+      expect(commands).toContain("| `--limit` | `<number>` |");
+      expect(commands).toContain("| `--label` | `<string>` |");
+      expect(commands).toContain("| `--include` | `<value...>` |");
+      // A bare boolean switch has no value placeholder.
+      expect(commands).toContain("| `--deep` | — |");
+      expect(commands).toContain("- Store: storeless.");
+      expect(commands).toContain("- MCP: exposed as the `gizmo_scan` tool.");
+      // A note becomes a trailing comment; a noteless example stays bare.
+      expect(commands).toContain("pragma gizmo scan  # scan everything");
+      expect(commands).toContain("pragma gizmo scan alpha --mode slow");
+    });
+
+    it("marks a store-backed destructive mutation's CLI attributes", () => {
+      expect(commands).toContain("### pragma gizmo wipe");
+      expect(commands).toContain("pragma gizmo wipe <path>");
+      expect(commands).toContain(
+        "- Store: reads the local store (`pragma sources update` builds it).",
+      );
+      expect(commands).toContain("- Mutation: plan-first");
+    });
+
+    it("marks a visible verb withheld from MCP", () => {
+      expect(commands).toContain("### pragma gizmo local");
+      expect(commands).toContain("- MCP: not exposed (CLI-only).");
+    });
+
+    it("renders a self-verb with no sub-command in its invocation", () => {
+      expect(commands).toContain("### pragma ping");
+      expect(commands).toContain("```\npragma ping\n```");
+    });
+
+    it("falls back to the summary when a verb has no doc", () => {
+      // `ping` has no `doc`; its summary is the section body.
+      const pingSection = commands.slice(commands.indexOf("### pragma ping"));
+      expect(pingSection).toContain("Ping the gizmo host.");
+    });
+  });
+
+  describe("tools.md", () => {
+    it("adds the disclosure `detail` param and comma-joined enum types", () => {
+      expect(tools).toContain("### gizmo_scan");
+      expect(tools).toContain("| `mode` | enum(fast, slow) | no |");
+      expect(tools).toContain("| `include` | string[] | no |");
+      expect(tools).toContain(
+        "| `detail` | enum(summary, detailed) | no | Progressive-disclosure level (default summary). |",
+      );
+    });
+
+    it("adds confirm + cwd to a mutating tool and flags it destructive", () => {
+      const wipe = tools.slice(tools.indexOf("### gizmo_wipe"));
+      expect(wipe).toContain("| `confirm` | boolean | no |");
+      expect(wipe).toContain("| `cwd` | string | no |");
+      expect(tools).toContain(
+        "Mutation — plan-first (set `confirm: true` to apply). Marked destructive.",
+      );
+    });
+
+    it("marks a non-destructive mutating tool as such", () => {
+      const tidy = tools.slice(tools.indexOf("### gizmo_tidy"));
+      expect(tidy).toContain("| `confirm` | boolean | no |");
+      // The `destructive: false` branch of `formatToolAnnotations`.
+      expect(tools).toContain(
+        "Mutation — plan-first (set `confirm: true` to apply). Non-destructive.",
+      );
+    });
+
+    it("omits verbs withheld from MCP", () => {
+      expect(tools).not.toContain("gizmo_local");
+    });
+
+    it("marks a no-param tool as taking no input", () => {
+      const ping = tools.slice(tools.indexOf("### ping"));
+      expect(ping.slice(0, 200)).toContain("_No input parameters._");
+    });
+
+    it("renders every non-tool surface bullet the module declares", () => {
+      expect(tools).toContain("## Non-tool surface");
+      // The module declares an `mcpResources` template surface (its `surface.
+      // templates` id) and an `mcpPrompts` native surface, so all three bullets
+      // render — exercising both optional branches of `renderNonToolSurface`.
+      expect(tools).toContain("- **Resources**: `gizmo:{+uri}`");
+      expect(tools).toContain("- **Prompts**:");
+      expect(tools).toContain("- **Instructions**:");
+    });
+  });
+
+  describe("errors.md", () => {
+    it("renders the exit-code table and the full error catalog", () => {
+      expect(errors).toContain("| `0` | success |");
+      expect(errors).toContain("| `3` | store unavailable |");
+      expect(errors).toContain("| `ENTITY_NOT_FOUND` |");
+      expect(errors).toContain("| `UNSUPPORTED` |");
+    });
+
+    it("lists every code in the closed ERROR_CODES tuple (exhaustive)", () => {
+      // Non-circular exhaustiveness: iterate the source-of-truth tuple and
+      // assert each code's `catalog` row is present, so a code added to the
+      // kernel without a catalog entry fails here (not just the 2 spot-checks).
+      for (const code of ERROR_CODES) {
+        expect(errors, `errors.md is missing \`${code}\``).toContain(
+          `\`${code}\``,
+        );
+      }
+    });
+
+    it("embeds the response envelope as a JSON block", () => {
+      expect(errors).toContain("```json");
+      expect(errors).toContain('"ok": true');
+      expect(errors).toContain('"code": "<ErrorCode>"');
+    });
+  });
+});
+
+describe("emitReference — MCP annotation branches", () => {
+  it("renders a destructive fixture tool and a native-prompt-free surface", () => {
+    // `fixtureModule.make` is exposed, mutating, and destructive — the same
+    // `Marked destructive.` branch, driven from the emitSurface fixture.
+    const tools = emitReference([fixtureModule]).get("tools.md") ?? "";
+    expect(tools).toContain("### widget_make");
+    expect(tools).toContain("Marked destructive.");
+    expect(tools).not.toContain("- **Prompts**:");
+  });
+});