@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/sources/sources.test.ts

@@ -5,6 +5,7 @@ import {
   mkdtempSync,
   readFileSync,
   rmSync,
+  symlinkSync,
   writeFileSync,
 } from "node:fs";
 import type { createRequire } from "node:module";
@@ -13,19 +14,30 @@ import { join } from "node:path";
 import { runTask } from "@canonical/task/node";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { VERSION } from "../../constants.js";
-import type { ConfigLayers, PackageEntry } from "../../kernel/config/types.js";
+import type {
+  ConfigLayers,
+  PackDeclaration,
+} from "../../kernel/config/types.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import { createQueryFacade } from "../../kernel/runtime/facade.js";
-import { readLock } from "../../kernel/runtime/lock.js";
-import { lockPath, packDir } from "../../kernel/runtime/paths.js";
-import { resolvePackageJson } from "../../kernel/runtime/refs/resolve.js";
+import { readManifest } from "../../kernel/runtime/graphpack/manifest.js";
+import {
+  activePackPath,
+  packDir,
+  readActivePack,
+} from "../../kernel/runtime/paths.js";
+import {
+  detectPrefixClashes,
+  resolvePackageJson,
+} from "../../kernel/runtime/refs/resolve.js";
 import { createLazyStore } from "../../kernel/runtime/store.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 { discoverSkills } from "../skill/discover.js";
+import { collectStatus } from "./collectStatus.js";
 import { sourcesModule } from "./index.js";
 import { buildUpdateTask } from "./runUpdate.js";
 
@@ -53,18 +65,17 @@ const tmp = (prefix: string): string => {
   return dir;
 };
 
-/** A runtime whose config is the given package list (no config files needed). */
-function runtimeFor(cwd: string, packages: PackageEntry[]): PragmaRuntime {
+/** A runtime whose config is the given pack list (no config files needed). */
+function runtimeFor(cwd: string, packs: PackDeclaration[]): PragmaRuntime {
   const layers: ConfigLayers = {
-    config: { channel: "normal", packages },
+    config: { channel: "normal", packs },
     origins: {
       tier: "default",
       channel: "default",
       detail: "default",
-      packages: "project",
+      packs: "project",
       stories: "default",
       prefixes: "default",
-      prompts: "default",
     },
     global: { path: "/nonexistent", exists: false },
     project: { exists: false },
@@ -96,30 +107,24 @@ function filePackage(): string {
   return pkg;
 }
 
-describe("sources lock round-trip (PROTECTED)", () => {
-  it("file source: builds, locks, and --frozen rewrites a byte-identical lock", async () => {
+describe("sources update round-trip (PROTECTED)", () => {
+  it("file source: builds and points the project at the built pack", async () => {
     const pkg = filePackage();
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-
-    const lock = readLock(cwd);
-    expect(lock?.packs).toHaveLength(1);
-    expect(lock?.packs[0]?.name).toBe("pkg-a");
-    expect(lock?.packs[0]?.resolved).toBe(pkg);
-    expect(lock?.contentHash).toBe(result.contentHash);
-
-    const firstBytes = readFileSync(lockPath(cwd), "utf-8");
-    // A --frozen re-run reproduces the locked state byte-for-byte.
-    await runTask(await buildUpdateTask(runtime, true));
-    expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
+    expect(result.packs).toEqual([
+      { name: "pkg-a", resolved: pkg, sourceCount: 1, storyCount: 0 },
+    ]);
+    // The pointer the next boot reads names exactly the pack just built.
+    expect(readActivePack(cwd)).toBe(result.contentHash);
   });
 
-  it("git source: resolves and locks a commit SHA, --frozen pins it", async () => {
+  it("git source: resolves the ref to a commit SHA", async () => {
     const repo = tmp("pragma-repo-");
     const git = (args: string[]) =>
       execFileSync("git", args, {
@@ -144,25 +149,83 @@ describe("sources lock round-trip (PROTECTED)", () => {
       { name: "pkg-git", source: `git+file://${repo}#main` },
     ]);
 
-    await runTask(await buildUpdateTask(runtime, false));
-    const lock = readLock(cwd);
-    expect(lock?.packs[0]?.resolved).toMatch(/^[0-9a-f]{40}$/);
+    const result = await runTask(await buildUpdateTask(runtime));
+    const sha = result.packs.at(0)?.resolved;
+    expect(sha).toMatch(/^[0-9a-f]{40}$/);
+    expect(readActivePack(cwd)).toBe(result.contentHash);
+    // The revision reaches the manifest's provenance label, which is the only
+    // place `sources status` and `doctor` can read it from now that no lock
+    // records it. Same `<name>@<kind>:<resolved>` shape the bundler writes.
+    expect(readManifest(packDir(result.contentHash))?.sourceRef).toBe(
+      `pkg-git@git:${sha}`,
+    );
+  });
+
+  it("a re-run over an unchanged source leaves the pointer byte-identical (L1)", async () => {
+    // On base the lock file carried a `resolvedAt` timestamp, so a no-op re-run
+    // rewrote it and dirtied the tree. The pointer holds only the content hash,
+    // which is a pure function of the sources — so this is now true by
+    // construction. The guard stays because it is the property users cared
+    // about: repeating an update changes nothing when nothing changed.
+    const pkg = filePackage();
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+    const firstBytes = readFileSync(activePackPath(cwd), "utf-8");
+    await runTask(await buildUpdateTask(runtime));
+    expect(readFileSync(activePackPath(cwd), "utf-8")).toBe(firstBytes);
+  });
+
+  it("follows a symlinked .ttl into the build (L6)", async () => {
+    // pnpm / workspace trees symlink their sources; Dirent.isFile is false for a
+    // symlink, so on base the only `.ttl` was skipped → 0 sources → the empty
+    // build. Following the link ingests it and the build succeeds.
+    const pkg = tmp("pragma-symlink-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    const realTtl = join(pkg, "real.ttl");
+    writeFileSync(realTtl, TTL);
+    symlinkSync(realTtl, join(pkg, "definitions", "linked.ttl"));
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+
+    const result = await runTask(await buildUpdateTask(runtime));
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(readActivePack(cwd)).toBe(result.contentHash);
+  });
+
+  it("does not recurse into a symlinked directory cycle (L6 safety)", async () => {
+    // The L6 fix follows symlinked FILES but must NOT recurse into a symlinked
+    // DIRECTORY: a link to an ancestor dir is a cycle that, if walked, recurses
+    // without bound → a stack-overflow RangeError (an INTERNAL "please report").
+    // The real `.ttl` is still ingested and the build completes.
+    const pkg = tmp("pragma-symlink-cycle-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    writeFileSync(join(pkg, "definitions", "widget.ttl"), TTL);
+    // `definitions/loop` → `definitions` (its own parent): a symlink cycle.
+    symlinkSync(join(pkg, "definitions"), join(pkg, "definitions", "loop"));
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
 
-    const firstBytes = readFileSync(lockPath(cwd), "utf-8");
-    await runTask(await buildUpdateTask(runtime, true));
-    expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
+    const result = await runTask(await buildUpdateTask(runtime));
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(readActivePack(cwd)).toBe(result.contentHash);
   });
 
-  it("undo restores the prior lock (no prior → removed)", async () => {
+  it("undo removes the pointer when the project had none before", async () => {
     const pkg = filePackage();
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
     const { runUndo } = await import("@canonical/task/node");
-    await runUndo(await buildUpdateTask(runtime, false));
-    // Prior lock was absent, so undo removes the file.
-    expect(readLock(cwd)).toBeUndefined();
+    await runUndo(await buildUpdateTask(runtime));
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -178,7 +241,7 @@ describe("sources update — package-declared prefixes (M1)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     const index = JSON.parse(
       readFileSync(join(packDir(result.contentHash), "index.json"), "utf-8"),
     ) as {
@@ -200,6 +263,114 @@ describe("sources update — package-declared prefixes (M1)", () => {
   });
 });
 
+describe("sources update — refuses an empty store (A4)", () => {
+  /** A local package that ships NO `.ttl` (an empty definitions directory). */
+  function emptyPackage(): string {
+    const pkg = tmp("pragma-empty-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    return pkg;
+  }
+
+  it("a package with no .ttl is refused, and no pointer is written", async () => {
+    // On base this builds a 0-triple pack whose empty data.nq fails the
+    // completeness gate — so the "successful" update boots to a PERMANENT
+    // STORE_UNAVAILABLE loop. The fix refuses before writing the pointer.
+    const pkg = emptyPackage();
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+    // No pointer → the embedded fallback / prior state survives, no boot loop.
+    expect(readActivePack(cwd)).toBeUndefined();
+  });
+
+  it("no configured packs is refused rather than pointing at an empty pack", async () => {
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, []);
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+    expect(readActivePack(cwd)).toBeUndefined();
+  });
+
+  it("a comment-only .ttl (0 triples) is refused too", async () => {
+    const pkg = tmp("pragma-noTriples-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    // Parses fine, but yields no triples — the post-build 0-triple guard.
+    writeFileSync(
+      join(pkg, "definitions", "empty.ttl"),
+      "# only a comment, no triples\n",
+    );
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+    expect(readActivePack(cwd)).toBeUndefined();
+  });
+});
+
+describe("sources update — conflicting @prefix detection (A5)", () => {
+  it("flags a label bound to two different IRIs across packages", () => {
+    const clashes = detectPrefixClashes([
+      { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },
+      { content: "@prefix ex: <https://b.test/#> .\nex:Two a ex:T ." },
+    ]);
+    expect(clashes).toHaveLength(1);
+    expect(clashes.at(0)?.label).toBe("ex");
+    expect(clashes.at(0)?.iris).toEqual([
+      "https://a.test/#",
+      "https://b.test/#",
+    ]);
+  });
+
+  it("does NOT flag harmless same-label/same-IRI redeclarations", () => {
+    const clashes = detectPrefixClashes([
+      { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },
+      { content: "@prefix ex: <https://a.test/#> .\nex:Two a ex:T ." },
+    ]);
+    expect(clashes).toEqual([]);
+  });
+
+  it("warns loudly on a cross-package prefix clash during update", async () => {
+    const owl = "@prefix owl: <http://www.w3.org/2002/07/owl#> .\n";
+    const pkgA = tmp("pragma-clash-a-");
+    mkdirSync(join(pkgA, "definitions"), { recursive: true });
+    writeFileSync(
+      join(pkgA, "definitions", "a.ttl"),
+      `@prefix ex: <https://a.test/#> .\n${owl}ex:Thing a owl:Class .\nex:one a ex:Thing .\n`,
+    );
+    const pkgB = tmp("pragma-clash-b-");
+    mkdirSync(join(pkgB, "definitions"), { recursive: true });
+    writeFileSync(
+      join(pkgB, "definitions", "b.ttl"),
+      `@prefix ex: <https://b.test/#> .\n${owl}ex:Widget a owl:Class .\nex:two a ex:Widget .\n`,
+    );
+    const cwd = tmp("pragma-proj-");
+    const reports: string[] = [];
+    const runtime: PragmaRuntime = {
+      ...runtimeFor(cwd, [
+        { name: "pkg-a", source: `file://${pkgA}` },
+        { name: "pkg-b", source: `file://${pkgB}` },
+      ]),
+      report: (message: string) => reports.push(message),
+    };
+
+    await runTask(await buildUpdateTask(runtime));
+    expect(
+      reports.some(
+        (r) => r.includes('Prefix "ex:"') && r.includes("conflicting"),
+      ),
+    ).toBe(true);
+  });
+});
+
 describe("sources update — network-free preview (M2)", () => {
   const updateVerb = sourcesModule.verbs[1] as VerbSpec;
   const DRY_RUN = { dryRun: true, undo: false, yes: false };
@@ -218,11 +389,12 @@ describe("sources update — network-free preview (M2)", () => {
 
     // A successful plan — the unreachable clone was never attempted.
     expect(outcome.exitCode).toBe(0);
-    expect(outcome.stdout).toContain("Resolve and build 1 package(s)");
+    expect(outcome.stdout).toContain("Resolve and build 1 pack(s)");
     expect(outcome.stdout).toContain(UNREACHABLE);
-    // The one project mutation is previewed, not performed.
-    expect(outcome.stdout).toContain("pragma.lock.json");
-    expect(readLock(cwd)).toBeUndefined();
+    // The project mutation is previewed, not performed: the plan names the
+    // exact pointer file a real run would write, and no pointer landed.
+    expect(outcome.stdout).toContain(activePackPath(cwd));
+    expect(readActivePack(cwd)).toBeUndefined();
     // The store was never even asked for.
     expect(runtime.store.booted).toBe(false);
   });
@@ -231,7 +403,7 @@ describe("sources update — network-free preview (M2)", () => {
     const cwd = tmp("pragma-proj-");
     writeFileSync(
       join(cwd, "pragma.config.ts"),
-      `export default { packages: [{ name: "pkg-remote", source: "${UNREACHABLE}" }] };\n`,
+      `export default { packs: [{ name: "pkg-remote", source: "${UNREACHABLE}" }] };\n`,
     );
 
     const mcp = await projectMcp([sourcesModule], cwd);
@@ -245,25 +417,8 @@ describe("sources update — network-free preview (M2)", () => {
     });
     const plan = (envelope.data as { plan: string[] }).plan;
     expect(plan.some((line) => line.includes(UNREACHABLE))).toBe(true);
-    // Plan-first withheld the write — no lock landed.
-    expect(readLock(cwd)).toBeUndefined();
-  });
-});
-
-describe("sources update — reproducible-or-fail (m5)", () => {
-  it("--frozen refuses a package that has no lock entry", async () => {
-    const pkg = filePackage();
-    const cwd = tmp("pragma-proj-");
-    const runtime = runtimeFor(cwd, [
-      { name: "pkg-a", source: `file://${pkg}` },
-    ]);
-
-    // No prior lock → nothing to reproduce → refuse rather than silently
-    // advance. The throw is raised during setup, before any Task is returned.
-    await expect(buildUpdateTask(runtime, true)).rejects.toMatchObject({
-      code: "CONFIG_ERROR",
-    });
-    expect(readLock(cwd)).toBeUndefined();
+    // Plan-first withheld the write — no pointer landed.
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -331,7 +486,7 @@ describe("sources update — data-failure classification (U6)", () => {
 
     let caught: unknown;
     try {
-      await buildUpdateTask(runtime, false);
+      await buildUpdateTask(runtime);
     } catch (error) {
       caught = error;
     }
@@ -349,8 +504,8 @@ describe("sources update — data-failure classification (U6)", () => {
     expect(err.recovery?.message ?? "").not.toContain("report this issue");
     // The recovery points the user at a runnable, useful next step.
     expect(err.recovery?.cli).toBe("pragma sources update --verbose");
-    // Nothing was locked on failure.
-    expect(readLock(cwd)).toBeUndefined();
+    // Nothing was pointed at on failure.
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("classifies a git clone failure, naming the package (not INTERNAL)", async () => {
@@ -367,7 +522,7 @@ describe("sources update — data-failure classification (U6)", () => {
 
     let caught: unknown;
     try {
-      await buildUpdateTask(runtime, false);
+      await buildUpdateTask(runtime);
     } catch (error) {
       caught = error;
     }
@@ -376,7 +531,7 @@ describe("sources update — data-failure classification (U6)", () => {
     expect(err.code).toBe("CONFIG_ERROR");
     expect(err.message).toContain("pkg-remote");
     expect(err.message).not.toContain("Internal error");
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("names the SPECIFIC bad file among several good ones", async () => {
@@ -390,12 +545,12 @@ describe("sources update — data-failure classification (U6)", () => {
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [{ name: "mix", source: `file://${pkg}` }]);
 
-    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
     let caught: unknown;
     try {
-      await buildUpdateTask(runtime, false);
+      await buildUpdateTask(runtime);
     } catch (error) {
       caught = error;
     }
@@ -427,9 +582,9 @@ describe("sources update — hidden files and --skip-invalid", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(readLock(cwd)?.packs).toHaveLength(1);
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
   });
 
   it("without --skip-invalid, one malformed source fails the whole update", async () => {
@@ -438,10 +593,10 @@ describe("sources update — hidden files and --skip-invalid", () => {
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
-    await expect(buildUpdateTask(runtime, false, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("with --skip-invalid, drops the bad source, warns loudly, and builds from the rest", async () => {
@@ -453,10 +608,10 @@ describe("sources update — hidden files and --skip-invalid", () => {
       report: (message: string) => reports.push(message),
     };
 
-    const result = await runTask(await buildUpdateTask(runtime, false, true));
+    const result = await runTask(await buildUpdateTask(runtime, true));
     // Built from the good widget.ttl, not aborted.
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(readLock(cwd)?.packs).toHaveLength(1);
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
     // Loud per-source warning names the dropped file …
     expect(
       reports.some(
@@ -476,10 +631,10 @@ describe("sources update — hidden files and --skip-invalid", () => {
       ...runtimeFor(cwd, [{ name: "pkg-a", source: `file://${pkg}` }]),
       report: () => {},
     };
-    await expect(buildUpdateTask(runtime, false, true)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime, true)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -573,7 +728,7 @@ describe("sources update — installs package skills (U10)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    await runTask(await buildUpdateTask(runtime, false));
+    await runTask(await buildUpdateTask(runtime));
 
     // Installed as a symlink into $XDG_DATA_HOME/pragma/skills …
     const linked = join(dataHome, "pragma", "skills", "foo");
@@ -595,7 +750,7 @@ describe("sources update — installs package skills (U10)", () => {
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
-    await runTask(await buildUpdateTask(runtime, false));
+    await runTask(await buildUpdateTask(runtime));
 
     const shared = discoverSkills(cwd).filter((s) => s.name === "shared");
     expect(shared).toHaveLength(1);
@@ -609,16 +764,42 @@ describe("sources update — installs package skills (U10)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
     const { runUndo } = await import("@canonical/task/node");
-    await runUndo(await buildUpdateTask(runtime, false));
+    await runUndo(await buildUpdateTask(runtime));
 
     expect(existsSync(join(dataHome, "pragma", "skills", "bar"))).toBe(false);
   });
 });
 
+describe("sources status — entityCount from the manifest (A10)", () => {
+  it("reports the count from the manifest even when index.json is unreadable", async () => {
+    // A pack of its OWN (unique TTL ⇒ unique content hash), so corrupting its
+    // cached index cannot reach any other test's pack in the shared cache.
+    const pkg = tmp("pragma-a10-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    writeFileSync(
+      join(pkg, "definitions", "widget.ttl"),
+      `${TTL}ex:a10only a ex:Widget ; rdfs:label "A10" .\n`,
+    );
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a10", source: `file://${pkg}` },
+    ]);
+    const result = await runTask(await buildUpdateTask(runtime));
+
+    // Corrupt index.json but keep it non-empty, so the pack still reads as
+    // complete: any path that PARSED it to count would now yield null.
+    writeFileSync(join(packDir(result.contentHash), "index.json"), "not json");
+
+    const status = await collectStatus(bootRuntime(flagsJson, cwd));
+    // Two abox individuals (ex:one, ex:a10only); ex:Widget is tbox, not counted.
+    expect(status.entityCount).toBe(2);
+  });
+});
+
 describe("sources status CLI-json == MCP tool (PROTECTED)", () => {
-  it("a cold store's status is byte-equal on both surfaces", async () => {
-    // Both surfaces boot from the SAME cwd + isolated config (default packages,
-    // no lock), so the storeless status must be identical.
+  it("a fresh install's status is byte-equal on both surfaces", async () => {
+    // Both surfaces boot from the SAME cwd + isolated config (default packs,
+    // nothing built), so the storeless status must be identical.
     const cwd = tmp("pragma-proj-");
     const cli = await executeVerb(
       statusVerb,
@@ -634,9 +815,8 @@ describe("sources status CLI-json == MCP tool (PROTECTED)", () => {
 
     expect(cliEnvelope).toEqual(mcpEnvelope);
     expect(cliEnvelope.ok).toBe(true);
-    expect((cliEnvelope.data as { lockPresent: boolean }).lockPresent).toBe(
-      false,
-    );
-    expect((cliEnvelope.data as { cached: boolean }).cached).toBe(false);
+    // Nothing built here, and the packs are the distribution's own — so the
+    // embedded snapshot is what answers reads, and status says exactly that.
+    expect((cliEnvelope.data as { store: string }).store).toBe("embedded");
   });
 });

package/src/capabilities/sources/status.render.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
+import { renderSourcesStatusPlain } from "./status.render.js";
+import type { SourcesStatusData } from "./types.js";
+
+/** A project reading from its own built pack, with two configured sources. */
+const BUILT: SourcesStatusData = {
+  cwd: "/repo",
+  store: "built",
+  contentHash: "abcdef012345aaaa",
+  sourceRef: "ds,extra",
+  builtAt: "2026-01-01",
+  entityCount: 42,
+  sources: [
+    { name: "ds", ref: "git+https://example.test/ds.git#main" },
+    { name: "extra", ref: "extra@1" },
+  ],
+};
+
+/** A sentinel styler — enabled, each color wrapped in a visible tag. */
+const TAGGED: RenderStyle = {
+  enabled: true,
+  bold: (t) => `<b>${t}</b>`,
+  dim: (t) => `<d>${t}</d>`,
+  cyan: (t) => `<c>${t}</c>`,
+  green: (t) => `<g>${t}</g>`,
+  yellow: (t) => `<y>${t}</y>`,
+};
+
+describe("renderSourcesStatusPlain", () => {
+  it("is byte-identical to the plain form when the styler is disabled", () => {
+    expect(renderSourcesStatusPlain(BUILT, styleFor(false))).toBe(
+      [
+        "Store: ready",
+        "  pack: abcdef012345 — 42 entities, built 2026-01-01",
+        "  from: ds,extra",
+        "",
+        "Sources:",
+        "  ds  git+https://example.test/ds.git#main",
+        "  extra  extra@1",
+      ].join("\n"),
+    );
+  });
+
+  it("bolds the heading, aligns names, and dims refs on a TTY", () => {
+    const out = renderSourcesStatusPlain(BUILT, TAGGED);
+    const nameWidth = "extra".length;
+    expect(out).toContain("<b>Sources:</b>");
+    expect(out).toContain(
+      `  ${"ds".padEnd(nameWidth)}  <d>git+https://example.test/ds.git#main</d>`,
+    );
+    expect(out).toContain(`  ${"extra".padEnd(nameWidth)}  <d>extra@1</d>`);
+  });
+
+  it("names the embedded snapshot AND the update that would replace it", () => {
+    // The embedded pack answers reads on a fresh install, but it IS a snapshot —
+    // rendering it as "ready" would read as "up to date", which it is not.
+    const out = renderSourcesStatusPlain(
+      {
+        ...BUILT,
+        store: "embedded",
+        sourceRef: "@canonical/design-system@git:abc",
+      },
+      styleFor(false),
+    );
+    expect(out).toContain("Store: embedded snapshot");
+    expect(out).toContain("pragma sources update");
+    expect(out).toContain("  from: @canonical/design-system@git:abc");
+  });
+
+  it("reports an unbuilt store with its recovery and no pack line", () => {
+    const out = renderSourcesStatusPlain(
+      {
+        ...BUILT,
+        store: "unavailable",
+        contentHash: null,
+        sourceRef: null,
+        builtAt: null,
+        entityCount: null,
+      },
+      styleFor(false),
+    );
+    expect(out).toContain("Store: not built (run `pragma sources update`)");
+    expect(out).not.toContain("  pack: ");
+  });
+
+  it("says so when no packs are configured", () => {
+    const out = renderSourcesStatusPlain(
+      { ...BUILT, sources: [] },
+      styleFor(false),
+    );
+    expect(out).toContain("  (none configured)");
+  });
+});