@canonical/pragma-cli 0.36.0 → 0.37.0

package/src/kernel/runtime/graphpack/embedded/pack.manifest.generated.ts

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by scripts/bundle.ts — do not edit by hand.
+// Regenerate from the packs pragma.conf.ts declares: `bun run bundle`.
+export const manifestJson = "{\"name\":\"pragma\",\"version\":\"0.36.0\",\"sourceRef\":\"@canonical/design-system@git:ce00818852628857da9c4a67bf8556c7cfda287d, @canonical/anatomy-dsl@npm:0.3.0, @canonical/token-ontology@npm:0.8.1, @canonical/code-standards@git:fcd3ac2dea458775e5b79344b3237a3fcb37add9, @canonical/ds-implementations@self:v0.36.0\",\"contentHash\":\"7ff2bbd5fd059584ad3285c7b1c7d59c734efef8006fb0bba726db03254392e8\",\"prefixes\":{\"rdf\":\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\",\"rdfs\":\"http://www.w3.org/2000/01/rdf-schema#\",\"owl\":\"http://www.w3.org/2002/07/owl#\",\"xsd\":\"http://www.w3.org/2001/XMLSchema#\",\"skos\":\"http://www.w3.org/2004/02/skos/core#\",\"sh\":\"http://www.w3.org/ns/shacl#\",\"dcterms\":\"http://purl.org/dc/terms/\",\"ds\":\"https://ds.canonical.com/\",\"anatomy\":\"http://anatomy-dsl.example.org/ontology#\",\"graphql\":\"https://pragma.canonical.com/graphql#\",\"w3c-tokens\":\"https://dt.canonical.com/w3c-tokens/\",\"dt\":\"https://dt.canonical.com/\",\"cs\":\"http://pragma.canonical.com/codestandards#\",\"dso\":\"https://ds.canonical.com/ontology#\"},\"createdAt\":\"2026-09-01T20:29:05.995Z\",\"tripleCount\":30346,\"entityCount\":2906}";

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

@@ -18,10 +18,12 @@
  *
  * The inlined strings are materialized into the ordinary content-addressed pack
  * cache on first use and then read back through {@link readPack}, so the
- * embedded pack and a built pack share one boot path. The story records live in
- * their OWN generated module (like the index): dispatch reads them on every
- * command, and pulling them out of `pack.generated.ts` would load its ~1.9 MB
- * of n-quads with them — a measured +28 ms on every invocation. Inlining as JS strings
+ * embedded pack and a built pack share one boot path. The story records, the
+ * index and the MANIFEST each live in their own generated module: every one of
+ * them is read on a path that does not need the n-quads, and leaving any of
+ * them beside `pack.generated.ts` would load its ~2.1 MB with them — a measured
+ * +28 ms on every invocation for the stories, and ~370 ms per CLI invocation
+ * for the manifest at a 30,340-triple pack. Inlining as JS strings
  * (rather than file assets) means the pack travels with the emitted modules —
  * it needs no asset step in any build, and no file lookup at run time.
  */
@@ -36,8 +38,8 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { packDir, packsCacheDir } from "../paths.js";
-import { dataNq, manifestJson, schemaJson } from "./embedded/pack.generated.js";
 import { indexJson } from "./embedded/pack.index.generated.js";
+import { manifestJson } from "./embedded/pack.manifest.generated.js";
 import { storiesJson } from "./embedded/pack.stories.generated.js";
 import { packIsComplete } from "./manifest.js";
 import { manifestSchema } from "./schemas.js";
@@ -72,10 +74,16 @@ export function embeddedManifest(): Manifest {
  * @returns The pack directory, ready for {@link readPack}.
  * @note Impure — writes the inlined pack files into the cache.
  */
-export function materializeEmbeddedPack(): string {
+export async function materializeEmbeddedPack(): Promise<string> {
   const dir = packDir(embeddedManifest().contentHash);
   if (packIsComplete(dir)) return dir;
 
+  // Loaded HERE, not at module scope: this is the only branch that needs the
+  // payload, and it is the branch that does NOT run once the pack is cached.
+  // A static import would parse ~2.1 MB of inlined n-quads on every boot to
+  // reach a return statement six lines above.
+  const { dataNq, schemaJson } = await import("./embedded/pack.generated.js");
+
   mkdirSync(packsCacheDir(), { recursive: true });
   const temp = mkdtempSync(join(packsCacheDir(), ".embed-"));
   try {

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

@@ -144,15 +144,21 @@ describe("the committed embedded pack (PROTECTED)", () => {
     // directory holds — which the next build then reuses, silently dropping the
     // difference. Comparing the two directories catches that on the day it lands.
     const built = await build([{ path: "a.ttl", content: TTL }]);
-    expect(readdirSync(materializeEmbeddedPack()).sort()).toEqual(
+    expect(readdirSync(await materializeEmbeddedPack()).sort()).toEqual(
       readdirSync(built.dir).sort(),
     );
-  });
-
-  it("is self-consistent: complete, content-addressed, and non-empty", () => {
+    // 60s, not the 5s default. This test does real work twice: it BUILDS a
+    // pack from source, and it materialises the embedded one — which on a cold
+    // cache takes the miss branch and imports the multi-megabyte payload. Both
+    // costs grow with the pack, and the pack grows whenever a source is added.
+    // A default that a pack size can outgrow turns a real assertion into an
+    // intermittent one.
+  }, 60_000);
+
+  it("is self-consistent: complete, content-addressed, and non-empty", async () => {
     // No network, so CI runs it: the committed strings really do materialize a
     // bootable pack whose parts agree with each other.
-    const dir = materializeEmbeddedPack();
+    const dir = await materializeEmbeddedPack();
     const manifest = embeddedManifest();
     expect(packIsComplete(dir)).toBe(true);
     expect(basename(dir)).toBe(manifest.contentHash);
@@ -162,6 +168,26 @@ describe("the committed embedded pack (PROTECTED)", () => {
     expect(index.contentHash).toBe(manifest.contentHash);
     expect(manifest.tripleCount ?? 0).toBeGreaterThan(0);
     expect(manifest.entityCount ?? 0).toBeGreaterThan(0);
+
+    // EXACT, not "> 0", and it earns its keep twice.
+    //
+    // The manifest and the n-quads now live in SEPARATE generated modules, so
+    // a partial regeneration or a one-file `git add` can leave them describing
+    // different packs — a skew that could not exist while they shared a
+    // module. `read.ts` tolerates a superset deliberately, so it would serve
+    // the skew rather than refuse it.
+    //
+    // It also pins the equivalence `read.ts` depends on but cannot state:
+    // `store.size` (quads) against a `tripleCount` that `build.ts` computes
+    // with `SELECT (COUNT(*))` over the union graph. They agree on oxigraph
+    // 0.5.6; oxigraph is pinned by caret, so this is where a future version
+    // that deduplicates the union would be caught.
+    const session = await readPack(dir);
+    try {
+      expect(session.store.size).toBe(manifest.tripleCount);
+    } finally {
+      session.store.dispose();
+    }
   });
 });
 

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

@@ -80,15 +80,25 @@ export async function readPack(dir: string): Promise<StoreSession> {
   // "populated index but empty store" check (via the now-empty dump,
   // `packIsComplete` turns false so recovery rebuilds) rather than serving an
   // empty graph as the pack.
-  const actualTriples = await countTriples(store);
+  // `store.size` is a field oxigraph maintains. The equivalent query —
+  // `SELECT (COUNT(*)) WHERE { ?s ?p ?o }`, which is what `build.ts` still runs
+  // to WRITE `tripleCount` — is a scan, and it ran on every boot to read a
+  // number the store already knew.
+  //
+  // The two agree: ke queries with `use_default_graph_as_union`, and oxigraph
+  // does not deduplicate across that union, so a quad count and the union's
+  // solution count are the same number even for a triple repeated across
+  // graphs. Verified against 0.5.6 rather than assumed — and the guard is `<`,
+  // which tolerates the direction a set-semantic union would drift.
+  const actualQuads = store.size;
   if (manifest.tripleCount !== undefined) {
-    if (actualTriples < manifest.tripleCount) {
+    if (actualQuads < manifest.tripleCount) {
       store.dispose();
       throw packUnavailable(
-        `The pack at ${dir} has a corrupt data cache (expected at least ${manifest.tripleCount} triples, loaded ${actualTriples}).`,
+        `The pack at ${dir} has a corrupt data cache (expected at least ${manifest.tripleCount} triples, loaded ${actualQuads}).`,
       );
     }
-  } else if (index.entities.length > 0 && actualTriples === 0) {
+  } else if (index.entities.length > 0 && actualQuads === 0) {
     store.dispose();
     throw packUnavailable(`The pack at ${dir} has a corrupt data cache.`);
   }
@@ -101,11 +111,3 @@ export async function readPack(dir: string): Promise<StoreSession> {
     index,
   };
 }
-
-/** Count the booted store's triples (a cheap aggregate over the union graph). */
-async function countTriples(store: StoreSession["store"]): Promise<number> {
-  const result = (await store.query(
-    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
-  )) as import("@canonical/ke").SelectResult;
-  return Number(result.bindings.at(0)?.n ?? 0);
-}

package/src/kernel/runtime/loadSession.ts

@@ -43,6 +43,8 @@ export async function loadStoreSession(
   }
 
   const dir =
-    decision.kind === "embedded" ? materializeEmbeddedPack() : decision.dir;
+    decision.kind === "embedded"
+      ? await materializeEmbeddedPack()
+      : decision.dir;
   return readPack(dir);
 }

package/src/kernel/runtime/probe.ts

@@ -21,7 +21,7 @@ export async function runStoreProbe(): Promise<string> {
     import("./graphpack/embedded.js"),
     import("./graphpack/read.js"),
   ]);
-  const session = await readPack(materializeEmbeddedPack());
+  const session = await readPack(await materializeEmbeddedPack());
   try {
     const result = await session.store.query(
       "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { redactUrl } from "./parseRef.js";
+import { parsePackDeclaration, redactUrl } from "./parseRef.js";
 
 describe("redactUrl", () => {
   it("strips user:password userinfo so an inlined token never reaches output", () => {
@@ -32,3 +32,51 @@ describe("redactUrl", () => {
     );
   });
 });
+
+describe("parsePackDeclaration — a git source may name a subdirectory", () => {
+  const url = "git+https://github.com/org/repo.git";
+
+  it("reaches a package nested in a monorepo", () => {
+    expect(
+      parsePackDeclaration({
+        name: "@org/thing",
+        source: `${url}#main:pkgs/thing`,
+      }),
+    ).toEqual({
+      kind: "git",
+      pkg: "@org/thing",
+      url: "https://github.com/org/repo.git",
+      ref: "main",
+      subdir: "pkgs/thing",
+      source: `${url}#main:pkgs/thing`,
+    });
+  });
+
+  it("leaves a plain ref untouched, with no subdir key", () => {
+    const ref = parsePackDeclaration({
+      name: "@org/thing",
+      source: `${url}#main`,
+    });
+    expect(ref).toEqual({
+      kind: "git",
+      pkg: "@org/thing",
+      url: "https://github.com/org/repo.git",
+      ref: "main",
+      source: `${url}#main`,
+    });
+    expect("subdir" in ref).toBe(false);
+  });
+
+  it("splits on the FIRST colon, so a nested path survives", () => {
+    // The ref cannot contain a colon; the subdirectory can contain slashes.
+    expect(
+      parsePackDeclaration({ name: "@org/t", source: `${url}#v1.2:a/b/c` }),
+    ).toMatchObject({ ref: "v1.2", subdir: "a/b/c" });
+  });
+
+  it("rejects an empty subdirectory rather than silently ignoring it", () => {
+    expect(() =>
+      parsePackDeclaration({ name: "@org/thing", source: `${url}#main:` }),
+    ).toThrow(/subdirectory after : is empty/);
+  });
+});

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

@@ -25,6 +25,8 @@ export type PackageRef =
       readonly pkg: string;
       readonly url: string;
       readonly ref: string;
+      /** Package root WITHIN the clone, for a package nested in a monorepo. */
+      readonly subdir?: string;
       readonly source: string;
     };
 
@@ -72,11 +74,33 @@ export function parsePackDeclaration(entry: PackDeclaration): PackageRef {
         },
       );
     }
+    // `#<ref>` or `#<ref>:<subdir>`. A git ref cannot contain a colon
+    // (git check-ref-format), so the split is unambiguous.
+    const fragment = source.slice(hashIdx + 1);
+    const colonIdx = fragment.indexOf(":");
+    if (colonIdx !== -1 && colonIdx === fragment.length - 1) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": the subdirectory after : is empty.`,
+        {
+          recovery: {
+            message:
+              "Example: git+https://github.com/org/repo.git#main:packages/thing",
+          },
+        },
+      );
+    }
+    const ref = colonIdx === -1 ? fragment : fragment.slice(0, colonIdx);
+    if (ref.length === 0) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": git URL must include a ref after #.`,
+      );
+    }
     return {
       kind: "git",
       pkg: name,
       url: source.slice("git+".length, hashIdx),
-      ref: source.slice(hashIdx + 1),
+      ref,
+      ...(colonIdx === -1 ? {} : { subdir: fragment.slice(colonIdx + 1) }),
       source,
     };
   }

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

@@ -383,13 +383,19 @@ export async function resolvePackage(
           },
         );
       }
+      // The clone lives at `dir`; the PACKAGE may be nested within it. A git
+      // source names a repository, so a package inside a monorepo is reached
+      // by its subdirectory — without which `readTtlSources` would scan a
+      // repository root that has no `definitions/` or `data/` and contribute
+      // nothing at all.
+      const packageRoot = ref.subdir ? join(dir, ref.subdir) : dir;
       return {
         name: ref.pkg,
         source: ref.source,
         resolved,
-        root: dir,
-        sources: readTtlSources(dir, ref.pkg),
-        stories: readStorySources(dir, ref.pkg),
+        root: packageRoot,
+        sources: readTtlSources(packageRoot, ref.pkg),
+        stories: readStorySources(packageRoot, ref.pkg),
       };
     }
   }

package/src/kernel/runtime/types.ts

@@ -8,6 +8,7 @@
  * that are actually populated by the time it runs.
  */
 
+import type { UndoOutcome } from "@canonical/task/node";
 import type { DetailLevel, OutputFormat } from "../../constants.js";
 import type { ConfigLayers } from "../config/types.js";
 
@@ -221,4 +222,20 @@ export interface PragmaRuntime {
    * plan of its own, which is what keeps the raw-effect render the default.
    */
   planData?: unknown;
+  /**
+   * The post-undo projection seam. `--undo` is two-phase: the undo
+   * interpreter WALKS the verb's task with every effect mocked to collect the
+   * reversals, and only then executes what it collected — so nothing the task
+   * body says while it is interpreted describes what the reversals did (the
+   * body only ever runs under the mocked walk). What DOES describe them is
+   * the interpreter's own per-undo outcomes, correlated by the `undoKey` each
+   * reversal was declared with. A verb that reports per-target results sets
+   * this (the same way it sets `exec`/`planData`, before returning its Task);
+   * the projector's undo branch awaits it with those outcomes AFTER the
+   * collected undos executed and before the `Undid N step(s).` line, so the
+   * verb projects them onto its own rows through the same path its forward
+   * run uses. A throw here is rendered as the run's error (nonzero exit) —
+   * the honest outcome when a reversal did not take.
+   */
+  undoReport?: (outcomes: readonly UndoOutcome[]) => void | Promise<void>;
 }

package/src/testing/helpers/runCli.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Pins how `runCli` reports a child that does not finish.
+ *
+ * `spawnSync` reports a timeout the same way it reports a failure to spawn —
+ * through `error` — and a caller that does not look will see only
+ * `status: null`, which reads downstream as an ordinary non-zero exit or, worse,
+ * as a content mismatch. These tests hold the boundary where that distinction
+ * is made, because the cost of losing it is paid in diagnosis rather than in a
+ * red test.
+ */
+
+import { describe, expect, it } from "vitest";
+import { runCli } from "./runCli.js";
+
+describe("runCli — a child that does not finish", () => {
+  it("reports a timeout as a timeout, with the duration", async () => {
+    // `--help` on a 1ms budget cannot complete; any real CLI start-up exceeds it.
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.toThrow(/timed out after 1ms/);
+  });
+
+  it("names the signal that killed it, so a hang is distinguishable", async () => {
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.toThrow(/killed by SIG/);
+  });
+
+  it("does not describe a timeout as a failure to spawn", async () => {
+    // The previous message said "failed to spawn", which sent a reader looking
+    // for a missing binary or a bad path instead of a slow or hung command.
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.not.toThrow(/failed to spawn/);
+  });
+
+  it("attaches whatever the child managed to write", async () => {
+    // Empty streams are still reported explicitly: "(empty)" is evidence, an
+    // absent section is an omission the reader has to interpret.
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.toThrow(/stdout:[\s\S]*stderr:/);
+  });
+});

package/src/testing/helpers/runCli.ts

@@ -46,10 +46,17 @@ export interface RunCliOptions {
    * test the shipped-entry boundary itself.
    */
   readonly mode?: "shipped" | "source";
-  /** Spawn timeout in milliseconds (default 20000). */
+  /** Spawn timeout in milliseconds (default {@link DEFAULT_TIMEOUT_MS}). */
   readonly timeoutMs?: number;
 }
 
+/**
+ * How long a spawned CLI may run before it is killed. Twenty seconds is far
+ * past any assertion these tests make; a run that reaches it has hung, not
+ * been slow.
+ */
+const DEFAULT_TIMEOUT_MS = 20_000;
+
 /** The captured outcome of a `runCli` invocation. */
 export interface RunCliResult {
   readonly stdout: string;
@@ -114,12 +121,29 @@ export function runCli(
     cwd: options.cwd,
     env: { ...env, ...options.env },
     encoding: "utf-8",
-    timeout: options.timeoutMs ?? 20_000,
+    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
   });
 
   if (result.error) {
+    // A timeout is not a spawn failure, and saying so costs real diagnosis
+    // time: `spawnSync` reports both through `error`, but a timed-out child
+    // has already produced output worth seeing, and the duration is the whole
+    // finding. Separated here so the message names what happened, and carries
+    // the evidence rather than making the reader go and get it.
+    const timedOutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const invocation = `${command} ${spawnArgs.join(" ")}`;
+    const captured = [
+      result.stdout ? `stdout:\n${result.stdout}` : "stdout: (empty)",
+      result.stderr ? `stderr:\n${result.stderr}` : "stderr: (empty)",
+    ].join("\n");
+
+    if ((result.error as NodeJS.ErrnoException).code === "ETIMEDOUT") {
+      throw new Error(
+        `runCli: ${invocation} timed out after ${timedOutMs}ms (killed by ${result.signal ?? "signal"}).\n${captured}`,
+      );
+    }
     throw new Error(
-      `runCli: failed to spawn ${command} ${spawnArgs.join(" ")} — ${result.error.message}`,
+      `runCli: failed to spawn ${invocation} — ${result.error.message}.\n${captured}`,
     );
   }