@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/shared/stories/pack/collectPackStories.test.ts

@@ -1,8 +1,29 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PragmaConfig } from "#config";
 import { PragmaError } from "#error";
 import { RECIPE_STORY } from "#testing";
 import type { SemanticPackage } from "../../semanticPackage.js";
-import collectPackStories from "./collectPackStories.js";
+import { BUNDLED_PACKS } from "./bundled/index.js";
+import realCollectPackStories from "./collectPackStories.js";
+import {
+  buildReservedVerbs,
+  deriveReservedVerbs,
+  isReserved,
+  type ReservedVerbs,
+} from "./reservedVerbs.js";
+
+/**
+ * Test wrapper that isolates the always-present bundled packs: unit tests
+ * asserting exact entries pass `[]` so the default bundled `tier` pack does not
+ * pollute their expectations. Bundled behavior is covered separately below.
+ */
+function collectPackStories(
+  config: PragmaConfig,
+  packages: readonly SemanticPackage[],
+  reserved: ReservedVerbs,
+): ReturnType<typeof realCollectPackStories> {
+  return realCollectPackStories(config, packages, reserved, []);
+}
 
 function makePackage(stories: SemanticPackage["stories"]): SemanticPackage {
   return {
@@ -17,6 +38,45 @@ function makePackage(stories: SemanticPackage["stories"]): SemanticPackage {
 
 const CONFIG = { tier: undefined, channel: "normal" as const };
 
+// A representative slice of the real built-in surface: leaf read nouns that
+// own `list`/`lookup`, plus operational nouns (graph, config, create, graphql,
+// setup, tokens) that own neither and so must be reserved wholesale.
+const BUILTIN_PAIRS: readonly (readonly [string, string | undefined])[] = [
+  ["standard", "list"],
+  ["standard", "lookup"],
+  ["standard", "categories"],
+  ["standard", "sample"],
+  ["block", "list"],
+  ["block", "lookup"],
+  ["token", "list"],
+  ["token", "lookup"],
+  ["tier", "list"],
+  ["config", "show"],
+  ["config", "tier"],
+  ["config", "channel"],
+  ["graph", "query"],
+  ["graph", "inspect"],
+  ["create", "component"],
+  ["create", "package"],
+  ["graphql", "build"],
+  ["graphql", "check"],
+  ["graphql", "serve"],
+  ["setup", "all"],
+  ["setup", "lsp"],
+  ["tokens", "add-config"],
+  ["info", undefined],
+];
+
+/** Run a thunk and return the error it throws (or `undefined`). */
+function caught(run: () => unknown): unknown {
+  try {
+    run();
+  } catch (error) {
+    return error;
+  }
+  return undefined;
+}
+
 describe("collectPackStories", () => {
   let warn: ReturnType<typeof vi.spyOn>;
 
@@ -39,7 +99,7 @@ describe("collectPackStories", () => {
           },
         ]),
       ],
-      new Set(["block"]),
+      buildReservedVerbs([["block", undefined]]),
     );
     expect(entries.map((entry) => entry.definition.noun)).toEqual([
       "recipe",
@@ -57,11 +117,13 @@ describe("collectPackStories", () => {
           { path: "/pkg/stories/recipe.json", definition: RECIPE_STORY },
         ]),
       ],
-      new Set(),
+      buildReservedVerbs([]),
     );
     expect(entries).toHaveLength(1);
     expect(entries.at(0)?.source).toBe("config");
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining("already taken"));
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("already provided"),
+    );
   });
 
   it("skips invalid package stories with a warning", () => {
@@ -72,7 +134,7 @@ describe("collectPackStories", () => {
           { path: "/pkg/stories/broken.json", definition: { nope: true } },
         ]),
       ],
-      new Set(),
+      buildReservedVerbs([]),
     );
     expect(entries).toHaveLength(0);
     expect(warn).toHaveBeenCalledWith(
@@ -85,7 +147,7 @@ describe("collectPackStories", () => {
       collectPackStories(
         { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "block" }] },
         [],
-        new Set(["block"]),
+        buildReservedVerbs([["block", undefined]]),
       ),
     ).toThrow(PragmaError);
   });
@@ -101,8 +163,244 @@ describe("collectPackStories", () => {
           },
         ]),
       ],
-      new Set(["block"]),
+      buildReservedVerbs([["block", undefined]]),
     );
     expect(entries).toHaveLength(0);
   });
+
+  it("admits a pack once its noun's verbs leave the reserved map", () => {
+    // Post-migration simulation: `standard`'s list/lookup wrappers are gone,
+    // so only categories/sample remain reserved — a `standard` pack (which
+    // emits list + lookup) is now admissible. `info` is a bare (whole-noun)
+    // built-in, so an `info` pack stays blocked. This is the keystone: the
+    // per-verb guard makes the leaf cutover incremental.
+    const reserved = buildReservedVerbs([
+      ["standard", "categories"],
+      ["standard", "sample"],
+      ["info", undefined],
+    ]);
+
+    const entries = collectPackStories(
+      CONFIG,
+      [
+        makePackage([
+          {
+            path: "/pkg/stories/standard.json",
+            definition: { ...RECIPE_STORY, noun: "standard" },
+          },
+          {
+            path: "/pkg/stories/info.json",
+            definition: { ...RECIPE_STORY, noun: "info" },
+          },
+        ]),
+      ],
+      reserved,
+    );
+
+    expect(entries.map((entry) => entry.definition.noun)).toEqual(["standard"]);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("shadows built-in command"),
+    );
+  });
+
+  // Regression restoration (FIX 1): operational nouns own no list/lookup, so
+  // deriveReservedVerbs promotes them to a whole-noun reservation. Since a
+  // pack always emits `list`, a pack targeting an operational namespace must
+  // stay BLOCKED — this is the load-bearing proof that the per-verb flip did
+  // not silently open pragma's core operational namespaces to packs.
+  describe("operational nouns stay reserved wholesale", () => {
+    const reserved = deriveReservedVerbs(BUILTIN_PAIRS);
+
+    it("promotes every operational noun to a whole-noun reservation", () => {
+      for (const noun of ["config", "graph", "create", "graphql", "setup"]) {
+        expect(isReserved(reserved, noun, "list")).toBe(true);
+      }
+      // `tokens` (the plural add-config noun) owns only `add-config`.
+      expect(isReserved(reserved, "tokens", "list")).toBe(true);
+    });
+
+    it("throws a config error when a config story shadows an operational noun", () => {
+      const error = caught(() =>
+        collectPackStories(
+          { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "graph" }] },
+          [],
+          reserved,
+        ),
+      );
+      expect(error).toBeInstanceOf(PragmaError);
+      expect((error as PragmaError).code).toBe("CONFIG_ERROR");
+    });
+
+    it("skips a package story that shadows an operational noun", () => {
+      const entries = collectPackStories(
+        CONFIG,
+        [
+          makePackage([
+            {
+              path: "/pkg/stories/graph.json",
+              definition: { ...RECIPE_STORY, noun: "graph" },
+            },
+          ]),
+        ],
+        reserved,
+      );
+      expect(entries).toHaveLength(0);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining("shadows built-in command"),
+      );
+    });
+  });
+
+  // Keystone incremental window (FIX 3): `standard`'s `list` wrapper is
+  // deleted but `lookup` is still built-in (alongside categories/sample).
+  describe("incremental leaf cutover window", () => {
+    const reserved = deriveReservedVerbs([
+      ["standard", "lookup"],
+      ["standard", "categories"],
+      ["standard", "sample"],
+      ["info", undefined],
+    ]);
+
+    it("keeps `standard` per-verb because it still owns lookup (not promoted)", () => {
+      // Disjointness check: the noun retains a read verb, so it must NOT be
+      // wholesale-promoted — otherwise `list` could never be freed.
+      expect(isReserved(reserved, "standard", "list")).toBe(false);
+      expect(isReserved(reserved, "standard", "lookup")).toBe(true);
+    });
+
+    it("admits a standard pack that declares only list", () => {
+      const listOnly = { ...RECIPE_STORY, noun: "standard", lookup: undefined };
+      const entries = collectPackStories(
+        CONFIG,
+        [
+          makePackage([
+            { path: "/pkg/stories/standard.json", definition: listOnly },
+          ]),
+        ],
+        reserved,
+      );
+      expect(entries.map((entry) => entry.definition.noun)).toEqual([
+        "standard",
+      ]);
+    });
+
+    it("rejects a standard pack that also declares lookup (config throws)", () => {
+      const error = caught(() =>
+        collectPackStories(
+          { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "standard" }] },
+          [],
+          reserved,
+        ),
+      );
+      expect(error).toBeInstanceOf(PragmaError);
+      expect((error as PragmaError).code).toBe("CONFIG_ERROR");
+    });
+
+    it("rejects a standard pack that also declares lookup (package skips)", () => {
+      const entries = collectPackStories(
+        CONFIG,
+        [
+          makePackage([
+            {
+              path: "/pkg/stories/standard.json",
+              definition: { ...RECIPE_STORY, noun: "standard" },
+            },
+          ]),
+        ],
+        reserved,
+      );
+      expect(entries).toHaveLength(0);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining("shadows built-in command"),
+      );
+    });
+
+    it("rejects a list-only standard pack whose extra verb is still built-in", () => {
+      // Pack v1 emissions beyond list/lookup are guarded too: `categories`
+      // here collides with the still-registered built-in wrapper.
+      const withCategories = {
+        ...RECIPE_STORY,
+        noun: "standard",
+        lookup: undefined,
+        verbs: [
+          {
+            verb: "categories",
+            query: RECIPE_STORY.list.query,
+            columns: RECIPE_STORY.list.columns,
+          },
+        ],
+      };
+      const error = caught(() =>
+        collectPackStories(
+          { ...CONFIG, stories: [withCategories] },
+          [],
+          reserved,
+        ),
+      );
+      expect(error).toBeInstanceOf(PragmaError);
+      expect((error as PragmaError).message).toContain("standard categories");
+    });
+
+    it("rejects a pack whose sample capability is still built-in", () => {
+      const withSample = {
+        ...RECIPE_STORY,
+        noun: "standard",
+        lookup: {
+          // biome-ignore lint/style/noNonNullAssertion: fixture always declares lookup
+          ...RECIPE_STORY.lookup!,
+          sample: true as const,
+        },
+      };
+      const error = caught(() =>
+        collectPackStories({ ...CONFIG, stories: [withSample] }, [], reserved),
+      );
+      expect(error).toBeInstanceOf(PragmaError);
+      expect((error as PragmaError).message).toContain("standard sample");
+    });
+  });
+
+  // Bundled transitional packs use the REAL collect (not the isolating wrapper).
+  describe("bundled packs", () => {
+    it("includes bundled packs by default, lowest precedence", () => {
+      const entries = realCollectPackStories(
+        CONFIG,
+        [],
+        buildReservedVerbs([]),
+      );
+      const nouns = entries.map((entry) => entry.definition.noun);
+      // Every bundled pack is present, tagged with a `bundled:` source.
+      for (const pack of BUNDLED_PACKS) {
+        expect(nouns).toContain(pack.noun);
+        const entry = entries.find((e) => e.definition.noun === pack.noun);
+        expect(entry?.source).toBe(`bundled:${pack.noun}`);
+      }
+    });
+
+    it("lets a config story override a bundled noun (config wins)", () => {
+      const bundledNoun = BUNDLED_PACKS[0]?.noun ?? "tier";
+      const entries = realCollectPackStories(
+        { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: bundledNoun }] },
+        [],
+        buildReservedVerbs([]),
+      );
+      const entry = entries.find((e) => e.definition.noun === bundledNoun);
+      // The config-declared story wins; the bundled one yields silently.
+      expect(entry?.source).toBe("config");
+      expect(
+        entries.filter((e) => e.definition.noun === bundledNoun),
+      ).toHaveLength(1);
+    });
+
+    it("yields a bundled noun to a still-reserved built-in", () => {
+      // If a bundled noun is still a built-in (not yet cut over), the bundled
+      // pack must not shadow it.
+      const bundledNoun = BUNDLED_PACKS[0]?.noun ?? "tier";
+      const entries = realCollectPackStories(
+        CONFIG,
+        [],
+        buildReservedVerbs([[bundledNoun, undefined]]),
+      );
+      expect(entries.map((e) => e.definition.noun)).not.toContain(bundledNoun);
+    });
+  });
 });

package/src/domains/shared/stories/pack/collectPackStories.ts

@@ -1,6 +1,8 @@
 import type { PragmaConfig } from "#config";
 import { PragmaError } from "#error";
 import type { SemanticPackage } from "../../semanticPackage.js";
+import { BUNDLED_PACKS } from "./bundled/index.js";
+import { isReserved, type ReservedVerbs } from "./reservedVerbs.js";
 import type { StoryPackDefinition } from "./types.js";
 import validateStoryPackDefinition from "./validateStoryPackDefinition.js";
 
@@ -10,6 +12,31 @@ export interface PackStoryEntry {
   readonly source: string;
 }
 
+/**
+ * The verbs a pack definition compiles to — mirrors `compilePackStories`,
+ * which always emits `list`, adds any declared extra verbs, and adds
+ * `lookup`/`sample` only when declared. The reserved-verb guard sees the
+ * FULL emission so a pack cannot shadow any built-in verb.
+ */
+function emittedVerbs(definition: StoryPackDefinition): string[] {
+  return [
+    "list",
+    ...(definition.verbs ?? []).map((verb) => verb.verb),
+    ...(definition.lookup ? ["lookup"] : []),
+    ...(definition.lookup?.sample ? ["sample"] : []),
+  ];
+}
+
+/**
+ * Name the built-in `(noun, verb)` command(s) a pack collides with, for
+ * actionable diagnostics — e.g. `built-in command "standard lookup"`.
+ * Since the guard is per-verb, reporting the noun alone is misleading.
+ */
+function describeShadow(noun: string, verbs: readonly string[]): string {
+  const pairs = verbs.map((verb) => `"${noun} ${verb}"`).join(", ");
+  return `built-in command${verbs.length > 1 ? "s" : ""} ${pairs}`;
+}
+
 /**
  * Gather the story-pack definitions active for a runtime.
  *
@@ -18,28 +45,40 @@ export interface PackStoryEntry {
  * config is the user's override layer. Package story files are validated
  * here; an invalid or colliding package story is skipped with a warning
  * so one bad file cannot break boot. A config story colliding with a
- * reserved (built-in) noun is a hard config error.
+ * reserved (built-in) noun is a hard config error. Bundled transitional
+ * packs come last (lowest precedence), so config or a package can override
+ * a bundled noun.
  *
  * @param config - The effective merged configuration.
  * @param packages - Resolved semantic packages (may ship `stories/*.json`).
- * @param reservedNouns - Built-in nouns story packs must not shadow.
+ * @param reserved - Built-in `(noun, verb)` reservations packs must not
+ *   shadow; a pack collides only when it emits a reserved verb.
+ * @param bundled - Transitional packs pragma ships by default (lowest
+ *   precedence). Defaults to {@link BUNDLED_PACKS}; tests pass `[]` to isolate.
  * @returns Validated, collision-free story entries.
  * @throws PragmaError with code `CONFIG_ERROR` when a config story shadows
- *   a reserved noun.
+ *   a reserved built-in verb.
  * @note Impure — warns on stderr for skipped package stories.
  */
 export default function collectPackStories(
   config: PragmaConfig,
   packages: readonly SemanticPackage[],
-  reservedNouns: ReadonlySet<string>,
+  reserved: ReservedVerbs,
+  bundled: readonly StoryPackDefinition[] = BUNDLED_PACKS,
 ): PackStoryEntry[] {
   const entries: PackStoryEntry[] = [];
   const taken = new Set<string>();
 
   for (const definition of config.stories ?? []) {
-    if (reservedNouns.has(definition.noun)) {
+    const shadowed = emittedVerbs(definition).filter((verb) =>
+      isReserved(reserved, definition.noun, verb),
+    );
+    if (shadowed.length > 0) {
       throw PragmaError.configError(
-        `Story noun "${definition.noun}" shadows a built-in command.`,
+        `Story noun "${definition.noun}" shadows ${describeShadow(
+          definition.noun,
+          shadowed,
+        )}.`,
       );
     }
     if (taken.has(definition.noun)) {
@@ -61,9 +100,21 @@ export default function collectPackStories(
         process.stderr.write(`Warning: skipping story — ${reason}\n`);
         continue;
       }
-      if (reservedNouns.has(definition.noun) || taken.has(definition.noun)) {
+      const shadowed = emittedVerbs(definition).filter((verb) =>
+        isReserved(reserved, definition.noun, verb),
+      );
+      if (shadowed.length > 0) {
+        process.stderr.write(
+          `Warning: skipping story "${definition.noun}" from ${file.path} — it shadows ${describeShadow(
+            definition.noun,
+            shadowed,
+          )}.\n`,
+        );
+        continue;
+      }
+      if (taken.has(definition.noun)) {
         process.stderr.write(
-          `Warning: skipping story "${definition.noun}" from ${file.path} — the noun is already taken.\n`,
+          `Warning: skipping story "${definition.noun}" from ${file.path} — the noun is already provided by a higher-precedence source.\n`,
         );
         continue;
       }
@@ -72,5 +123,36 @@ export default function collectPackStories(
     }
   }
 
+  // Bundled transitional packs — lowest precedence, so a config- or
+  // package-declared story for the same noun overrides them (the P4 handoff).
+  // Authored in-repo but still validated: only a validation failure (an
+  // authoring slip) is skipped with a warning (consistent with package
+  // stories — one bad pack cannot break boot), and the pack's own parity tests
+  // catch a bundled pack that fails to load. When a still-reserved built-in or
+  // a higher-precedence source already owns the noun, the bundled pack yields
+  // silently (no warning) — the shadow/duplicate check below, matching the
+  // precedence order rather than flagging an error.
+  for (const raw of bundled) {
+    const source = `bundled:${raw.noun}`;
+    let definition: StoryPackDefinition;
+    try {
+      definition = validateStoryPackDefinition(raw, source);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`Warning: skipping bundled story — ${reason}\n`);
+      continue;
+    }
+    const shadowed = emittedVerbs(definition).filter((verb) =>
+      isReserved(reserved, definition.noun, verb),
+    );
+    if (shadowed.length > 0 || taken.has(definition.noun)) {
+      // A still-registered built-in (not yet cut over) or a higher-precedence
+      // source already owns this noun — the bundled pack yields to it silently.
+      continue;
+    }
+    taken.add(definition.noun);
+    entries.push({ definition, source });
+  }
+
   return entries;
 }

package/src/domains/shared/stories/pack/compilePackCommands.ts

@@ -1,29 +1,31 @@
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../context.js";
-import { PREFIX_MAP } from "../../prefixes.js";
+import { resolvePrefixes } from "../../prefixes.js";
 import compileLookupCommand from "../compileLookupCommand.js";
 import compileReadCommand from "../compileReadCommand.js";
 import collectPackStories from "./collectPackStories.js";
 import compilePackStories from "./compilePackStories.js";
+import type { ReservedVerbs } from "./reservedVerbs.js";
 
 /**
  * Compile every active story pack into CLI command definitions.
  *
  * Story packs come from the merged config (`stories`) and from resolved
  * semantic packages (`stories/*.json`); each yields `<noun> list` and,
- * when declared, `<noun> lookup` — projected through the same kernel as
- * the built-in read stories, so completions and help come for free.
+ * when declared, `<noun> lookup`, extra list verbs, and `<noun> sample` —
+ * projected through the same kernel as the built-in read stories, so
+ * completions and help come for free.
  *
  * @param ctx - Pragma context carrying config, packages, and the store.
- * @param reservedNouns - Built-in nouns packs must not shadow.
+ * @param reserved - Built-in `(noun, verb)` reservations packs must not shadow.
  * @returns Command definitions for every pack story.
  */
 export default function compilePackCommands(
   ctx: PragmaContext,
-  reservedNouns: ReadonlySet<string>,
+  reserved: ReservedVerbs,
 ): CommandDefinition[] {
-  const prefixes = { ...PREFIX_MAP, ...ctx.config.prefixes };
-  const entries = collectPackStories(ctx.config, ctx.packages, reservedNouns);
+  const prefixes = resolvePrefixes(ctx.packages ?? [], ctx.config.prefixes);
+  const entries = collectPackStories(ctx.config, ctx.packages ?? [], reserved);
 
   return entries.flatMap((entry) => {
     const compiled = compilePackStories(
@@ -31,10 +33,18 @@ export default function compilePackCommands(
       entry.source,
       prefixes,
     );
+    // Surface order mirrors the built-in leaf domains: list, lookup,
+    // extra verbs, sample.
     const commands = [compileReadCommand(ctx, compiled.list)];
     if (compiled.lookup) {
       commands.push(compileLookupCommand(ctx, compiled.lookup));
     }
+    for (const verb of compiled.verbs) {
+      commands.push(compileReadCommand(ctx, verb));
+    }
+    if (compiled.sample) {
+      commands.push(compileReadCommand(ctx, compiled.sample));
+    }
     return commands;
   });
 }