@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/shared/stories/pack/bundled/standardPack.ts

@@ -0,0 +1,164 @@
+/**
+ * Bundled transitional `standard` pack.
+ *
+ * Replaces the hand-written `standard` domain (~1,300 LOC of command/
+ * operation/formatter/orchestration/MCP wiring) with a declarative pack
+ * definition. `standard list|lookup|categories|sample` and the
+ * `standard_list|_lookup|_categories|_sample` MCP tools compile from this
+ * definition through the same kernel as every other pack, so the CLI core
+ * stops carrying standard-specific TypeScript.
+ *
+ * @remarks transitional — this ships inside pragma today; in P4 it moves
+ * into the `@canonical/code-standards` package as `stories/standard.json`
+ * alongside that package's prefix declaration, at which point the core
+ * carries no standard at all.
+ *
+ * Scope notes (semantic parity, not byte parity — see standardParity.test):
+ * - Rows/entities are the uniform pack shapes: the list SELECT binds the
+ *   standard IRI to `uri` and renames `categoryName` → `category`, so JSON
+ *   carries the same keys as the old summary items.
+ * - The old domain's `--digest`/`--detailed` LIST enrichment is not
+ *   reproduced (pack lists have a single level); the same data is reachable
+ *   through `standard lookup --detail …` and `standard sample`.
+ * - Lookup disclosure keeps three levels. The old digest's bespoke
+ *   "first do-example truncated to 120 chars" rendering is not expressible
+ *   generically; here `digest` gates the full `dos` expand (richer than the
+ *   old digest) and `detailed` adds `donts`.
+ * - `extends` stays the raw IRI in JSON (renderers compact it at display
+ *   time); the old domain compacted it in resolved data.
+ */
+
+import type { StoryPackDefinition } from "../types.js";
+
+/**
+ * The `standard` read stories as data.
+ *
+ * The list SELECT mirrors the query the old `listStandards` operation sent
+ * the store — `cs:name` and the category path stay OPTIONAL so a standard
+ * without a display name or category still appears — while `ORDER BY ?name`
+ * sorts by the human-facing name. The BIND reproduces the old
+ * `deriveStandardName` fallback declaratively: a standard without `cs:name`
+ * displays its IRI fragment with dots rendered as slashes
+ * (`…#react.component.props` → `react/component/props`). Category filtering
+ * is value-free (the category set lives in the graph) and search covers
+ * name + description; both are post-query row predicates, so user input
+ * never touches this query text.
+ */
+export const standardPack: StoryPackDefinition = {
+  noun: "standard",
+  description: "List all code standards",
+  toolDescription:
+    "List code standards. Optionally filter by category or search term.",
+  list: {
+    query: [
+      "SELECT ?uri ?name ?category ?description",
+      "WHERE {",
+      "  ?uri a cs:CodeStandard ;",
+      "       cs:description ?description .",
+      "  OPTIONAL { ?uri cs:name ?n . }",
+      '  BIND(COALESCE(?n, REPLACE(STRAFTER(STR(?uri), "#"), "\\\\.", "/")) AS ?name)',
+      "  OPTIONAL {",
+      "    ?uri cs:hasCategory ?cat .",
+      "    ?cat cs:slug ?category .",
+      "  }",
+      "}",
+      "ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+      { field: "category", label: "Category" },
+      { field: "description", label: "Description" },
+    ],
+    filters: [
+      {
+        param: "category",
+        variable: "category",
+        description: "Filter by category name",
+      },
+    ],
+    search: {
+      variables: ["name", "description"],
+      description: "Search in name and description",
+    },
+  },
+  verbs: [
+    {
+      verb: "categories",
+      description: "List all standard categories with counts",
+      toolDescription: "List all code standard categories.",
+      // OPTIONAL keeps zero-count categories in the result (a category with
+      // no standards still lists, with count 0), mirroring the old
+      // listCategories operation.
+      query: [
+        "SELECT ?name (COUNT(?standard) AS ?count)",
+        "WHERE {",
+        "  ?cat a cs:Category ;",
+        "       cs:slug ?name .",
+        "  OPTIONAL {",
+        "    ?standard a cs:CodeStandard ;",
+        "              cs:hasCategory ?cat .",
+        "  }",
+        "}",
+        "GROUP BY ?name",
+        "ORDER BY ?name",
+      ].join("\n"),
+      columns: [
+        { field: "name", label: "Category" },
+        { field: "count", label: "Standards" },
+      ],
+    },
+  ],
+  lookup: {
+    by: "cs:name",
+    type: "cs:CodeStandard",
+    description:
+      "Look up detailed information for a standard by name, IRI, or glob",
+    toolDescription:
+      "Get detailed information about one or more code standards including dos and donts with code examples. Address standards by name, prefixed name (cs:…), absolute IRI, or glob pattern (react/component/*).",
+    fields: [
+      {
+        name: "category",
+        property: "cs:hasCategory/cs:slug",
+        label: "Category",
+      },
+      {
+        name: "description",
+        property: "cs:description",
+        label: "Description",
+      },
+      { name: "extends", property: "cs:extends", label: "Extends" },
+    ],
+    expand: [
+      {
+        name: "dos",
+        heading: "Do",
+        relation: "cs:do",
+        select: [
+          { name: "caption", property: "cs:description" },
+          { name: "language", property: "cs:language" },
+          { name: "code", property: "cs:code" },
+        ],
+        level: "digest",
+      },
+      {
+        name: "donts",
+        heading: "Don't",
+        relation: "cs:dont",
+        select: [
+          { name: "caption", property: "cs:description" },
+          { name: "language", property: "cs:language" },
+          { name: "code", property: "cs:code" },
+        ],
+        level: "detailed",
+      },
+    ],
+    disclosure: { levels: ["summary", "digest", "detailed"] },
+    sample: {
+      description:
+        "Return randomly selected complete standard instances as exemplars for shape discovery",
+      toolDescription:
+        "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
+    },
+  },
+};

package/src/domains/shared/stories/pack/bundled/tierPack.ts

@@ -0,0 +1,50 @@
+/**
+ * Bundled transitional `tier` pack.
+ *
+ * Replaces the hand-written `tier` domain (~179 LOC of command/operation/
+ * formatter/MCP wiring) with a declarative list story. `tier list` and the
+ * `tier_list` MCP tool are compiled from this definition through the same
+ * kernel as every other pack, so the CLI core stops carrying tier-specific
+ * TypeScript.
+ *
+ * @remarks transitional — this ships inside pragma today; in P4 it moves into
+ * the `@canonical/design-system` package as `stories/tier.json` alongside that
+ * package's prefix declaration, at which point the core carries no tier at all.
+ *
+ * Scope note: the old domain's `TierEntry.depth`/`parent` fields were always
+ * `0`/absent — tier hierarchy is encoded in the slash-separated *path string*
+ * (`apps/lxd`), not in graph edges, and the ordered-inheritance logic lives in
+ * `buildTierFilter`/`resolveTierChain` (a filter primitive other domains use).
+ * `tier list` is therefore a flat, name-ordered list, which this pack
+ * reproduces faithfully; there is no graph tree to project.
+ */
+
+import type { StoryPackDefinition } from "../types.js";
+
+/**
+ * The `tier` list story as data.
+ *
+ * The SELECT binds the tier IRI to `uri` and its `ds:name` to `name` (the
+ * honest mapping of the `ds:name` property), so `--format json` is the uniform
+ * `{uri, name}` pack shape and the generic renderer emits `- ` + "`ds:apps`" +
+ * ` — **Apps**` in llm mode. The store injects PREFIX declarations, so `ds:`
+ * resolves against the merged prefix map. The old domain's always-zero
+ * `depth` field is intentionally dropped.
+ */
+export const tierPack: StoryPackDefinition = {
+  noun: "tier",
+  description: "List all tiers in the design system ontology",
+  toolDescription: "List all tiers in the design-system ontology.",
+  list: {
+    query: [
+      "SELECT ?uri ?name WHERE {",
+      "  ?uri a ds:Tier ;",
+      "       ds:name ?name .",
+      "} ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+    ],
+  },
+};

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

@@ -0,0 +1,406 @@
+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 { 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 {
+    name: "@canonical/example",
+    version: "1.0.0",
+    source: "local",
+    graphs: [],
+    skills: [],
+    stories,
+  };
+}
+
+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>;
+
+  beforeEach(() => {
+    warn = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it("collects config stories and validated package stories", () => {
+    const entries = collectPackStories(
+      { ...CONFIG, stories: [RECIPE_STORY] },
+      [
+        makePackage([
+          {
+            path: "/pkg/stories/other.json",
+            definition: { ...RECIPE_STORY, noun: "other" },
+          },
+        ]),
+      ],
+      buildReservedVerbs([["block", undefined]]),
+    );
+    expect(entries.map((entry) => entry.definition.noun)).toEqual([
+      "recipe",
+      "other",
+    ]);
+    expect(entries.at(0)?.source).toBe("config");
+    expect(entries.at(1)?.source).toBe("/pkg/stories/other.json");
+  });
+
+  it("lets config stories win noun collisions against packages", () => {
+    const entries = collectPackStories(
+      { ...CONFIG, stories: [RECIPE_STORY] },
+      [
+        makePackage([
+          { path: "/pkg/stories/recipe.json", definition: RECIPE_STORY },
+        ]),
+      ],
+      buildReservedVerbs([]),
+    );
+    expect(entries).toHaveLength(1);
+    expect(entries.at(0)?.source).toBe("config");
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("already provided"),
+    );
+  });
+
+  it("skips invalid package stories with a warning", () => {
+    const entries = collectPackStories(
+      CONFIG,
+      [
+        makePackage([
+          { path: "/pkg/stories/broken.json", definition: { nope: true } },
+        ]),
+      ],
+      buildReservedVerbs([]),
+    );
+    expect(entries).toHaveLength(0);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("skipping story"),
+    );
+  });
+
+  it("throws when a config story shadows a built-in noun", () => {
+    expect(() =>
+      collectPackStories(
+        { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "block" }] },
+        [],
+        buildReservedVerbs([["block", undefined]]),
+      ),
+    ).toThrow(PragmaError);
+  });
+
+  it("skips package stories that shadow built-in nouns", () => {
+    const entries = collectPackStories(
+      CONFIG,
+      [
+        makePackage([
+          {
+            path: "/pkg/stories/block.json",
+            definition: { ...RECIPE_STORY, noun: "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);
+    });
+  });
+});