@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -3,26 +3,17 @@ import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
 import { renderSourcesStatusPlain } from "./status.render.js";
 import type { SourcesStatusData } from "./types.js";
 
-const DATA: SourcesStatusData = {
+/** A project reading from its own built pack, with two configured sources. */
+const BUILT: SourcesStatusData = {
   cwd: "/repo",
-  lockPresent: true,
+  store: "built",
   contentHash: "abcdef012345aaaa",
-  cached: true,
+  sourceRef: "ds,extra",
   builtAt: "2026-01-01",
   entityCount: 42,
   sources: [
-    {
-      name: "ds",
-      ref: "ds@1",
-      resolved: "1111111111112222",
-      staleness: "up-to-date",
-    },
-    {
-      name: "extra",
-      ref: "extra@1",
-      resolved: null,
-      staleness: "config-drift",
-    },
+    { name: "ds", ref: "git+https://example.test/ds.git#main" },
+    { name: "extra", ref: "extra@1" },
   ],
 };
 
@@ -38,28 +29,66 @@ const TAGGED: RenderStyle = {
 
 describe("renderSourcesStatusPlain", () => {
   it("is byte-identical to the plain form when the styler is disabled", () => {
-    expect(renderSourcesStatusPlain(DATA, styleFor(false))).toBe(
+    expect(renderSourcesStatusPlain(BUILT, styleFor(false))).toBe(
       [
         "Store: ready",
         "  pack: abcdef012345 — 42 entities, built 2026-01-01",
+        "  from: ds,extra",
         "",
         "Sources:",
-        "  ds [ok] @ 111111111111",
-        "  extra [config drift]",
+        "  ds  git+https://example.test/ds.git#main",
+        "  extra  extra@1",
       ].join("\n"),
     );
   });
 
-  it("bolds the heading, aligns names, and tints markers on a TTY", () => {
-    const out = renderSourcesStatusPlain(DATA, TAGGED);
+  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>");
-    // up-to-date tints green with a dim resolved suffix; drift tints yellow.
     expect(out).toContain(
-      `  ${"ds".padEnd(nameWidth)}  <g>[ok]</g><d> @ 111111111111</d>`,
+      `  ${"ds".padEnd(nameWidth)}  <d>git+https://example.test/ds.git#main</d>`,
     );
-    expect(out).toContain(
-      `  ${"extra".padEnd(nameWidth)}  <y>[config drift]</y>`,
+    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)");
   });
 });

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

@@ -2,14 +2,20 @@
  * Formatters for `pragma sources status` — plain, llm, json.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { SourcesStatusData } from "./types.js";
 
-const STALENESS_MARK: Record<string, string> = {
-  "up-to-date": "ok",
-  "config-drift": "config drift",
-  uncached: "not built",
+/**
+ * The headline for each boot decision. The `embedded` case names the update
+ * explicitly: the distribution's snapshot answers reads, but it is a snapshot,
+ * so reporting it as "up to date" would be a lie.
+ */
+const STORE_HEADLINE: Record<SourcesStatusData["store"], string> = {
+  built: "ready",
+  embedded: `embedded snapshot (run \`${BIN_NAME} sources update\` to build from the configured packs)`,
+  unavailable: `not built (run \`${BIN_NAME} sources update\`)`,
 };
 
 /**
@@ -18,22 +24,19 @@ const STALENESS_MARK: Record<string, string> = {
  * @param data - The resolved sources-status payload.
  * @param style - TTY styling; defaults to the process style. On a color-capable
  *   terminal the `Sources:` heading is bold, source names align into a column,
- *   and each staleness marker is tinted (green up-to-date, else yellow); off a
- *   TTY the styler is inert, so the output is byte-identical to the plain form.
+ *   and each configured ref is dimmed; off a TTY the styler is inert, so the
+ *   output is byte-identical to the plain form.
  * @returns The formatted status block.
  */
 export function renderSourcesStatusPlain(
   data: SourcesStatusData,
   style: RenderStyle = defaultStyle(),
 ): string {
-  const lines = [
-    data.lockPresent
-      ? `Store: ${data.cached ? "ready" : "locked but not cached"}`
-      : "Store: no lock (run `pragma sources update`)",
-  ];
-  if (data.cached) {
+  const lines = [`Store: ${STORE_HEADLINE[data.store]}`];
+  if (data.contentHash !== null) {
     lines.push(
-      `  pack: ${data.contentHash?.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
+      `  pack: ${data.contentHash.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
+      `  from: ${data.sourceRef ?? "?"}`,
     );
   }
   lines.push("", style.enabled ? style.bold("Sources:") : "Sources:");
@@ -44,17 +47,10 @@ export function renderSourcesStatusPlain(
     ? Math.max(0, ...data.sources.map((source) => source.name.length))
     : 0;
   for (const source of data.sources) {
-    const mark = STALENESS_MARK[source.staleness] ?? source.staleness;
-    const resolved = source.resolved
-      ? ` @ ${source.resolved.slice(0, 12)}`
-      : "";
-    if (!style.enabled) {
-      lines.push(`  ${source.name} [${mark}]${resolved}`);
-      continue;
-    }
-    const tint = source.staleness === "up-to-date" ? style.green : style.yellow;
     lines.push(
-      `  ${source.name.padEnd(nameWidth)}  ${tint(`[${mark}]`)}${style.dim(resolved)}`,
+      style.enabled
+        ? `  ${source.name.padEnd(nameWidth)}  ${style.dim(source.ref)}`
+        : `  ${source.name}  ${source.ref}`,
     );
   }
   return lines.join("\n");
@@ -66,13 +62,12 @@ export const statusFormatters: Formatters<SourcesStatusData> = {
   },
 
   llm(data) {
-    const lines = [
-      `# sources`,
-      `- Store: ${data.lockPresent ? (data.cached ? "ready" : "locked, not cached") : "no lock"}`,
-      ...(data.cached ? [`- Entities: ${data.entityCount ?? "?"}`] : []),
-    ];
+    const lines = [`# sources`, `- Store: ${data.store}`];
+    if (data.sourceRef !== null) lines.push(`- From: ${data.sourceRef}`);
+    if (data.entityCount !== null)
+      lines.push(`- Entities: ${data.entityCount}`);
     for (const source of data.sources) {
-      lines.push(`- ${source.name}: ${source.staleness}`);
+      lines.push(`- ${source.name}: ${source.ref}`);
     }
     return lines.join("\n");
   },

package/src/capabilities/sources/status.verb.ts

@@ -2,13 +2,14 @@
  * The `sources status` verb — a storeless read.
  *
  * `needsStore: false` is load-bearing: status must report even a cold or
- * unbuilt store (staleness `uncached`), so it must NOT boot the store — booting
- * a cold store would throw STORE_UNAVAILABLE before status could say so. Its
- * `run` is a lazy thunk (the collector is dynamic-imported), keeping the config
- * reader off the fast path, exactly like `info`.
+ * unbuilt store (`store: "unavailable"`), so it must NOT boot the store —
+ * booting a cold store would throw STORE_UNAVAILABLE before status could say
+ * so. Its `run` is a lazy thunk (the collector is dynamic-imported), keeping
+ * the config reader off the fast path, exactly like `info`.
  */
 
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import { BIN_NAME } from "../../constants.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { statusFormatters } from "./status.render.js";
 import type { SourcesStatusData } from "./types.js";
 
@@ -18,13 +19,19 @@ export const statusVerb: VerbSpec<
   SourcesStatusData
 > = {
   path: ["sources", "status"],
-  summary: "Report the local store's readiness and per-source staleness.",
-  doc: "Storeless — reads the lock, config, and pack cache without booting the store, so it works even when the store is cold.",
+  summary: "Report which pack answers reads, and the packs it was built from.",
+  doc: "Storeless — reads config and the pack cache without booting the store, so it works even when the store is cold. Reports whether reads are answered by a locally built pack, by the embedded snapshot, or not at all.",
   params: [],
   output: { formatters: statusFormatters },
   examples: [
-    { cmd: "pragma sources status", note: "human-readable readiness summary" },
-    { cmd: "pragma sources status --format json", note: "the full envelope" },
+    {
+      cmd: `${BIN_NAME} sources status`,
+      note: "human-readable readiness summary",
+    },
+    {
+      cmd: `${BIN_NAME} sources status --format json`,
+      note: "the full envelope",
+    },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/sources/types.ts

@@ -1,37 +1,29 @@
 /**
  * Data shapes for the `sources` noun — `status` (storeless read) and `update`
- * (the Task that resolves, builds, and locks the store).
+ * (the Task that resolves, builds, and points the project at a pack).
  */
 
-/** How a configured source stands relative to the lock and the pack cache. */
-export type SourceStaleness = "up-to-date" | "config-drift" | "uncached";
-
-/** One configured source's status. */
-export interface SourceStatusEntry {
-  /** Package name. */
-  readonly name: string;
-  /** The config `packages` source ref (verbatim). */
-  readonly ref: string;
-  /** The lock's resolved revision, or null when not locked. */
-  readonly resolved: string | null;
-  /** Whether the config ref matches the lock and the pack is cached. */
-  readonly staleness: SourceStaleness;
-}
-
 /** The `sources status` payload — assembled without booting the store. */
 export interface SourcesStatusData {
   readonly cwd: string;
-  /** Whether a `pragma.lock.json` is present. */
-  readonly lockPresent: boolean;
-  /** The locked combined-pack content hash, or null. */
+  /**
+   * Which pack answers reads, straight from the boot decision: the project's
+   * own `built` pack, the distribution's `embedded` snapshot, or none at all.
+   */
+  readonly store: "embedded" | "built" | "unavailable";
+  /** The answering pack's content hash, or null when there is none. */
   readonly contentHash: string | null;
-  /** Whether the locked pack is present in the cache. */
-  readonly cached: boolean;
-  /** When the cached pack was built (manifest `createdAt`), or null. */
+  /** The answering pack's provenance label (manifest `sourceRef`), or null. */
+  readonly sourceRef: string | null;
+  /** When the answering pack was built (manifest `createdAt`), or null. */
   readonly builtAt: string | null;
-  /** Total indexed entity count from the cached pack, or null. */
+  /** Total indexed entity count from the answering pack, or null. */
   readonly entityCount: number | null;
-  readonly sources: readonly SourceStatusEntry[];
+  /** The configured pack declarations, as written in the config. */
+  readonly sources: readonly {
+    readonly name: string;
+    readonly ref: string;
+  }[];
 }
 
 /** One resolved source in the `sources update` result. */
@@ -39,6 +31,8 @@ export interface UpdatedSource {
   readonly name: string;
   readonly resolved: string;
   readonly sourceCount: number;
+  /** How many `stories/*.json` files this package contributed to the pack. */
+  readonly storyCount: number;
 }
 
 /** The `sources update` result payload. */
@@ -46,6 +40,5 @@ export interface SourcesUpdateData {
   readonly contentHash: string;
   /** Whether the pack was reused from cache rather than rebuilt. */
   readonly reused: boolean;
-  readonly lockPath: string;
   readonly packs: readonly UpdatedSource[];
 }

package/src/capabilities/sources/update.render.ts

@@ -2,7 +2,7 @@
  * Formatters for `pragma sources update` — plain, llm, json.
  */
 
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { SourcesUpdateData } from "./types.js";
 
 export const updateFormatters: Formatters<SourcesUpdateData> = {
@@ -11,11 +11,18 @@ export const updateFormatters: Formatters<SourcesUpdateData> = {
       data.reused
         ? `Store up to date (pack ${data.contentHash.slice(0, 12)}).`
         : `Built pack ${data.contentHash.slice(0, 12)}.`,
-      `Wrote ${data.lockPath}.`,
     ];
     for (const pack of data.packs) {
+      // FILES, not usable stories: `sources update` carries them verbatim and
+      // never validates them (zod would have to run per record, in the build).
+      // `doctor` is where "2 stories ignored" comes from — saying "stories"
+      // here would put a green count next to a broken file.
+      const stories =
+        pack.storyCount > 0
+          ? `, ${pack.storyCount} story file${pack.storyCount === 1 ? "" : "s"}`
+          : "";
       lines.push(
-        `  ${pack.name} @ ${pack.resolved.slice(0, 12)} (${pack.sourceCount} source${pack.sourceCount === 1 ? "" : "s"})`,
+        `  ${pack.name} @ ${pack.resolved.slice(0, 12)} (${pack.sourceCount} source${pack.sourceCount === 1 ? "" : "s"}${stories})`,
       );
     }
     return lines.join("\n");

package/src/capabilities/sources/update.verb.ts

@@ -1,35 +1,32 @@
 /**
- * The `sources update` verb — resolve, build, and lock the store.
+ * The `sources update` verb — resolve the configured packs, build the store,
+ * and point the project at it.
  *
  * A mutation (`mutates: true`) that needs the network (`needsNetwork: true`)
  * but NOT the pre-booted store (`needsStore: false`): update is what *creates*
  * the store, so the dispatcher must not try to boot it first (a cold boot would
  * throw STORE_UNAVAILABLE). `run` returns a `Promise<Task<R>>` — the union's
  * third arm — which the dispatcher awaits: for a real execution it resolves and
- * builds before handing back the lock-writing Task; for a preview
+ * builds before handing back the pointer-writing Task; for a preview
  * (`runtime.mutation.preview`) it stays network-free and hands back a
- * plan-only Task. `--frozen` re-resolves to the lock's pinned revisions.
+ * plan-only Task.
  */
 
 import type { Task } from "@canonical/task";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import { BIN_NAME } from "../../constants.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import type { SourcesUpdateData } from "./types.js";
 import { updateFormatters } from "./update.render.js";
 
 /** The `sources update` verb spec. */
 export const updateVerb: VerbSpec<
-  { frozen?: boolean; skipInvalid?: boolean },
+  { skipInvalid?: boolean },
   SourcesUpdateData
 > = {
   path: ["sources", "update"],
-  summary: "Resolve configured packages, build the local store, and lock it.",
-  doc: "Resolves each configured package (git/file/npm), builds one content-addressed pack, and writes pragma.lock.json. Networkless boots then load from the lock.",
+  summary: "Resolve configured packs and build the local store from them.",
+  doc: "Resolves each configured pack (git/file/npm) and builds one content-addressed pack, which every later boot reads with no network access. Pin a revision by putting a commit SHA in the pack's source ref.",
   params: [
-    {
-      kind: "boolean",
-      name: "frozen",
-      doc: "Re-resolve to the lock's pinned revisions exactly; never advance.",
-    },
     {
       kind: "boolean",
       name: "skipInvalid",
@@ -38,13 +35,9 @@ export const updateVerb: VerbSpec<
   ],
   output: { formatters: updateFormatters },
   examples: [
-    { cmd: "pragma sources update", note: "resolve, build, and lock" },
-    {
-      cmd: "pragma sources update --frozen",
-      note: "reproduce the locked state",
-    },
+    { cmd: `${BIN_NAME} sources update`, note: "resolve and build" },
     {
-      cmd: "pragma sources update --skip-invalid",
+      cmd: `${BIN_NAME} sources update --skip-invalid`,
       note: "build from the parseable sources, warning about any dropped",
     },
   ],
@@ -59,7 +52,7 @@ export const updateVerb: VerbSpec<
   },
   // `run` really returns `Promise<Task<R>>`: `buildUpdateTask` awaits config
   // (and, on a real execution, resolves + builds) before handing back the
-  // lock-writing Task — or, when `runtime.mutation.preview` is set, a
+  // pointer-writing Task — or, when `runtime.mutation.preview` is set, a
   // network-free plan Task. The dispatcher and MCP handler both `await` this
   // promise into a `Task`. The `VerbSpec.run` union is deliberately two-armed
   // (`Promise<R> | Task<R>`) — a third `Promise<Task<R>>` arm would poison async
@@ -67,10 +60,6 @@ export const updateVerb: VerbSpec<
   // `Task<R>` arm by this single, honest cast.
   run: (params, runtime) =>
     import("./runUpdate.js").then((module) =>
-      module.buildUpdateTask(
-        runtime,
-        params.frozen === true,
-        params.skipInvalid === true,
-      ),
+      module.buildUpdateTask(runtime, params.skipInvalid === true),
     ) as unknown as Task<SourcesUpdateData>,
 };