@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,154 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ConfigLayers } from "../config/types.js";
+import { loadStoreSession } from "./loadSession.js";
+import { writeLock } from "./lock.js";
+import { packDir } from "./paths.js";
+import { resolveSources } from "./resolveSources.js";
+
+/**
+ * Pin the store-boot decision table (`resolveSources`) — especially the two
+ * STORE_UNAVAILABLE rows and the single `pragma sources update` recovery — so
+ * the error/recovery UX PR3+ leans on cannot drift silently.
+ */
+
+let roots: string[] = [];
+const tmp = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-resolvesrc-"));
+  roots.push(dir);
+  return dir;
+};
+
+/** Config layers whose only relevant knob is the `packages` origin. */
+function layersWith(packagesOrigin: "default" | "project"): ConfigLayers {
+  return {
+    config: {
+      channel: "normal",
+      packages:
+        packagesOrigin === "project"
+          ? [{ name: "x", source: "file:///x" }]
+          : [],
+    },
+    origins: {
+      tier: "default",
+      channel: "default",
+      detail: "default",
+      packages: packagesOrigin,
+      stories: "default",
+      prefixes: "default",
+      prompts: "default",
+    },
+    global: { path: "/nonexistent", exists: false },
+    project: { exists: false },
+  };
+}
+
+/** Write a pack's manifest.json at the given hash (the completeness marker). */
+function writeManifest(dir: string, hash: string): void {
+  writeFileSync(
+    join(dir, "manifest.json"),
+    JSON.stringify({
+      name: "t",
+      version: "0",
+      sourceRef: "t",
+      contentHash: hash,
+      prefixes: {},
+      createdAt: new Date().toISOString(),
+    }),
+  );
+}
+
+/** Materialize a COMPLETE pack — manifest + non-empty dump, schema, and index. */
+function writeCompletePack(hash: string): string {
+  const dir = packDir(hash);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "data.nq"), "<urn:s> <urn:p> <urn:o> .\n");
+  writeFileSync(join(dir, "schema.json"), "{}");
+  writeFileSync(join(dir, "index.json"), "{}");
+  writeManifest(dir, hash);
+  return dir;
+}
+
+beforeEach(() => {
+  roots = [];
+});
+afterEach(() => {
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("resolveSources decision table", () => {
+  it("lock present + pack cached → load the locked pack", () => {
+    const cwd = tmp();
+    const hash = "a".repeat(64);
+    const dir = writeCompletePack(hash);
+    writeLock(cwd, { version: 1, contentHash: hash, packs: [] });
+
+    expect(resolveSources(layersWith("default"), cwd)).toEqual({
+      kind: "pack",
+      dir,
+      contentHash: hash,
+    });
+  });
+
+  it("lock present + pack evicted → STORE_UNAVAILABLE", () => {
+    const cwd = tmp();
+    // A lock whose content-addressed pack is absent from the cache.
+    writeLock(cwd, { version: 1, contentHash: "b".repeat(64), packs: [] });
+
+    expect(resolveSources(layersWith("default"), cwd)).toEqual({
+      kind: "unavailable",
+      reason: "the locked pack is missing from the cache",
+    });
+  });
+
+  it("lock present + pack with a torn schema/index → STORE_UNAVAILABLE", () => {
+    const cwd = tmp();
+    const hash = "c".repeat(64);
+    // manifest + non-empty dump present, but the extracted schema/index are
+    // missing (a torn or partially-evicted pack). This used to slip through
+    // `packIsComplete` and then crash at read time as an INTERNAL error; it must
+    // now be treated as not-built so the boot surfaces STORE_UNAVAILABLE.
+    const dir = packDir(hash);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "data.nq"), "<urn:s> <urn:p> <urn:o> .\n");
+    writeManifest(dir, hash);
+    writeLock(cwd, { version: 1, contentHash: hash, packs: [] });
+
+    expect(resolveSources(layersWith("default"), cwd)).toEqual({
+      kind: "unavailable",
+      reason: "the locked pack is missing from the cache",
+    });
+  });
+
+  it("no lock + default packages → embedded fallback", () => {
+    expect(resolveSources(layersWith("default"), tmp())).toEqual({
+      kind: "embedded",
+    });
+  });
+
+  it("no lock + packages configured → STORE_UNAVAILABLE", () => {
+    expect(resolveSources(layersWith("project"), tmp())).toEqual({
+      kind: "unavailable",
+      reason: "packages are configured but the store has not been built",
+    });
+  });
+});
+
+describe("loadStoreSession recovery", () => {
+  it("surfaces the `pragma sources update` recovery (CLI + MCP tool) when cold", async () => {
+    const cwd = tmp();
+    const ctx = { cwd, loadConfig: async () => layersWith("project") };
+
+    // An agent can't run a shell command — the recovery also names the tool it
+    // calls (then retries: PR9 C1 cold-store retry makes the retry succeed).
+    await expect(loadStoreSession(ctx)).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+      recovery: {
+        cli: "pragma sources update",
+        mcp: { tool: "sources_update" },
+      },
+    });
+  });
+});

package/src/kernel/runtime/resolveSources.ts

@@ -0,0 +1,66 @@
+/**
+ * The store-boot decision table — storeless, and the single place the boot
+ * strategy is decided.
+ *
+ * Boot never touches the network. From the lock and the resolved config:
+ *
+ * | lock present | pack cached | packages origin | → decision            |
+ * |--------------|-------------|-----------------|-----------------------|
+ * | yes          | yes         | —               | load the locked pack  |
+ * | yes          | no          | —               | STORE_UNAVAILABLE     |
+ * | no           | —           | default         | embedded fallback     |
+ * | no           | —           | configured      | STORE_UNAVAILABLE     |
+ *
+ * A configured-but-unbuilt store (or a lock whose pack the cache lost)
+ * surfaces STORE_UNAVAILABLE with a single recovery: `pragma sources update`.
+ * "packages origin default" means the user has not pinned their own packages —
+ * a fresh install — so the embedded fallback answers reads offline.
+ */
+
+import type { ConfigLayers } from "../config/types.js";
+import { packIsComplete } from "./graphpack/manifest.js";
+import { readLock } from "./lock.js";
+import { packDir } from "./paths.js";
+
+/** The resolved boot strategy. */
+export type SourcesDecision =
+  | {
+      readonly kind: "pack";
+      readonly dir: string;
+      readonly contentHash: string;
+    }
+  | { readonly kind: "embedded" }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/**
+ * Decide how (or whether) to boot the store — without any network or store I/O.
+ *
+ * @param layers - The resolved config layers (for the `packages` origin).
+ * @param cwd - The project directory (for the lock).
+ * @returns The boot decision.
+ * @note Impure — reads the lock and probes the pack cache.
+ */
+export function resolveSources(
+  layers: ConfigLayers,
+  cwd: string,
+): SourcesDecision {
+  const lock = readLock(cwd);
+  if (lock) {
+    const dir = packDir(lock.contentHash);
+    if (packIsComplete(dir)) {
+      return { kind: "pack", dir, contentHash: lock.contentHash };
+    }
+    return {
+      kind: "unavailable",
+      reason: "the locked pack is missing from the cache",
+    };
+  }
+
+  if (layers.origins.packages === "default") {
+    return { kind: "embedded" };
+  }
+  return {
+    kind: "unavailable",
+    reason: "packages are configured but the store has not been built",
+  };
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Unit tests for the lazy store's long-lived-server behaviour (PR9 Stream 3):
+ *
+ * - C1: a REJECTED boot is not memoized, so a retry after STORE_UNAVAILABLE can
+ *   succeed once `sources update` has built the pack (the failure mode that
+ *   strands an MCP session until a full server restart).
+ * - `invalidate()`: drops the memoized session so the next `get()` re-boots, and
+ *   fires the `onInvalidate` hook the runtime wires to also clear its config memo.
+ *
+ * The loader is a hard-wired `await import("./loadSession.js")`, so we mock that
+ * module to drive success/failure across calls without booting oxigraph.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { ConfigLayers } from "../config/types.js";
+import { PragmaError } from "../error/PragmaError.js";
+import { createLazyStore, type LazyStoreContext } from "./store.js";
+import type { StoreSession } from "./types.js";
+
+// Hoisted so the (hoisted) `vi.mock` factory below can close over it.
+const loadStoreSession = vi.hoisted(() => vi.fn());
+vi.mock("./loadSession.js", () => ({ loadStoreSession }));
+
+/** A stand-in session — the store never inspects it, so identity is enough. */
+const fakeSession = { marker: "session" } as unknown as StoreSession;
+
+/** A minimal, correctly-typed ctx (the mocked loader ignores it). */
+function makeCtx(onInvalidate?: () => void): LazyStoreContext {
+  return {
+    cwd: "/fixture",
+    loadConfig: async () => ({}) as unknown as ConfigLayers,
+    ...(onInvalidate ? { onInvalidate } : {}),
+  };
+}
+
+describe("createLazyStore — cold-boot recovery (C1)", () => {
+  it("does not memoize a rejected boot: a retry after STORE_UNAVAILABLE can succeed", async () => {
+    loadStoreSession.mockReset();
+    // Cold on the first attempt, then warm (as if `sources update` ran between).
+    loadStoreSession
+      .mockRejectedValueOnce(PragmaError.storeUnavailable("no pack"))
+      .mockResolvedValueOnce(fakeSession);
+
+    const store = createLazyStore(makeCtx());
+
+    await expect(store.get()).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+    });
+    // The failed boot left the store cold — the rejection was NOT memoized.
+    expect(store.booted).toBe(false);
+
+    // The retry re-attempts the loader (not a memoized rejection) and resolves.
+    await expect(store.get()).resolves.toBe(fakeSession);
+    expect(store.booted).toBe(true);
+    expect(loadStoreSession).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("createLazyStore — invalidate()", () => {
+  it("memoizes a successful boot until invalidated", async () => {
+    loadStoreSession.mockReset();
+    loadStoreSession.mockResolvedValue(fakeSession);
+
+    const store = createLazyStore(makeCtx());
+    await store.get();
+    await store.get();
+
+    // A successful session is memoized: the second get() does not re-boot.
+    expect(loadStoreSession).toHaveBeenCalledTimes(1);
+    expect(store.booted).toBe(true);
+  });
+
+  it("drops the memo, re-boots on the next get(), and fires onInvalidate", async () => {
+    loadStoreSession.mockReset();
+    loadStoreSession.mockResolvedValue(fakeSession);
+    const onInvalidate = vi.fn();
+
+    const store = createLazyStore(makeCtx(onInvalidate));
+    await store.get();
+    expect(store.booted).toBe(true);
+    expect(loadStoreSession).toHaveBeenCalledTimes(1);
+
+    store.invalidate();
+
+    // booted resets and the sibling-cache hook fires...
+    expect(store.booted).toBe(false);
+    expect(onInvalidate).toHaveBeenCalledTimes(1);
+
+    // ...so the next get() re-boots against (potentially new) on-disk state.
+    await store.get();
+    expect(store.booted).toBe(true);
+    expect(loadStoreSession).toHaveBeenCalledTimes(2);
+  });
+});

package/src/kernel/runtime/store.ts

@@ -0,0 +1,90 @@
+/**
+ * The lazy store — the ONE guarded factory the storeless-guarantee spy targets.
+ *
+ * `get()` dynamic-imports the heavy session loader, so constructing a runtime —
+ * or importing any capability — never pulls ke/ke-graphql/oxigraph. The
+ * dispatcher calls `get()` only for `capability.needsStore` verbs, which is what
+ * makes the storeless guarantee hold by construction: a storeless verb has no
+ * path to the store factory, so `booted` stays false.
+ *
+ * Memoization WITH invalidation — the store is long-lived (the MCP server boots
+ * ONE runtime for its whole lifetime and shares it across every tool call), not
+ * one-shot:
+ *
+ * - A SUCCESSFUL boot is memoized (the session is immutable until invalidated).
+ *   A REJECTED boot is NOT: a cold store throws STORE_UNAVAILABLE from the
+ *   loader, and `get()` clears the memo before re-throwing so a later `get()`
+ *   retries from scratch. This matters precisely because the server is
+ *   long-lived: an agent that hits STORE_UNAVAILABLE can run `sources update`
+ *   (which builds the pack on disk) and retry — something DID change to make the
+ *   retry succeed, so memoizing the rejection would strand the session forever.
+ *   For a one-shot CLI (a single `get()` per process) clearing the memo on
+ *   failure is a harmless no-op.
+ * - `invalidate()` drops the memoized session so the next `get()` re-boots
+ *   against the current on-disk pack. Because boot reads config through
+ *   `ctx.loadConfig` (which is itself memoized upstream), invalidating the store
+ *   must also drop that config memo — otherwise a re-boot would reuse stale
+ *   config. `onInvalidate` is the hook the runtime wires for exactly that (it
+ *   clears the boot-level `configPromise`). The MCP projector calls
+ *   `invalidate()` after every real mutation so a `config_set`/`sources update`
+ *   becomes visible to the next read tool.
+ */
+
+import type { ConfigLayers } from "../config/types.js";
+import type { LazyStore, StoreSession } from "./types.js";
+
+/** What the lazy store needs to boot: a cwd and a memoized config loader. */
+export interface LazyStoreContext {
+  readonly cwd: string;
+  readonly loadConfig: () => Promise<ConfigLayers>;
+  /**
+   * Called by `invalidate()` after the store memo is dropped, so the runtime can
+   * also drop the sibling caches this store's boot depends on (the memoized
+   * config `loadConfig` resolves) — a re-boot must not reuse stale config.
+   */
+  readonly onInvalidate?: () => void;
+}
+
+/**
+ * Create a lazy store handle.
+ *
+ * @param ctx - The working directory, memoized config loader, and optional
+ *   invalidation hook.
+ * @returns The lazy store: a `get()` that memoizes a successful boot (never a
+ *   rejection), a `booted` flag, and an `invalidate()` reset.
+ */
+export function createLazyStore(ctx: LazyStoreContext): LazyStore {
+  let session: Promise<StoreSession> | undefined;
+  let booted = false;
+
+  return {
+    get booted(): boolean {
+      return booted;
+    },
+    get(): Promise<StoreSession> {
+      if (session === undefined) {
+        session = (async () => {
+          try {
+            const { loadStoreSession } = await import("./loadSession.js");
+            const loaded = await loadStoreSession(ctx);
+            booted = true;
+            return loaded;
+          } catch (err) {
+            // Clear the memo BEFORE the rejection propagates (inside the async
+            // IIFE, so there is no window where a concurrent caller adopts the
+            // rejected promise): the next `get()` retries a fresh boot, which a
+            // `sources update` between calls can make succeed.
+            session = undefined;
+            throw err;
+          }
+        })();
+      }
+      return session;
+    },
+    invalidate(): void {
+      session = undefined;
+      booted = false;
+      ctx.onInvalidate?.();
+    },
+  };
+}

package/src/kernel/runtime/storeReadiness.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 lock + config probe — no store, no
+ * ke), so a caller on the storeless fast path can pre-check availability without
+ * ever booting the store.
+ */
+
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
+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 locked pack is missing").
+ * @returns The structured STORE_UNAVAILABLE error.
+ */
+export function storeUnavailable(reason: string): PragmaError {
+  return PragmaError.storeUnavailable(`${reason}.`, {
+    recovery: cliRecovery(
+      `${RECOVERY_CLI_PREFIX}sources update`,
+      "Build the local store from the configured packages.",
+      { tool: "sources_update" },
+    ),
+  });
+}
+
+/**
+ * The STORE_UNAVAILABLE error to surface when the store cannot boot from the
+ * current config/lock, 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

@@ -0,0 +1,86 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { configModule } from "../../capabilities/config/index.js";
+import { infoModule } from "../../capabilities/info/index.js";
+import { completeVerb } from "../../capabilities/meta/complete.verb.js";
+import { sourcesModule } from "../../capabilities/sources/index.js";
+import { executeVerb } from "../project/cli/dispatch.js";
+import type { GlobalFlags, VerbSpec } from "../spec/types.js";
+import { bootRuntime } from "./boot.js";
+
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+const infoVerb = infoModule.verbs[0] as VerbSpec;
+const showVerb = configModule.verbs[0] as VerbSpec;
+const sourcesStatusVerb = sourcesModule.verbs[0] as VerbSpec;
+
+/** A needs-store READ verb whose body never touches the store — so a `booted`
+ * flag flipping to true proves the *dispatcher* booted it for `needsStore`. */
+const needsStoreVerb: VerbSpec = {
+  path: ["fixture", "needs-store"],
+  summary: "A store-backed read.",
+  params: [],
+  output: {
+    formatters: {
+      plain: (d) => JSON.stringify(d),
+      llm: (d) => JSON.stringify(d),
+      json: (d) => JSON.stringify(d),
+    },
+  },
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: { expose: false, reason: "test fixture" },
+  },
+  run: async () => ({ ok: true }),
+};
+
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-storeless-"));
+
+describe("storeless guarantee — the store never boots for storeless verbs (PROTECTED)", () => {
+  it("info does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    await executeVerb(infoVerb, {}, NO_MUT, runtime);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("config show does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    await executeVerb(showVerb, {}, NO_MUT, runtime);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("sources status does not construct the store (reports a cold store)", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    const outcome = await executeVerb(sourcesStatusVerb, {}, NO_MUT, runtime);
+    expect(outcome.exitCode).toBe(0);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("__complete does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    await executeVerb(
+      completeVerb as VerbSpec,
+      { words: ["config"] },
+      NO_MUT,
+      runtime,
+    );
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("a needsStore verb DOES construct the store (spy fires)", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    expect(runtime.store.booted).toBe(false);
+    const outcome = await executeVerb(needsStoreVerb, {}, NO_MUT, runtime);
+    expect(outcome.exitCode).toBe(0);
+    expect(runtime.store.booted).toBe(true);
+  });
+});