@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import projectCliParameters from "./projectCliParameters.js";
+import type { StoryParam } from "./types.js";
+
+describe("projectCliParameters", () => {
+  it("drops MCP-only parameters", () => {
+    const params: StoryParam[] = [
+      { name: "a", type: "boolean", description: "a" },
+      { name: "b", type: "boolean", description: "b", surfaces: "mcp" },
+      { name: "c", type: "boolean", description: "c", surfaces: "cli" },
+    ];
+    expect(projectCliParameters(params).map((p) => p.name)).toEqual(["a", "c"]);
+  });
+
+  it("maps string[] to multiselect and enum strings to select with choices", () => {
+    const params: StoryParam[] = [
+      { name: "names", type: "string[]", description: "names" },
+      {
+        name: "mode",
+        type: "string",
+        description: "mode",
+        enum: ["fast", "slow"],
+      },
+    ];
+    const projected = projectCliParameters(params);
+    expect(projected.at(0)?.type).toBe("multiselect");
+    expect(projected.at(1)?.type).toBe("select");
+    expect(projected.at(1)?.choices).toEqual([
+      { label: "fast", value: "fast" },
+      { label: "slow", value: "slow" },
+    ]);
+  });
+
+  it("carries defaults, positionals, required, and completion through", async () => {
+    const complete = async () => ["x"];
+    const params: StoryParam[] = [
+      {
+        name: "prefix",
+        type: "string",
+        description: "prefix",
+        positional: true,
+        required: true,
+        default: "ds",
+        complete,
+      },
+    ];
+    const projected = projectCliParameters(params);
+    const first = projected.at(0);
+    expect(first?.positional).toBe(true);
+    expect(first?.required).toBe(true);
+    expect(first?.default).toBe("ds");
+    await expect(
+      first?.complete?.("d", {
+        cwd: "/",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      }),
+    ).resolves.toEqual(["x"]);
+  });
+});

package/src/domains/shared/stories/projectCliParameters.ts

@@ -0,0 +1,57 @@
+import type { ParameterDefinition } from "@canonical/cli-core";
+import type { StoryParam } from "./types.js";
+
+/**
+ * Project story parameters onto cli-core `ParameterDefinition`s.
+ *
+ * MCP-only parameters are dropped; `string[]` becomes a multiselect;
+ * an `enum` on a string parameter becomes a select with choices.
+ */
+export default function projectCliParameters(
+  params: readonly StoryParam[],
+): ParameterDefinition[] {
+  return params
+    .filter((param) => (param.surfaces ?? "both") !== "mcp")
+    .map((param) => toParameterDefinition(param));
+}
+
+function toParameterDefinition(param: StoryParam): ParameterDefinition {
+  const definition: {
+    name: string;
+    description: string;
+    type: ParameterDefinition["type"];
+    choices?: ParameterDefinition["choices"];
+    default?: unknown;
+    positional?: boolean;
+    required?: boolean;
+    complete?: ParameterDefinition["complete"];
+  } = {
+    name: param.name,
+    description: param.description,
+    type: resolveCliType(param),
+  };
+
+  if (param.enum) {
+    definition.choices = param.enum.map((value) => ({ label: value, value }));
+  }
+  if (param.default !== undefined) {
+    definition.default = param.default;
+  }
+  if (param.positional === true) {
+    definition.positional = true;
+  }
+  if (param.required === true) {
+    definition.required = true;
+  }
+  if (param.complete) {
+    definition.complete = param.complete;
+  }
+
+  return definition;
+}
+
+function resolveCliType(param: StoryParam): ParameterDefinition["type"] {
+  if (param.type === "string[]") return "multiselect";
+  if (param.type === "string" && param.enum) return "select";
+  return param.type;
+}

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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import projectToolParams from "./projectToolParams.js";
+import type { StoryParam } from "./types.js";
+
+describe("projectToolParams", () => {
+  it("drops CLI-only parameters", () => {
+    const params: StoryParam[] = [
+      { name: "a", type: "boolean", description: "a" },
+      { name: "b", type: "boolean", description: "b", surfaces: "cli" },
+      { name: "c", type: "boolean", description: "c", surfaces: "mcp" },
+    ];
+    expect(Object.keys(projectToolParams(params))).toEqual(["a", "c"]);
+  });
+
+  it("prefers the tool description and sets optional from required", () => {
+    const params: StoryParam[] = [
+      {
+        name: "names",
+        type: "string[]",
+        description: "cli text",
+        toolDescription: "mcp text",
+        required: true,
+      },
+      { name: "flag", type: "boolean", description: "shared text" },
+    ];
+    const projected = projectToolParams(params);
+    expect(projected.names).toEqual({
+      type: "string[]",
+      description: "mcp text",
+      optional: false,
+    });
+    expect(projected.flag).toEqual({
+      type: "boolean",
+      description: "shared text",
+      optional: true,
+    });
+  });
+
+  it("carries enums through", () => {
+    const params: StoryParam[] = [
+      {
+        name: "mode",
+        type: "string",
+        description: "mode",
+        enum: ["fast", "slow"],
+      },
+    ];
+    expect(projectToolParams(params).mode?.enum).toEqual(["fast", "slow"]);
+  });
+});

package/src/domains/shared/stories/projectToolParams.ts

@@ -0,0 +1,32 @@
+import type { ToolParamDef } from "../ToolSpec.js";
+import type { StoryParam } from "./types.js";
+
+/**
+ * Project story parameters onto MCP `ToolParamDef`s.
+ *
+ * CLI-only parameters are dropped, along with CLI-only attributes
+ * (defaults, positionals, completion). Required parameters set
+ * `optional: false` explicitly — the MCP adapter treats anything
+ * else as optional.
+ */
+export default function projectToolParams(
+  params: readonly StoryParam[],
+): Record<string, ToolParamDef> {
+  const projected: Record<string, ToolParamDef> = {};
+
+  for (const param of params) {
+    if ((param.surfaces ?? "both") === "cli") continue;
+    projected[param.name] = toToolParamDef(param);
+  }
+
+  return projected;
+}
+
+function toToolParamDef(param: StoryParam): ToolParamDef {
+  return {
+    type: param.type,
+    description: param.toolDescription ?? param.description,
+    optional: param.required !== true,
+    ...(param.enum && { enum: param.enum }),
+  };
+}

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../context.js";
+import requirePragmaContext from "./requirePragmaContext.js";
+
+describe("requirePragmaContext", () => {
+  it("returns a context that carries the pragma runtime", () => {
+    const ctx = {
+      cwd: "/",
+      globalFlags: { llm: false, format: "text", verbose: false },
+      store: {},
+    } as unknown as PragmaContext;
+    expect(requirePragmaContext(ctx)).toBe(ctx);
+  });
+
+  it("throws for a context without the runtime", () => {
+    const bare = {
+      cwd: "/",
+      globalFlags: { llm: false, format: "text" as const, verbose: false },
+    };
+    expect(() => requirePragmaContext(bare)).toThrow(PragmaError);
+  });
+});

package/src/domains/shared/stories/requirePragmaContext.ts

@@ -0,0 +1,23 @@
+import type { CommandContext } from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../context.js";
+
+/**
+ * Narrow a cli-core `CommandContext` to the pragma context.
+ *
+ * Story completion callbacks receive the cli-core context type, but every
+ * context the pragma pipeline constructs is a `PragmaContext` (it carries
+ * the ke store and config). This asserts that invariant at runtime instead
+ * of casting silently, failing fast if a foreign context ever appears.
+ */
+export default function requirePragmaContext(
+  ctx: CommandContext,
+): PragmaContext {
+  if (!("store" in ctx)) {
+    throw PragmaError.internalError(
+      "completion context is missing the pragma runtime",
+    );
+  }
+  // Proven one line up: a context carrying `store` is a PragmaContext.
+  return ctx as PragmaContext;
+}

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

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import resolveLookupDetailed from "./resolveLookupDetailed.js";
+import type { LookupStory } from "./types.js";
+
+type AnyLookupStory = LookupStory<unknown, unknown>;
+
+const baseStory: Pick<
+  AnyLookupStory,
+  "noun" | "description" | "toolDescription" | "namesDescription"
+> = {
+  noun: "thing",
+  description: "d",
+  toolDescription: "td",
+  namesDescription: "names",
+};
+
+function makeStory(overrides: Partial<AnyLookupStory>): AnyLookupStory {
+  return {
+    ...baseStory,
+    examples: [],
+    resolve: async () => ({ results: [], errors: [] }),
+    toFmtInput: (entity) => entity,
+    formatters: {
+      plain: () => "",
+      llm: () => "",
+      json: () => "",
+    },
+    ...overrides,
+  };
+}
+
+describe("resolveLookupDetailed", () => {
+  it("is never detailed when the story has no detailed param", () => {
+    const story = makeStory({});
+    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(false);
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
+  });
+
+  it("defaults detailed to true on MCP and false on CLI", () => {
+    const story = makeStory({ detailedParam: { description: "d" } });
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(true);
+    expect(resolveLookupDetailed(story, "mcp", { detailed: false })).toBe(
+      false,
+    );
+    expect(resolveLookupDetailed(story, "cli", {})).toBe(false);
+    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(true);
+  });
+
+  it("lets a story override the surface defaults", () => {
+    const story = makeStory({
+      detailedParam: { description: "d" },
+      resolveDetailed: (surface) => surface === "cli",
+    });
+    expect(resolveLookupDetailed(story, "cli", {})).toBe(true);
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
+  });
+});

package/src/domains/shared/stories/resolveLookupDetailed.ts

@@ -0,0 +1,27 @@
+import type { LookupStory } from "./types.js";
+
+/**
+ * Resolve the effective `detailed` flag for a lookup story on a surface.
+ *
+ * Defaults follow the ratified surface contract: the CLI opts in
+ * (`detailed` is false unless set) while MCP opts out (`detailed` is true
+ * unless set, since agents want full data by default). Stories without a
+ * `detailed` parameter are never detailed. A story's `resolveDetailed`
+ * override wins — block uses it to let aspect flags imply detail.
+ */
+export default function resolveLookupDetailed<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+  surface: "cli" | "mcp",
+  params: Record<string, unknown>,
+): boolean {
+  if (story.resolveDetailed) {
+    return story.resolveDetailed(surface, params);
+  }
+  if (!story.detailedParam) {
+    return false;
+  }
+  if (surface === "mcp") {
+    return ((params.detailed as boolean | undefined) ?? true) === true;
+  }
+  return params.detailed === true;
+}

package/src/domains/shared/stories/types.ts

@@ -0,0 +1,179 @@
+/**
+ * Read-story spec types — one declaration per read story, many projections.
+ *
+ * A read story (list, show, or lookup) is declared once per domain and
+ * compiled into both surfaces: a cli-core `CommandDefinition` and a
+ * declarative MCP `ToolSpec`. The compilers in this folder own the shared
+ * execute skeletons — parameter projection, condensed rendering with token
+ * estimates, empty-result guards, and summary projection — so a domain
+ * supplies only its facts: descriptions, parameters, resolve function,
+ * formatters, and envelope mapping. This kills the per-domain duplication
+ * between `commands/*.ts` and `mcp/specs.ts` for read verbs and makes
+ * CLI/MCP parity structural instead of conventional.
+ */
+
+import type { CommandContext } from "@canonical/cli-core";
+import type { PragmaError } from "#error";
+import type { LookupResult } from "../contracts.js";
+import type { Formatters } from "../formatters.js";
+import type { PragmaRuntime } from "../types/index.js";
+
+/** Surfaces a story parameter is projected to (default: "both"). */
+export type StorySurface = "both" | "cli" | "mcp";
+
+/**
+ * Neutral parameter definition projected to a CLI flag and an MCP tool
+ * parameter. `string[]` becomes a CLI multiselect and an MCP string array.
+ */
+export interface StoryParam {
+  readonly name: string;
+  readonly type: "string" | "boolean" | "string[]";
+  /** CLI help text; also the MCP description unless `toolDescription` is set. */
+  readonly description: string;
+  /** MCP-specific description override. */
+  readonly toolDescription?: string;
+  readonly required?: boolean;
+  /** CLI default value — MCP parameters carry no defaults. */
+  readonly default?: unknown;
+  /** Allowed values; projects to CLI select choices and an MCP enum. */
+  readonly enum?: readonly string[];
+  /** If true, the CLI accepts this parameter as a positional argument. */
+  readonly positional?: boolean;
+  /** Surfaces this parameter appears on (default: "both"). */
+  readonly surfaces?: StorySurface;
+  /** CLI tab-completion for this parameter's argument. */
+  readonly complete?: (
+    partial: string,
+    ctx: CommandContext,
+  ) => Promise<string[]>;
+}
+
+/** MCP envelope fragment produced by a story's `toEnvelope`. */
+export interface StoryEnvelope {
+  readonly data: unknown;
+  readonly meta?: Record<string, unknown>;
+}
+
+/**
+ * A collection-or-singleton read story (`<noun> list`, `<noun> show`).
+ *
+ * `TData` is the domain's resolved payload; `TOutput` is the formatter and
+ * renderer input derived from it via `toOutput`.
+ */
+export interface ReadStory<TData, TOutput> {
+  readonly noun: string;
+  /** Read verb this story projects to (e.g. "list", "show"). */
+  readonly verb: string;
+  /** CLI one-line help description. */
+  readonly description: string;
+  /** MCP tool description. */
+  readonly toolDescription: string;
+  readonly params: readonly StoryParam[];
+  /** Usage examples shown in CLI help. */
+  readonly examples: readonly string[];
+  /** Fetch the story's data. Shared verbatim by both surfaces. */
+  readonly resolve: (
+    rt: PragmaRuntime,
+    params: Record<string, unknown>,
+  ) => Promise<TData>;
+  /** Map resolved data to the formatter/renderer input. */
+  readonly toOutput: (data: TData, params: Record<string, unknown>) => TOutput;
+  readonly formatters: Formatters<TOutput>;
+  /** Map resolved data to the MCP `{ data, meta }` envelope. */
+  readonly toEnvelope: (data: TData) => StoryEnvelope;
+  /**
+   * CLI-only pre-resolve guard: return an error to reject invalid
+   * parameters (e.g. an empty required positional).
+   */
+  readonly guardParams?: (
+    params: Record<string, unknown>,
+  ) => PragmaError | undefined;
+  /**
+   * CLI-only post-resolve guard: return an error to reject an empty
+   * result set with a recovery hint.
+   */
+  readonly emptyError?: (
+    data: TData,
+    params: Record<string, unknown>,
+  ) => PragmaError | undefined;
+  /** Optional interactive (ink) renderer for the CLI. */
+  readonly renderInk?: (output: TOutput) => unknown;
+}
+
+/** Per-invocation view state passed to lookup story hooks. */
+export interface LookupStoryView {
+  readonly surface: "cli" | "mcp";
+  /** Effective detail level after surface defaults and flag implications. */
+  readonly detailed: boolean;
+  readonly params: Record<string, unknown>;
+}
+
+/**
+ * A batch retrieval story (`<noun> lookup <names...>`).
+ *
+ * `TDetailed` is the looked-up entity; `TFmtInput` is the per-entity
+ * formatter input derived via `toFmtInput` (some domains pair the entity
+ * with view flags such as `detailed` or aspect selections).
+ */
+export interface LookupStory<TDetailed, TFmtInput> {
+  readonly noun: string;
+  readonly description: string;
+  readonly toolDescription: string;
+  /** CLI description of the `names` positional parameter. */
+  readonly namesDescription: string;
+  /** MCP-specific `names` description override. */
+  readonly namesToolDescription?: string;
+  /** CLI tab-completion for names. */
+  readonly complete?: (
+    partial: string,
+    ctx: CommandContext,
+  ) => Promise<string[]>;
+  /**
+   * The `detailed` toggle, when the story supports one. MCP defaults
+   * `detailed` to true; the CLI defaults it to false.
+   */
+  readonly detailedParam?: {
+    readonly description: string;
+    readonly toolDescription?: string;
+  };
+  /** Additional story parameters beyond `names` and `detailed`. */
+  readonly params?: readonly StoryParam[];
+  /** Named groups for organizing CLI parameters in help output. */
+  readonly parameterGroups?: Readonly<Record<string, readonly string[]>>;
+  readonly examples: readonly string[];
+  /**
+   * Resolve all queries, collecting per-query failures.
+   *
+   * The compilers pass the per-invocation `view` so surface-sensitive
+   * resolution (e.g. pack disclosure defaults, which differ between the
+   * CLI and MCP per the ratified surface contract) can see which surface
+   * is calling; most stories ignore it.
+   */
+  readonly resolve: (
+    rt: PragmaRuntime,
+    names: readonly string[],
+    params: Record<string, unknown>,
+    view?: LookupStoryView,
+  ) => Promise<LookupResult<TDetailed>>;
+  /**
+   * Effective `detailed` for a surface. Defaults to the plain flag value
+   * (CLI: false unless set; MCP: true unless set). Domains override this
+   * when other flags imply detail (e.g. block aspect filters).
+   */
+  readonly resolveDetailed?: (
+    surface: "cli" | "mcp",
+    params: Record<string, unknown>,
+  ) => boolean;
+  /** Map an entity to the per-entity formatter input. */
+  readonly toFmtInput: (entity: TDetailed, view: LookupStoryView) => TFmtInput;
+  readonly formatters: Formatters<TFmtInput>;
+  /** MCP summary projection applied when `detailed` is false. */
+  readonly project?: (entity: TDetailed) => unknown;
+  /** CLI-only error thrown when no names are supplied. */
+  readonly emptyNamesError?: () => PragmaError;
+  /** Optional interactive (ink) renderer for the CLI. */
+  readonly renderInk?: (
+    result: LookupResult<TDetailed>,
+    view: LookupStoryView,
+  ) => unknown;
+}

package/src/domains/shared/suggestions/expandGlob.ts

@@ -41,6 +41,7 @@ function globToRegex(glob: string): RegExp {
   for (const char of glob) {
     if (char === "*") {
       pattern += ".*";
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: regex meta-characters to escape, not a JS template
     } else if (".+^${}()|[]\\".includes(char)) {
       pattern += `\\${char}`;
     } else {

package/src/domains/shared/suggestions/suggestNames.ts

@@ -63,35 +63,68 @@ function damerauLevenshtein(a: string, b: string): number {
   if (lenA === 0) return lenB;
   if (lenB === 0) return lenA;
 
+  // Fully allocated (lenA + 1) × (lenB + 1) grid: every row/column index in
+  // [0, lenA] × [0, lenB] below is provably in bounds, so `row.at(j)` never
+  // yields undefined for the indices we read.
   const matrix: number[][] = Array.from({ length: lenA + 1 }, () =>
     Array.from<number>({ length: lenB + 1 }).fill(0),
   );
 
   for (let i = 0; i <= lenA; i++) {
-    matrix[i]![0] = i;
+    getRow(matrix, i)[0] = i;
   }
+  const firstRow = getRow(matrix, 0);
   for (let j = 0; j <= lenB; j++) {
-    matrix[0]![j] = j;
+    firstRow[j] = j;
   }
 
   for (let i = 1; i <= lenA; i++) {
+    const prevRow = getRow(matrix, i - 1);
+    const row = getRow(matrix, i);
     for (let j = 1; j <= lenB; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1;
 
-      matrix[i]![j] = Math.min(
-        matrix[i - 1]![j]! + 1, // deletion
-        matrix[i]![j - 1]! + 1, // insertion
-        matrix[i - 1]![j - 1]! + cost, // substitution
+      row[j] = Math.min(
+        getCell(prevRow, j) + 1, // deletion
+        getCell(row, j - 1) + 1, // insertion
+        getCell(prevRow, j - 1) + cost, // substitution
       );
 
       if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
-        matrix[i]![j] = Math.min(
-          matrix[i]![j]!,
-          matrix[i - 2]![j - 2]! + cost, // transposition
+        const prevPrevRow = getRow(matrix, i - 2);
+        row[j] = Math.min(
+          getCell(row, j),
+          getCell(prevPrevRow, j - 2) + cost, // transposition
         );
       }
     }
   }
 
-  return matrix[lenA]![lenB]!;
+  return getCell(getRow(matrix, lenA), lenB);
+}
+
+/**
+ * Read a matrix row that is structurally guaranteed to exist.
+ *
+ * @throws if the row is missing, signalling a broken allocation invariant.
+ */
+function getRow(matrix: number[][], index: number): number[] {
+  const row = matrix.at(index);
+  if (row === undefined) {
+    throw new Error(`matrix row ${index} is out of bounds`);
+  }
+  return row;
+}
+
+/**
+ * Read a matrix cell that is structurally guaranteed to exist.
+ *
+ * @throws if the cell is missing, signalling a broken allocation invariant.
+ */
+function getCell(row: number[], index: number): number {
+  const cell = row.at(index);
+  if (cell === undefined) {
+    throw new Error(`matrix cell ${index} is out of bounds`);
+  }
+  return cell;
 }

package/src/domains/shared/types/index.ts

@@ -26,21 +26,17 @@ export type {
 } from "./modifier.js";
 export type {
   OntologyClass,
+  OntologyClassFocus,
+  OntologyConstraint,
   OntologyDetailed,
+  OntologyMeta,
   OntologyProperty,
+  OntologyQueryHint,
   OntologySummary,
 } from "./ontology.js";
 export type { PragmaRuntime } from "./runtime.js";
 export type { SampleOutput, SampleResult } from "./sample.js";
-export type {
-  CategorySummary,
-  CodeBlock,
-  StandardDetailed,
-  StandardDigest,
-  StandardListFilters,
-  StandardRef,
-  StandardSummary,
-} from "./standard.js";
+export type { StandardRef } from "./standard.js";
 export type { TierEntry } from "./tier.js";
 export type {
   TokenDetailed,