@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -31,7 +31,7 @@ import { storyModules } from "../../capabilities/distribution.js";
 import { graphQueryVerb } from "../../capabilities/graph/query.verb.js";
 import {
   ontologyListVerb,
-  ontologyShowVerb,
+  ontologyLookupVerb,
 } from "../../capabilities/ontology/verbs.js";
 import { updateVerb } from "../../capabilities/sources/update.verb.js";
 import {
@@ -268,7 +268,7 @@ describe("default-pack journey — block list, populated and empty (E1)", () =>
   });
 
   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
+    // D10-A, MEASURED at the dispatch seam the CLI 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
@@ -306,10 +306,10 @@ describe("default-pack journey — ontology list/show, populated and empty (E1)"
     ]);
   });
 
-  it("ontology show ds surfaces the two block domain classes", async () => {
+  it("ontology lookup ds surfaces the two block domain classes", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
     const envelope = await readVerb(
-      ontologyShowVerb,
+      ontologyLookupVerb,
       { prefix: "ds" },
       fixture.cwd,
     );
@@ -326,11 +326,11 @@ describe("default-pack journey — ontology list/show, populated and empty (E1)"
     expect(envelope.data).toEqual([]);
   });
 
-  it("ontology show of an unknown prefix is NOT_FOUND, not a crash", async () => {
+  it("ontology lookup 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,
+        ontologyLookupVerb,
         { prefix: "nope" },
         NO_MUTATION,
         bootRuntime(JSON_FLAGS, fixture.cwd),
@@ -447,7 +447,7 @@ describe("default-pack journey — real-data shapes the clean fixture masked (E1
   // `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
+  // "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

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

@@ -158,10 +158,15 @@ describe("first install — the surfaces say where the answers come from", () =>
     expect(status.entityCount).toBeGreaterThan(0);
   });
 
-  it("doctor passes, naming the embedded snapshot rather than the config", async () => {
+  it("doctor passes, saying the packs came with the CLI rather than from the config", async () => {
     const result = await checkPackageRefs(bootRuntime(JSON_FLAGS, emptyCwd()));
     expect(result.status).toBe("pass");
-    expect(result.detail).toContain("embedded snapshot @ ");
+    // What is pinned is the DISTINCTION — a fresh install reads packs it
+    // shipped with, not packs this project configured — and that the row says
+    // how to change that. The wording is the reader's ("shipped with the CLI"),
+    // not the build's ("embedded snapshot"); the per-pack revisions moved to
+    // the row's sub-items when each pack got its own line.
+    expect(result.detail).toContain("shipped with the CLI");
     expect(result.detail).toContain("pragma sources update");
   });
 });

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

@@ -0,0 +1,206 @@
+/**
+ * The `implementation` story's SEMANTICS, in-process through the real CLI
+ * dispatch path (`executeVerb`), against the canonical fixture.
+ *
+ * The generic live-surface tests call `implementation_list` with empty
+ * parameters and check the envelope, so they stay green whether or not the
+ * story means anything: the block-name join could resolve to the wrong subject,
+ * the IRI fallback could never fire, and `--platform` / `--library` could
+ * filter nothing at all. Those are the four claims the noun actually makes, so
+ * they are pinned here rather than left to the envelope.
+ *
+ * The join is the reason this noun exists and the reason it is worth a
+ * fixture-backed test: `ds:implementsBlock` points from an implementation
+ * collected in THIS repository at a block declared by a DIFFERENT pack, and the
+ * row's `block` column is the design system's own `ds:name` reached across that
+ * edge — not a string this repository holds anywhere.
+ */
+
+import { afterAll, describe, expect, it } from "vitest";
+import { storyModules } from "../../capabilities/distribution.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { JSON_FLAGS, NO_MUTATION } from "../helpers/parity.js";
+
+const implementationModule = storyModules.get("implementation");
+if (!implementationModule) {
+  throw new Error('pragma.conf.ts declares no story for "implementation"');
+}
+
+const verbOf = (key: string): VerbSpec =>
+  implementationModule.verbs.find((v) => verbKey(v.path) === key) as VerbSpec;
+
+const listVerb = verbOf("implementation list");
+const librariesVerb = verbOf("implementation libraries");
+
+const fixtures: FixtureGraph[] = [];
+afterAll(async () => {
+  await Promise.all(fixtures.map((f) => f.dispose()));
+});
+
+/** Boot one tracked canonical fixture, for auto-disposal. */
+async function boot(): Promise<FixtureGraph> {
+  const fixture = await bootFixtureRuntime({
+    ttl: CANONICAL_TTL,
+    config: CANONICAL_CONFIG,
+  });
+  fixtures.push(fixture);
+  return fixture;
+}
+
+type Row = Record<string, string>;
+
+async function rows(
+  verb: VerbSpec,
+  params: Record<string, unknown> = {},
+): Promise<Row[]> {
+  const fixture = await boot();
+  const out = await executeVerb(
+    verb,
+    params,
+    NO_MUTATION,
+    bootRuntime(JSON_FLAGS, fixture.cwd),
+  );
+  return JSON.parse(out.stdout as string).data as Row[];
+}
+
+/**
+ * What the fixture's implementation graph says, as pairs: Button is
+ * implemented TWICE, on two platforms, and Modal once.
+ */
+const EVERY_PAIR = [
+  "Button|@canonical/react-ds-global",
+  "Button|@canonical/svelte-ds-global",
+  "Modal|@canonical/react-ds-global",
+];
+
+const pairs = (list: Row[]): string[] =>
+  list.map((r) => `${r.block}|${r.library}`).sort();
+
+describe("implementation list — the cross-pack join", () => {
+  it("names each block by the design system's ds:name, not by its IRI", async () => {
+    // `ds:implementsBlock ds:button` carries no name; `Button` exists only on
+    // the block node BLOCK_TTL declares. A row reading `button` here would mean
+    // the join silently degraded to the IRI fallback and nobody noticed.
+    const list = await rows(listVerb);
+    expect(pairs(list)).toEqual(EVERY_PAIR);
+    expect(list.map((r) => r.block)).not.toContain("button");
+  });
+
+  it("one block implemented twice yields two rows, one per library", async () => {
+    // The row is the EDGE, not the block: collapsing the two Button rows into
+    // one would answer "is this implemented?" while losing "by whom", which is
+    // the question the noun exists for.
+    const list = await rows(listVerb);
+    expect(list.filter((r) => r.block === "Button")).toHaveLength(2);
+  });
+
+  it("carries the source link and the implementation's own IRI", async () => {
+    const list = await rows(listVerb);
+    const react = list.find(
+      (r) => r.block === "Button" && r.platform === "react",
+    );
+    expect(react?.source).toBe("https://example.test/react/Button.tsx");
+    expect(react?.uri).toBe(
+      "https://ds.canonical.com/implementation.react-ds-global.button",
+    );
+  });
+
+  it("falls back to the IRI local name for a block the store does not declare", async () => {
+    // The design-system pack can be absent while this one is present — a
+    // `sources` config carrying only the implementation graph. The row must
+    // stay readable, so the fallback is exercised against an edge whose target
+    // is a bare IRI with no `ds:name` anywhere in the store.
+    const fixture = await bootFixtureRuntime({
+      ttl: `${CANONICAL_TTL}
+ds:implementation.library.orphan-lib a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/orphan-lib" ;
+  ds:platform "react" ;
+  ds:hasImplementation ds:implementation.orphan-lib.unnamed .
+
+ds:implementation.orphan-lib.unnamed a ds:ImplementationObject ;
+  ds:implementsBlock ds:global.component.unnamed_block ;
+  ds:headLink "https://example.test/orphan/Unnamed.tsx" .
+`,
+      config: CANONICAL_CONFIG,
+    });
+    fixtures.push(fixture);
+    const out = await executeVerb(
+      listVerb,
+      {},
+      NO_MUTATION,
+      bootRuntime(JSON_FLAGS, fixture.cwd),
+    );
+    const list = JSON.parse(out.stdout as string).data as Row[];
+    const orphan = list.find((r) => r.library === "@canonical/orphan-lib");
+    expect(orphan?.block).toBe("global.component.unnamed_block");
+  });
+});
+
+describe("implementation list — the declared filters", () => {
+  it("--platform keeps only that platform's rows", async () => {
+    expect(pairs(await rows(listVerb, { platform: "svelte" }))).toEqual([
+      "Button|@canonical/svelte-ds-global",
+    ]);
+  });
+
+  it("--library keeps only that library's rows", async () => {
+    expect(
+      pairs(await rows(listVerb, { library: "@canonical/react-ds-global" })),
+    ).toEqual([
+      "Button|@canonical/react-ds-global",
+      "Modal|@canonical/react-ds-global",
+    ]);
+  });
+
+  it("--search matches the block name and the library name alike", async () => {
+    expect(pairs(await rows(listVerb, { search: "modal" }))).toEqual([
+      "Modal|@canonical/react-ds-global",
+    ]);
+    expect(pairs(await rows(listVerb, { search: "svelte" }))).toEqual([
+      "Button|@canonical/svelte-ds-global",
+    ]);
+  });
+});
+
+describe("implementation libraries — the library rows", () => {
+  it("lists every library with its platform, tier, version and block count", async () => {
+    const list = await rows(librariesVerb);
+    expect(list.map((r) => r.name).sort()).toEqual([
+      "@canonical/react-ds-global",
+      "@canonical/svelte-ds-global",
+    ]);
+    const react = list.find((r) => r.name === "@canonical/react-ds-global");
+    expect(react).toMatchObject({
+      platform: "react",
+      tier: "global",
+      version: "0.34.0",
+      count: "2",
+    });
+  });
+
+  it("the counts agree with the rows `implementation list` returns", async () => {
+    // `ds:implementationCount` is asserted by the aggregate INDEX, on the same
+    // subject the per-library file describes. The two files can drift apart in
+    // the generator, and a count that disagrees with the edges is worse than no
+    // count at all — so the two halves are compared rather than each pinned.
+    const [libraries, list] = await Promise.all([
+      rows(librariesVerb),
+      rows(listVerb),
+    ]);
+    for (const library of libraries) {
+      const actual = list.filter((r) => r.library === library.name).length;
+      expect(Number(library.count)).toBe(actual);
+    }
+  });
+});

package/src/testing/behavioral/journeys.interactiveTty.e2e.test.ts

@@ -24,8 +24,8 @@
  *
  * TODO(AV-231/E4): when `node-pty` (or an equivalent PTY shim) is on the
  * devDependency set, replace each `it.todo` with a PTY-driven `it` that spawns
- * `dist/pragma create …` under a pty, writes the keystroke, and asserts the exit
- * code + "Cancelled." line. The compiled binary is already provisioned for the
+ * the shipped `pragma create …` under a pty, writes the keystroke, and asserts the exit
+ * code + "Cancelled." line. The shipped entry is already provisioned for the
  * spawn-e2e layer by `testing/perf/globalSetup.ts`.
  */
 

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

@@ -1,11 +1,11 @@
 /**
- * The package tier, end to end: a noun the binary never shipped.
+ * The package tier, end to end: a noun the distribution never shipped.
  *
  * A package that ships `stories/*.json` and is declared as a `file:` pack
  * contributes a working command to a project that declares it — resolved by
  * `sources update`, hashed into the pack, written into the pack directory, read
  * back storelessly at dispatch, and answered from the fixture graph. Proven both
- * in-process and through the COMPILED binary in a real subprocess.
+ * in-process and through the SHIPPED entry in a real subprocess.
  *
  * The same package also ships a malformed story and a schema-invalid one. Those
  * must be DROPPED, not fatal: package stories reach dispatch before the command
@@ -43,7 +43,7 @@ ex:soup a ex:Recipe ; ex:name "Soup" .
 ex:stew a ex:Recipe ; ex:name "Stew" .
 `;
 
-/** A valid read story — the noun the binary never shipped. */
+/** A valid read story — the noun the distribution never shipped. */
 const RECIPE_STORY = JSON.stringify({
   noun: "recipe",
   description: "List recipes.",
@@ -138,16 +138,19 @@ describe("the two recoveries still run with bad stories in the pack", () => {
     // The pack DOES answer reads, so the check passes…
     expect(check?.status).toBe("pass");
     expect(check?.detail).toContain("2 stories ignored");
-    // …with the unusable stories named underneath it.
-    expect(check?.items?.map((item) => item.label).sort()).toEqual([
+    // …with the unusable stories named underneath it. The items also carry
+    // one PASSING row per pack the answer was built from, so this pins the
+    // FAILING ones: what a story problem contributes is a failing item, and
+    // that claim must not break every time provenance gains a row.
+    const failing = (check?.items ?? []).filter((i) => i.status === "fail");
+    expect(failing.map((item) => item.label).sort()).toEqual([
       "fixture/stories/broken.json",
       "fixture/stories/invalid.json",
     ]);
-    for (const item of check?.items ?? []) expect(item.status).toBe("fail");
   });
 });
 
-describe("the compiled binary answers the package's noun (subprocess)", () => {
+describe("the shipped entry answers the package's noun (subprocess)", () => {
   it("pragma recipe list --format json returns the package's rows", () => {
     const result = runCli(["recipe", "list", "--format", "json"], {
       cwd: graph.cwd,

package/src/testing/behavioral/mcpServe.e2e.test.ts

@@ -1,10 +1,17 @@
 /**
- * A7 — `pragma mcp` serve boot, observed through the real compiled binary.
+ * A7 — `pragma mcp serve` boot, observed through the real shipped entry.
  *
  * Replaces the old mocked-SIGINT unit test: `runCli` spawns with no `input`,
  * which gives the child an immediately-EOF stdin (verified equivalent to
  * `< /dev/null`) — the shape a host that closes the pipe on shutdown produces.
  * The server must connect and exit cleanly, not hang or crash.
+ *
+ * The other half of the contract is the one the bin's narrow short-circuit
+ * exists to keep honest: only the exact serve invocation serves. `pragma mcp`,
+ * any help form, and any argv with a token after `serve` print text or an
+ * error and start NO server — which is only observable across the process
+ * boundary, because in-process dispatch never reaches the short-circuit at
+ * all.
  */
 
 import { describe, expect, it } from "vitest";
@@ -12,10 +19,58 @@ import { runCli } from "../helpers/runCli.js";
 
 describe("mcp serve — stdin close boots and exits cleanly (A7, e2e)", () => {
   it("exits 0 with no output and no signal", () => {
-    const result = runCli(["mcp"]);
+    const result = runCli(["mcp", "serve"]);
     expect(result.exitCode).toBe(0);
     expect(result.signal).toBeNull();
     expect(result.stdout).toBe("");
     expect(result.stderr).toBe("");
   });
 });
+
+describe("mcp — the noun is ordinary grammar (e2e)", () => {
+  it("bare `mcp` prints the noun help and exits 0, serving nothing", () => {
+    const result = runCli(["mcp"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("Usage: pragma mcp");
+    expect(result.stdout).toContain("serve");
+    // A JSON-RPC handshake would have started with `{`; help never does.
+    expect(result.stdout.startsWith("{")).toBe(false);
+  });
+
+  it("`mcp --help` prints help rather than starting the server", () => {
+    const result = runCli(["mcp", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("serve");
+  });
+
+  it("`mcp serve --help` documents the verb rather than starting it", () => {
+    const result = runCli(["mcp", "serve", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("Start the MCP server over stdio");
+    expect(result.stdout).toContain("Usage: pragma mcp serve");
+  });
+});
+
+/**
+ * The short-circuit matches argv EXACTLY. A prefix match would extend the
+ * stdio-purity budget — no flag parsing, no first-run, nothing on stdout but
+ * JSON-RPC — to argv the server was never asked to answer, so a suffixed line
+ * would serve instead of being parsed. These are the two suffixes that prove
+ * the fall-through: a global flag the program owns, and a stray operand.
+ */
+describe("mcp serve — anything suffixed falls through to the grammar (e2e)", () => {
+  it("`mcp serve --version` answers the global flag, serving nothing", () => {
+    const result = runCli(["mcp", "serve", "--version"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+    // A JSON-RPC handshake would have started with `{`; a version never does.
+    expect(result.stdout.startsWith("{")).toBe(false);
+  });
+
+  it("`mcp serve extra` is parsed, so its bad global value is rejected", () => {
+    const result = runCli(["mcp", "serve", "extra", "--format", "bogus"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid format "bogus"');
+    expect(result.stdout).toBe("");
+  });
+});

package/src/testing/behavioral/mcpSurface.test.ts

@@ -13,7 +13,7 @@
  * Representative args are built structurally: a lookup/sample's positional
  * resolves through its noun's OWN `list` (browse-then-address, same as B1); a
  * `prefix`/`uri`-named positional (the grammar's TBox/entity-inspection
- * convention, used today by `ontology show`/`graph inspect`) resolves from the
+ * convention, used today by `ontology lookup`/`graph inspect`) resolves from the
  * pack index generically, not by noun name. A mutating tool is called WITHOUT
  * `confirm` (a safe plan-only preview).
  */

package/src/testing/behavioral/rootCli.e2e.test.ts

@@ -22,8 +22,32 @@ describe("--version at every level (A2, e2e)", () => {
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
   });
 
-  it("-v is equivalent to --version", () => {
-    expect(runCli(["-v"]).stdout.trim()).toBe(VERSION);
+  it("-v is rejected — --version is the one spelling", () => {
+    const result = runCli(["-v"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Unknown option "-v"');
+  });
+});
+
+describe("global value flags reject bad values loudly (e2e)", () => {
+  it("--format text is not a format", () => {
+    const result = runCli(["config", "show", "--format", "text"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid format "text"');
+    expect(result.stderr).toContain("plain, llm, json");
+  });
+
+  it("--detail rejects an unrecognized level, naming the valid ones", () => {
+    const result = runCli(["config", "show", "--detail", "bogus"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid detail "bogus"');
+    expect(result.stderr).toContain("summary, standard, detailed");
+  });
+
+  it("--verbose=<x> is rejected — the flag takes no value", () => {
+    const result = runCli(["config", "show", "--verbose=true"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("`--verbose` takes no value");
   });
 });
 

package/src/testing/eval/__snapshots__/eval.test.ts.snap

@@ -63,7 +63,12 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "passed": true,
   },
   {
-    "id": "content-standard-list-length-equals-category-count-sum",
+    "id": "content-standard-category-counts-match-filtered-list",
+    "kind": "content",
+    "passed": true,
+  },
+  {
+    "id": "content-standard-category-rollup-keeps-the-direct-member",
     "kind": "content",
     "passed": true,
   },
@@ -172,6 +177,21 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-standard-list-empty-category-is-a-calm-empty-list",
+    "kind": "tool",
+    "passed": true,
+  },
+  {
+    "id": "tool-standard-list-names-are-addressable-by-lookup",
+    "kind": "tool",
+    "passed": true,
+  },
+  {
+    "id": "tool-standard-lookup-advertised-glob-matches",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-standard-lookup-has-dos-and-donts",
     "kind": "tool",
@@ -182,6 +202,11 @@ exports[`eval harness — seed gate > runs the full seed (stable + read-noun) ca
     "kind": "tool",
     "passed": true,
   },
+  {
+    "id": "tool-token-lookup-addresses-only-what-list-publishes",
+    "kind": "tool",
+    "passed": true,
+  },
   {
     "id": "tool-token-noun-is-read-only",
     "kind": "tool",

package/src/testing/eval/cases/effectful.ts

@@ -88,7 +88,7 @@ export const effectfulEvalCases: readonly EvalCase[] = [
     id: "tool-doctor-reports-check-tallies",
     kind: "tool",
     input:
-      "doctor returns a { checks, passed, failed, skipped } diagnostic report where the tallies sum to the checks.",
+      "doctor returns a { checks, passed, failed, available, skipped } diagnostic report where the tallies sum to the checks.",
     async expect({ mcp }) {
       const result = await mcp.callTool("doctor");
       assert.equal(result.ok, true);
@@ -96,11 +96,12 @@ export const effectfulEvalCases: readonly EvalCase[] = [
         checks: unknown[];
         passed: number;
         failed: number;
+        available: number;
         skipped: number;
       };
       assert.ok(Array.isArray(data.checks), "expected a checks array");
       assert.equal(
-        data.passed + data.failed + data.skipped,
+        data.passed + data.failed + data.available + data.skipped,
         data.checks.length,
       );
     },