@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/testing/behavioral/journeys.defaultPack.test.ts

@@ -0,0 +1,477 @@
+/**
+ * E1 (AV-231, Backlog E) — the hermetic default-pack journey.
+ *
+ * The root method fix: the pre-existing suite tested specs against a clean,
+ * single-typed 6-entity fixture, never the PRODUCT against a cold, real,
+ * multi-typed pack. This file drives the REAL path end to end over the vendored
+ * {@link DEFAULT_PACK_TTL} default pack — `sources update` (resolve → build →
+ * point, via `bootFixtureRuntime`) → boot → `graph query` → `block list` /
+ * `ontology list` (populated AND empty) → the error paths (malformed `.ttl`,
+ * a torn `schema.json`, a corrupt `schema.json`).
+ *
+ * It also pins, in-process, the real-data shapes the clean fixture masked — the
+ * `entityTotal` double-count (A1), the untiered block that `block list` drops
+ * (A2), and the multilingual label (A7). These were HAND-OFFS to lane A, pinned
+ * with `it.fails`; lane A's fixes have landed, so they are now LIVE regression
+ * guards. This is the durable fix the issue asks for: "we'd have caught this in
+ * use" becomes "CI catches it".
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  truncateSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { storyModules } from "../../capabilities/distribution.js";
+import { graphQueryVerb } from "../../capabilities/graph/query.verb.js";
+import {
+  ontologyListVerb,
+  ontologyShowVerb,
+} from "../../capabilities/ontology/verbs.js";
+import { updateVerb } from "../../capabilities/sources/update.verb.js";
+import {
+  entityTotal,
+  readPackIndex,
+} from "../../kernel/completion/entitySource.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
+import { SCHEMA_FILE } from "../../kernel/runtime/graphpack/types.js";
+import { packDir, readActivePack } from "../../kernel/runtime/paths.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  DEFAULT_PACK_ALL_VISIBLE_CONFIG,
+  DEFAULT_PACK_CONFIG,
+  DEFAULT_PACK_TTL,
+  INSTANCE_ONLY_TTL,
+  MALFORMED_TTL,
+  NO_BLOCKS_TTL,
+  UNTIERED_BLOCK_NAME,
+} from "../fixtures/graph/defaultPack.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+  type FixtureGraphOptions,
+} from "../helpers/fixtureGraph.js";
+
+const JSON_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+const NO_MUTATION = { dryRun: false, undo: false, yes: false };
+
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
+const blockListVerb = blockModule.verbs.find(
+  (verb) => verb.path.join(" ") === "block list",
+) as VerbSpec;
+
+/** Track fixtures so a single `afterAll` disposes every temp dir + store. */
+const fixtures: FixtureGraph[] = [];
+
+/** Boot a tracked fixture from inline TTL (+ optional config), for auto-disposal. */
+async function boot(
+  ttl: string,
+  config?: FixtureGraphOptions["config"],
+): Promise<FixtureGraph> {
+  const fixture = await bootFixtureRuntime({
+    ttl,
+    ...(config ? { config } : {}),
+  });
+  fixtures.push(fixture);
+  return fixture;
+}
+afterAll(async () => {
+  await Promise.all(fixtures.map((fixture) => fixture.dispose()));
+});
+
+/** The index of the pack a fixture's boot decision names — what `info` reads. */
+async function activeIndex(
+  fixture: FixtureGraph,
+): Promise<PackIndex | undefined> {
+  return readPackIndex(
+    resolveSources(await fixture.runtime.loadConfig(), fixture.cwd),
+  );
+}
+
+/** The `--format json` envelope a read verb renders. */
+interface Envelope {
+  readonly ok: boolean;
+  readonly data: unknown;
+  readonly meta: Record<string, unknown>;
+}
+
+/** Run a read verb at a fixture's cwd and parse its JSON envelope. */
+async function readVerb(
+  verb: VerbSpec,
+  params: Record<string, unknown>,
+  cwd: string,
+): Promise<Envelope> {
+  const outcome = await executeVerb(
+    verb,
+    params,
+    NO_MUTATION,
+    bootRuntime(JSON_FLAGS, cwd),
+  );
+  return JSON.parse(outcome.stdout as string) as Envelope;
+}
+
+/** The sorted `name` column of a `block list` invocation. */
+async function blockListNames(cwd: string): Promise<string[]> {
+  const envelope = await readVerb(blockListVerb, {}, cwd);
+  const rows = envelope.data as { name: string }[];
+  return rows.map((row) => row.name).sort();
+}
+
+describe("default-pack journey — sources update, build, boot (E1)", () => {
+  it("bootFixtureRuntime runs the real resolve/build and points the project at the pack", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    expect(readActivePack(fixture.cwd)).toMatch(/^[0-9a-f]{64}$/);
+    // The booted store answers a read against the freshly built pack.
+    const ask = await fixture.runtime.query.sparql(
+      "ASK { ds:button a ds:Component }",
+    );
+    expect(ask.type === "ask" && ask.result).toBe(true);
+  });
+
+  it("drives the literal `sources update` verb over a cold project, then boots a read", async () => {
+    // A cold file-package project with nothing built yet — the real CLI path.
+    const pkg = mkdtempSync(join(tmpdir(), "e1-pkg-"));
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    writeFileSync(join(pkg, "definitions", "pack.ttl"), DEFAULT_PACK_TTL);
+    const cwd = mkdtempSync(join(tmpdir(), "e1-proj-"));
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      `export default { packs: [{ name: "default", source: "file://${pkg}" }] };\n`,
+    );
+    try {
+      // `sources update` is a real mutation — resolve, build, point the project.
+      const outcome = await executeVerb(
+        updateVerb,
+        {},
+        NO_MUTATION,
+        bootRuntime(JSON_FLAGS, cwd),
+      );
+      expect(outcome.exitCode).toBe(0);
+      expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
+      // A SEPARATE, fresh runtime boots the just-built pack from the pointer and
+      // answers a read over it. Since L-OPEN-9 the list is unfiltered, so the
+      // cold-boot read returns the pack's WHOLE block set — the beta-gated Beta
+      // Badge and the untiered Orphan Widget included. That makes this the
+      // strictest form of the assert (an exact set, not a tolerant subset).
+      expect(await blockListNames(cwd)).toEqual([
+        "Beta Badge",
+        "Button",
+        "Card",
+        UNTIERED_BLOCK_NAME,
+      ]);
+    } finally {
+      rmSync(pkg, { recursive: true, force: true });
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("default-pack journey — graph query over the real pack (E1)", () => {
+  it("a SELECT resolves every ds:Component, including the untiered one", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const envelope = await readVerb(
+      graphQueryVerb,
+      {
+        sparql:
+          "SELECT ?name WHERE { ?c a ds:Component ; ds:name ?name } ORDER BY ?name",
+      },
+      fixture.cwd,
+    );
+    expect(envelope.ok).toBe(true);
+    const data = envelope.data as {
+      type: string;
+      bindings: { name: string }[];
+    };
+    expect(data.type).toBe("select");
+    // All THREE components are in the graph — the untiered Orphan Widget too.
+    expect(data.bindings.map((binding) => binding.name)).toEqual([
+      "Beta Badge",
+      "Button",
+      "Orphan Widget",
+    ]);
+  });
+
+  it("an ASK over a known individual returns true", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const envelope = await readVerb(
+      graphQueryVerb,
+      { sparql: "ASK { ds:card a ds:Pattern }" },
+      fixture.cwd,
+    );
+    const data = envelope.data as { type: string; result: boolean };
+    expect(data.type).toBe("ask");
+    expect(data.result).toBe(true);
+  });
+
+  it("a malformed query surfaces INVALID_INPUT, not an internal crash", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    await expect(
+      executeVerb(
+        graphQueryVerb,
+        { sparql: "SELECT ?s WHERE { ?s ?p" },
+        NO_MUTATION,
+        bootRuntime(JSON_FLAGS, fixture.cwd),
+      ),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+});
+
+describe("default-pack journey — block list, populated and empty (E1)", () => {
+  /** The pack's WHOLE block set — what the declared list returns, always. */
+  const ALL_FOUR = ["Beta Badge", "Button", "Card", UNTIERED_BLOCK_NAME];
+
+  it("the `normal` channel lists the beta-gated block too (L-OPEN-9)", async () => {
+    // This used to answer ["Button", "Card"]: the hand-written query hid Beta
+    // Badge behind the channel and Orphan Widget behind the required tier join.
+    // The declared list has neither filter, so the signed-off consequence is
+    // pinned right where the old scoping was.
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    expect(await blockListNames(fixture.cwd)).toEqual(ALL_FOUR);
+  });
+
+  it("the `prerelease` channel returns the SAME rows — channel scopes nothing", async () => {
+    const fixture = await boot(
+      DEFAULT_PACK_TTL,
+      DEFAULT_PACK_ALL_VISIBLE_CONFIG,
+    );
+    expect(await blockListNames(fixture.cwd)).toEqual(ALL_FOUR);
+  });
+
+  it("a configured tier returns the SAME rows — there is no chain to walk", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, {
+      tier: "apps",
+      channel: "prerelease",
+    });
+    // The hand-written verb expanded `apps` to [global, apps] and listed the
+    // union; the declared list never reads the tier at all, so `apps` and the
+    // unset default are indistinguishable.
+    expect(await blockListNames(fixture.cwd)).toEqual(ALL_FOUR);
+  });
+
+  it("an ontology-only pack with no blocks lists empty — a calm exit 0", async () => {
+    // D10-A, MEASURED at the dispatch seam the binary uses: the declared list
+    // body (`makeListRun`) returns `[]` and never throws on emptiness, so the
+    // process still exits 0 — no exit-code delta against the hand-written verb.
+    // Only the empty MESSAGE moved (the story's `emptyRecovery` replaces the
+    // tier/channel wording and the `--all-tiers` hint).
+    const fixture = await boot(NO_BLOCKS_TTL);
+    const outcome = await executeVerb(
+      blockListVerb,
+      {},
+      NO_MUTATION,
+      bootRuntime(JSON_FLAGS, fixture.cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    const envelope = JSON.parse(outcome.stdout as string) as Envelope;
+    expect(envelope.ok).toBe(true);
+    expect(envelope.data).toEqual([]);
+  });
+});
+
+describe("default-pack journey — ontology list/show, populated and empty (E1)", () => {
+  it("lists the ds namespace with its class and property counts", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const envelope = await readVerb(ontologyListVerb, {}, fixture.cwd);
+    const summaries = envelope.data as {
+      prefix: string;
+      classCount: number;
+      propertyCount: number;
+    }[];
+    expect(summaries).toEqual([
+      {
+        prefix: "ds",
+        namespace: "https://ds.canonical.com/",
+        classCount: 5,
+        propertyCount: 4,
+      },
+    ]);
+  });
+
+  it("ontology show ds surfaces the two block domain classes", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const envelope = await readVerb(
+      ontologyShowVerb,
+      { prefix: "ds" },
+      fixture.cwd,
+    );
+    const data = envelope.data as { classes: { uri: string }[] };
+    const localNames = data.classes.map((klass) => klass.uri.split("/").at(-1));
+    expect(localNames).toContain("Component");
+    expect(localNames).toContain("Pattern");
+  });
+
+  it("a pack of pure instance data lists NO ontology namespaces — empty, calm", async () => {
+    const fixture = await boot(INSTANCE_ONLY_TTL);
+    const envelope = await readVerb(ontologyListVerb, {}, fixture.cwd);
+    expect(envelope.ok).toBe(true);
+    expect(envelope.data).toEqual([]);
+  });
+
+  it("ontology show of an unknown prefix is NOT_FOUND, not a crash", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    await expect(
+      executeVerb(
+        ontologyShowVerb,
+        { prefix: "nope" },
+        NO_MUTATION,
+        bootRuntime(JSON_FLAGS, fixture.cwd),
+      ),
+    ).rejects.toBeInstanceOf(PragmaError);
+  });
+});
+
+describe("default-pack journey — error paths (E1)", () => {
+  it("a malformed .ttl fails the build with a NAMED CONFIG_ERROR, not INTERNAL", async () => {
+    // bootFixtureRuntime writes the ttl into `fixture/definitions/fixture.ttl`
+    // and runs the REAL sources-update build, which classifies the parser error.
+    await expect(
+      bootFixtureRuntime({ ttl: MALFORMED_TTL }),
+    ).rejects.toMatchObject({ code: "CONFIG_ERROR" });
+  });
+
+  it("a torn (emptied) schema.json boots to STORE_UNAVAILABLE with the update recovery", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const active = readActivePack(fixture.cwd) ?? "";
+    // Simulate a torn/evicted extraction: truncate schema.json in the pack cache.
+    truncateSync(join(packDir(active), SCHEMA_FILE), 0);
+    // A brand-new runtime (fresh store memo) boots against the now-incomplete pack.
+    let caught: unknown;
+    try {
+      await executeVerb(
+        blockListVerb,
+        {},
+        NO_MUTATION,
+        bootRuntime(JSON_FLAGS, fixture.cwd),
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(PragmaError);
+    expect((caught as PragmaError).code).toBe("STORE_UNAVAILABLE");
+    expect((caught as PragmaError).recovery?.cli).toBe("pragma sources update");
+  });
+});
+
+describe("default-pack journey — real-data shapes the clean fixture masked (E1, hand-off to lanes A)", () => {
+  it("every block is co-typed owl:NamedIndividual and indexed as an individual (abox)", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const index = await activeIndex(fixture);
+    // The vendored pack indexes 17 distinct entities (5 classes + 4 properties +
+    // 2 tiers + 2 channels + 4 blocks).
+    expect(index?.entities).toHaveLength(17);
+    const button = index?.entities.find(
+      (entity) => entity.name === "ds:button",
+    );
+    expect(button?.box).toBe("abox");
+    expect(button?.types).toContain("owl:NamedIndividual");
+    expect(button?.types).toContain("ds:Component");
+  });
+
+  it("a multilingual rdfs:label is stored in BOTH languages and indexed tag-stripped (A7)", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    // Both language variants are retrievable directly from the store.
+    const en = await fixture.runtime.query.sparql(
+      'SELECT ?l WHERE { ds:button rdfs:label ?l . FILTER(LANG(?l) = "en") }',
+    );
+    const fr = await fixture.runtime.query.sparql(
+      'SELECT ?l WHERE { ds:button rdfs:label ?l . FILTER(LANG(?l) = "fr") }',
+    );
+    const value = (result: typeof en): string | undefined =>
+      result.type === "select"
+        ? (result.bindings.at(0) as { l?: string } | undefined)?.l
+        : undefined;
+    expect(value(en)).toBe("Button");
+    expect(value(fr)).toBe("Bouton");
+    // The single-valued index carries ONE label, tag-stripped (no `@en`/`@fr`).
+    // NOTE(A7): which language wins is store-order-arbitrary — the index picks
+    // whichever the store yields first (no `@en` preference). E3 (live oxigraph)
+    // is where that ordering is confirmed against the real pack; here we only
+    // assert the tag is stripped and the value is one of the two declared forms.
+    const label = (await activeIndex(fixture))?.entities.find(
+      (entity) => entity.name === "ds:button",
+    )?.label;
+    expect(label).not.toMatch(/@(en|fr)/);
+    expect(["Button", "Bouton"]).toContain(label);
+  });
+
+  // ----- HAND-OFFS (A1, A2): lane A's fixes have landed in this branch, so the
+  // former `it.fails` pins are now LIVE regression guards. -----
+
+  it("A1: info's entity total must not exceed the distinct entity count (owl:NamedIndividual double-count)", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const index = await activeIndex(fixture);
+    // `entityTotal` (the figure `info`/`doctor` report) once SUMMED per-type
+    // instance counts, double-counting each entity per asserted rdf:type (each
+    // block under owl:NamedIndividual AND its domain class; ds:tier/ds:release
+    // under owl:ObjectProperty AND owl:FunctionalProperty — 23 for 17 distinct
+    // entities). Lane A fixed the count, so the true total no longer exceeds the
+    // distinct count — guard it stays that way.
+    expect(entityTotal(index as NonNullable<typeof index>)).toBeLessThanOrEqual(
+      (index as NonNullable<typeof index>).entities.length,
+    );
+  });
+
+  it("A2: an untiered block must still appear in `block list`", async () => {
+    const fixture = await boot(
+      DEFAULT_PACK_TTL,
+      DEFAULT_PACK_ALL_VISIBLE_CONFIG,
+    );
+    // `block list`'s SELECT once inner-joined `?c ds:tier ?t`, dropping a
+    // ds:Component with no ds:tier even under --all-tiers (though `graph query`
+    // found it, proven above). Lane A made the tier join OPTIONAL; L-OPEN-9 then
+    // removed the filtering entirely, so the untiered block is visible in the
+    // ONE view that now exists — guard it stays that way.
+    expect(await blockListNames(fixture.cwd)).toContain(UNTIERED_BLOCK_NAME);
+  });
+
+  // KNOWN GAP / product follow-up (NOT a lane hand-off): a corrupt, NON-EMPTY
+  // `schema.json` currently surfaces UNCLASSIFIED. `packIsComplete` only checks
+  // size > 0, so torn-but-nonempty garbage bypasses the completeness guard and
+  // `compileFromExtraction` throws a raw `SyntaxError` (renders as INTERNAL
+  // "please report") instead of a classified error. It SHOULD degrade to
+  // STORE_UNAVAILABLE like the emptied case does — the fix belongs in
+  // `kernel/runtime/graphpack/read.ts` (guard the `schema.json` read/compile).
+  // No lane in this wave owns that, so rather than a false `it.fails` hand-off
+  // that would never flip, this is a plain test pinning the CURRENT behavior:
+  // when read.ts starts classifying it, this guard trips — swap the assertion
+  // to expect a STORE_UNAVAILABLE PragmaError then.
+  it("corrupt (non-empty, invalid) schema.json currently surfaces an UNCLASSIFIED error (known gap)", async () => {
+    const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
+    const active = readActivePack(fixture.cwd) ?? "";
+    writeFileSync(join(packDir(active), SCHEMA_FILE), "{ not valid json ]");
+    let caught: unknown;
+    try {
+      await executeVerb(
+        blockListVerb,
+        {},
+        NO_MUTATION,
+        bootRuntime(JSON_FLAGS, fixture.cwd),
+      );
+    } catch (error) {
+      caught = error;
+    }
+    // It throws — but as a raw, unclassified error, NOT a PragmaError. Assert the
+    // gap explicitly so a future classification fix in read.ts trips this guard.
+    expect(caught).toBeInstanceOf(Error);
+    expect(caught).not.toBeInstanceOf(PragmaError);
+  });
+});

package/src/testing/behavioral/journeys.firstInstall.test.ts

@@ -0,0 +1,167 @@
+/**
+ * The first-install journey — this PR's whole point, pinned.
+ *
+ * A machine with no cache, no pointer, no network and an empty cwd must answer
+ * real store-backed reads from the embedded pack, and must say honestly where
+ * those answers come from. Equally: a project that declared its OWN packs and
+ * never built them must NOT be handed the distribution's graph — it is a
+ * different graph, and quietly serving it is the failure the boot decision
+ * exists to prevent.
+ *
+ * Assertions pin MEMBERSHIP, never counts: the row counts move whenever the
+ * upstream design system does, but a design system with no `Button`, or a tier
+ * hierarchy with no `Global`, is a change a human should be made to look at.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { storyModules } from "../../capabilities/distribution.js";
+import { checkPackageRefs } from "../../capabilities/doctor/checks/checkPackageRefs.js";
+import { promptListVerb } from "../../capabilities/prompt/verbs.js";
+import { collectStatus } from "../../capabilities/sources/collectStatus.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+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 { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+
+const JSON_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+const NO_MUTATION = { dryRun: false, undo: false, yes: false };
+
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+const standardModule = storyModules.get("standard");
+if (!standardModule) {
+  throw new Error('pragma.conf.ts declares no story for "standard"');
+}
+const tierModule = storyModules.get("tier");
+if (!tierModule) {
+  throw new Error('pragma.conf.ts declares no story for "tier"');
+}
+const tokenModule = storyModules.get("token");
+if (!tokenModule) {
+  throw new Error('pragma.conf.ts declares no story for "token"');
+}
+
+const verbOf = (module: CapabilityModule, path: string): VerbSpec =>
+  module.verbs.find((verb) => verb.path.join(" ") === path) as VerbSpec;
+
+/** A cwd with nothing in it — the cold-install shape (the XDG dirs are isolated). */
+const emptyCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-first-"));
+
+/**
+ * A cwd whose `pragma.config.ts` declares its own packs and has never been
+ * built — `origins.packs` is "project", so the embedded pack must not answer.
+ */
+function unbuiltProjectCwd(): string {
+  const cwd = mkdtempSync(join(tmpdir(), "pragma-unbuilt-"));
+  writeFileSync(
+    join(cwd, "pragma.config.ts"),
+    'export default { packs: [{ name: "mine", source: "file:///pragma-never-built" }] };\n',
+  );
+  return cwd;
+}
+
+/** Run a read verb at a cwd and return the parsed `data` payload. */
+async function readData(verb: VerbSpec, cwd: string): Promise<unknown> {
+  const outcome = await executeVerb(
+    verb,
+    {},
+    NO_MUTATION,
+    bootRuntime(JSON_FLAGS, cwd),
+  );
+  return (JSON.parse(outcome.stdout as string) as { data: unknown }).data;
+}
+
+describe("first install — an empty cwd answers real reads offline", () => {
+  it("block list resolves the design system's blocks", async () => {
+    const rows = (await readData(
+      verbOf(blockModule, "block list"),
+      emptyCwd(),
+    )) as { name: string }[];
+    expect(rows.map((row) => row.name)).toContain("Button");
+  });
+
+  it("standard list resolves the code standards", async () => {
+    const rows = (await readData(
+      verbOf(standardModule, "standard list"),
+      emptyCwd(),
+    )) as { uri: string; name: string }[];
+    expect(rows.length).toBeGreaterThan(0);
+    // Every row is a code standard from the standards pack's own namespace.
+    for (const row of rows) {
+      expect(row.uri).toContain("codestandards#");
+    }
+  });
+
+  it("tier list resolves the tier hierarchy", async () => {
+    const rows = (await readData(
+      verbOf(tierModule, "tier list"),
+      emptyCwd(),
+    )) as { name: string }[];
+    expect(rows.map((row) => row.name)).toContain("Global");
+  });
+});
+
+describe("first install — empty results are honest, not papered over", () => {
+  it("token list exits calmly with no rows (the graph carries no ds:Token)", async () => {
+    expect(
+      await readData(verbOf(tokenModule, "token list"), emptyCwd()),
+    ).toEqual([]);
+  });
+
+  it("prompt list exits calmly with no prompts (the graph carries no ds:Prompt)", async () => {
+    expect(await readData(promptListVerb as VerbSpec, emptyCwd())).toEqual({
+      prompts: [],
+    });
+  });
+});
+
+describe("first install — a project with its own unbuilt packs is refused", () => {
+  it("a read throws STORE_UNAVAILABLE naming `pragma sources update`", async () => {
+    let caught: unknown;
+    try {
+      await readData(verbOf(blockModule, "block list"), unbuiltProjectCwd());
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(PragmaError);
+    expect((caught as PragmaError).code).toBe("STORE_UNAVAILABLE");
+    expect((caught as PragmaError).recovery?.cli).toBe("pragma sources update");
+  });
+
+  it("doctor reports it as a failure, not a healthy install", async () => {
+    const result = await checkPackageRefs(
+      bootRuntime(JSON_FLAGS, unbuiltProjectCwd()),
+    );
+    expect(result.status).toBe("fail");
+    expect(result.detail).toContain("the store has not been built");
+    expect(result.remedy).toBe("pragma sources update");
+  });
+});
+
+describe("first install — the surfaces say where the answers come from", () => {
+  it("sources status reports the embedded snapshot with its provenance", async () => {
+    const status = await collectStatus(bootRuntime(JSON_FLAGS, emptyCwd()));
+    expect(status.store).toBe("embedded");
+    // The upstream revisions the snapshot was compiled from — never "up to date".
+    expect(status.sourceRef).toContain("@canonical/design-system@");
+    expect(status.entityCount).toBeGreaterThan(0);
+  });
+
+  it("doctor passes, naming the embedded snapshot rather than the config", async () => {
+    const result = await checkPackageRefs(bootRuntime(JSON_FLAGS, emptyCwd()));
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("embedded snapshot @ ");
+    expect(result.detail).toContain("pragma sources update");
+  });
+});