@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,55 +0,0 @@
-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

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1,213 +0,0 @@
-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

@@ -1,170 +0,0 @@
-/**
- * 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

@@ -1,31 +0,0 @@
-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;
-}