@canonical/pragma-cli 0.33.0 → 0.35.0

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.mcpLifecycle.mcp.test.ts

@@ -30,7 +30,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { capabilities } from "../../capabilities/index.js";
-import { readLock } from "../../kernel/runtime/lock.js";
+import { readActivePack } from "../../kernel/runtime/paths.js";
 import { DEFAULT_PACK_TTL } from "../fixtures/graph/defaultPack.js";
 import { type McpHarness, projectMcp } from "../helpers/projectMcp.js";
 
@@ -44,7 +44,7 @@ const tempDir = (prefix: string): string => {
 
 /**
  * A COLD project directory: a `pragma.config.ts` pointing at a real file
- * package, but NO lock yet — so the store boots cold until `sources_update`.
+ * package, but nothing built yet — so the store boots cold until `sources_update`.
  */
 function coldProject(ttl: string): string {
   const pkg = tempDir("e2-pkg-");
@@ -53,7 +53,7 @@ function coldProject(ttl: string): string {
   const cwd = tempDir("e2-proj-");
   writeFileSync(
     join(cwd, "pragma.config.ts"),
-    `export default { packages: [{ name: "default", source: "file://${pkg}" }] };\n`,
+    `export default { packs: [{ name: "default", source: "file://${pkg}" }] };\n`,
   );
   return cwd;
 }
@@ -83,7 +83,7 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     };
     expect(error.code).toBe("STORE_UNAVAILABLE");
     expect(error.recovery?.mcp?.tool).toBe("sources_update");
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
 
     // 2) The agent runs the recovery tool for real (confirm) — it builds the pack.
     const update = await mcp.callTool("sources_update", { confirm: true });
@@ -93,7 +93,7 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     expect((update.data as { contentHash: string }).contentHash).toMatch(
       /^[0-9a-f]{64}$/,
     );
-    expect(readLock(cwd)?.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
 
     // 3) RETRY on the SAME server: the shared store was invalidated by the
     //    mutation, so the memoized cold rejection is gone and the read re-boots
@@ -104,7 +104,10 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     const names = (warm.data as { name: string }[])
       .map((row) => row.name)
       .sort();
-    expect(names).toEqual(["Button", "Card"]);
+    // The whole pack — `block_list` is the declared, unfiltered list since
+    // L-OPEN-9, so no channel hides Beta Badge and no tier join hides the
+    // untiered Orphan Widget.
+    expect(names).toEqual(["Beta Badge", "Button", "Card", "Orphan Widget"]);
   });
 });
 

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

@@ -0,0 +1,188 @@
+/**
+ * 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 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
+ * tree exists, so a throw there fails every command — including `sources update`
+ * and `doctor`, the only two that can recover from it. Both of those are run
+ * here after the bad stories are in the pack.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runTask } from "@canonical/task/node";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runChecks } from "../../capabilities/doctor/runChecks.js";
+import { capabilities } from "../../capabilities/index.js";
+import { buildUpdateTask } from "../../capabilities/sources/runUpdate.js";
+import { loadEffectiveModules } from "../../kernel/packs/collect.js";
+import { packDir, readActivePack } from "../../kernel/runtime/paths.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { runCli } from "../helpers/runCli.js";
+
+const TTL = `
+@prefix ex: <https://example.org/kitchen#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ex:Recipe a owl:Class .
+ex:name a owl:DatatypeProperty ; rdfs:domain ex:Recipe ; rdfs:range xsd:string .
+
+ex:soup a ex:Recipe ; ex:name "Soup" .
+ex:stew a ex:Recipe ; ex:name "Stew" .
+`;
+
+/** A valid read story — the noun the distribution never shipped. */
+const RECIPE_STORY = JSON.stringify({
+  noun: "recipe",
+  description: "List recipes.",
+  colophon: "Recipes are modelled as ex:Recipe individuals.",
+  list: {
+    query:
+      "SELECT ?uri ?name WHERE { ?uri a ex:Recipe ; ex:name ?name } ORDER BY ?name",
+    columns: [{ field: "uri" }, { field: "name" }],
+  },
+});
+
+/** Schema-invalid: a well-formed JSON document the pack grammar rejects. */
+const INVALID_STORY = JSON.stringify({ noun: "Bad Noun", list: {} });
+
+let graph: FixtureGraph;
+beforeAll(async () => {
+  graph = await bootFixtureRuntime({
+    ttl: TTL,
+    stories: {
+      "recipe.json": RECIPE_STORY,
+      // Not JSON at all.
+      "broken.json": "{ this is not json",
+      "invalid.json": INVALID_STORY,
+    },
+  });
+}, 60_000);
+afterAll(async () => {
+  await graph.dispose();
+});
+
+describe("a package's stories reach the pack", () => {
+  it("sources update carries all three story files into the pack, verbatim", () => {
+    const hash = readActivePack(graph.cwd);
+    expect(hash).toBeDefined();
+    const carried = JSON.parse(
+      readFileSync(join(packDir(hash as string), "stories.json"), "utf-8"),
+    ) as { source: string; content: string }[];
+    expect(carried.map((record) => record.source)).toEqual([
+      "fixture/stories/broken.json",
+      "fixture/stories/invalid.json",
+      "fixture/stories/recipe.json",
+    ]);
+    expect(
+      carried.find((r) => r.source === "fixture/stories/recipe.json")?.content,
+    ).toBe(RECIPE_STORY);
+  });
+});
+
+describe("a package-declared noun answers reads (in-process)", () => {
+  it("recipe list returns rows from the package's own graph", async () => {
+    const { modules } = await loadEffectiveModules(capabilities, graph.cwd);
+    const recipe = modules.find((module) => module.name === "recipe");
+    expect(recipe?.story).toBe(true);
+    expect(recipe?.colophon).toBe(
+      "Recipes are modelled as ex:Recipe individuals.",
+    );
+    const list = recipe?.verbs.find(
+      (verb) => verb.path.join(" ") === "recipe list",
+    ) as VerbSpec;
+    const rows = (await list.run({}, graph.runtime)) as { name: string }[];
+    expect(rows.map((row) => row.name)).toEqual(["Soup", "Stew"]);
+  });
+
+  it("names the unusable stories without failing the load", async () => {
+    const { problems } = await loadEffectiveModules(capabilities, graph.cwd);
+    expect(problems.map((problem) => problem.source).sort()).toEqual([
+      "fixture/stories/broken.json",
+      "fixture/stories/invalid.json",
+    ]);
+    // Each says WHY, not just that something was wrong.
+    const invalid = problems.find((p) => p.source.endsWith("invalid.json"));
+    expect(invalid?.message).toMatch(/Invalid story/);
+  });
+});
+
+describe("the two recoveries still run with bad stories in the pack", () => {
+  it("sources update re-resolves and reports the carried story count", async () => {
+    const result = await runTask(await buildUpdateTask(graph.runtime));
+    expect(result.packs).toEqual([
+      {
+        name: "fixture",
+        resolved: expect.any(String),
+        sourceCount: 1,
+        storyCount: 3,
+      },
+    ]);
+  });
+
+  it("doctor passes `pack refs` and lists each ignored story as a failing item", async () => {
+    const data = await runChecks(graph.runtime);
+    const check = data.checks.find((entry) => entry.name === "pack refs");
+    // 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([
+      "fixture/stories/broken.json",
+      "fixture/stories/invalid.json",
+    ]);
+    for (const item of check?.items ?? []) expect(item.status).toBe("fail");
+  });
+});
+
+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,
+    });
+    expect(result.exitCode).toBe(0);
+    const rows = (JSON.parse(result.stdout) as { data: { name: string }[] })
+      .data;
+    expect(rows.map((row) => row.name)).toEqual(["Soup", "Stew"]);
+    // The bad stories are named on stderr, never on stdout — `--format json`
+    // stays machine-readable.
+    expect(result.stderr).toContain("fixture/stories/broken.json");
+    expect(result.stderr).toContain("fixture/stories/invalid.json");
+  });
+
+  it("pragma capabilities lists the package's tools — the surface agents read", () => {
+    // The MCP server registers its tools from the effective modules, so a
+    // catalog built from the STATIC registry would omit exactly the nouns
+    // `tools/list` advertises. `config show` points agents here for the verbs a
+    // story produces; that pointer has to be true.
+    const result = runCli(["capabilities", "--format", "json"], {
+      cwd: graph.cwd,
+    });
+    expect(result.exitCode).toBe(0);
+    const { data } = JSON.parse(result.stdout) as {
+      data: { tools: { name: string }[] };
+    };
+    expect(data.tools.map((tool) => tool.name)).toContain("recipe_list");
+  });
+
+  it("pragma --help does NOT list recipe — the documented fast-path limit", () => {
+    // `--help` reads the STATIC capability set (no config, no pack read), which
+    // is what keeps its budget. A package-declared noun is dispatch-only.
+    const help = runCli(["--help"], { cwd: graph.cwd });
+    expect(help.exitCode).toBe(0);
+    expect(help.stdout).not.toContain("recipe");
+    // …and the command it does not advertise still runs (asserted above).
+  });
+});

package/src/testing/behavioral/liveReadSurface.ts

@@ -61,9 +61,10 @@ export const liveVerbs: readonly LiveVerb[] = buildLiveVerbs();
 /**
  * Read nouns' `lookup` verbs, MCP-exposed, store-backed — restricted to the
  * PACK-lookup contract (a variadic `<name...>` positional), which the B-tier
- * list→lookup→batch suites drive uniformly. Bespoke single-name lookups
- * (`tier_lookup`, `prompt_lookup`) have their own tests, so they are excluded
- * here structurally (by param shape, not by naming the noun — R2).
+ * list→lookup→batch suites drive uniformly. The one bespoke single-name lookup
+ * left (`prompt_lookup`) has its own tests, so it is excluded here structurally
+ * (by param shape, not by naming the noun — R2). `tier_lookup` joined the pack
+ * contract in L-OPEN-9, so it is swept here like every other declared lookup.
  */
 export const lookupVerbs: readonly LiveVerb[] = liveVerbs.filter(
   (v) =>

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).
  */
@@ -21,6 +21,8 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { capabilities } from "../../capabilities/index.js";
 import { readPackIndex } from "../../kernel/completion/entitySource.js";
+import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import {
   ALL_VISIBLE_CONFIG,
   CANONICAL_TTL,
@@ -41,6 +43,8 @@ let mcp: Awaited<ReturnType<typeof projectMcp>>;
 let firstNameByNoun: Map<string, string>;
 /** The registered tool list, fetched once (annotations are call-invariant). */
 let registeredTools: Awaited<ReturnType<typeof mcp.listTools>>;
+/** The index of the pack the fixture's boot decision names. */
+let activeIndex: PackIndex | undefined;
 
 beforeAll(async () => {
   fixture = await bootFixtureRuntime({
@@ -49,6 +53,9 @@ beforeAll(async () => {
   });
   mcp = await projectMcp(capabilities, fixture.cwd);
   registeredTools = await mcp.listTools();
+  activeIndex = readPackIndex(
+    resolveSources(await fixture.runtime.loadConfig(), fixture.cwd),
+  );
 
   firstNameByNoun = new Map();
   for (const v of listVerbs) {
@@ -81,15 +88,13 @@ function representativeValue(
   param: LiveVerb["spec"]["params"][number],
 ): unknown {
   if (param.name === "prefix") {
-    const prefix = Object.keys(readPackIndex(fixture.cwd)?.prefixes ?? {}).find(
+    const prefix = Object.keys(activeIndex?.prefixes ?? {}).find(
       (p) => p !== "owl" && p !== "rdfs" && p !== "rdf" && p !== "xsd",
     );
     return prefix ?? "ds";
   }
   if (param.name === "uri") {
-    const entity = readPackIndex(fixture.cwd)?.entities.find(
-      (e) => e.box === "abox",
-    );
+    const entity = activeIndex?.entities.find((e) => e.box === "abox");
     return entity?.prefixed ?? entity?.name ?? "";
   }
   // An enum positional (e.g. `config set <key>`) must

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/behavioral/staleCommands.test.ts

@@ -51,6 +51,16 @@ const BANNED: readonly BannedPattern[] = [
     reason:
       "retired `--llm` flag (now the `--format llm` form, auto-detected when piped)",
   },
+  {
+    pattern: /--all-tiers\b/,
+    reason:
+      "retired `--all-tiers` flag (L-OPEN-9: `block list` is the declared, unfiltered story — there is no tier filter to escape)",
+  },
+  {
+    pattern: /\btoken[ _]add-config\b/,
+    reason:
+      "removed `token add-config` command / `token_add-config` tool (L-OPEN-9: a mutation the declared read grammar has no verb for)",
+  },
 ];
 
 // Every shipped doc must be free of retired vocabulary: the README plus every