@canonical/pragma-cli 0.30.0 → 0.31.0

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

@@ -9,12 +9,16 @@ import type { StoryPackFilter } from "./types.js";
  * query's ordering is preserved.
  *
  * Matching semantics:
- * - Input is trimmed, unicode-normalized (NFC), and matched against the
- *   declared values case-insensitively; the DECLARED value is canonical
- *   and is what rows are compared against.
- * - Row comparison is exact on the canonical value (NFC on both sides).
- *   ke bindings carry lexical forms — language tags and datatypes are
- *   already stripped — so plain equality is sound.
+ * - With declared `values`: input is trimmed, unicode-normalized (NFC),
+ *   and matched against the declared values case-insensitively; the
+ *   DECLARED value is canonical and rows are compared against it exactly
+ *   (NFC on both sides).
+ * - Without `values` (value-free filter): the input itself is the term —
+ *   trimmed, NFC-normalized — and rows match on case-insensitive equality
+ *   with the variable's value. Nothing is rejected up front because the
+ *   valid set lives in the data.
+ * - ke bindings carry lexical forms — language tags and datatypes are
+ *   already stripped — so plain string comparison is sound.
  * - A row without a binding for the variable (e.g. from OPTIONAL) never
  *   matches an active filter.
  * - Several provided filters combine conjunctively.
@@ -25,7 +29,8 @@ import type { StoryPackFilter } from "./types.js";
  * @returns Rows matching every provided filter.
  * @throws PragmaError with code `INVALID_INPUT` (carrying the declared
  *         values as valid options) when a provided value is not in the
- *         filter's declared set.
+ *         filter's declared set, or when a value-free filter receives a
+ *         non-string value.
  */
 export default function applyPackFilters(
   rows: Record<string, string>[],
@@ -39,7 +44,16 @@ export default function applyPackFilters(
   for (const filter of filters ?? []) {
     const provided = params[filter.param];
     if (provided === undefined) continue;
-    const canonical = canonicalizeFilterValue(provided, filter);
+    const values = filter.values;
+    if (values === undefined) {
+      // Value-free filter: case-insensitive equality against the variable.
+      const term = requireStringValue(provided, filter).toLowerCase();
+      result = result.filter(
+        (row) => row[filter.variable]?.normalize("NFC").toLowerCase() === term,
+      );
+      continue;
+    }
+    const canonical = canonicalizeFilterValue(provided, filter, values);
     result = result.filter(
       (row) => row[filter.variable]?.normalize("NFC") === canonical,
     );
@@ -47,6 +61,26 @@ export default function applyPackFilters(
   return result;
 }
 
+/**
+ * Require a value-free filter's input to be a trimmed, NFC-normalized
+ * string.
+ *
+ * @throws PragmaError with code `INVALID_INPUT` when it is not a string.
+ */
+function requireStringValue(
+  provided: unknown,
+  filter: StoryPackFilter,
+): string {
+  if (typeof provided !== "string") {
+    throw PragmaError.invalidInput(filter.param, String(provided), {
+      recovery: {
+        message: `Provide a string value for --${filter.param}.`,
+      },
+    });
+  }
+  return provided.trim().normalize("NFC");
+}
+
 /**
  * Resolve a provided filter value to its declared canonical form.
  *
@@ -56,10 +90,11 @@ export default function applyPackFilters(
 function canonicalizeFilterValue(
   provided: unknown,
   filter: StoryPackFilter,
+  values: readonly string[],
 ): string {
   if (typeof provided === "string") {
     const normalized = provided.trim().normalize("NFC");
-    const match = filter.values.find(
+    const match = values.find(
       (value) =>
         value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
     );
@@ -68,9 +103,9 @@ function canonicalizeFilterValue(
     }
   }
   throw PragmaError.invalidInput(filter.param, String(provided), {
-    validOptions: [...filter.values],
+    validOptions: [...values],
     recovery: {
-      message: `Allowed values for --${filter.param}: ${filter.values.join(", ")}.`,
+      message: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
     },
   });
 }

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

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import applyPackSearch from "./applyPackSearch.js";
+import type { StoryPackSearch } from "./types.js";
+
+const ROWS = [
+  { name: "Gazpacho", description: "A cold soup" },
+  { name: "Pancakes", description: "Fried batter" },
+  { name: "Mystery" },
+];
+const SEARCH: StoryPackSearch = { variables: ["name", "description"] };
+
+describe("applyPackSearch", () => {
+  it("returns rows unchanged when no search is declared", () => {
+    expect(applyPackSearch(ROWS, undefined, { search: "soup" })).toEqual(ROWS);
+  });
+
+  it("returns rows unchanged when no term is provided", () => {
+    expect(applyPackSearch(ROWS, SEARCH, {})).toEqual(ROWS);
+  });
+
+  it("returns rows unchanged for an empty or whitespace term", () => {
+    expect(applyPackSearch(ROWS, SEARCH, { search: "   " })).toEqual(ROWS);
+  });
+
+  it("keeps rows where any searched variable contains the term", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "soup" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("matches case-insensitively", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "PANCAKE" });
+    expect(rows.map((row) => row.name)).toEqual(["Pancakes"]);
+  });
+
+  it("matches substrings mid-value", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "batter" });
+    expect(rows.map((row) => row.name)).toEqual(["Pancakes"]);
+  });
+
+  it("never matches rows without a binding for a searched variable", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "myst" });
+    expect(rows.map((row) => row.name)).toEqual(["Mystery"]);
+    expect(applyPackSearch(ROWS, SEARCH, { search: "absent" })).toEqual([]);
+  });
+
+  it("matches unicode terms across NFC/NFD normalization forms", () => {
+    const rows = [{ name: "Entr\u00e9e" }];
+    const search: StoryPackSearch = { variables: ["name"] };
+    expect(
+      applyPackSearch(rows, search, { search: "entre\u0301e" }),
+    ).toHaveLength(1);
+  });
+
+  it("ignores non-string search values", () => {
+    expect(applyPackSearch(ROWS, SEARCH, { search: 3 })).toEqual(ROWS);
+  });
+});

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

@@ -0,0 +1,41 @@
+import type { StoryPackSearch } from "./types.js";
+
+/**
+ * Apply a pack list's free-text search to resolved rows.
+ *
+ * Search is a row predicate on projected SELECT variables — like filters,
+ * it runs AFTER the author query, so user input never touches the query
+ * text (injection-safe by construction) and the author's ORDER BY is
+ * preserved.
+ *
+ * Matching semantics:
+ * - The term is NFC-normalized and matched case-insensitively.
+ * - A row passes when ANY declared variable's value contains the term as
+ *   a substring; unbound variables (e.g. from OPTIONAL) never match.
+ * - A non-string or empty term is a no-op — search is a refinement, not a
+ *   validated enum, so there is nothing to reject against.
+ *
+ * @param rows - Rows produced by the pack's list query (post-filter).
+ * @param search - The declared search (absent means no searching).
+ * @param params - Story parameters as provided by the surface.
+ * @returns Rows containing the term in at least one searched variable.
+ */
+export default function applyPackSearch(
+  rows: Record<string, string>[],
+  search: StoryPackSearch | undefined,
+  params: Record<string, unknown>,
+): Record<string, string>[] {
+  const provided = params.search;
+  if (search === undefined || typeof provided !== "string") {
+    return rows;
+  }
+  const term = provided.trim().normalize("NFC").toLowerCase();
+  if (term === "") {
+    return rows;
+  }
+  return rows.filter((row) =>
+    search.variables.some((variable) =>
+      row[variable]?.normalize("NFC").toLowerCase().includes(term),
+    ),
+  );
+}

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import buildLookupQuery, {
+  buildLookupByIriQuery,
   buildLookupNamesQuery,
   escapeSparqlString,
   formatTerm,
@@ -41,6 +42,35 @@ describe("buildLookupQuery", () => {
   });
 });
 
+describe("buildLookupByIriQuery", () => {
+  it("binds the resolved IRI instead of filtering on the name", () => {
+    const query = buildLookupByIriQuery(
+      {
+        by: "ex:name",
+        type: "ex:Recipe",
+        fields: [{ name: "category", property: "ex:category" }],
+      },
+      "http://example.org/recipes/pancakes",
+    );
+    expect(query).toContain(
+      "BIND(<http://example.org/recipes/pancakes> AS ?uri)",
+    );
+    expect(query).toContain("?uri ex:name ?name .");
+    expect(query).toContain("?uri a ex:Recipe .");
+    expect(query).toContain("OPTIONAL { ?uri ex:category ?category . }");
+    expect(query).not.toContain("FILTER");
+    expect(query).toContain("LIMIT 1");
+  });
+
+  it("omits the type constraint when absent", () => {
+    const query = buildLookupByIriQuery(
+      { by: "ex:name" },
+      "http://example.org/x",
+    );
+    expect(query).not.toContain("?uri a ");
+  });
+});
+
 describe("buildLookupNamesQuery", () => {
   it("selects all names for the by property", () => {
     const query = buildLookupNamesQuery({ by: "ex:name", type: "ex:Recipe" });

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

@@ -1,4 +1,4 @@
-import type { StoryPackLookup } from "./types.js";
+import type { StoryPackExpand, StoryPackLookup } from "./types.js";
 
 /**
  * Build the generated, injection-safe lookup queries for a pack story.
@@ -59,6 +59,80 @@ export default function buildLookupQuery(
     .join("\n");
 }
 
+/**
+ * Build the SELECT retrieving one entity addressed directly by IRI.
+ *
+ * Mirrors {@link buildLookupQuery} but binds the already-resolved IRI to
+ * `?uri` instead of filtering on the `by` property's value, so absolute
+ * IRIs and prefixed names address an entity exactly. Injection-safe by
+ * construction: the caller resolves and validates `iri` against the
+ * embeddable-IRI shape (no whitespace or `<>"` characters) BEFORE it is
+ * interpolated here — raw user input never reaches this function.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param iri - A resolved, validated absolute IRI.
+ * @returns SPARQL SELECT text.
+ */
+export function buildLookupByIriQuery(
+  lookup: StoryPackLookup,
+  iri: string,
+): string {
+  const fields = [...(lookup.fields ?? []), ...(lookup.sections ?? [])];
+  const vars = fields.map((field) => `?${field.name}`).join(" ");
+  const optionals = fields
+    .map(
+      (field) =>
+        `  OPTIONAL { ?uri ${formatTerm(field.property)} ?${field.name} . }`,
+    )
+    .join("\n");
+  const typeConstraint = lookup.type
+    ? `  ?uri a ${formatTerm(lookup.type)} .\n`
+    : "";
+
+  return [
+    `SELECT ?uri ?name${vars.length > 0 ? ` ${vars}` : ""} WHERE {`,
+    `  BIND(<${iri}> AS ?uri)`,
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    typeConstraint + optionals,
+    "}",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the sub-SELECT retrieving one expand's child rows for a resolved
+ * entity.
+ *
+ * Injection-safe by construction: the only interpolated value is
+ * `entityUri`, which is the IRI the base lookup already resolved from the
+ * store (never user input), and the relation/properties are validated pack
+ * terms. Returns one row per child node, each carrying the declared fields.
+ *
+ * @param expand - The expand declaration.
+ * @param entityUri - The resolved entity IRI (from the base lookup's `?uri`).
+ * @returns SPARQL SELECT text yielding one row per child node.
+ */
+export function buildExpandQuery(
+  expand: StoryPackExpand,
+  entityUri: string,
+): string {
+  const vars = expand.select.map((field) => `?${field.name}`).join(" ");
+  const optionals = expand.select
+    .map(
+      (field) =>
+        `  OPTIONAL { ?child ${formatTerm(field.property)} ?${field.name} . }`,
+    )
+    .join("\n");
+  return [
+    `SELECT ${vars} WHERE {`,
+    `  <${entityUri}> ${formatTerm(expand.relation)} ?child .`,
+    optionals,
+    "}",
+  ].join("\n");
+}
+
 /**
  * Build the SELECT listing all entity names — lookup-miss suggestions.
  *

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

@@ -0,0 +1,23 @@
+/**
+ * Bundled transitional story packs.
+ *
+ * These are declarative replacements for design-system domains that used to be
+ * hand-written TypeScript in the CLI core. They ship inside pragma during the
+ * strangler migration (ADR C.07) and are the **lowest-precedence** pack
+ * source: a `pragma.config.json` `stories` entry or a semantic package's
+ * `stories/*.json` for the same noun overrides the bundled one, so a package
+ * can take ownership of its noun (the P4 end state) without a code change here.
+ *
+ * As each leaf domain is cut over, its built-in command is deleted (freeing the
+ * noun from the reserved set) and its pack is added to this list.
+ */
+
+import type { StoryPackDefinition } from "../types.js";
+import { standardPack } from "./standardPack.js";
+import { tierPack } from "./tierPack.js";
+
+/** Every pack pragma ships by default, lowest precedence. */
+export const BUNDLED_PACKS: readonly StoryPackDefinition[] = [
+  tierPack,
+  standardPack,
+];

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" },
+    ],
+  },
+};