@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/kernel/runtime/graphpack/stories.ts

@@ -0,0 +1,84 @@
+/**
+ * Read the read stories the ANSWERING pack carries.
+ *
+ * It CONSUMES the one boot decision ({@link resolveSources}) rather than
+ * re-deriving it, so the nouns a project's reads answer with can never differ
+ * from the nouns its pack carries: a project pointed at its own pack gets that
+ * pack's stories, a fresh install gets the embedded snapshot's, and a
+ * configured-but-unbuilt project gets none (its reads refuse too).
+ *
+ * Total: any unreadable or unparseable `stories.json` yields `[]`. The records
+ * are RAW TEXT — validating them is `kernel/packs/collect.validateStories`'s
+ * job, behind one guard, because a third-party story must never break a command.
+ *
+ * The embedded snapshot's records come from their OWN generated module, so
+ * reading them costs a small string and never loads `pack.generated.ts`'s
+ * ~1.9 MB of n-quads (a measured +28 ms on every invocation).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SourcesDecision } from "../resolveSources.js";
+import { storiesJson } from "./embedded/pack.stories.generated.js";
+import { STORIES_FILE } from "./types.js";
+
+/** One package-declared story as the pack carries it: the file it came from, verbatim. */
+export interface PackStoryRecord {
+  /** Where the story was declared, e.g. `@canonical/design-system/stories/block.json`. */
+  readonly source: string;
+  /** The file's raw text — unparsed, uninterpreted. */
+  readonly content: string;
+}
+
+/** A record shaped as this module promises — the file is a user-writable cache. */
+function isRecord(value: unknown): value is PackStoryRecord {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as PackStoryRecord).source === "string" &&
+    typeof (value as PackStoryRecord).content === "string"
+  );
+}
+
+/**
+ * Parse a `stories.json` body; anything malformed degrades to no stories.
+ *
+ * The elements are checked, not just the container: a record that is not
+ * `{ source, content }` would otherwise reach `validateStories` and be reported
+ * as `Ignored story undefined: …` — a diagnostic that names no file.
+ */
+function parseRecords(json: string): readonly PackStoryRecord[] {
+  try {
+    const parsed: unknown = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The read stories the answering pack carries.
+ *
+ * @param decision - The boot decision from `resolveSources`.
+ * @returns The carried story records — `[]` when the pack carries none, no pack
+ *   answers, or the file is unreadable.
+ * @note Impure — reads `stories.json` from the answering pack directory.
+ */
+export function activeStories(
+  decision: SourcesDecision,
+): readonly PackStoryRecord[] {
+  switch (decision.kind) {
+    case "pack":
+      try {
+        return parseRecords(
+          readFileSync(join(decision.dir, STORIES_FILE), "utf-8"),
+        );
+      } catch {
+        return [];
+      }
+    case "embedded":
+      return parseRecords(storiesJson);
+    case "unavailable":
+      return [];
+  }
+}

package/src/kernel/runtime/graphpack/types.ts

@@ -1,28 +1,56 @@
 /**
- * Graphpack artifact contracts — the four files a built pack directory holds
- * and the zod schemas that keep them honest on read.
+ * Graphpack artifact contracts — the five files a built pack directory holds,
+ * as hand-written types with NO runtime dependency.
  *
  * A pack is the content-addressed, boot-ready form of a set of RDF sources:
  * `data.nq` (the store's n-quads dump — boots via ke's cache path, no TTL
  * parse), `schema.json` (the serialized ke-graphql extraction — boots via
  * `compileFromExtraction`, no live 7-pass compile), `index.json` (the storeless
- * entity index the completion tier and reads consume), and `manifest.json`
+ * entity index the completion tier and reads consume), `stories.json` (the read
+ * stories the packages ship, carried verbatim as raw text), and `manifest.json`
  * (provenance + the prefixes the store was built with). A directory missing
  * `manifest.json` is treated as absent (a torn build), so writes are always
  * temp-dir + atomic rename.
  *
- * This module is reached only behind a dynamic import (pack build / read /
- * store boot), so its zod dependency never lands on the storeless fast path.
+ * FIVE AND ONLY FIVE: the constants below are the single place the artifact set
+ * is named, and three modules must agree with them — `buildPack` writes them,
+ * `packIsComplete` gates on them, and `materializeEmbeddedPack` writes them back
+ * out. A sixth artifact added to only some of those makes a pack whose content
+ * hash claims more than its directory holds, which the next build then reuses,
+ * silently dropping the difference. The agreement is pinned by `graphpack.test.ts`'s
+ * "the committed embedded pack (PROTECTED) > materializes exactly the files
+ * buildPack produces" — extend the set here and that test fails until every
+ * side follows.
+ *
+ * This module is on the STORELESS FAST PATH — `capabilities/index.ts` →
+ * `resolveSources` → `packIsComplete` → `readManifest` reaches it while
+ * `__complete` builds the command tree — so it carries NO runtime import at
+ * all. It used to hold the zod schemas too, which put zod on that graph through
+ * a genuine value import and cost ~3–4 ms of a ~30 ms budget; they now live in
+ * `schemas.ts`, imported only by the two readers that are already off the fast
+ * path. `capabilities/lazy.test.ts` pins the result — no module on that graph
+ * imports zod — so the split cannot silently close.
  */
 
-import { z } from "zod";
-
 /** The n-quads store dump — ke boots it via `createStore({ cache })`. */
 export const DATA_FILE = "data.nq";
 /** The serialized ke-graphql extraction — boots via `compileFromExtraction`. */
 export const SCHEMA_FILE = "schema.json";
 /** The storeless entity index (PR-C's dynamic-completion contract). */
 export const INDEX_FILE = "index.json";
+/**
+ * The read stories the packages shipped, as raw text: one
+ * `{ source, content }` record per `stories/*.json` file, in a JSON array.
+ *
+ * Written ALWAYS, even as `[]`, and gated by `packIsComplete` alongside the
+ * other three — an optional artifact would put the same condition in all three
+ * modules below, which is exactly how a pack ends up claiming stories its
+ * directory does not hold. Raw text rather than parsed definitions so the pack stays a
+ * faithful carrier of the package's bytes and EVERY interpretation failure
+ * (malformed JSON and schema-invalid JSON alike) is caught behind the one guard
+ * in `kernel/packs/collect.validateStories`.
+ */
+export const STORIES_FILE = "stories.json";
 /** Provenance + prefixes; its presence marks a pack directory as complete. */
 export const MANIFEST_FILE = "manifest.json";
 
@@ -45,9 +73,10 @@ export interface PackIndexEntity {
   /** Human label (rdfs:label / skos:prefLabel / dcterms:title / schema:name). */
   readonly label?: string | null;
   /**
-   * Alternative completable names — the `ds:name` values a family (e.g.
-   * `ds:Tier`, matched by `tier lookup`) is addressed by, when they differ from
-   * `name`/`label`. Enrichment for the storeless name-completion sources.
+   * Alternative completable names — the values of the distribution's declared
+   * alternative-name property (`kernel/vocabulary.ts`), which is what a
+   * bespoke lookup matches on, when they differ from `name`/`label`.
+   * Enrichment for the storeless name-completion sources.
    */
   readonly altNames?: readonly string[];
   /** Schema (`tbox`) vs individual (`abox`). */
@@ -74,37 +103,24 @@ export interface PackIndex {
   readonly instanceCountByType: Readonly<Record<string, number>>;
 }
 
-/** zod schema validating a persisted {@link PackIndexEntity}. */
-export const packIndexEntitySchema: z.ZodType<PackIndexEntity> = z.object({
-  name: z.string(),
-  type: z.string(),
-  uri: z.string().optional(),
-  prefixed: z.string().optional(),
-  types: z.array(z.string()).optional(),
-  label: z.string().nullable().optional(),
-  altNames: z.array(z.string()).optional(),
-  box: z.enum(["tbox", "abox"]).optional(),
-  description: z.string().nullable().optional(),
-});
-
-/** zod schema validating a persisted {@link PackIndex}. */
-export const packIndexSchema: z.ZodType<PackIndex> = z.object({
-  version: z.union([z.literal(1), z.literal(2)]),
-  contentHash: z.string(),
-  prefixes: z.record(z.string(), z.string()),
-  entities: z.array(packIndexEntitySchema),
-  instanceCountByType: z.record(z.string(), z.number()),
-});
-
-/** zod schema validating a persisted `manifest.json`. */
-export const manifestSchema = z.object({
-  name: z.string(),
-  version: z.string(),
-  /** The config `packages` ref this pack was built from (verbatim), or a label. */
-  sourceRef: z.string(),
-  contentHash: z.string(),
-  prefixes: z.record(z.string(), z.string()),
-  createdAt: z.string(),
+/**
+ * Pack provenance and the prefixes the store was built with — the parsed shape
+ * of `manifest.json`.
+ *
+ * Hand-written rather than inferred from a zod schema, so reading a manifest
+ * needs no validator library (see the module docblock). `schemas.ts`'s
+ * {@link manifestSchema} is annotated against this type, so the two cannot
+ * drift in their FIELDS; `graphpack.test.ts` pins that they do not drift in
+ * what they ACCEPT either.
+ */
+export interface Manifest {
+  readonly name: string;
+  readonly version: string;
+  /** The config `packs` ref this pack was built from (verbatim), or a label. */
+  readonly sourceRef: string;
+  readonly contentHash: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+  readonly createdAt: string;
   /**
    * The store's triple count at build time. Cross-checked against the booted
    * store so a truncated-but-non-empty `data.nq` (a partial graph that passes
@@ -112,14 +128,11 @@ export const manifestSchema = z.object({
    * than being served silently (A9). Optional — packs built before this field
    * skip the check.
    */
-  tripleCount: z.number().optional(),
+  readonly tripleCount?: number;
   /**
-   * The distinct abox entity count (matches {@link entityTotal}). Lets
+   * The distinct abox entity count (matches `entityTotal`). Lets
    * `sources status` report the figure without parsing the whole `index.json`
    * (A10). Optional — packs built before this field fall back to the index read.
    */
-  entityCount: z.number().optional(),
-});
-
-/** Pack provenance and the prefixes the store was built with. */
-export type Manifest = z.infer<typeof manifestSchema>;
+  readonly entityCount?: number;
+}

package/src/kernel/runtime/paths.ts

@@ -1,27 +1,44 @@
 /**
  * Filesystem locations for the store layer: the content-addressed pack cache,
- * the git-ref checkout cache, and the project lock file.
+ * the git-ref checkout cache, and the per-project active-pack pointer.
  *
- * The pack cache lives under `$XDG_CACHE_HOME/pragma/packs/<contentHash>/`
+ * The pack cache lives under `$XDG_CACHE_HOME/<bin>/packs/<contentHash>/`
  * (content-addressed, so a new source set is a new directory and invalidation
- * is free); ref checkouts under `.../pragma/refs/`. The lock is a committed
- * project artifact at `<cwd>/pragma.lock.json`. All cache paths derive from the
- * config kernel's {@link cacheDir}, so the XDG isolation the tests install
- * contains them.
+ * is free); ref checkouts under `.../<bin>/refs/`. Which pack answers a
+ * project's reads is recorded by a one-line POINTER under
+ * `.../<bin>/projects/` — the content hash `sources update` last built there,
+ * and nothing else. It lives in the cache rather than the repo because the pack
+ * it names is machine-local: a committed pointer would promise a store the next
+ * machine does not have.
+ *
+ * A LEAF module on purpose: it imports node builtins and the distribution's
+ * {@link BIN_NAME}, and owns the cache root's XDG resolution outright
+ * (`kernel/config/paths.ts` keeps config and state). The storeless `__complete`
+ * fast path (`kernel/completion/entitySource.ts`) has to read the pointer, and
+ * `completion/safety.test.ts` forbids the config LAYER anywhere on that import
+ * graph — so the cache root is resolved here rather than imported. `constants.ts`
+ * is not the config layer: it reads inert data, and that same guard positive-lists
+ * it.
  */
 
-import { join } from "node:path";
-import { cacheDir } from "../config/paths.js";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
-/** The lock file basename, committed at the project root. */
-export const LOCK_BASENAME = "pragma.lock.json";
+/** `$XDG_CACHE_HOME/<bin>` (default `~/.cache/<bin>`) — the cache root. */
+function cacheDir(): string {
+  const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  return join(base, BIN_NAME);
+}
 
-/** `$XDG_CACHE_HOME/pragma/packs` — the content-addressed pack cache root. */
+/** `$XDG_CACHE_HOME/<bin>/packs` — the content-addressed pack cache root. */
 export function packsCacheDir(): string {
   return join(cacheDir(), "packs");
 }
 
-/** `$XDG_CACHE_HOME/pragma/refs` — cached git-ref checkouts. */
+/** `$XDG_CACHE_HOME/<bin>/refs` — cached git-ref checkouts. */
 export function refsCacheDir(): string {
   return join(cacheDir(), "refs");
 }
@@ -31,7 +48,39 @@ export function packDir(contentHash: string): string {
   return join(packsCacheDir(), contentHash);
 }
 
-/** The project lock file for a working directory. */
-export function lockPath(cwd: string): string {
-  return join(cwd, LOCK_BASENAME);
+/**
+ * The active-pack pointer for a project: `$XDG_CACHE_HOME/<bin>/projects/<key>`.
+ *
+ * The key is the SHA-256 of the resolved `cwd` — a hash rather than the path
+ * itself so a deep project directory can never exceed the 255-byte filename
+ * limit, and a cryptographic one so two projects can never collide onto each
+ * other's graph.
+ */
+export function activePackPath(cwd: string): string {
+  return join(
+    cacheDir(),
+    "projects",
+    createHash("sha256").update(resolve(cwd)).digest("hex"),
+  );
+}
+
+/**
+ * The content hash of the pack `sources update` built for a project.
+ *
+ * @param cwd - The project directory.
+ * @returns The 64-hex content hash, or `undefined` when the project was never
+ *   built. A pointer that is unreadable, or that does not hold exactly one
+ *   hash, is treated as absent — a corrupt pointer must never name an arbitrary
+ *   cache directory.
+ * @note Impure — reads the pointer from the cache.
+ */
+export function readActivePack(cwd: string): string | undefined {
+  const path = activePackPath(cwd);
+  if (!existsSync(path)) return undefined;
+  try {
+    const hash = readFileSync(path, "utf-8").trim();
+    return /^[0-9a-f]{64}$/.test(hash) ? hash : undefined;
+  } catch {
+    return undefined;
+  }
 }

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

@@ -1,16 +1,20 @@
 import { describe, expect, it } from "vitest";
+import { embeddedManifest } from "./graphpack/embedded.js";
 import { runStoreProbe } from "./probe.js";
 
 describe("store probe (in-process)", () => {
-  it("boots the embedded pack and reports entity + triple counts", async () => {
+  it("boots the embedded pack and finds the triples its manifest claims", async () => {
     const out = JSON.parse(await runStoreProbe()) as {
       ok: boolean;
       entities: number;
       triples: string;
     };
     expect(out.ok).toBe(true);
-    // The embedded sample pack ships six indexed entities (3 abox + 3 tbox).
-    expect(out.entities).toBe(6);
-    expect(Number(out.triples)).toBeGreaterThan(0);
+    // Against the COMMITTED manifest, not a recomputation: a store booted from
+    // `data.nq` must really hold what `manifest.json` says was built into it.
+    // That catches a regenerated dump that disagrees with its own provenance,
+    // and needs no literal that churns whenever upstream moves.
+    expect(Number(out.triples)).toBe(embeddedManifest().tripleCount);
+    expect(out.entities).toBeGreaterThan(0);
   });
 });

package/src/kernel/runtime/readEntity.ts

@@ -16,6 +16,7 @@
  */
 
 import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
 import { resolveUri } from "../packs/iri.js";
 import type { PragmaRuntime } from "./types.js";
 
@@ -57,11 +58,11 @@ export async function readEntity(
 
   if (result.type !== "select" || result.bindings.length === 0) {
     throw PragmaError.notFound("entity", uri, {
-      recovery: {
-        message: "Check the URI, or list known entities.",
-        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
-        mcp: { tool: "graph_query" },
-      },
+      recovery: cliRecovery(
+        `graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'`,
+        "Check the URI, or list known entities.",
+        { tool: "graph_query" },
+      ),
     });
   }
 

package/src/kernel/runtime/refs/gitOps.ts

@@ -9,7 +9,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 /** Whether a ref looks like a commit SHA (7-40 hex chars). */
@@ -64,24 +64,6 @@ export function fetchRef(url: string, ref: string, dest: string): string {
   return gitOutput(dest, ["rev-parse", "HEAD"]);
 }
 
-/** Check out an exact commit in an existing clone (fetching it if needed). */
-export function checkoutCommit(
-  url: string,
-  commit: string,
-  dest: string,
-): void {
-  if (!existsSync(dest)) {
-    cloneRef(url, commit, dest);
-    return;
-  }
-  try {
-    git(dest, ["checkout", commit]);
-  } catch {
-    git(dest, ["fetch", "--depth", "1", url, commit]);
-    git(dest, ["checkout", commit]);
-  }
-}
-
 /** The resolved HEAD commit of a checkout. */
 export function headCommit(dest: string): string {
   return gitOutput(dest, ["rev-parse", "HEAD"]);

package/src/kernel/runtime/refs/parseRef.ts

@@ -1,14 +1,14 @@
 /**
- * Parse a config `packages` entry into a typed {@link PackageRef}.
+ * Parse a config `packs` declaration into a typed {@link PackageRef}.
  *
  * Ported from the v1 refs domain. Three resolution strategies, discriminated by
  * `kind`: `npm` (a bare package name, resolved via `require.resolve`), `file`
  * (a `file://` local path override), and `git` (a `git+<proto>://…#ref` shallow
- * clone). The `source` string is kept verbatim so the lock records exactly what
- * the config declared.
+ * clone). The `source` string is kept verbatim so `sources status` reports
+ * exactly what the config declared.
  */
 
-import type { PackageEntry } from "../../config/types.js";
+import type { PackDeclaration } from "../../config/types.js";
 import { PragmaError } from "../../error/PragmaError.js";
 
 /** A parsed, validated package reference — discriminated by `kind`. */
@@ -29,13 +29,13 @@ export type PackageRef =
     };
 
 /**
- * Parse a config `packages` entry into a {@link PackageRef}.
+ * Parse a config `packs` declaration into a {@link PackageRef}.
  *
  * @param entry - A bare npm name, or a `{ name, source }` declaration.
  * @returns The parsed reference (with the verbatim `source`).
  * @throws PragmaError CONFIG_ERROR on an invalid `source`.
  */
-export function parsePackageEntry(entry: PackageEntry): PackageRef {
+export function parsePackDeclaration(entry: PackDeclaration): PackageRef {
   if (typeof entry === "string") {
     return { kind: "npm", pkg: entry, source: entry };
   }
@@ -43,7 +43,7 @@ export function parsePackageEntry(entry: PackageEntry): PackageRef {
   const { name, source } = entry;
   if (typeof name !== "string" || name.length === 0) {
     throw PragmaError.configError(
-      'Package entry must have a non-empty "name".',
+      'Pack declaration must have a non-empty "name".',
     );
   }
   if (source === undefined) {