@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,724 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import resolveUri from "../../../graph/helpers/resolveUri.js";
+import type {
+  ColumnDef,
+  LookupField,
+  RenderListOptions,
+  RenderLookupOptions,
+  SectionDef,
+} from "../../contracts.js";
+import type { Formatters } from "../../formatters.js";
+import lookupMany from "../../lookupMany.js";
+import parseSampleCount, {
+  DEFAULT_SAMPLE_COUNT,
+  MAX_SAMPLE_COUNT,
+  MIN_SAMPLE_COUNT,
+} from "../../parseSampleCount.js";
+import pickRandom from "../../pickRandom.js";
+import {
+  renderListLlm,
+  renderListPlain,
+  renderLookupLlm,
+  renderLookupPlain,
+} from "../../renderers.js";
+import createSampleFormatters from "../../sampleFormatters.js";
+import {
+  expandGlob,
+  isGlobPattern,
+  suggestNames,
+} from "../../suggestions/index.js";
+import type { SampleOutput } from "../../types/index.js";
+import requirePragmaContext from "../requirePragmaContext.js";
+import type { LookupStory, ReadStory, StoryParam } from "../types.js";
+import applyPackFilters from "./applyPackFilters.js";
+import applyPackSearch from "./applyPackSearch.js";
+import buildLookupQuery, {
+  buildExpandQuery,
+  buildLookupByIriQuery,
+  buildLookupNamesQuery,
+} from "./buildLookupQuery.js";
+import runSelectQuery from "./runSelectQuery.js";
+import type {
+  StoryPackDefinition,
+  StoryPackDisclosure,
+  StoryPackFilter,
+  StoryPackList,
+  StoryPackLookup,
+  StoryPackSearch,
+} from "./types.js";
+import { isEmbeddableIri } from "./validateStoryPackDefinition.js";
+
+/** A pack entity/row: SELECT variable name → string value. */
+type PackRow = Record<string, string>;
+
+/**
+ * A looked-up pack entity: flat SELECT fields plus any expanded child arrays
+ * (pack v1 nested projections). Scalar fields are strings; an expand's value
+ * is the array of its child rows.
+ */
+type PackEntity = Record<string, string | readonly PackRow[]>;
+
+/** Resolved sample data: the drawn entities plus the population size. */
+interface PackSampleData {
+  readonly samples: PackEntity[];
+  readonly totalCount: number;
+}
+
+/** The read stories a pack definition compiles to. */
+export interface CompiledPackStories {
+  readonly list: ReadStory<PackRow[], PackRow[]>;
+  /** Extra list-shaped verbs (e.g. `categories`), in declaration order. */
+  readonly verbs: readonly ReadStory<PackRow[], PackRow[]>[];
+  readonly lookup?: LookupStory<PackEntity, PackEntity>;
+  /** The `sample` story, when the lookup declares the capability. */
+  readonly sample?: ReadStory<PackSampleData, SampleOutput<PackEntity>>;
+}
+
+/**
+ * Compile one validated story-pack definition into kernel read stories.
+ *
+ * The list story (and any extra list-shaped verbs) run the pack's
+ * preferred SELECT verbatim; the lookup and sample stories run generated,
+ * injection-safe queries. All 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, extra verbs, and — when declared —
+ *   the lookup and sample stories.
+ */
+export default function compilePackStories(
+  definition: StoryPackDefinition,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): CompiledPackStories {
+  const { noun } = definition;
+  const description = definition.description ?? `List ${noun} entries`;
+
+  const list = compileListVerb(definition.list, {
+    noun,
+    verb: "list",
+    heading: capitalize(noun),
+    description,
+    toolDescription:
+      definition.toolDescription ?? `${description} (story pack: ${source}).`,
+    source,
+    prefixes,
+  });
+
+  const verbs = (definition.verbs ?? []).map((verb) => {
+    const verbDescription = verb.description ?? `List ${noun} ${verb.verb}`;
+    return compileListVerb(verb, {
+      noun,
+      verb: verb.verb,
+      heading: `${capitalize(noun)} ${verb.verb}`,
+      description: verbDescription,
+      toolDescription:
+        verb.toolDescription ?? `${verbDescription} (story pack: ${source}).`,
+      source,
+      prefixes,
+    });
+  });
+
+  const compiled = definition.lookup
+    ? compileLookup(definition.lookup, noun, source, prefixes)
+    : undefined;
+
+  return {
+    list,
+    verbs,
+    ...(compiled ? { lookup: compiled.lookup } : {}),
+    ...(compiled?.sample ? { sample: compiled.sample } : {}),
+  };
+}
+
+/** Presentation facts for one compiled list-shaped verb. */
+interface ListVerbMeta {
+  readonly noun: string;
+  readonly verb: string;
+  readonly heading: string;
+  readonly description: string;
+  readonly toolDescription: string;
+  readonly source: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+/**
+ * Compile one list-shaped story half (the `list` verb or an extra verb)
+ * into a kernel read story.
+ */
+function compileListVerb(
+  shape: StoryPackList,
+  meta: ListVerbMeta,
+): ReadStory<PackRow[], PackRow[]> {
+  const { noun, verb, source, prefixes } = meta;
+  const listColumns: ColumnDef<PackRow>[] = shape.columns.map((column) => ({
+    key: column.field,
+    label: column.label ?? column.field,
+  }));
+  const listOptions: RenderListOptions<PackRow> = {
+    heading: meta.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 = shape.filters;
+  const search = shape.search;
+  // The generated example uses the first filter with a declared value set —
+  // a value-free filter has no representative value to show.
+  const filterExample = filters?.find((filter) => filter.values !== undefined);
+  return {
+    noun,
+    verb,
+    description: meta.description,
+    toolDescription: meta.toolDescription,
+    params: [...projectFilterParams(filters), ...projectSearchParam(search)],
+    examples: [
+      `pragma ${noun} ${verb}`,
+      ...(filterExample
+        ? [
+            `pragma ${noun} ${verb} --${filterExample.param} ${quoteExampleValue(filterExample.values?.at(0) ?? "")}`,
+          ]
+        : []),
+      `pragma ${noun} ${verb} --llm`,
+    ],
+    resolve: async (rt, params) =>
+      applyPackSearch(
+        applyPackFilters(
+          await runSelectQuery(rt.store, shape.query, source),
+          filters,
+          params,
+        ),
+        search,
+        params,
+      ),
+    toOutput: (rows) => rows,
+    formatters: listFormatters,
+    toEnvelope: (rows) => ({ data: rows, meta: { count: rows.length } }),
+  };
+}
+
+function compileLookup(
+  lookup: StoryPackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): {
+  lookup: LookupStory<PackEntity, PackEntity>;
+  sample?: ReadStory<PackSampleData, SampleOutput<PackEntity>>;
+} {
+  const fields: LookupField<PackEntity>[] = (lookup.fields ?? []).map(
+    (field) => ({
+      label: field.label ?? field.name,
+      value: (entity) => entity[field.name],
+    }),
+  );
+  const flatSections: SectionDef<PackEntity>[] = (lookup.sections ?? []).map(
+    (section) => ({
+      key: section.name,
+      heading: section.label ?? section.name,
+      kind: section.kind ?? "field",
+    }),
+  );
+  // Expands render after the flat sections, as list/table collections.
+  const expandSections: SectionDef<PackEntity>[] = (lookup.expand ?? []).map(
+    (expand) => ({
+      key: expand.name,
+      heading: expand.heading ?? expand.name,
+      kind: expand.kind ?? "list",
+      ...(expand.showWhenEmpty ? { showWhenEmpty: true } : {}),
+    }),
+  );
+  const sections = [...flatSections, ...expandSections];
+  const lookupOptions: RenderLookupOptions<PackEntity> = {
+    title: (entity) => scalar(entity.name) ?? scalar(entity.uri) ?? "(unnamed)",
+    fields,
+    sections,
+    prefixes,
+  };
+  const lookupFormatters: Formatters<PackEntity> = {
+    plain: (entity) => renderLookupPlain(entity, lookupOptions),
+    llm: (entity) => renderLookupLlm(entity, lookupOptions),
+    json: (entity) => JSON.stringify(entity, null, 2),
+  };
+
+  // Disclosure capability: a declared level set derives a `--detail <level>`
+  // parameter (enum of the levels) on both surfaces, plus one legacy alias
+  // boolean per non-base level (`--digest`, `--detailed`) that implies its
+  // level — preserving the pre-pack flag ergonomics on both surfaces.
+  const disclosure = lookup.disclosure;
+  const detailParams: StoryParam[] = disclosure
+    ? [
+        {
+          name: "detail",
+          type: "string",
+          description: `Disclosure level (${disclosure.levels.join(", ")})`,
+          enum: [...disclosure.levels],
+        },
+        ...disclosure.levels.slice(1).map(
+          (level): StoryParam => ({
+            name: level,
+            type: "boolean",
+            description: `Shorthand for --detail ${level}`,
+            toolDescription: `Shorthand for detail="${level}"`,
+            default: false,
+          }),
+        ),
+      ]
+    : [];
+
+  const lookupStory: LookupStory<PackEntity, PackEntity> = {
+    noun,
+    description:
+      lookup.description ?? `Look up ${noun} details by name, IRI, or glob`,
+    toolDescription:
+      lookup.toolDescription ??
+      `Get details for one or more ${noun} entries by name, prefixed name (ex:thing), absolute IRI, or glob pattern (story pack: ${source}).`,
+    namesDescription: `${capitalize(noun)} names, IRIs/prefixed names, or glob patterns`,
+    params: detailParams,
+    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: async (rt, names, params, view) => {
+      const level = disclosure
+        ? resolveDetailLevel(
+            params,
+            rt.config ?? {},
+            disclosure,
+            view?.surface ?? "cli",
+          )
+        : undefined;
+      // Glob queries (`react/*`) expand against the entity name list before
+      // resolution; a glob matching nothing becomes its own error entry.
+      const expanded = await expandPackLookupQueries(
+        rt.store,
+        lookup,
+        noun,
+        source,
+        names,
+      );
+      const result = await lookupMany(expanded.names, (query) =>
+        lookupPackEntity(
+          rt.store,
+          lookup,
+          noun,
+          query,
+          source,
+          level,
+          prefixes,
+        ),
+      );
+      return {
+        ...result,
+        errors: [...result.errors, ...expanded.globErrors],
+      };
+    },
+    toFmtInput: (entity) => entity,
+    formatters: lookupFormatters,
+    emptyNamesError: () =>
+      PragmaError.invalidInput("names", "(empty)", {
+        recovery: {
+          message: `List available ${noun} entries.`,
+          cli: `pragma ${noun} list`,
+          mcp: { tool: `${noun}_list` },
+        },
+      }),
+  };
+
+  const sample = lookup.sample
+    ? compileSample(lookup, noun, source, prefixes, lookupFormatters)
+    : undefined;
+
+  return { lookup: lookupStory, ...(sample ? { sample } : {}) };
+}
+
+/**
+ * Compile the `sample` story for a lookup that declares the capability.
+ *
+ * Draws N random entity names (clamped 1–5) and resolves each through the
+ * SAME lookup path at the HIGHEST disclosure level, so exemplars carry the
+ * full shape — fields, expands, and all. Rendering reuses the lookup
+ * formatters per entity under the shared sample header.
+ */
+function compileSample(
+  lookup: StoryPackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+  lookupFormatters: Formatters<PackEntity>,
+): ReadStory<PackSampleData, SampleOutput<PackEntity>> {
+  const config =
+    lookup.sample === true || lookup.sample === undefined ? {} : lookup.sample;
+  const description =
+    config.description ??
+    `Return randomly selected complete ${noun} entries as exemplars for shape discovery`;
+  const toolDescription =
+    config.toolDescription ??
+    `Return ${MIN_SAMPLE_COUNT}–${MAX_SAMPLE_COUNT} randomly selected complete ${noun} entries as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.`;
+  const sampleFormatters = createSampleFormatters<PackEntity>(
+    `${noun} entries`,
+    (entity, mode) => lookupFormatters[mode](entity),
+  );
+  const toOutput = (data: PackSampleData): SampleOutput<PackEntity> => ({
+    ...data,
+    nextSteps: sampleNextSteps(noun, data),
+  });
+
+  return {
+    noun,
+    verb: "sample",
+    description,
+    toolDescription,
+    params: [
+      {
+        name: "count",
+        type: "string",
+        description: `Number of samples to return (${MIN_SAMPLE_COUNT}–${MAX_SAMPLE_COUNT}, default ${config.count ?? DEFAULT_SAMPLE_COUNT})`,
+        positional: true,
+      },
+    ],
+    examples: [`pragma ${noun} sample`, `pragma ${noun} sample 3`],
+    resolve: async (rt, params) => {
+      const count = parseSampleCount(params.count ?? config.count);
+      const names = await listEntityNames(rt.store, lookup, source);
+      // Exemplars resolve at the HIGHEST disclosure level so every expand
+      // is fetched — samples exist to show the full data shape.
+      const level = lookup.disclosure?.levels.at(-1);
+      const selected = pickRandom(names, count);
+      const samples = await Promise.all(
+        selected.map((name) =>
+          lookupPackEntity(
+            rt.store,
+            lookup,
+            noun,
+            name,
+            source,
+            level,
+            prefixes,
+          ),
+        ),
+      );
+      return { samples, totalCount: names.length };
+    },
+    toOutput,
+    formatters: sampleFormatters,
+    toEnvelope: (data) => ({
+      data: toOutput(data),
+      meta: { count: data.samples.length },
+    }),
+  };
+}
+
+/** Agent-facing follow-ups appended to sample output. */
+function sampleNextSteps(noun: string, data: PackSampleData): string[] {
+  return [
+    `These are ${data.samples.length} of ${data.totalCount} total ${noun} entries.`,
+    `Use ${noun}_lookup to inspect specific entries by name.`,
+    `Use ${noun}_list to browse all entries.`,
+  ];
+}
+
+/**
+ * Partition lookup queries into concrete names and expanded globs.
+ *
+ * Literal names pass through unchanged. Glob patterns expand against the
+ * pack's entity name list; a glob matching nothing produces an
+ * `EMPTY_RESULTS` error entry (mirroring the shared lookup-glob contract)
+ * instead of failing the whole batch.
+ *
+ * @note Impure — fetches the entity name list when a glob is present.
+ */
+async function expandPackLookupQueries(
+  store: Store,
+  lookup: StoryPackLookup,
+  noun: string,
+  source: string,
+  queries: readonly string[],
+): Promise<{
+  names: string[];
+  globErrors: { query: string; code: string; message: string }[];
+}> {
+  if (!queries.some(isGlobPattern)) {
+    return { names: [...queries], globErrors: [] };
+  }
+
+  const allNames = await listEntityNames(store, lookup, source);
+  const names: string[] = [];
+  const globErrors: { query: string; code: string; message: string }[] = [];
+  for (const query of queries) {
+    if (!isGlobPattern(query)) {
+      names.push(query);
+      continue;
+    }
+    const expanded = expandGlob(query, allNames);
+    if (expanded.length === 0) {
+      globErrors.push({
+        query,
+        code: "EMPTY_RESULTS",
+        message: `No ${noun} entries matching "${query}".`,
+      });
+    } else {
+      names.push(...expanded);
+    }
+  }
+  return { names, globErrors };
+}
+
+/**
+ * Look up one pack entity by name, prefixed name, or absolute IRI.
+ *
+ * A query shaped like an IRI (`https://…` or `prefix:local`) is resolved
+ * through the runtime prefix map and addressed exactly via a generated
+ * `BIND(<iri> AS ?uri)` query; anything else matches the `by` property's
+ * value case-insensitively. Both query forms are generated — the resolved
+ * IRI is validated against the embeddable-IRI shape and names are escaped
+ * as SPARQL string literals, so user input never reaches query text raw.
+ *
+ * @throws PragmaError with code `ENTITY_NOT_FOUND` and ranked suggestions
+ *   when no entity matches, or `INVALID_INPUT` when an IRI-shaped query
+ *   uses an unknown prefix or malformed IRI.
+ * @note Impure — queries the ke store.
+ */
+async function lookupPackEntity(
+  store: Store,
+  lookup: StoryPackLookup,
+  noun: string,
+  query: string,
+  source: string,
+  level: string | undefined,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<PackEntity> {
+  const rows = await runSelectQuery(
+    store,
+    buildEntityQuery(lookup, query, prefixes),
+    source,
+  );
+  const base = rows.at(0);
+  if (!base) {
+    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` },
+      },
+    });
+  }
+
+  // Enrich with any declared multi-valued expands (pack v1 nested projections).
+  // Each expand runs a sub-SELECT bound to the resolved entity IRI (`base.uri`),
+  // which is store-derived, never user input. An expand tagged with a
+  // disclosure level is fetched only at/above that level — so a lower level
+  // never runs the sub-SELECT and the renderer omits the (absent) section.
+  const entity: PackEntity = { ...base };
+  const entityUri = base.uri;
+  if (entityUri) {
+    const levels = lookup.disclosure?.levels ?? [];
+    const activeIdx = level ? levels.indexOf(level) : Number.POSITIVE_INFINITY;
+    for (const expand of lookup.expand ?? []) {
+      const requiredIdx = expand.level ? levels.indexOf(expand.level) : 0;
+      if (activeIdx < requiredIdx) continue;
+      entity[expand.name] = await runSelectQuery(
+        store,
+        buildExpandQuery(expand, entityUri),
+        source,
+      );
+    }
+  }
+  return entity;
+}
+
+/**
+ * Build the base entity SELECT for a lookup query.
+ *
+ * Detection mirrors the retired built-in standard lookup: a query starting
+ * with `http(s)://` or containing `:` is treated as an IRI or prefixed
+ * name and resolved through the merged prefix map. The resolved IRI must
+ * still match the embeddable shape the pack validator holds authored
+ * terms to; anything else is rejected before it can reach query text.
+ *
+ * @throws PragmaError with code `INVALID_INPUT` when the query is
+ *   IRI-shaped but uses an unknown prefix or resolves to a non-embeddable
+ *   IRI.
+ */
+function buildEntityQuery(
+  lookup: StoryPackLookup,
+  query: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (!looksLikeIri(query)) {
+    return buildLookupQuery(lookup, query);
+  }
+  // resolveUri validates prefix membership and rejects IRI-breaking
+  // characters; the embeddable-shape check adds the validator's stricter
+  // `scheme://` contract before the IRI is embedded as `<iri>`.
+  const resolved = resolveUri(query, prefixes);
+  if (!isEmbeddableIri(resolved)) {
+    throw PragmaError.invalidInput("name", query, {
+      recovery: {
+        message:
+          "Use an absolute IRI (https://…), a prefixed name (ex:thing), or a plain entity name.",
+      },
+    });
+  }
+  return buildLookupByIriQuery(lookup, resolved);
+}
+
+/** Whether a lookup query addresses an entity by IRI or prefixed name. */
+function looksLikeIri(query: string): boolean {
+  return (
+    query.startsWith("http://") ||
+    query.startsWith("https://") ||
+    query.includes(":")
+  );
+}
+
+/**
+ * Resolve the effective disclosure level for a lookup call.
+ *
+ * Precedence (highest → lowest): an explicit `--detail`/`detail` value, a
+ * legacy alias flag set to true (the HIGHEST requested level wins when
+ * several are set), the global `config.detail` default, the MCP full-data
+ * default, the pack's declared `disclosure.default`, then the base level
+ * (the first declared). A config/pack value that is not one of the pack's
+ * levels is ignored (a global default may target another pack).
+ *
+ * `config.detail` deliberately outranks the MCP default: the config value
+ * is something the user explicitly chose, while the MCP default is only a
+ * surface fallback — a user who configured `detail: summary` gets summary
+ * on both surfaces.
+ *
+ * The MCP default follows the ratified surface contract (see
+ * `resolveLookupDetailed`): the CLI opts in while MCP opts out, so an MCP
+ * call with no explicit or configured choice resolves to the highest
+ * level — agents want full data by default — and an alias explicitly set
+ * to false (e.g. `detailed: false`) opts down to the pack default or base
+ * level.
+ */
+function resolveDetailLevel(
+  params: Record<string, unknown>,
+  config: { readonly detail?: string },
+  disclosure: StoryPackDisclosure,
+  surface: "cli" | "mcp",
+): string {
+  const { levels } = disclosure;
+  const explicit =
+    typeof params.detail === "string" ? params.detail : undefined;
+  if (explicit !== undefined && levels.includes(explicit)) {
+    return explicit;
+  }
+
+  const aliased = levels
+    .filter((level, index) => index > 0 && params[level] === true)
+    .at(-1);
+  if (aliased !== undefined) {
+    return aliased;
+  }
+
+  if (config.detail !== undefined && levels.includes(config.detail)) {
+    return config.detail;
+  }
+
+  if (surface === "mcp") {
+    const optedDown = levels.some(
+      (level, index) => index > 0 && params[level] === false,
+    );
+    const highest = levels.at(-1);
+    if (!optedDown && highest !== undefined) {
+      return highest;
+    }
+  }
+
+  const packDefault = disclosure.default;
+  if (packDefault !== undefined && levels.includes(packDefault)) {
+    return packDefault;
+  }
+  return levels[0] ?? "";
+}
+
+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 !== "");
+}
+
+/** Return a value only when it is a scalar string (expands hold arrays). */
+function scalar(
+  value: string | readonly PackRow[] | undefined,
+): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * 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.
+ *
+ * A declared value set becomes the parameter's enum, which the kernel
+ * projects to CLI select choices and an MCP enum schema. A value-free
+ * filter projects as a plain string parameter — its valid values are
+ * data-driven and enforced only as a post-query row predicate.
+ */
+function projectFilterParams(
+  filters: readonly StoryPackFilter[] | undefined,
+): StoryParam[] {
+  return (filters ?? []).map((filter) => ({
+    name: filter.param,
+    type: "string",
+    description:
+      filter.description ??
+      (filter.values
+        ? `Filter by ${filter.variable} (${filter.values.join(", ")})`
+        : `Filter by ${filter.variable}`),
+    ...(filter.values ? { enum: filter.values } : {}),
+  }));
+}
+
+/**
+ * Project a declared free-text search onto the `search` story parameter.
+ */
+function projectSearchParam(search: StoryPackSearch | undefined): StoryParam[] {
+  if (!search) return [];
+  return [
+    {
+      name: "search",
+      type: "string",
+      description:
+        search.description ?? `Search in ${search.variables.join(", ")}`,
+    },
+  ];
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}