@canonical/pragma-cli 0.30.0 → 0.32.0

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

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

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

@@ -1,146 +0,0 @@
-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"]);
-  });
-});

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

@@ -1,253 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { PragmaError } from "#error";
-import type {
-  ColumnDef,
-  LookupField,
-  RenderListOptions,
-  RenderLookupOptions,
-  SectionDef,
-} from "../../contracts.js";
-import type { Formatters } from "../../formatters.js";
-import lookupMany from "../../lookupMany.js";
-import {
-  renderListLlm,
-  renderListPlain,
-  renderLookupLlm,
-  renderLookupPlain,
-} from "../../renderers.js";
-import { suggestNames } from "../../suggestions/index.js";
-import requirePragmaContext from "../requirePragmaContext.js";
-import type { LookupStory, ReadStory, StoryParam } from "../types.js";
-import applyPackFilters from "./applyPackFilters.js";
-import buildLookupQuery, { buildLookupNamesQuery } from "./buildLookupQuery.js";
-import runSelectQuery from "./runSelectQuery.js";
-import type {
-  StoryPackDefinition,
-  StoryPackFilter,
-  StoryPackLookup,
-} from "./types.js";
-
-/** A pack entity/row: SELECT variable name → string value. */
-type PackRow = Record<string, string>;
-
-/** The read stories a pack definition compiles to. */
-export interface CompiledPackStories {
-  readonly list: ReadStory<PackRow[], PackRow[]>;
-  readonly lookup?: LookupStory<PackRow, PackRow>;
-}
-
-/**
- * Compile one validated story-pack definition into kernel read stories.
- *
- * The list story runs the pack's preferred SELECT verbatim; the lookup
- * story runs the generated, injection-safe per-name query. Both render
- * through the shared generic renderers with the runtime's merged prefix
- * map, so foreign namespaces display compacted.
- *
- * @param definition - A validated pack definition.
- * @param source - Where the definition came from, for diagnostics.
- * @param prefixes - The merged prefix map used for display.
- * @returns The compiled list story and, when declared, the lookup story.
- */
-export default function compilePackStories(
-  definition: StoryPackDefinition,
-  source: string,
-  prefixes: Readonly<Record<string, string>>,
-): CompiledPackStories {
-  const { noun } = definition;
-  const heading = capitalize(noun);
-  const description = definition.description ?? `List ${noun} entries`;
-
-  const listColumns: ColumnDef<PackRow>[] = definition.list.columns.map(
-    (column) => ({
-      key: column.field,
-      label: column.label ?? column.field,
-    }),
-  );
-  const listOptions: RenderListOptions<PackRow> = {
-    heading,
-    columns: listColumns,
-    prefixes,
-  };
-  const listFormatters: Formatters<PackRow[]> = {
-    plain: (rows) => renderListPlain(rows, listOptions),
-    llm: (rows) => renderListLlm(rows, listOptions),
-    json: (rows) => JSON.stringify(rows, null, 2),
-  };
-
-  const filters = definition.list.filters;
-  const filterExample = filters?.at(0);
-  const list: ReadStory<PackRow[], PackRow[]> = {
-    noun,
-    verb: "list",
-    description,
-    toolDescription:
-      definition.toolDescription ?? `${description} (story pack: ${source}).`,
-    params: projectFilterParams(filters),
-    examples: [
-      `pragma ${noun} list`,
-      ...(filterExample
-        ? [
-            `pragma ${noun} list --${filterExample.param} ${quoteExampleValue(filterExample.values.at(0) ?? "")}`,
-          ]
-        : []),
-      `pragma ${noun} list --llm`,
-    ],
-    resolve: async (rt, params) =>
-      applyPackFilters(
-        await runSelectQuery(rt.store, definition.list.query, source),
-        filters,
-        params,
-      ),
-    toOutput: (rows) => rows,
-    formatters: listFormatters,
-    toEnvelope: (rows) => ({ data: rows, meta: { count: rows.length } }),
-  };
-
-  const lookup = definition.lookup
-    ? compileLookup(definition.lookup, noun, source, prefixes)
-    : undefined;
-
-  return { list, ...(lookup ? { lookup } : {}) };
-}
-
-function compileLookup(
-  lookup: StoryPackLookup,
-  noun: string,
-  source: string,
-  prefixes: Readonly<Record<string, string>>,
-): LookupStory<PackRow, PackRow> {
-  const fields: LookupField<PackRow>[] = (lookup.fields ?? []).map((field) => ({
-    label: field.label ?? field.name,
-    value: (entity) => entity[field.name],
-  }));
-  const sections: SectionDef<PackRow>[] = (lookup.sections ?? []).map(
-    (section) => ({
-      key: section.name,
-      heading: section.label ?? section.name,
-      kind: section.kind ?? "field",
-    }),
-  );
-  const lookupOptions: RenderLookupOptions<PackRow> = {
-    title: (entity) => entity.name ?? entity.uri ?? "(unnamed)",
-    fields,
-    sections,
-    prefixes,
-  };
-  const lookupFormatters: Formatters<PackRow> = {
-    plain: (entity) => renderLookupPlain(entity, lookupOptions),
-    llm: (entity) => renderLookupLlm(entity, lookupOptions),
-    json: (entity) => JSON.stringify(entity, null, 2),
-  };
-
-  return {
-    noun,
-    description: `Look up ${noun} details by name`,
-    toolDescription: `Get details for one or more ${noun} entries by name (story pack: ${source}).`,
-    namesDescription: `${capitalize(noun)} names`,
-    complete: async (partial, cmdCtx) => {
-      const ctx = requirePragmaContext(cmdCtx);
-      const names = await listEntityNames(ctx.store, lookup, source);
-      return names.filter((name) =>
-        name.toLowerCase().startsWith(partial.toLowerCase()),
-      );
-    },
-    examples: [`pragma ${noun} lookup <name>`],
-    resolve: (rt, names) =>
-      lookupMany(names, (query) =>
-        lookupPackEntity(rt.store, lookup, noun, query, source),
-      ),
-    toFmtInput: (entity) => entity,
-    formatters: lookupFormatters,
-    emptyNamesError: () =>
-      PragmaError.invalidInput("names", "(empty)", {
-        recovery: {
-          message: `List available ${noun} entries.`,
-          cli: `pragma ${noun} list`,
-          mcp: { tool: `${noun}_list` },
-        },
-      }),
-  };
-}
-
-/**
- * Look up one pack entity by name via the generated query.
- *
- * @throws PragmaError with code `ENTITY_NOT_FOUND` and ranked suggestions
- *   when no entity matches.
- * @note Impure — queries the ke store.
- */
-async function lookupPackEntity(
-  store: Store,
-  lookup: StoryPackLookup,
-  noun: string,
-  query: string,
-  source: string,
-): Promise<PackRow> {
-  const rows = await runSelectQuery(
-    store,
-    buildLookupQuery(lookup, query),
-    source,
-  );
-  const entity = rows.at(0);
-  if (entity) {
-    return entity;
-  }
-
-  const candidates = await listEntityNames(store, 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` },
-    },
-  });
-}
-
-async function listEntityNames(
-  store: Store,
-  lookup: StoryPackLookup,
-  source: string,
-): Promise<string[]> {
-  const rows = await runSelectQuery(
-    store,
-    buildLookupNamesQuery(lookup),
-    source,
-  );
-  return rows.map((row) => row.name ?? "").filter((name) => name !== "");
-}
-
-/**
- * Quote a filter value for a shell help example when it is not a bare word.
- *
- * Values with whitespace or shell-sensitive characters are double-quoted
- * so the generated `pragma … list --flag value` example stays valid to
- * copy-paste; simple tokens render unquoted.
- */
-function quoteExampleValue(value: string): string {
-  return /^[\w.-]+$/.test(value) ? value : JSON.stringify(value);
-}
-
-/**
- * Project declared pack filters onto kernel story parameters.
- *
- * The declared value set becomes the parameter's enum, which the kernel
- * projects to CLI select choices and an MCP enum schema.
- */
-function projectFilterParams(
-  filters: readonly StoryPackFilter[] | undefined,
-): StoryParam[] {
-  return (filters ?? []).map((filter) => ({
-    name: filter.param,
-    type: "string",
-    description:
-      filter.description ??
-      `Filter by ${filter.variable} (${filter.values.join(", ")})`,
-    enum: filter.values,
-  }));
-}
-
-function capitalize(value: string): string {
-  return value.charAt(0).toUpperCase() + value.slice(1);
-}

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

@@ -1,43 +0,0 @@
-import { PREFIX_MAP } 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";
-
-/**
- * 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`, registered alongside
- * the built-in tools.
- *
- * @param runtime - Pragma runtime carrying config, packages, and the store.
- * @param reservedNouns - Built-in nouns packs must not shadow.
- * @returns Tool specs for every pack story.
- */
-export default function compilePackToolSpecs(
-  runtime: PragmaRuntime,
-  reservedNouns: ReadonlySet<string>,
-): ToolSpec[] {
-  const prefixes = { ...PREFIX_MAP, ...runtime.config.prefixes };
-  const entries = collectPackStories(
-    runtime.config,
-    runtime.packages,
-    reservedNouns,
-  );
-
-  return entries.flatMap((entry) => {
-    const compiled = compilePackStories(
-      entry.definition,
-      entry.source,
-      prefixes,
-    );
-    const specs = [compileReadTool(compiled.list)];
-    if (compiled.lookup) {
-      specs.push(compileLookupTool(compiled.lookup));
-    }
-    return specs;
-  });
-}

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

@@ -1,28 +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 { default as runSelectQuery } from "./runSelectQuery.js";
-export type {
-  StoryPackColumn,
-  StoryPackDefinition,
-  StoryPackField,
-  StoryPackList,
-  StoryPackLookup,
-  StoryPackSection,
-  StoryPackSource,
-} from "./types.js";
-export { default as validateStoryPackDefinition } from "./validateStoryPackDefinition.js";

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;
-}