@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

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

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import applyPackFilters from "./applyPackFilters.js";
+import type { StoryPackFilter } from "./types.js";
+
+const ROWS = [
+  { name: "Gazpacho", category: "soup" },
+  { name: "Pancakes", category: "breakfast" },
+];
+const FILTERS: StoryPackFilter[] = [
+  { param: "category", variable: "category", values: ["breakfast", "soup"] },
+];
+
+describe("applyPackFilters", () => {
+  it("returns rows unchanged when no filter value is provided", () => {
+    expect(applyPackFilters(ROWS, FILTERS, {})).toEqual(ROWS);
+  });
+
+  it("returns rows unchanged when no filters are declared", () => {
+    expect(applyPackFilters(ROWS, undefined, { category: "soup" })).toEqual(
+      ROWS,
+    );
+  });
+
+  it("keeps only rows matching the provided value", () => {
+    const rows = applyPackFilters(ROWS, FILTERS, { category: "soup" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("rejects values outside the declared set", () => {
+    expect(() =>
+      applyPackFilters(ROWS, FILTERS, { category: "dinner" }),
+    ).toThrowError(PragmaError);
+    try {
+      applyPackFilters(ROWS, FILTERS, { category: "dinner" });
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+      expect((error as PragmaError).recovery?.message).toContain("breakfast");
+    }
+  });
+
+  it("rejects non-string values and suggests the declared set", () => {
+    expect(() => applyPackFilters(ROWS, FILTERS, { category: 3 })).toThrowError(
+      PragmaError,
+    );
+    try {
+      applyPackFilters(ROWS, FILTERS, { category: ["soup"] });
+    } catch (error) {
+      expect((error as PragmaError).validOptions).toEqual([
+        "breakfast",
+        "soup",
+      ]);
+    }
+  });
+
+  it("canonicalizes case-insensitive input to the declared value", () => {
+    const rows = applyPackFilters(ROWS, FILTERS, { category: "SOUP" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("trims surrounding whitespace from the provided value", () => {
+    const rows = applyPackFilters(ROWS, FILTERS, { category: "  soup " });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("matches unicode values across NFC/NFD normalization forms", () => {
+    const filters: StoryPackFilter[] = [
+      { param: "kind", variable: "kind", values: ["entr\u00e9e"] },
+    ];
+    const rows = [{ name: "Salad", kind: "entre\u0301e" }];
+    expect(
+      applyPackFilters(rows, filters, { kind: "entre\u0301e" }),
+    ).toHaveLength(1);
+  });
+
+  it("never matches rows without a binding for the variable", () => {
+    const rows = [{ name: "Mystery" }, ...ROWS];
+    const filtered = applyPackFilters(rows, FILTERS, { category: "soup" });
+    expect(filtered.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("carries the declared values as valid options on rejection", () => {
+    try {
+      applyPackFilters(ROWS, FILTERS, { category: "sopu" });
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+      expect((error as PragmaError).validOptions).toContain("soup");
+    }
+  });
+
+  it("applies several filters conjunctively", () => {
+    const filters: StoryPackFilter[] = [
+      ...FILTERS,
+      { param: "name", variable: "name", values: ["Gazpacho", "Pancakes"] },
+    ];
+    const rows = applyPackFilters(ROWS, filters, {
+      category: "soup",
+      name: "Pancakes",
+    });
+    expect(rows).toEqual([]);
+  });
+});

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

@@ -0,0 +1,76 @@
+import { PragmaError } from "#error";
+import type { StoryPackFilter } from "./types.js";
+
+/**
+ * Apply declared pack filters to resolved list rows.
+ *
+ * Filters are row predicates on projected SELECT variables — the author
+ * query is never modified, so user input cannot inject SPARQL and the
+ * 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.
+ * - A row without a binding for the variable (e.g. from OPTIONAL) never
+ *   matches an active filter.
+ * - Several provided filters combine conjunctively.
+ *
+ * @param rows - Rows produced by the pack's list query.
+ * @param filters - Declared filters (absent means no filtering).
+ * @param params - Story parameters as provided by the surface.
+ * @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.
+ */
+export default function applyPackFilters(
+  rows: Record<string, string>[],
+  filters: readonly StoryPackFilter[] | undefined,
+  params: Record<string, unknown>,
+): Record<string, string>[] {
+  // Start from the caller's array; each active filter's `.filter()` yields a
+  // fresh array, so with no active filter the rows pass through unmodified —
+  // no defensive clone (the caller owns the query result).
+  let result = rows;
+  for (const filter of filters ?? []) {
+    const provided = params[filter.param];
+    if (provided === undefined) continue;
+    const canonical = canonicalizeFilterValue(provided, filter);
+    result = result.filter(
+      (row) => row[filter.variable]?.normalize("NFC") === canonical,
+    );
+  }
+  return result;
+}
+
+/**
+ * Resolve a provided filter value to its declared canonical form.
+ *
+ * @throws PragmaError with code `INVALID_INPUT` when the value is not a
+ *         string or not in the declared set.
+ */
+function canonicalizeFilterValue(
+  provided: unknown,
+  filter: StoryPackFilter,
+): string {
+  if (typeof provided === "string") {
+    const normalized = provided.trim().normalize("NFC");
+    const match = filter.values.find(
+      (value) =>
+        value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
+    );
+    if (match !== undefined) {
+      return match.normalize("NFC");
+    }
+  }
+  throw PragmaError.invalidInput(filter.param, String(provided), {
+    validOptions: [...filter.values],
+    recovery: {
+      message: `Allowed values for --${filter.param}: ${filter.values.join(", ")}.`,
+    },
+  });
+}

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import buildLookupQuery, {
+  buildLookupNamesQuery,
+  escapeSparqlString,
+  formatTerm,
+} from "./buildLookupQuery.js";
+
+describe("escapeSparqlString", () => {
+  it("escapes quotes, backslashes, and newlines", () => {
+    expect(escapeSparqlString('a"b\\c\nd')).toBe('a\\"b\\\\c\\nd');
+  });
+});
+
+describe("formatTerm", () => {
+  it("keeps prefixed names and wraps absolute IRIs", () => {
+    expect(formatTerm("ex:Recipe")).toBe("ex:Recipe");
+    expect(formatTerm("http://example.org/x")).toBe("<http://example.org/x>");
+  });
+});
+
+describe("buildLookupQuery", () => {
+  it("generates a typed, escaped, case-insensitive match", () => {
+    const query = buildLookupQuery(
+      {
+        by: "ex:name",
+        type: "ex:Recipe",
+        fields: [{ name: "category", property: "ex:category" }],
+      },
+      'Pan"cakes',
+    );
+    expect(query).toContain("?uri ex:name ?name .");
+    expect(query).toContain("?uri a ex:Recipe .");
+    expect(query).toContain("OPTIONAL { ?uri ex:category ?category . }");
+    expect(query).toContain('LCASE("Pan\\"cakes")');
+    expect(query).toContain("LIMIT 1");
+  });
+
+  it("omits the type constraint when absent", () => {
+    const query = buildLookupQuery({ by: "ex:name" }, "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" });
+    expect(query).toContain("SELECT ?name WHERE {");
+    expect(query).toContain("?uri ex:name ?name .");
+    expect(query).toContain("?uri a ex:Recipe .");
+  });
+});

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

@@ -0,0 +1,80 @@
+import type { StoryPackLookup } from "./types.js";
+
+/**
+ * Build the generated, injection-safe lookup queries for a pack story.
+ *
+ * Pack authors declare *what* names an entity (`by`, optional `type`) and
+ * which properties to read; the query text is generated here so
+ * user-supplied names are always escaped SPARQL string literals — a pack
+ * definition never interpolates user input itself. Matching is exact and
+ * case-insensitive on the `by` property's string value.
+ */
+
+/** Escape a user-supplied value as a SPARQL string literal body. */
+export function escapeSparqlString(value: string): string {
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r");
+}
+
+/** Render a validated term (prefixed name or absolute IRI) as a query token. */
+export function formatTerm(term: string): string {
+  return term.includes("://") ? `<${term}>` : term;
+}
+
+/**
+ * Build the SELECT retrieving one named entity with its declared fields.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param name - User-supplied entity name (escaped here).
+ * @returns SPARQL SELECT text.
+ */
+export default function buildLookupQuery(
+  lookup: StoryPackLookup,
+  name: 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 {`,
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    typeConstraint + optionals,
+    `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+    "}",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the SELECT listing all entity names — lookup-miss suggestions.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @returns SPARQL SELECT text yielding a `?name` per entity.
+ */
+export function buildLookupNamesQuery(lookup: StoryPackLookup): string {
+  const typeConstraint = lookup.type
+    ? `  ?uri a ${formatTerm(lookup.type)} .\n`
+    : "";
+  return [
+    "SELECT ?name WHERE {",
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    typeConstraint.trimEnd(),
+    "}",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}

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

@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PragmaError } from "#error";
+import { RECIPE_STORY } from "#testing";
+import type { SemanticPackage } from "../../semanticPackage.js";
+import collectPackStories from "./collectPackStories.js";
+
+function makePackage(stories: SemanticPackage["stories"]): SemanticPackage {
+  return {
+    name: "@canonical/example",
+    version: "1.0.0",
+    source: "local",
+    graphs: [],
+    skills: [],
+    stories,
+  };
+}
+
+const CONFIG = { tier: undefined, channel: "normal" as const };
+
+describe("collectPackStories", () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warn = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it("collects config stories and validated package stories", () => {
+    const entries = collectPackStories(
+      { ...CONFIG, stories: [RECIPE_STORY] },
+      [
+        makePackage([
+          {
+            path: "/pkg/stories/other.json",
+            definition: { ...RECIPE_STORY, noun: "other" },
+          },
+        ]),
+      ],
+      new Set(["block"]),
+    );
+    expect(entries.map((entry) => entry.definition.noun)).toEqual([
+      "recipe",
+      "other",
+    ]);
+    expect(entries.at(0)?.source).toBe("config");
+    expect(entries.at(1)?.source).toBe("/pkg/stories/other.json");
+  });
+
+  it("lets config stories win noun collisions against packages", () => {
+    const entries = collectPackStories(
+      { ...CONFIG, stories: [RECIPE_STORY] },
+      [
+        makePackage([
+          { path: "/pkg/stories/recipe.json", definition: RECIPE_STORY },
+        ]),
+      ],
+      new Set(),
+    );
+    expect(entries).toHaveLength(1);
+    expect(entries.at(0)?.source).toBe("config");
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("already taken"));
+  });
+
+  it("skips invalid package stories with a warning", () => {
+    const entries = collectPackStories(
+      CONFIG,
+      [
+        makePackage([
+          { path: "/pkg/stories/broken.json", definition: { nope: true } },
+        ]),
+      ],
+      new Set(),
+    );
+    expect(entries).toHaveLength(0);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("skipping story"),
+    );
+  });
+
+  it("throws when a config story shadows a built-in noun", () => {
+    expect(() =>
+      collectPackStories(
+        { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "block" }] },
+        [],
+        new Set(["block"]),
+      ),
+    ).toThrow(PragmaError);
+  });
+
+  it("skips package stories that shadow built-in nouns", () => {
+    const entries = collectPackStories(
+      CONFIG,
+      [
+        makePackage([
+          {
+            path: "/pkg/stories/block.json",
+            definition: { ...RECIPE_STORY, noun: "block" },
+          },
+        ]),
+      ],
+      new Set(["block"]),
+    );
+    expect(entries).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,76 @@
+import type { PragmaConfig } from "#config";
+import { PragmaError } from "#error";
+import type { SemanticPackage } from "../../semanticPackage.js";
+import type { StoryPackDefinition } from "./types.js";
+import validateStoryPackDefinition from "./validateStoryPackDefinition.js";
+
+/** A validated story definition paired with where it was declared. */
+export interface PackStoryEntry {
+  readonly definition: StoryPackDefinition;
+  readonly source: string;
+}
+
+/**
+ * Gather the story-pack definitions active for a runtime.
+ *
+ * Config-declared stories come first (already validated by the config
+ * parser) and win noun collisions against package-shipped ones — the
+ * config is the user's override layer. Package story files are validated
+ * here; an invalid or colliding package story is skipped with a warning
+ * so one bad file cannot break boot. A config story colliding with a
+ * reserved (built-in) noun is a hard config error.
+ *
+ * @param config - The effective merged configuration.
+ * @param packages - Resolved semantic packages (may ship `stories/*.json`).
+ * @param reservedNouns - Built-in nouns story packs must not shadow.
+ * @returns Validated, collision-free story entries.
+ * @throws PragmaError with code `CONFIG_ERROR` when a config story shadows
+ *   a reserved noun.
+ * @note Impure — warns on stderr for skipped package stories.
+ */
+export default function collectPackStories(
+  config: PragmaConfig,
+  packages: readonly SemanticPackage[],
+  reservedNouns: ReadonlySet<string>,
+): PackStoryEntry[] {
+  const entries: PackStoryEntry[] = [];
+  const taken = new Set<string>();
+
+  for (const definition of config.stories ?? []) {
+    if (reservedNouns.has(definition.noun)) {
+      throw PragmaError.configError(
+        `Story noun "${definition.noun}" shadows a built-in command.`,
+      );
+    }
+    if (taken.has(definition.noun)) {
+      throw PragmaError.configError(
+        `Duplicate story noun "${definition.noun}" in config.`,
+      );
+    }
+    taken.add(definition.noun);
+    entries.push({ definition, source: "config" });
+  }
+
+  for (const pkg of packages) {
+    for (const file of pkg.stories) {
+      let definition: StoryPackDefinition;
+      try {
+        definition = validateStoryPackDefinition(file.definition, file.path);
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Warning: skipping story — ${reason}\n`);
+        continue;
+      }
+      if (reservedNouns.has(definition.noun) || taken.has(definition.noun)) {
+        process.stderr.write(
+          `Warning: skipping story "${definition.noun}" from ${file.path} — the noun is already taken.\n`,
+        );
+        continue;
+      }
+      taken.add(definition.noun);
+      entries.push({ definition, source: file.path });
+    }
+  }
+
+  return entries;
+}

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

@@ -0,0 +1,40 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../../context.js";
+import { PREFIX_MAP } from "../../prefixes.js";
+import compileLookupCommand from "../compileLookupCommand.js";
+import compileReadCommand from "../compileReadCommand.js";
+import collectPackStories from "./collectPackStories.js";
+import compilePackStories from "./compilePackStories.js";
+
+/**
+ * Compile every active story pack into CLI command definitions.
+ *
+ * Story packs come from the merged config (`stories`) and from resolved
+ * semantic packages (`stories/*.json`); each yields `<noun> list` and,
+ * when declared, `<noun> lookup` — projected through the same kernel as
+ * the built-in read stories, so completions and help come for free.
+ *
+ * @param ctx - Pragma context carrying config, packages, and the store.
+ * @param reservedNouns - Built-in nouns packs must not shadow.
+ * @returns Command definitions for every pack story.
+ */
+export default function compilePackCommands(
+  ctx: PragmaContext,
+  reservedNouns: ReadonlySet<string>,
+): CommandDefinition[] {
+  const prefixes = { ...PREFIX_MAP, ...ctx.config.prefixes };
+  const entries = collectPackStories(ctx.config, ctx.packages, reservedNouns);
+
+  return entries.flatMap((entry) => {
+    const compiled = compilePackStories(
+      entry.definition,
+      entry.source,
+      prefixes,
+    );
+    const commands = [compileReadCommand(ctx, compiled.list)];
+    if (compiled.lookup) {
+      commands.push(compileLookupCommand(ctx, compiled.lookup));
+    }
+    return commands;
+  });
+}

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

@@ -0,0 +1,146 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import {
+  createTestStore,
+  RECIPE_PREFIXES,
+  RECIPE_STORY,
+  RECIPE_TTL,
+} from "#testing";
+import { PREFIX_MAP } from "../../prefixes.js";
+import type { PragmaRuntime } from "../../types/index.js";
+import compilePackStories from "./compilePackStories.js";
+
+const PREFIXES = { ...PREFIX_MAP, ...RECIPE_PREFIXES };
+
+let store: Store;
+let cleanup: () => void;
+let rt: PragmaRuntime;
+
+beforeAll(async () => {
+  const result = await createTestStore({
+    ttl: RECIPE_TTL,
+    prefixes: RECIPE_PREFIXES,
+  });
+  store = result.store;
+  cleanup = result.cleanup;
+  rt = { store } as PragmaRuntime;
+});
+
+afterAll(() => cleanup());
+
+describe("compilePackStories — list", () => {
+  it("resolves the pack's preferred query into rows", async () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const rows = await list.resolve(rt, {});
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho", "Pancakes"]);
+    expect(list.toEnvelope(rows)).toEqual({
+      data: rows,
+      meta: { count: 2 },
+    });
+  });
+
+  it("renders the generic formatters with compacted prefixes", async () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const rows = await list.resolve(rt, {});
+    const plain = list.formatters.plain(rows);
+    expect(plain).toContain("Pancakes");
+    expect(plain).toContain("breakfast");
+    const llm = list.formatters.llm(rows);
+    expect(llm).toContain("## Recipe (2)");
+    expect(llm).toContain("`ex:gazpacho`");
+    expect(JSON.parse(list.formatters.json(rows))).toHaveLength(2);
+  });
+});
+
+describe("compilePackStories — list filters", () => {
+  it("projects declared filters as enum story parameters", () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const param = list.params.at(0);
+    expect(param?.name).toBe("category");
+    expect(param?.type).toBe("string");
+    expect(param?.enum).toEqual(["breakfast", "soup"]);
+  });
+
+  it("filters resolved rows by the provided value", async () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const rows = await list.resolve(rt, { category: "soup" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+    expect(list.toEnvelope(rows).meta).toEqual({ count: 1 });
+  });
+
+  it("canonicalizes case-insensitive input through resolve", async () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const rows = await list.resolve(rt, { category: "SOUP" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("rejects a value outside the declared set with INVALID_INPUT", async () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    await expect(
+      list.resolve(rt, { category: "dinner" }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
+  it("mentions the first filter in the examples", () => {
+    const { list } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    expect(list.examples).toContain("pragma recipe list --category breakfast");
+  });
+});
+
+describe("compilePackStories — lookup", () => {
+  it("looks an entity up by name, case-insensitively", async () => {
+    const { lookup } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const result = await lookup?.resolve(rt, ["pancakes"], {});
+    expect(result?.results).toHaveLength(1);
+    const entity = result?.results.at(0);
+    expect(entity?.name).toBe("Pancakes");
+    expect(entity?.category).toBe("breakfast");
+    expect(entity?.instructions).toBe("Mix, fry, flip.");
+  });
+
+  it("renders fields and sections through the generic lookup renderer", async () => {
+    const { lookup } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const result = await lookup?.resolve(rt, ["Gazpacho"], {});
+    const entity = result?.results.at(0);
+    expect(entity).toBeDefined();
+    if (!entity || !lookup) throw new Error("expected entity");
+    const llm = lookup.formatters.llm(
+      lookup.toFmtInput(entity, {
+        surface: "cli",
+        detailed: false,
+        params: {},
+      }),
+    );
+    expect(llm).toContain("Gazpacho");
+    expect(llm).toContain("soup");
+    expect(llm).toContain("Blend everything cold.");
+  });
+
+  it("collects not-found errors with ranked suggestions", async () => {
+    const { lookup } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const result = await lookup?.resolve(rt, ["Pancake"], {});
+    expect(result?.results).toHaveLength(0);
+    const error = result?.errors.at(0);
+    expect(error?.code).toBe("ENTITY_NOT_FOUND");
+    expect(error?.suggestions).toContain("Pancakes");
+  });
+
+  it("rejects empty names with a recovery hint", () => {
+    const { lookup } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    expect(() => {
+      const error = lookup?.emptyNamesError?.();
+      if (error) throw error;
+    }).toThrow(PragmaError);
+  });
+
+  it("completes names from the store", async () => {
+    const { lookup } = compilePackStories(RECIPE_STORY, "test", PREFIXES);
+    const ctx = {
+      cwd: "/tmp",
+      globalFlags: { llm: false, format: "text" as const, verbose: false },
+      store,
+    };
+    await expect(lookup?.complete?.("pan", ctx)).resolves.toEqual(["Pancakes"]);
+  });
+});