@canonical/pragma-cli 0.31.0 → 0.32.0

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

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