@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/kernel/packs/compile.test.ts

@@ -8,12 +8,14 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import type { PragmaRuntime } from "../runtime/types.js";
 import { compilePack } from "./compile.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackRow } from "./types.js";
+import { distributionSource } from "./types.js";
 import { assertUniqueVerbs, verbKey } from "./uniqueness.js";
 
 const PREFIXES = {
@@ -92,8 +94,33 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
     expect(parsePackDefinition(raw, "test:widget")).toEqual(WIDGET_PACK);
   });
 
+  it("round-trips a fixed-count sample — the field the no-argument samples declare", () => {
+    // `sample.fixedCount` is a documented grammar field (packs/types.ts) that
+    // three of the distribution's own stories use and the covenant freezes
+    // (`block sample` takes no argument). It was missing from the `.strict()`
+    // sample schema, so ANY config- or package-declared story using it died
+    // with a fatal CONFIG_ERROR before ever reaching the compiler.
+    const lookup = WIDGET_PACK.lookup as NonNullable<PackDefinition["lookup"]>;
+    const fixed: PackDefinition = {
+      ...WIDGET_PACK,
+      lookup: { ...lookup, sample: { fixedCount: true } },
+    };
+    expect(parsePackDefinition(JSON.parse(JSON.stringify(fixed)), "t")).toEqual(
+      fixed,
+    );
+    // …and the compiler honours it: no `[count]` positional on the sample verb.
+    const sample = compilePack(fixed, distributionSource("t"), PREFIXES).find(
+      (v) => verbKey(v.path) === "widget sample",
+    );
+    expect(sample?.params).toEqual([]);
+  });
+
   it("projects list, lookup, and sample verbs with unique keys", () => {
-    const verbs = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const verbs = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    );
     expect(verbs.map((v) => verbKey(v.path))).toEqual([
       "widget list",
       "widget lookup",
@@ -103,7 +130,11 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
   });
 
   it("projects list filters as params (enum) + a search flag", () => {
-    const [list] = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const [list] = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    );
     expect(list?.params.map((p) => p.name)).toEqual(["kind", "search"]);
     const kind = list?.params.find((p) => p.name === "kind");
     expect(kind?.kind).toBe("enum");
@@ -112,7 +143,11 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
   });
 
   it("projects the lookup as a variadic name-completing positional + disclosure", () => {
-    const verbs = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES);
+    const verbs = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    );
     const lookup = verbs.find((v) => verbKey(v.path) === "widget lookup");
     const name = lookup?.params.at(0);
     expect(name?.kind).toBe("string[]");
@@ -132,7 +167,7 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
       PackDefinition["lookup"]
     >;
     const nameParam = (def: PackDefinition) =>
-      compilePack(def, "bundled:widget", PREFIXES)
+      compilePack(def, distributionSource("bundled:widget"), PREFIXES)
         .find((v) => verbKey(v.path) === "widget lookup")
         ?.params.at(0);
 
@@ -162,6 +197,125 @@ describe("pack compiler — round-trip + shape (PROTECTED, storeless)", () => {
   });
 });
 
+describe("the grammar rejects what the compiler cannot build (PROTECTED)", () => {
+  // A definition that compiles to a duplicate `(noun, verb)` key or a duplicate
+  // CLI option is not merely odd — it throws out of `assembleEffectiveModules`
+  // or out of `buildProgram`, both of which run BEFORE the command tree exists.
+  // For a package-shipped story that means every command dies, `doctor` and
+  // `sources update` included. The collision is a property of the definition,
+  // so it is rejected here, where a package story degrades to a dropped file.
+  const listShape = {
+    query: "SELECT ?uri WHERE { ?uri a ex:Widget }",
+    columns: [{ field: "uri" }],
+  };
+  const parse = (def: unknown) => () =>
+    parsePackDefinition(def, "pkg/stories/widget.json");
+
+  it("rejects an extra verb that repeats list, lookup, sample, or itself", () => {
+    const lookup = { by: "ex:name", type: "ex:Widget", sample: true };
+    expect(
+      parse({
+        noun: "widget",
+        list: listShape,
+        verbs: [{ ...listShape, verb: "list" }],
+      }),
+    ).toThrow(/verb "list" is already compiled/);
+    expect(
+      parse({
+        noun: "widget",
+        lookup,
+        verbs: [{ ...listShape, verb: "lookup" }],
+      }),
+    ).toThrow(/verb "lookup" is already compiled/);
+    expect(
+      parse({
+        noun: "widget",
+        lookup,
+        verbs: [{ ...listShape, verb: "sample" }],
+      }),
+    ).toThrow(/verb "sample" is already compiled/);
+    expect(
+      parse({
+        noun: "widget",
+        list: listShape,
+        verbs: [
+          { ...listShape, verb: "categories" },
+          { ...listShape, verb: "categories" },
+        ],
+      }),
+    ).toThrow(/verb "categories" is already compiled/);
+  });
+
+  it("rejects a filter param declared twice, on list or on an extra verb", () => {
+    const twice = [
+      { param: "kind", variable: "uri" },
+      { param: "kind", variable: "uri" },
+    ];
+    expect(
+      parse({ noun: "widget", list: { ...listShape, filters: twice } }),
+    ).toThrow(/filter param "kind" is declared twice/);
+    expect(
+      parse({
+        noun: "widget",
+        list: listShape,
+        verbs: [{ ...listShape, verb: "categories", filters: twice }],
+      }),
+    ).toThrow(/filter param "kind" is declared twice/);
+  });
+
+  it("still accepts the distinct forms, and they compile to unique keys/params", () => {
+    const definition = parsePackDefinition(
+      {
+        noun: "widget",
+        list: {
+          ...listShape,
+          filters: [
+            { param: "kind", variable: "uri" },
+            { param: "tier", variable: "uri" },
+          ],
+        },
+        verbs: [{ ...listShape, verb: "categories" }],
+        lookup: { by: "ex:name", type: "ex:Widget", sample: true },
+      },
+      "pkg/stories/widget.json",
+    );
+    const verbs = compilePack(
+      definition,
+      { label: "pkg/stories/widget.json", origin: "package" },
+      PREFIXES,
+    );
+    expect(verbs.map((v) => verbKey(v.path))).toEqual([
+      "widget list",
+      "widget categories",
+      "widget lookup",
+      "widget sample",
+    ]);
+    expect(() => assertUniqueVerbs(verbs)).not.toThrow();
+    expect(verbs.at(0)?.params.map((p) => p.name)).toEqual(["kind", "tier"]);
+  });
+
+  it("names the shape a noun must have, not the regex", () => {
+    expect(parse({ noun: "Bad Noun", list: listShape })).toThrow(
+      /noun: must be lowercase kebab-case/,
+    );
+  });
+
+  it("rejects an emptyRecovery.cli that names a binary, and names the change", () => {
+    // The hint is rendered as `<consuming distribution> <cli>`, so a story
+    // carrying the old prefixed form would render `pragma pragma sources
+    // update`. Third-party packs are third-party DATA: they get an error that
+    // names the grammar change, not a silently doubled string.
+    const withCli = (cli: string) => ({
+      noun: "widget",
+      list: { ...listShape, emptyRecovery: { message: "None.", cli } },
+    });
+    expect(parse(withCli(`${RECOVERY_CLI_PREFIX}sources update`))).toThrow(
+      /WITHOUT the binary name/,
+    );
+    expect(parse(withCli("sources update"))).not.toThrow();
+  });
+});
+
 describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
   let rt: PragmaRuntime;
 
@@ -178,9 +332,11 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
   });
 
   const run = <R>(verbLabel: string, params: Record<string, unknown>) => {
-    const verb = compilePack(WIDGET_PACK, "bundled:widget", PREFIXES).find(
-      (v) => verbKey(v.path) === `widget ${verbLabel}`,
-    );
+    const verb = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    ).find((v) => verbKey(v.path) === `widget ${verbLabel}`);
     if (!verb) throw new Error(`no widget ${verbLabel}`);
     return verb.run(params, rt) as Promise<R>;
   };

package/src/kernel/packs/compile.ts

@@ -7,12 +7,14 @@
  *
  * Pure, storeless spec-generation: it builds paths, params, formatters, and run
  * closures without touching the store or zod, so it runs on the
- * `--help`/`__complete` fast path (the bundled packs compile at import; the
- * dynamic merge is `collect.assembleEffectiveModules`/`loadEffectiveModules`).
+ * `--help`/`__complete` fast path (the distribution's declared stories compile
+ * at import, in `capabilities/distribution.ts`; the dynamic merge is
+ * `collect.assembleEffectiveModules`/`loadEffectiveModules`).
  * The heavy work is deferred into the run closures (behind the lazy runtime
  * facade).
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../runtime/types.js";
 import { asVerb } from "../spec/asVerb.js";
 import type { DisclosureSpec, ParamSpec, VerbSpec } from "../spec/types.js";
@@ -35,6 +37,7 @@ import type {
   PackLookup,
   PackRow,
   PackSearch,
+  StorySource,
 } from "./types.js";
 
 // The run bodies pull the SPARQL/GraphQL fetch layer; they are dynamic-imported
@@ -62,7 +65,7 @@ const READ_CAPABILITY = {
  */
 export function compilePack(
   definition: PackDefinition,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): VerbSpec[] {
   const { noun } = definition;
@@ -111,7 +114,7 @@ interface ListVerbMeta {
   readonly summary: string;
   /** The authored MCP tool description (from `toolDescription`), if any. */
   readonly doc?: string;
-  readonly source: string;
+  readonly source: StorySource;
   readonly prefixes: Readonly<Record<string, string>>;
 }
 
@@ -135,17 +138,17 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
       }),
     },
     examples: [
-      { cmd: `pragma ${meta.noun} ${meta.verb}` },
+      { cmd: `${BIN_NAME} ${meta.noun} ${meta.verb}` },
       ...(filterExample
         ? [
             {
-              cmd: `pragma ${meta.noun} ${meta.verb} --${filterExample.param} ${quoteExample(
+              cmd: `${BIN_NAME} ${meta.noun} ${meta.verb} --${filterExample.param} ${quoteExample(
                 filterExample.values?.at(0) ?? "",
               )}`,
             },
           ]
         : []),
-      { cmd: `pragma ${meta.noun} ${meta.verb} --format llm` },
+      { cmd: `${BIN_NAME} ${meta.noun} ${meta.verb} --format llm` },
     ],
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
@@ -160,7 +163,7 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
 function compileLookupVerb(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): VerbSpec {
   // Derive-by-default: every lookup completes its `<name>` from the pack index
@@ -197,7 +200,7 @@ function compileLookupVerb(
     ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
     params: [nameParam],
     output: { formatters: lookupFormatters(lookup, prefixes) },
-    examples: [{ cmd: `pragma ${noun} lookup <name>` }],
+    examples: [{ cmd: `${BIN_NAME} ${noun} lookup <name>` }],
     ...(lookup.disclosure
       ? { disclosure: disclosureSpec(lookup.disclosure) }
       : {}),
@@ -214,7 +217,7 @@ function compileLookupVerb(
 function compileSampleVerb(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): VerbSpec {
   const defaultCount = sampleDefaultCount(lookup);
@@ -241,8 +244,8 @@ function compileSampleVerb(
     params: countParam,
     output: { formatters: sampleFormatters(lookup, noun, prefixes) },
     examples: [
-      { cmd: `pragma ${noun} sample` },
-      ...(config?.fixedCount ? [] : [{ cmd: `pragma ${noun} sample 3` }]),
+      { cmd: `${BIN_NAME} ${noun} sample` },
+      ...(config?.fixedCount ? [] : [{ cmd: `${BIN_NAME} ${noun} sample 3` }]),
     ],
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>

package/src/kernel/packs/disclosure.test.ts

@@ -66,13 +66,16 @@ const PACK: PackDefinition = {
 };
 
 const lookupVerb = () =>
-  compilePack(PACK, "test:widget", PREFIXES).find(
+  compilePack(PACK, { label: "test:widget", origin: "package" }, PREFIXES).find(
     (v) => verbKey(v.path) === "widget lookup",
   );
 
 async function lookupAt(
   detail?: "summary" | "standard" | "detailed",
-  config?: { configDetail: string; detailOrigin: "global" | "project" },
+  config?: {
+    configDetail: "summary" | "standard" | "detailed";
+    detailOrigin: "global" | "project";
+  },
 ): Promise<Record<string, unknown>> {
   const { rt } = await buildFixtureRuntime({
     ttl: TTL,

package/src/kernel/packs/graphql/fetchGraphqlLookup.ts

@@ -15,6 +15,7 @@
  */
 
 import { PragmaError } from "../../error/PragmaError.js";
+import { cliRecovery } from "../../error/recovery.js";
 import type { PragmaRuntime } from "../../runtime/types.js";
 import type { PackChildRow, PackEntity, PackLookup } from "../types.js";
 import {
@@ -55,12 +56,12 @@ export async function fetchGraphqlLookup(
       .map((error) => error.message)
       .join("; ");
     throw PragmaError.storeUnavailable(`GraphQL lookup failed: ${messages}`, {
-      recovery: {
-        message: "Check the loaded ontology and namespaces.",
-        // `graph inspect` needs a <uri>; `ontology list` is runnable as-is.
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      // `graph inspect` needs a <uri>; `ontology list` is runnable as-is.
+      recovery: cliRecovery(
+        "ontology list",
+        "Check the loaded ontology and namespaces.",
+        { tool: "ontology_list" },
+      ),
     });
   }
 
@@ -72,10 +73,10 @@ export async function fetchGraphqlLookup(
     throw new PragmaError({
       code: "ENTITY_NOT_FOUND",
       message: `Could not resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
-      recovery: {
-        message: "Inspect the entity's triples to check its rdf:type.",
-        cli: `pragma graph inspect ${entityUri}`,
-      },
+      recovery: cliRecovery(
+        `graph inspect ${entityUri}`,
+        "Inspect the entity's triples to check its rdf:type.",
+      ),
     });
   }
 

package/src/kernel/packs/graphqlSource.test.ts

@@ -17,6 +17,7 @@ import { buildLookupDocument } from "./graphql/buildLookupDocument.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackLookup } from "./types.js";
+import { distributionSource } from "./types.js";
 import { verbKey } from "./uniqueness.js";
 
 const DS = "https://ds.canonical.com/";
@@ -292,9 +293,11 @@ describe("GraphQL lookup end to end + shape parity with SPARQL (PROTECTED)", ()
   });
 
   const lookupVia = (definition: PackDefinition, name: string) => {
-    const verb = compilePack(definition, "t", BLOCK_PREFIXES).find(
-      (v) => verbKey(v.path) === `${definition.noun} lookup`,
-    );
+    const verb = compilePack(
+      definition,
+      distributionSource("t"),
+      BLOCK_PREFIXES,
+    ).find((v) => verbKey(v.path) === `${definition.noun} lookup`);
     if (!verb) throw new Error("no lookup verb");
     return verb.run({ name: [name] }, rt) as Promise<LookupOutput>;
   };

package/src/kernel/packs/iri.ts

@@ -8,6 +8,7 @@
  */
 
 import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
 
 /** Characters not allowed inside a SPARQL `<IRI>`. */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
@@ -39,8 +40,7 @@ export function resolveUri(
   if (colonIdx === -1) {
     throw PragmaError.invalidInput("uri", uri, {
       recovery: {
-        message:
-          'Use a prefixed URI (e.g. "ds:global.component.button") or a full URI.',
+        message: 'Use a prefixed URI (e.g. "prefix:name") or a full URI.',
       },
     });
   }
@@ -60,11 +60,9 @@ export function resolveUri(
 
   throw PragmaError.invalidInput("prefix", prefix, {
     validOptions: Object.keys(prefixes),
-    recovery: {
-      message: "List known ontology prefixes.",
-      cli: "pragma ontology list",
-      mcp: { tool: "ontology_list" },
-    },
+    recovery: cliRecovery("ontology list", "List known ontology prefixes.", {
+      tool: "ontology_list",
+    }),
   });
 }
 

package/src/kernel/packs/renderPack.ts

@@ -9,6 +9,7 @@
  * them (disclosure gates the fetch), never HOW it is laid out.
  */
 
+import { BIN_NAME, RECOVERY_CLI_PREFIX } from "../../constants.js";
 import type {
   ColumnDef,
   LookupField,
@@ -52,8 +53,7 @@ export interface RenderMeta {
  * list on a BUILT store (a cold store would have failed with STORE_UNAVAILABLE
  * first) means "nothing matched", so point at both possible fixes.
  */
-const DEFAULT_EMPTY_HINT =
-  "If you haven't built the store yet, run `pragma sources update`; otherwise broaden your filter or channel.";
+const DEFAULT_EMPTY_HINT = `If you haven't built the store yet, run \`${BIN_NAME} sources update\`; otherwise broaden your filter or channel.`;
 
 /** Build the list formatters for a list-shaped verb (list or an extra verb). */
 export function listFormatters(
@@ -69,7 +69,9 @@ export function listFormatters(
   // `emptyRecovery` becomes the hint; otherwise the generic build/broaden hint.
   const emptyHint = shape.emptyRecovery
     ? `${shape.emptyRecovery.message}${
-        shape.emptyRecovery.cli ? ` Run \`${shape.emptyRecovery.cli}\`.` : ""
+        shape.emptyRecovery.cli
+          ? ` Run \`${RECOVERY_CLI_PREFIX}${shape.emptyRecovery.cli}\`.`
+          : ""
       }`
     : DEFAULT_EMPTY_HINT;
   const options: RenderListOptions<PackRow> = {

package/src/kernel/packs/resolveEntity.ts

@@ -13,6 +13,7 @@
  */
 
 import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
 import { suggestNames } from "../project/cli/suggestNames.js";
 import type { PragmaRuntime } from "../runtime/types.js";
 import { activeExpands } from "./disclosure.js";
@@ -27,7 +28,12 @@ import {
   buildNameResolveQuery,
 } from "./sparql/buildLookupQuery.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type { PackChildRow, PackEntity, PackLookup } from "./types.js";
+import type {
+  PackChildRow,
+  PackEntity,
+  PackLookup,
+  StorySource,
+} from "./types.js";
 
 /** A structured per-query lookup failure (never rejects the whole batch). */
 export interface LookupError {
@@ -56,17 +62,15 @@ export async function resolveLookup(
   lookup: PackLookup,
   noun: string,
   queries: readonly string[],
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
 ): Promise<LookupOutput> {
   if (queries.length === 0) {
     throw PragmaError.invalidInput("names", "(empty)", {
-      recovery: {
-        message: `List available ${noun} entries.`,
-        cli: `pragma ${noun} list`,
-        mcp: { tool: `${noun}_list` },
-      },
+      recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+        tool: `${noun}_list`,
+      }),
     });
   }
 
@@ -111,7 +115,7 @@ async function expandQueries(
   rt: LookupRuntime,
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   queries: readonly string[],
 ): Promise<{ names: string[]; globErrors: LookupError[] }> {
   if (!queries.some(isGlobPattern))
@@ -144,7 +148,7 @@ async function lookupOne(
   lookup: PackLookup,
   noun: string,
   query: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
 ): Promise<PackEntity> {
@@ -161,11 +165,9 @@ async function lookupOne(
     const candidates = await listEntityNames(rt, lookup, source);
     throw PragmaError.notFound(noun, query, {
       suggestions: suggestNames(query, candidates),
-      recovery: {
-        message: `List available ${noun} entries.`,
-        cli: `pragma ${noun} list`,
-        mcp: { tool: `${noun}_list` },
-      },
+      recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+        tool: `${noun}_list`,
+      }),
     });
   }
 
@@ -175,7 +177,9 @@ async function lookupOne(
       lookup,
       base.uri,
       base.name ?? query,
-      source,
+      // The GraphQL lane's only use of the source is CONFIG_ERROR attribution,
+      // which is right for any origin — so it takes the label, not provenance.
+      source.label,
       prefixes,
       level,
     );
@@ -205,7 +209,7 @@ function buildEntityQuery(
     throw PragmaError.invalidInput("name", query, {
       recovery: {
         message:
-          "Use an absolute IRI (https://…), a prefixed name (ds:thing), or a plain entity name.",
+          "Use an absolute IRI (https://…), a prefixed name (prefix:local), or a plain entity name.",
       },
     });
   }
@@ -225,7 +229,7 @@ function looksLikeIri(query: string): boolean {
 export async function listEntityNames(
   rt: LookupRuntime,
   lookup: PackLookup,
-  source: string,
+  source: StorySource,
 ): Promise<string[]> {
   const rows = await runSelect(rt, buildLookupNamesQuery(lookup), source);
   return rows.map((row) => row.name ?? "").filter((name) => name !== "");

package/src/kernel/packs/runBodies.ts

@@ -10,6 +10,7 @@
  */
 
 import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
 import type { PragmaRuntime } from "../runtime/types.js";
 import { resolvePackDetail } from "./disclosure.js";
 import type { SampleOutput } from "./renderPack.js";
@@ -22,14 +23,14 @@ import { parseSampleCount, pickRandom } from "./sample.js";
 import { applyPackFilters } from "./sparql/applyFilters.js";
 import { applyPackSearch } from "./sparql/applySearch.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type { PackList, PackLookup, PackRow } from "./types.js";
+import type { PackList, PackLookup, PackRow, StorySource } from "./types.js";
 
 /** The highest canonical level — sample fetches everything for shape discovery. */
 const HIGHEST_LEVEL = "detailed";
 
 /** Facts a list-shaped run body needs beyond its `shape`. */
 export interface ListRunMeta {
-  readonly source: string;
+  readonly source: StorySource;
 }
 
 /**
@@ -61,7 +62,7 @@ export function makeListRun(
 export function makeLookupRun(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
 ): (
   params: Record<string, unknown>,
@@ -88,11 +89,11 @@ export function makeLookupRun(
           code: first.code as PragmaError["code"],
           message: first.message,
           suggestions: first.suggestions ? [...first.suggestions] : undefined,
-          recovery: {
-            message: `List available ${noun} entries.`,
-            cli: `pragma ${noun} list`,
-            mcp: { tool: `${noun}_list` },
-          },
+          recovery: cliRecovery(
+            `${noun} list`,
+            `List available ${noun} entries.`,
+            { tool: `${noun}_list` },
+          ),
         });
       }
     }
@@ -104,7 +105,7 @@ export function makeLookupRun(
 export function makeSampleRun(
   lookup: PackLookup,
   noun: string,
-  source: string,
+  source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   defaultCount: number,
 ): (
@@ -119,11 +120,11 @@ export function makeSampleRun(
     if (names.length === 0) {
       throw PragmaError.emptyResults(noun, {
         message: `No ${noun} entries to sample.`,
-        recovery: {
-          message: `List available ${noun} entries.`,
-          cli: `pragma ${noun} list`,
-          mcp: { tool: `${noun}_list` },
-        },
+        recovery: cliRecovery(
+          `${noun} list`,
+          `List available ${noun} entries.`,
+          { tool: `${noun}_list` },
+        ),
       });
     }
     const selected = pickRandom(names, count);