@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/shared/lookupMany.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import lookupMany, { lookupToolMeta } from "./lookupMany.js";
+
+describe("lookupMany", () => {
+  it("returns all results when every query resolves", async () => {
+    const result = await lookupMany(["a", "b"], async (q) => q.toUpperCase());
+
+    expect(result.results).toEqual(["A", "B"]);
+    expect(result.errors).toEqual([]);
+    expect(result.meta).toEqual({ internalErrorCount: 0 });
+  });
+
+  it("collects PragmaError failures as structured error entries", async () => {
+    const result = await lookupMany(["Button", "Buton"], async (q) => {
+      if (q === "Buton") {
+        throw PragmaError.notFound("block", q, { suggestions: ["Button"] });
+      }
+      return q;
+    });
+
+    expect(result.results).toEqual(["Button"]);
+    expect(result.errors).toEqual([
+      {
+        query: "Buton",
+        code: "ENTITY_NOT_FOUND",
+        message: 'block "Buton" not found.',
+        suggestions: ["Button"],
+      },
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 0 });
+  });
+
+  it("keeps N-1 results when one query throws a non-PragmaError", async () => {
+    const result = await lookupMany(
+      ["a", "poisoned", "c"],
+      async (q): Promise<string> => {
+        if (q === "poisoned") {
+          throw new TypeError("cannot read properties of undefined");
+        }
+        return q.toUpperCase();
+      },
+    );
+
+    expect(result.results).toEqual(["A", "C"]);
+    expect(result.errors).toEqual([
+      {
+        query: "poisoned",
+        code: "INTERNAL_ERROR",
+        message: "Internal error: cannot read properties of undefined",
+      },
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 1 });
+  });
+
+  it("stringifies non-Error rejection values", async () => {
+    const result = await lookupMany(["a"], async () => {
+      throw "string failure";
+    });
+
+    expect(result.results).toEqual([]);
+    expect(result.errors).toEqual([
+      {
+        query: "a",
+        code: "INTERNAL_ERROR",
+        message: "Internal error: string failure",
+      },
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 1 });
+  });
+
+  it("counts each internal error and mixes with PragmaError entries", async () => {
+    const result = await lookupMany(
+      ["ok", "missing", "boom-1", "boom-2"],
+      async (q): Promise<string> => {
+        if (q === "missing") throw PragmaError.notFound("token", q);
+        if (q.startsWith("boom")) throw new Error(q);
+        return q;
+      },
+    );
+
+    expect(result.results).toEqual(["ok"]);
+    expect(result.errors).toHaveLength(3);
+    expect(result.errors.map((e) => e.code)).toEqual([
+      "ENTITY_NOT_FOUND",
+      "INTERNAL_ERROR",
+      "INTERNAL_ERROR",
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 2 });
+  });
+});
+
+describe("lookupToolMeta", () => {
+  it("reports count and omits internalErrorCount when zero", async () => {
+    const result = await lookupMany(["a", "b"], async (q) => q);
+
+    expect(lookupToolMeta(result)).toEqual({ count: 2 });
+  });
+
+  it("includes internalErrorCount when at least one query failed unexpectedly", async () => {
+    const result = await lookupMany(
+      ["a", "boom"],
+      async (q): Promise<string> => {
+        if (q === "boom") throw new Error("boom");
+        return q;
+      },
+    );
+
+    expect(lookupToolMeta(result)).toEqual({
+      count: 1,
+      internalErrorCount: 1,
+    });
+  });
+
+  it("tolerates hand-built results without meta", () => {
+    expect(lookupToolMeta({ results: ["x"], errors: [] })).toEqual({
+      count: 1,
+    });
+  });
+});

package/src/domains/shared/lookupMany.ts

@@ -6,6 +6,11 @@ import type { LookupResult } from "./contracts.js";
  *
  * Used by MCP lookup tools so a single call can return multiple results
  * without failing the entire request when one query is missing.
+ *
+ * The collection loop never rejects: a `PragmaError` becomes an error entry
+ * with its own code, and any other thrown value becomes an `INTERNAL_ERROR`
+ * entry — so one poisoned query cannot discard the other queries' results.
+ * `meta.internalErrorCount` reports how many entries are internal errors.
  */
 export default async function lookupMany<TResult>(
   queries: readonly string[],
@@ -21,6 +26,7 @@ export default async function lookupMany<TResult>(
     queries.map((query) => lookup(query)),
   );
   const results: TResult[] = [];
+  let internalErrorCount = 0;
 
   for (const [index, outcome] of settled.entries()) {
     const query = queries[index];
@@ -45,9 +51,35 @@ export default async function lookupMany<TResult>(
         }),
       });
     } else {
-      throw error;
+      internalErrorCount += 1;
+      const reason = error instanceof Error ? error.message : String(error);
+      errors.push({
+        query,
+        code: "INTERNAL_ERROR",
+        message: `Internal error: ${reason}`,
+      });
     }
   }
 
-  return { results, errors };
+  return { results, errors, meta: { internalErrorCount } };
+}
+
+/**
+ * Build MCP envelope metadata for a lookup result.
+ *
+ * Always reports `count`; includes `internalErrorCount` only when at least
+ * one query failed unexpectedly, so healthy responses stay unchanged.
+ *
+ * @param result - A lookup result, typically produced via {@link lookupMany}.
+ * @returns Meta object for the `{ ok, data, meta }` tool envelope.
+ */
+export function lookupToolMeta<TResult>(result: LookupResult<TResult>): {
+  count: number;
+  internalErrorCount?: number;
+} {
+  const internalErrorCount = result.meta?.internalErrorCount ?? 0;
+  return {
+    count: result.results.length,
+    ...(internalErrorCount > 0 && { internalErrorCount }),
+  };
 }

package/src/domains/shared/mergeAndParseRefs.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { RawPackageEntry } from "../refs/operations/parseRef.js";
+import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
+import { DEFAULT_PACKAGES } from "./packages.js";
+
+const DEFAULT_NAMES = DEFAULT_PACKAGES.map((entry) =>
+  typeof entry === "string" ? entry : entry.name,
+);
+
+function writeGlobalRefs(
+  xdgDir: string,
+  packages: ReadonlyArray<RawPackageEntry>,
+): void {
+  const dir = join(xdgDir, "pragma");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "refs.json"), JSON.stringify({ packages }));
+}
+
+describe("mergeAndParseRefs", () => {
+  let tmpDir: string;
+  const origEnv = { ...process.env };
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-merge-refs-"));
+    // Point XDG_CONFIG_HOME to our temp dir so readGlobalRefs() resolves there
+    process.env.XDG_CONFIG_HOME = tmpDir;
+  });
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns parsed defaults when config and global refs are absent", () => {
+    const refs = mergeAndParseRefs(undefined);
+    expect(refs.map((ref) => ref.pkg)).toEqual(DEFAULT_NAMES);
+    expect(refs.every((ref) => ref.kind === "git")).toBe(true);
+  });
+
+  it("treats an explicitly empty config list as not configured", () => {
+    expect(mergeAndParseRefs([])).toEqual(mergeAndParseRefs(undefined));
+  });
+
+  it("falls back to global refs when the config list is empty", () => {
+    writeGlobalRefs(tmpDir, [
+      { name: "@canonical/design-system", source: "file:///tmp/ds" },
+    ]);
+
+    const refs = mergeAndParseRefs([]);
+
+    expect(refs.map((ref) => ref.pkg)).toEqual(DEFAULT_NAMES);
+    expect(refs.at(0)).toEqual({
+      kind: "file",
+      pkg: "@canonical/design-system",
+      path: "/tmp/ds",
+    });
+  });
+
+  it("merges global refs over defaults by package name", () => {
+    writeGlobalRefs(tmpDir, [
+      { name: "@canonical/design-system", source: "file:///tmp/ds" },
+      "@acme/extra",
+    ]);
+
+    const refs = mergeAndParseRefs(undefined);
+
+    expect(refs.map((ref) => ref.pkg)).toEqual([
+      ...DEFAULT_NAMES,
+      "@acme/extra",
+    ]);
+    expect(refs.at(0)?.kind).toBe("file");
+    expect(refs.at(-1)).toEqual({ kind: "npm", pkg: "@acme/extra" });
+  });
+
+  it("replaces defaults and global refs with a non-empty config list", () => {
+    writeGlobalRefs(tmpDir, ["@acme/global-only"]);
+
+    const refs = mergeAndParseRefs([
+      { name: "@acme/only", source: "file:///tmp/only" },
+    ]);
+
+    expect(refs).toEqual([
+      { kind: "file", pkg: "@acme/only", path: "/tmp/only" },
+    ]);
+  });
+});

package/src/domains/shared/mergeAndParseRefs.ts

@@ -0,0 +1,44 @@
+import {
+  type PackageRef,
+  parsePackageEntry,
+  type RawPackageEntry,
+} from "../refs/operations/parseRef.js";
+import readGlobalRefs from "../refs/operations/readGlobalRefs.js";
+import { DEFAULT_PACKAGES } from "./packages.js";
+
+/**
+ * Merge config packages, global refs, and the built-in defaults into a
+ * final parsed `PackageRef` array.
+ *
+ * Priority: config `packages` > global `refs.json` > hardcoded defaults.
+ * A non-empty config list is a full replacement — only the listed packages
+ * resolve. An empty or absent list means "not configured": global refs are
+ * merged over the defaults by package name, so a global entry for
+ * "@canonical/foo" overrides the default entry for the same package.
+ *
+ * Kept free of store imports so config-only consumers (e.g.
+ * `resolveConfiguredGraphs`) can merge refs without loading the ke/WASM
+ * runtime.
+ *
+ * @note Impure — reads global refs from `~/.config/pragma/refs.json`.
+ *
+ * @param configPackages - The `packages` field from `pragma.config.json`.
+ * @returns Parsed refs ready for the loader chain.
+ * @throws PragmaError with code CONFIG_ERROR when an entry is malformed.
+ */
+export function mergeAndParseRefs(
+  configPackages?: ReadonlyArray<RawPackageEntry>,
+): PackageRef[] {
+  // A non-empty config list replaces the package set entirely.
+  if (configPackages && configPackages.length > 0) {
+    return configPackages.map((entry) => parsePackageEntry(entry));
+  }
+
+  // Empty or absent → merge global refs over the defaults, keyed by name.
+  const merged = new Map<string, RawPackageEntry>();
+  for (const entry of [...DEFAULT_PACKAGES, ...readGlobalRefs()]) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    merged.set(name, entry);
+  }
+  return [...merged.values()].map((entry) => parsePackageEntry(entry));
+}

package/src/domains/shared/packages.ts

@@ -1,27 +1,20 @@
 /**
  * Default semantic graph package registry.
  *
- * Defines the default graph packages loaded when no config overrides
- * are present. Each entry is a git ref pointing to the canonical
- * repository so `pragma update-refs` fetches data out of the box.
+ * Sourced from the declarative built-in defaults document
+ * (`src/config/defaults.json`) — pragma core carries no hardcoded
+ * knowledge of specific design-system packages. These form the base
+ * package set whenever a config layer does not declare a non-empty
+ * `packages` list; global `refs.json` entries then merge over them by
+ * package name, and a non-empty config list replaces them entirely
+ * (see `mergeAndParseRefs`).
  *
  * Resolution is handled by the loader chain in `loaders/`.
  */
 
+import { DEFAULT_CONFIG } from "../../config/defaultConfig.js";
 import type { RawPackageEntry } from "../refs/operations/parseRef.js";
 
 /** Default semantic graph packages loaded when no config overrides are present. */
-export const DEFAULT_PACKAGES: readonly RawPackageEntry[] = [
-  {
-    name: "@canonical/design-system",
-    source: "git+https://github.com/canonical/design-system.git#main",
-  },
-  {
-    name: "@canonical/anatomy-dsl",
-    source: "git+https://github.com/canonical/anatomy-dsl.git#main",
-  },
-  {
-    name: "@canonical/code-standards",
-    source: "git+https://github.com/canonical/web-code-standards.git#main",
-  },
-];
+export const DEFAULT_PACKAGES: readonly RawPackageEntry[] =
+  DEFAULT_CONFIG.packages;

package/src/domains/shared/resolveConfiguredGraphs.test.ts

@@ -0,0 +1,27 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import resolveConfiguredGraphs from "./resolveConfiguredGraphs.js";
+
+describe("resolveConfiguredGraphs", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-rcg-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("resolves the default semantic packages' TTL graphs", async () => {
+    // No pragma.config.json in the temp dir → mergeAndParseRefs falls back to
+    // the default packages, which resolve from node_modules in the workspace.
+    const graphs = await resolveConfiguredGraphs(dir);
+
+    expect(graphs.length).toBeGreaterThan(0);
+    expect(graphs[0]).toMatchObject({ format: "turtle" });
+    expect(typeof graphs[0]?.content).toBe("string");
+  });
+});

package/src/domains/shared/resolveConfiguredGraphs.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolve every TTL graph from the semantically-configured packages.
+ *
+ * Reads `pragma.config.json`, merges its `packages` with the global refs
+ * and the built-in defaults (a non-empty `packages` list replaces the set
+ * entirely; an empty or absent list falls back to global refs merged over
+ * the defaults), resolves each package through the loader chain
+ * (local > git > bundled), and returns the union of their definitions/ and
+ * data/ graph content — the same discovery the runtime store performs at
+ * boot, minus the store.
+ *
+ * @note Impure — reads config and package files from disk.
+ *
+ * @param cwd - Working directory used to locate `pragma.config.json`.
+ * @returns The TTL graph content of every resolved package.
+ */
+
+import { readConfig } from "#config";
+import {
+  createBundledLoader,
+  createGitLoader,
+  createLocalLoader,
+} from "./loaders/index.js";
+import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
+import {
+  type GraphContent,
+  resolveSemanticPackages,
+} from "./semanticPackage.js";
+
+export default async function resolveConfiguredGraphs(
+  cwd: string,
+): Promise<GraphContent[]> {
+  const config = readConfig(cwd);
+  const refs = mergeAndParseRefs(config.packages);
+  const packages = await resolveSemanticPackages(refs, [
+    createLocalLoader(),
+    createGitLoader(),
+    createBundledLoader(),
+  ]);
+  return packages.flatMap((pkg) => pkg.graphs);
+}

package/src/domains/shared/runtime.ts

@@ -10,14 +10,8 @@
 
 import type { SourceSpec } from "@canonical/ke";
 import { readConfig } from "#config";
-import {
-  type PackageRef,
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../refs/operations/parseRef.js";
-import readGlobalRefs from "../refs/operations/readGlobalRefs.js";
 import { bootStore } from "./bootStore.js";
-import { DEFAULT_PACKAGES } from "./packages.js";
+import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
 import type { PragmaRuntime } from "./types/index.js";
 
 export type { PragmaRuntime } from "./types/index.js";
@@ -43,7 +37,8 @@ export async function bootPragma(options?: {
   const cwd = options?.cwd ?? process.cwd();
   const config = readConfig(cwd);
 
-  // Merge package refs: project overrides global, both override defaults.
+  // Merge package refs: a non-empty config list replaces global refs and
+  // defaults; otherwise global refs merge over the defaults.
   const refs = options?.sources
     ? undefined
     : mergeAndParseRefs(config.packages);
@@ -53,6 +48,7 @@ export async function bootPragma(options?: {
     sources: options?.sources,
     refs,
     trace: config.trace,
+    prefixes: config.prefixes,
   });
 
   return {
@@ -63,58 +59,3 @@ export async function bootPragma(options?: {
     dispose: () => store.dispose(),
   };
 }
-
-// ---------------------------------------------------------------------------
-// Ref merging
-// ---------------------------------------------------------------------------
-
-/**
- * Merge global refs, project config packages, and defaults into a final
- * parsed PackageRef array.
- *
- * Priority: project packages > global refs > hardcoded defaults.
- * Merging is by package name — a project entry for "@canonical/foo"
- * overrides the global entry for the same package.
- */
-function mergeAndParseRefs(
-  projectPackages?: ReadonlyArray<RawPackageEntry>,
-): PackageRef[] {
-  const globalEntries = readGlobalRefs();
-
-  // If neither project nor global defines packages, return undefined
-  // so resolvePackages() uses hardcoded defaults.
-  if (
-    (!projectPackages || projectPackages.length === 0) &&
-    globalEntries.length === 0
-  ) {
-    return DEFAULT_PACKAGES.map((pkg) => parsePackageEntry(pkg));
-  }
-
-  // Build a name → entry map, global first, project overrides.
-  const merged = new Map<string, RawPackageEntry>();
-
-  // Start with defaults (lowest priority)
-  for (const entry of DEFAULT_PACKAGES) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-
-  // Global overrides defaults
-  for (const entry of globalEntries) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-
-  // Project overrides global
-  if (projectPackages) {
-    // When project explicitly declares packages, it's a full replacement
-    // of the package list — clear defaults and global, use project only.
-    merged.clear();
-    for (const entry of projectPackages) {
-      const name = typeof entry === "string" ? entry : entry.name;
-      merged.set(name, entry);
-    }
-  }
-
-  return [...merged.values()].map(parsePackageEntry);
-}

package/src/domains/shared/semanticPackage.ts

@@ -24,7 +24,18 @@ export interface GraphContent {
   readonly format: "turtle";
 }
 
-/** A discovered skill directory with its filesystem path. */
+/** A discovered story-pack JSON file with its content. */
+export interface StoryFileEntry {
+  /**
+   * Original file path, or a virtual identifier for embedded sources
+   * (e.g. `(bundled)/…`) — for provenance/debugging, not guaranteed to
+   * exist on disk.
+   */
+  readonly path: string;
+  /** The file's parsed JSON — validated by the story-pack compiler. */
+  readonly definition: unknown;
+}
+
 export interface SkillEntry {
   /** Absolute path to the skill directory (must exist on disk for symlinking). */
   readonly dir: string;
@@ -44,6 +55,11 @@ export interface SemanticPackage {
   readonly graphs: GraphContent[];
   /** Skills available in this package. */
   readonly skills: SkillEntry[];
+  /**
+   * Raw story-pack files shipped by this package (`stories/*.json`).
+   * Parsed JSON, validated at compile time so one bad file cannot break boot.
+   */
+  readonly stories: StoryFileEntry[];
 }
 
 /**

package/src/domains/shared/stories/compileLookupCommand.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../context.js";
+import type { LookupResult } from "../contracts.js";
+import compileLookupCommand from "./compileLookupCommand.js";
+import type { LookupStory } from "./types.js";
+
+interface FakeEntity {
+  readonly name: string;
+  readonly detail: string;
+}
+
+function makeStory(
+  overrides: Partial<LookupStory<FakeEntity, string>> = {},
+): LookupStory<FakeEntity, string> {
+  return {
+    noun: "thing",
+    description: "Look up things",
+    toolDescription: "Look up things over MCP.",
+    namesDescription: "Thing names",
+    detailedParam: { description: "Show details" },
+    examples: ["pragma thing lookup a"],
+    resolve: async (_rt, names) => {
+      const results = names
+        .filter((name) => name !== "missing")
+        .map((name) => ({ name, detail: `detail-${name}` }));
+      const errors: LookupResult<FakeEntity>["errors"] = names
+        .filter((name) => name === "missing")
+        .map((name) => ({
+          query: name,
+          code: "ENTITY_NOT_FOUND",
+          message: `thing "${name}" not found.`,
+        }));
+      return { results, errors };
+    },
+    toFmtInput: (entity, view) =>
+      view.detailed ? `${entity.name}:${entity.detail}` : entity.name,
+    formatters: {
+      plain: (text) => `plain:${text}`,
+      llm: (text) => `llm:${text}`,
+      json: (text) => JSON.stringify(text),
+    },
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: "/tmp",
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    ...overrides,
+  } as PragmaContext;
+}
+
+async function executeText(
+  story: LookupStory<FakeEntity, string>,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<string> {
+  const cmd = compileLookupCommand(ctx, story);
+  const result = await cmd.execute(params, ctx);
+  if (result.tag !== "output") throw new Error("expected output result");
+  return result.render.plain(result.value);
+}
+
+describe("compileLookupCommand", () => {
+  it("projects names, detailed, and extra parameters", () => {
+    const story = makeStory({
+      params: [
+        { name: "extra", type: "boolean", description: "extra flag" },
+        { name: "mcpOnly", type: "boolean", description: "x", surfaces: "mcp" },
+      ],
+      parameterGroups: { Extras: ["extra"] },
+    });
+    const cmd = compileLookupCommand(makeCtx(), story);
+    expect(cmd.path).toEqual(["thing", "lookup"]);
+    expect(cmd.parameters.map((p) => p.name)).toEqual([
+      "names",
+      "detailed",
+      "extra",
+    ]);
+    const names = cmd.parameters.at(0);
+    expect(names?.type).toBe("multiselect");
+    expect(names?.positional).toBe(true);
+    expect(names?.required).toBe(true);
+    expect(cmd.parameterGroups).toEqual({ Extras: ["extra"] });
+  });
+
+  it("omits the detailed parameter when the story has none", () => {
+    const cmd = compileLookupCommand(
+      makeCtx(),
+      makeStory({ detailedParam: undefined }),
+    );
+    expect(cmd.parameters.map((p) => p.name)).toEqual(["names"]);
+  });
+
+  it("renders each result and appends an errors section", async () => {
+    const text = await executeText(
+      makeStory(),
+      { names: ["a", "missing"] },
+      makeCtx(),
+    );
+    expect(text).toContain("plain:a");
+    expect(text).toContain("Errors:");
+    expect(text).toContain('thing "missing" not found.');
+  });
+
+  it("is summary by default and detailed with the flag", async () => {
+    const summary = await executeText(makeStory(), { names: ["a"] }, makeCtx());
+    expect(summary).toBe("plain:a");
+
+    const detailed = await executeText(
+      makeStory(),
+      { names: ["a"], detailed: true },
+      makeCtx(),
+    );
+    expect(detailed).toBe("plain:a:detail-a");
+  });
+
+  it("accepts the legacy single name parameter", async () => {
+    const text = await executeText(makeStory(), { name: "a" }, makeCtx());
+    expect(text).toBe("plain:a");
+  });
+
+  it("throws the story's empty-names error when no names are given", async () => {
+    const story = makeStory({
+      emptyNamesError: () => PragmaError.invalidInput("names", "(empty)"),
+    });
+    const cmd = compileLookupCommand(makeCtx(), story);
+    await expect(cmd.execute({ names: [] }, makeCtx())).rejects.toThrow(
+      PragmaError,
+    );
+  });
+
+  it("exposes an ink renderer only when the story defines one", async () => {
+    const story = makeStory({
+      renderInk: (result, view) =>
+        `ink:${result.results.length}:${view.detailed}`,
+    });
+    const cmd = compileLookupCommand(makeCtx(), story);
+    const result = await cmd.execute({ names: ["a"] }, makeCtx());
+    if (result.tag !== "output") throw new Error("expected output result");
+    expect(result.render.ink?.(result.value)).toBe("ink:1:false");
+  });
+});