@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,55 @@
+import { resolvePrefixes } from "../../prefixes.js";
+import type { ToolSpec } from "../../ToolSpec.js";
+import type { PragmaRuntime } from "../../types/index.js";
+import compileLookupTool from "../compileLookupTool.js";
+import compileReadTool from "../compileReadTool.js";
+import collectPackStories from "./collectPackStories.js";
+import compilePackStories from "./compilePackStories.js";
+import type { ReservedVerbs } from "./reservedVerbs.js";
+
+/**
+ * Compile every active story pack into MCP tool specs.
+ *
+ * Mirrors `compilePackCommands` on the MCP surface: each pack yields
+ * `<noun>_list` and, when declared, `<noun>_lookup`, extra `<noun>_<verb>`
+ * tools, and `<noun>_sample`, registered alongside the built-in tools.
+ *
+ * @param runtime - Pragma runtime carrying config, packages, and the store.
+ * @param reserved - Built-in `(noun, verb)` reservations packs must not shadow.
+ * @returns Tool specs for every pack story.
+ */
+export default function compilePackToolSpecs(
+  runtime: PragmaRuntime,
+  reserved: ReservedVerbs,
+): ToolSpec[] {
+  const prefixes = resolvePrefixes(
+    runtime.packages ?? [],
+    runtime.config.prefixes,
+  );
+  const entries = collectPackStories(
+    runtime.config,
+    runtime.packages ?? [],
+    reserved,
+  );
+
+  return entries.flatMap((entry) => {
+    const compiled = compilePackStories(
+      entry.definition,
+      entry.source,
+      prefixes,
+    );
+    // Registration order mirrors compilePackCommands: list, lookup,
+    // extra verbs, sample.
+    const specs = [compileReadTool(compiled.list)];
+    if (compiled.lookup) {
+      specs.push(compileLookupTool(compiled.lookup));
+    }
+    for (const verb of compiled.verbs) {
+      specs.push(compileReadTool(verb));
+    }
+    if (compiled.sample) {
+      specs.push(compileReadTool(compiled.sample));
+    }
+    return specs;
+  });
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Story packs — declarative read stories compiled through the kernel.
+ * @module
+ */
+
+export {
+  buildLookupNamesQuery,
+  default as buildLookupQuery,
+  escapeSparqlString,
+  formatTerm,
+} from "./buildLookupQuery.js";
+export type { PackStoryEntry } from "./collectPackStories.js";
+export { default as collectPackStories } from "./collectPackStories.js";
+export { default as compilePackCommands } from "./compilePackCommands.js";
+export type { CompiledPackStories } from "./compilePackStories.js";
+export { default as compilePackStories } from "./compilePackStories.js";
+export { default as compilePackToolSpecs } from "./compilePackToolSpecs.js";
+export type { ReservedVerbs } from "./reservedVerbs.js";
+export {
+  buildReservedVerbs,
+  deriveReservedVerbs,
+  isReserved,
+  nounVerbFromPath,
+  nounVerbFromToolName,
+} from "./reservedVerbs.js";
+export { default as runSelectQuery } from "./runSelectQuery.js";
+export type {
+  StoryPackColumn,
+  StoryPackDefinition,
+  StoryPackDisclosure,
+  StoryPackExpand,
+  StoryPackField,
+  StoryPackFilter,
+  StoryPackList,
+  StoryPackLookup,
+  StoryPackSample,
+  StoryPackSearch,
+  StoryPackSection,
+  StoryPackSource,
+  StoryPackVerb,
+} from "./types.js";
+export { default as validateStoryPackDefinition } from "./validateStoryPackDefinition.js";

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

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildReservedVerbs,
+  deriveReservedVerbs,
+  isReserved,
+  nounVerbFromPath,
+  nounVerbFromToolName,
+} from "./reservedVerbs.js";
+
+describe("nounVerbFromPath", () => {
+  it("splits a [noun, verb] path", () => {
+    expect(nounVerbFromPath(["standard", "list"])).toEqual([
+      "standard",
+      "list",
+    ]);
+  });
+
+  it("treats a single-segment path as a whole-noun reservation", () => {
+    expect(nounVerbFromPath(["info"])).toEqual(["info", undefined]);
+  });
+
+  it("preserves the hyphenated multi-word built-in verb", () => {
+    expect(nounVerbFromPath(["tokens", "add-config"])).toEqual([
+      "tokens",
+      "add-config",
+    ]);
+  });
+});
+
+describe("nounVerbFromToolName", () => {
+  it("splits a single-underscore tool name", () => {
+    expect(nounVerbFromToolName("standard_list")).toEqual(["standard", "list"]);
+  });
+
+  it("keeps every segment after the first for multi-underscore names", () => {
+    expect(nounVerbFromToolName("tokens_add_config")).toEqual([
+      "tokens",
+      "add_config",
+    ]);
+  });
+
+  it("treats a single-token name as a whole-noun reservation", () => {
+    expect(nounVerbFromToolName("info")).toEqual(["info", undefined]);
+  });
+});
+
+describe("buildReservedVerbs", () => {
+  // Mirrors the real built-in CLI command paths (pinned by
+  // collectCommands.test.ts's golden snapshot).
+  const CLI_PATHS: readonly (readonly string[])[] = [
+    ["standard", "list"],
+    ["standard", "lookup"],
+    ["standard", "categories"],
+    ["standard", "sample"],
+    ["token", "list"],
+    ["token", "lookup"],
+    ["token", "sample"],
+    ["tokens", "add-config"],
+    ["config", "show"],
+    ["config", "tier"],
+    ["config", "channel"],
+    ["info"],
+    ["llm"],
+    ["doctor"],
+    ["capabilities"],
+  ];
+
+  // Mirrors the real built-in MCP tool names (pinned by registerTools.test.ts).
+  const MCP_NAMES: readonly string[] = [
+    "standard_list",
+    "standard_lookup",
+    "standard_categories",
+    "standard_sample",
+    "token_list",
+    "token_lookup",
+    "token_sample",
+    "tokens_add_config",
+    "info",
+    "llm",
+  ];
+
+  it("assembles verb sets per noun from real CLI command paths", () => {
+    const reserved = buildReservedVerbs(
+      CLI_PATHS.map((path) => nounVerbFromPath(path)),
+    );
+
+    expect(reserved.get("standard")).toEqual(
+      new Set(["list", "lookup", "categories", "sample"]),
+    );
+    expect(reserved.get("token")).toEqual(
+      new Set(["list", "lookup", "sample"]),
+    );
+    expect(reserved.get("tokens")).toEqual(new Set(["add-config"]));
+    expect(reserved.get("info")).toEqual(new Set(["*"]));
+  });
+
+  it("assembles verb sets per noun from real MCP tool names", () => {
+    const reserved = buildReservedVerbs(
+      MCP_NAMES.map((name) => nounVerbFromToolName(name)),
+    );
+
+    expect(reserved.get("standard")).toEqual(
+      new Set(["list", "lookup", "categories", "sample"]),
+    );
+    // The token/tokens split plus underscore verb is harmless surface skew.
+    expect(reserved.get("tokens")).toEqual(new Set(["add_config"]));
+    expect(reserved.get("info")).toEqual(new Set(["*"]));
+  });
+
+  it("keeps both entries when a noun has a concrete verb and a bare form", () => {
+    const reserved = buildReservedVerbs([
+      ["config", "show"],
+      ["config", undefined],
+    ]);
+
+    expect(reserved.get("config")).toEqual(new Set(["show", "*"]));
+  });
+});
+
+describe("isReserved", () => {
+  // Raw grouping (buildReservedVerbs, no promotion): a partially reserved
+  // noun like `config` keeps only its concrete verbs. The policy-applied
+  // promotion of operational nouns is exercised under `deriveReservedVerbs`.
+  const reserved = buildReservedVerbs(
+    (
+      [
+        ["standard", "list"],
+        ["standard", "lookup"],
+        ["standard", "categories"],
+        ["standard", "sample"],
+        ["config", "show"],
+        ["info"],
+      ] as const
+    ).map((path) => nounVerbFromPath(path)),
+  );
+
+  it("reserves a verb the built-in noun owns", () => {
+    expect(isReserved(reserved, "standard", "list")).toBe(true);
+  });
+
+  it("admits a new verb on an existing noun (per-verb relaxation)", () => {
+    expect(isReserved(reserved, "standard", "foo")).toBe(false);
+  });
+
+  it("reserves every verb of a whole-noun (`*`) reservation", () => {
+    expect(isReserved(reserved, "info", "list")).toBe(true);
+  });
+
+  it("does not reserve an unowned verb of a partially reserved noun (raw map)", () => {
+    // buildReservedVerbs alone does NOT promote `config`; deriveReservedVerbs
+    // does (asserted below). This pins the pure-grouping behavior.
+    expect(isReserved(reserved, "config", "list")).toBe(false);
+  });
+
+  it("does not reserve a noun with no built-in", () => {
+    expect(isReserved(reserved, "recipe", "list")).toBe(false);
+  });
+});
+
+describe("deriveReservedVerbs", () => {
+  // Mirrors the real built-in surface: leaf read nouns that own list/lookup
+  // plus operational nouns that own neither.
+  const PAIRS: readonly (readonly [string, string | undefined])[] = [
+    ["standard", "list"],
+    ["standard", "lookup"],
+    ["standard", "categories"],
+    ["standard", "sample"],
+    ["config", "show"],
+    ["config", "tier"],
+    ["config", "channel"],
+    ["graph", "query"],
+    ["graph", "inspect"],
+    ["create", "component"],
+    ["create", "package"],
+    ["graphql", "build"],
+    ["setup", "all"],
+    ["tokens", "add-config"],
+    ["info", undefined],
+  ];
+  const derived = deriveReservedVerbs(PAIRS);
+
+  it("promotes operational nouns (no list/lookup) to a whole-noun reservation", () => {
+    for (const noun of ["config", "graph", "create", "graphql", "setup"]) {
+      expect(isReserved(derived, noun, "list")).toBe(true);
+      // Whole-noun means every verb is reserved, not just list.
+      expect(isReserved(derived, noun, "anything")).toBe(true);
+    }
+    // The plural add-config noun owns only a non-read verb, so it too promotes.
+    expect(isReserved(derived, "tokens", "list")).toBe(true);
+    // The promoted set is exactly the whole-noun sentinel.
+    expect(derived.get("config")).toEqual(new Set(["*"]));
+  });
+
+  it("keeps leaf read nouns per-verb (does not promote `standard`)", () => {
+    expect(isReserved(derived, "standard", "list")).toBe(true);
+    expect(isReserved(derived, "standard", "lookup")).toBe(true);
+    // A verb the built-in noun does not own stays admissible.
+    expect(isReserved(derived, "standard", "foo")).toBe(false);
+    // Untouched: the per-verb set is preserved verbatim.
+    expect(derived.get("standard")).toEqual(
+      new Set(["list", "lookup", "categories", "sample"]),
+    );
+  });
+
+  it("leaves a bare whole-noun reservation idempotent", () => {
+    expect(derived.get("info")).toEqual(new Set(["*"]));
+    expect(isReserved(derived, "info", "list")).toBe(true);
+  });
+
+  it("does not reserve a noun with no built-in", () => {
+    expect(isReserved(derived, "recipe", "list")).toBe(false);
+  });
+});

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

@@ -0,0 +1,170 @@
+/**
+ * Per-(noun, verb) reservation for story packs.
+ *
+ * A story pack must not shadow a built-in command. The built-in surface is
+ * derived at assembly time into a {@link ReservedVerbs} map via
+ * {@link deriveReservedVerbs}: each built-in noun maps to the set of verbs it
+ * already occupies. A pack is only blocked when it would emit a verb the
+ * built-in noun actually owns — so a new verb on an existing noun is
+ * admissible, and once a noun's `list`/`lookup` wrapper is deleted (leaf
+ * cutover, ADR C.07) that verb automatically leaves the map, making the
+ * migration incremental.
+ *
+ * Per-verb relaxation applies ONLY to nouns that own a `list`/`lookup` read
+ * verb (the real leaf-migration targets: block/standard/modifier/token/tier).
+ * A built-in noun that owns neither — an operational command like `config`,
+ * `graph`, `setup` — is reserved wholesale by {@link deriveReservedVerbs}, so
+ * a pack can never colonize its namespace.
+ *
+ * The {@link WHOLE_NOUN} sentinel (`"*"`) reserves a whole noun: single-word
+ * built-ins (e.g. `info`, `llm`, `doctor`) have no verb, so they reserve every
+ * verb, as do promoted operational nouns.
+ * @module
+ */
+
+/** Sentinel verb reserving an entire noun (matches every verb). */
+const WHOLE_NOUN = "*";
+
+/**
+ * The read-story verbs a pack can emit — the only verbs a leaf cutover frees.
+ *
+ * A built-in noun that owns one of these is a declarative-read migration
+ * target and keeps per-verb reservation; a noun disjoint from this set is
+ * operational and is reserved wholesale.
+ */
+const READ_STORY_VERBS: ReadonlySet<string> = new Set(["list", "lookup"]);
+
+/**
+ * Built-in reservations: noun → the verbs it occupies.
+ *
+ * The {@link WHOLE_NOUN} (`"*"`) sentinel in a noun's verb set reserves the
+ * entire noun.
+ */
+export type ReservedVerbs = ReadonlyMap<string, ReadonlySet<string>>;
+
+/**
+ * Whether a `(noun, verb)` pair is reserved by a built-in command.
+ *
+ * @param reserved - The assembled reservation map.
+ * @param noun - The story pack noun.
+ * @param verb - A verb the pack would emit (e.g. `"list"`).
+ * @returns `true` when the noun reserves this verb or the whole noun (`"*"`).
+ */
+export function isReserved(
+  reserved: ReservedVerbs,
+  noun: string,
+  verb: string,
+): boolean {
+  const verbs = reserved.get(noun);
+  return verbs !== undefined && (verbs.has(verb) || verbs.has(WHOLE_NOUN));
+}
+
+/**
+ * Split a CLI command path into a `(noun, verb)` pair.
+ *
+ * `["standard", "list"]` → `["standard", "list"]`; a single-segment path
+ * like `["info"]` → `["info", undefined]` (whole-noun reservation).
+ *
+ * @param path - A command's path segments.
+ * @returns The `[noun, verb]` pair; `verb` is `undefined` for a bare noun.
+ */
+export function nounVerbFromPath(
+  path: readonly string[],
+): [string, string | undefined] {
+  return [path.at(0) ?? "", path.at(1)];
+}
+
+/**
+ * Split an MCP tool name into a `(noun, verb)` pair on `"_"`.
+ *
+ * The verb keeps every segment after the first, so the one multi-underscore
+ * built-in parses as `"tokens_add_config"` → `["tokens", "add_config"]`;
+ * `"standard_list"` → `["standard", "list"]`; a bare `"info"` →
+ * `["info", undefined]`.
+ *
+ * Note the surface asymmetry this tolerates: the CLI reserves `tokens
+ * add-config` (hyphen) while MCP reserves `tokens_add_config` (underscore),
+ * and CLI/MCP reserve different noun sets overall. That is harmless — each
+ * surface derives and consumes its own map, and packs only ever emit the
+ * `list`/`lookup` verbs.
+ *
+ * @param name - An MCP tool name (e.g. `"token_lookup"`).
+ * @returns The `[noun, verb]` pair; `verb` is `undefined` for a bare noun.
+ */
+export function nounVerbFromToolName(
+  name: string,
+): [string, string | undefined] {
+  const parts = name.split("_");
+  const noun = parts.at(0) ?? "";
+  const verb = parts.length > 1 ? parts.slice(1).join("_") : undefined;
+  return [noun, verb];
+}
+
+/**
+ * Assemble a {@link ReservedVerbs} map from `(noun, verb)` pairs.
+ *
+ * Pure grouping only — no reservation policy. A pair with an `undefined`
+ * verb reserves the whole noun (stored as the {@link WHOLE_NOUN} sentinel).
+ * A noun appearing with both a concrete verb and `undefined` keeps both
+ * entries in its set, which is harmless because `"*"` already matches every
+ * verb. Callers wanting the policy-applied surface use
+ * {@link deriveReservedVerbs}, not this function.
+ *
+ * @param pairs - `(noun, verb)` pairs, e.g. from {@link nounVerbFromPath}.
+ * @returns The assembled reservation map (raw grouping).
+ */
+export function buildReservedVerbs(
+  pairs: Iterable<readonly [string, string | undefined]>,
+): ReservedVerbs {
+  const reserved = new Map<string, Set<string>>();
+  for (const [noun, verb] of pairs) {
+    const verbs = reserved.get(noun) ?? new Set<string>();
+    verbs.add(verb ?? WHOLE_NOUN);
+    reserved.set(noun, verbs);
+  }
+  return reserved;
+}
+
+/**
+ * Derive the policy-applied {@link ReservedVerbs} the guard consumes.
+ *
+ * A built-in noun that exposes neither `list` nor `lookup` is an operational
+ * command (config, graph, setup, …), never a declarative-read migration
+ * target, so it is reserved wholesale — a pack may not colonize its
+ * namespace. Nouns that own `list`/`lookup` keep per-verb reservation so a
+ * later cutover phase can free an individual read verb by deleting its
+ * wrapper.
+ *
+ * Both the CLI and MCP surfaces route through this single derivation, so the
+ * two surfaces reserve the same `list`/`lookup` verbs for every leaf noun.
+ *
+ * Limitation: a fully-migrated leaf noun whose only *remaining* built-in
+ * verbs are non-read (e.g. `sample`/`categories` after both `list` and
+ * `lookup` are deleted) would be wholesale-promoted here; that Phase-3 case
+ * is served by the built-in pack's own precedence (C.07) and must be
+ * revisited when it lands.
+ *
+ * @param pairs - `(noun, verb)` pairs, e.g. from {@link nounVerbFromPath}.
+ * @returns The reservation map with operational nouns promoted to whole-noun.
+ */
+export function deriveReservedVerbs(
+  pairs: Iterable<readonly [string, string | undefined]>,
+): ReservedVerbs {
+  // Mutable working copy of the pure grouping.
+  const map = new Map<string, Set<string>>();
+  for (const [noun, verbs] of buildReservedVerbs(pairs)) {
+    map.set(noun, new Set(verbs));
+  }
+
+  // Promote every operational noun (verb-set disjoint from the read verbs)
+  // to a wholesale reservation. Bare nouns already hold `{"*"}`, so this is
+  // idempotent for them; leaf read nouns keep their per-verb sets untouched.
+  for (const [noun, verbs] of map) {
+    const ownsReadVerb = [...verbs].some((verb) => READ_STORY_VERBS.has(verb));
+    if (!ownsReadVerb) {
+      map.set(noun, new Set([WHOLE_NOUN]));
+    }
+  }
+
+  return map;
+}

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

@@ -0,0 +1,31 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../buildQuery.js";
+
+/**
+ * Run a pack story's SELECT and return its binding rows.
+ *
+ * The store rejects non-read queries at the engine level; this guards the
+ * result shape so a pack whose query is not a SELECT fails with a
+ * recoverable config error instead of a shape mismatch downstream.
+ *
+ * @param store - The ke store to query.
+ * @param query - SPARQL SELECT text (the store injects PREFIX declarations).
+ * @param source - The pack source, for error attribution.
+ * @returns One record per row, keyed by SELECT variable name.
+ * @throws PragmaError with code `CONFIG_ERROR` when the query is not a SELECT.
+ * @note Impure — queries the ke store.
+ */
+export default async function runSelectQuery(
+  store: Store,
+  query: string,
+  source: string,
+): Promise<Record<string, string>[]> {
+  const result = await store.query(buildQuery(query));
+  if (result.type !== "select") {
+    throw PragmaError.configError(
+      `Story query in ${source} must be a SELECT (got ${result.type}).`,
+    );
+  }
+  return result.bindings;
+}