@canonical/pragma-cli 0.29.0 → 0.30.0

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

@@ -0,0 +1,100 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+  type ParameterDefinition,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../context.js";
+import type { LookupResult } from "../contracts.js";
+import { renderLookupResults } from "../formatters.js";
+import normalizeNames from "./normalizeNames.js";
+import projectCliParameters from "./projectCliParameters.js";
+import resolveLookupDetailed from "./resolveLookupDetailed.js";
+import type { LookupStory, LookupStoryView } from "./types.js";
+
+/**
+ * Compile a lookup story into its CLI `CommandDefinition` projection.
+ *
+ * Owns the shared execute skeleton: normalize the positional `names`,
+ * reject empty input when the story defines an error, resolve the batch,
+ * then render each result through the story's formatters with the shared
+ * multi-result renderer (which appends the "Errors:" section).
+ */
+export default function compileLookupCommand<TDetailed, TFmtInput>(
+  ctx: PragmaContext,
+  story: LookupStory<TDetailed, TFmtInput>,
+): CommandDefinition {
+  interface LookupOutput {
+    readonly result: LookupResult<TDetailed>;
+    readonly view: LookupStoryView;
+  }
+
+  return {
+    path: [story.noun, "lookup"],
+    description: story.description,
+    parameters: buildParameters(story),
+    ...(story.parameterGroups && { parameterGroups: story.parameterGroups }),
+    meta: {
+      examples: story.examples,
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const names = normalizeNames(params.names, params.name);
+      if (names.length === 0 && story.emptyNamesError) {
+        throw story.emptyNamesError();
+      }
+
+      const view: LookupStoryView = {
+        surface: "cli",
+        detailed: resolveLookupDetailed(story, "cli", params),
+        params,
+      };
+      const result = await story.resolve(ctx, names, params);
+      const renderInk = story.renderInk;
+
+      return createOutputResult<LookupOutput>(
+        { result, view },
+        {
+          plain: (output) =>
+            renderLookupResults({
+              ctx,
+              result: output.result,
+              formatters: story.formatters,
+              mapResult: (entity) => story.toFmtInput(entity, output.view),
+            }),
+          ...(renderInk && {
+            ink: (output: LookupOutput) =>
+              renderInk(output.result, output.view),
+          }),
+        },
+      );
+    },
+  };
+}
+
+function buildParameters<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+): ParameterDefinition[] {
+  const names: ParameterDefinition = {
+    name: "names",
+    description: story.namesDescription,
+    type: "multiselect",
+    positional: true,
+    required: true,
+    ...(story.complete && { complete: story.complete }),
+  };
+
+  const detailed: ParameterDefinition[] = story.detailedParam
+    ? [
+        {
+          name: "detailed",
+          description: story.detailedParam.description,
+          type: "boolean",
+          default: false,
+        },
+      ]
+    : [];
+
+  return [names, ...detailed, ...projectCliParameters(story.params ?? [])];
+}

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

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import type { LookupResult } from "../contracts.js";
+import type { PragmaRuntime } from "../types/index.js";
+import compileLookupTool from "./compileLookupTool.js";
+import type { LookupStory } from "./types.js";
+
+interface FakeEntity {
+  readonly name: string;
+  readonly detail: string;
+}
+
+function makeStory(
+  overrides: Partial<LookupStory<FakeEntity, string>> = {},
+): LookupStory<FakeEntity, string> {
+  return {
+    noun: "thing",
+    description: "Look up things",
+    toolDescription: "Look up things over MCP.",
+    namesDescription: "Thing names",
+    namesToolDescription: "Thing names to look up",
+    detailedParam: { description: "Show details" },
+    examples: [],
+    resolve: async (_rt, names) => {
+      const results = names
+        .filter((name) => name !== "missing")
+        .map((name) => ({ name, detail: `detail-${name}` }));
+      const errors: LookupResult<FakeEntity>["errors"] = names
+        .filter((name) => name === "missing")
+        .map((name) => ({
+          query: name,
+          code: "ENTITY_NOT_FOUND",
+          message: `thing "${name}" not found.`,
+        }));
+      return { results, errors, meta: { internalErrorCount: 0 } };
+    },
+    toFmtInput: (entity, view) =>
+      view.detailed ? `${entity.name}:${entity.detail}` : entity.name,
+    formatters: {
+      plain: (text) => `plain:${text}`,
+      llm: (text) => `llm:${text}`,
+      json: (text) => JSON.stringify(text),
+    },
+    project: (entity) => ({ name: entity.name }),
+    ...overrides,
+  };
+}
+
+const rt = {} as PragmaRuntime;
+
+describe("compileLookupTool", () => {
+  it("derives the tool name and params", () => {
+    const tool = compileLookupTool(makeStory());
+    expect(tool.name).toBe("thing_lookup");
+    expect(tool.readOnly).toBe(true);
+    expect(Object.keys(tool.params ?? {})).toEqual([
+      "names",
+      "detailed",
+      "condensed",
+    ]);
+    expect(tool.params?.names).toEqual({
+      type: "string[]",
+      description: "Thing names to look up",
+      optional: false,
+    });
+  });
+
+  it("returns full results by default (MCP detailed defaults to true)", async () => {
+    const tool = compileLookupTool(makeStory());
+    const result = await tool.execute(rt, { names: ["a"] });
+    expect(result).toEqual({
+      data: {
+        results: [{ name: "a", detail: "detail-a" }],
+        errors: [],
+      },
+      meta: { count: 1 },
+    });
+  });
+
+  it("applies the summary projection when detailed is false", async () => {
+    const tool = compileLookupTool(makeStory());
+    const result = await tool.execute(rt, {
+      names: ["a", "b"],
+      detailed: false,
+    });
+    expect(result).toEqual({
+      data: {
+        results: [{ name: "a" }, { name: "b" }],
+        errors: [],
+      },
+      meta: { count: 2 },
+    });
+  });
+
+  it("renders condensed output per entity and appends an errors section", async () => {
+    const tool = compileLookupTool(makeStory());
+    const result = await tool.execute(rt, {
+      names: ["a", "missing"],
+      condensed: true,
+    });
+    if (!("condensed" in result)) throw new Error("expected condensed result");
+    expect(result.text).toContain("llm:a:detail-a");
+    expect(result.text).toContain("### Errors");
+    expect(result.text).toContain('- missing: thing "missing" not found.');
+  });
+});

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

@@ -0,0 +1,96 @@
+import { lookupToolMeta } from "../lookupMany.js";
+import type { ToolParamDef, ToolSpec } from "../ToolSpec.js";
+import condense from "./condense.js";
+import projectToolParams from "./projectToolParams.js";
+import resolveLookupDetailed from "./resolveLookupDetailed.js";
+import type { LookupStory, LookupStoryView } from "./types.js";
+
+/**
+ * Compile a lookup story into its MCP `ToolSpec` projection.
+ *
+ * The tool is named `<noun>_lookup` and takes a required `names` array.
+ * Condensed responses render each entity through the story's llm
+ * formatter and append a `### Errors` section for failed queries. When
+ * the story supports `detailed` (MCP default: true), a false value
+ * applies the story's summary projection to each result.
+ */
+export default function compileLookupTool<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+): ToolSpec {
+  return {
+    name: `${story.noun}_lookup`,
+    description: story.toolDescription,
+    params: buildParams(story),
+    readOnly: true,
+    async execute(rt, params) {
+      const names = (params.names as string[] | undefined) ?? [];
+      const view: LookupStoryView = {
+        surface: "mcp",
+        detailed: resolveLookupDetailed(story, "mcp", params),
+        params,
+      };
+      const result = await story.resolve(rt, names, params);
+
+      if (params.condensed) {
+        const textParts = result.results.map((entity) =>
+          story.formatters.llm(story.toFmtInput(entity, view)),
+        );
+
+        if (result.errors.length > 0) {
+          textParts.push(
+            [
+              "### Errors",
+              ...result.errors.map(
+                (error) => `- ${error.query}: ${error.message}`,
+              ),
+            ].join("\n"),
+          );
+        }
+
+        return condense(textParts.join("\n\n"));
+      }
+
+      const project = story.project;
+      const results =
+        !view.detailed && project
+          ? result.results.map((entity) => project(entity))
+          : result.results;
+
+      return {
+        data: { results, errors: result.errors },
+        meta: lookupToolMeta(result),
+      };
+    },
+  };
+}
+
+function buildParams<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+): Record<string, ToolParamDef> {
+  const detailed: Record<string, ToolParamDef> = story.detailedParam
+    ? {
+        detailed: {
+          type: "boolean",
+          description:
+            story.detailedParam.toolDescription ??
+            story.detailedParam.description,
+          optional: true,
+        },
+      }
+    : {};
+
+  return {
+    names: {
+      type: "string[]",
+      description: story.namesToolDescription ?? story.namesDescription,
+      optional: false,
+    },
+    ...detailed,
+    ...projectToolParams(story.params ?? []),
+    condensed: {
+      type: "boolean",
+      description: "Token-optimized output",
+      optional: true,
+    },
+  };
+}

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../context.js";
+import compileReadCommand from "./compileReadCommand.js";
+import type { ReadStory } from "./types.js";
+
+interface FakeData {
+  readonly items: readonly string[];
+}
+
+function makeStory(
+  overrides: Partial<ReadStory<FakeData, readonly string[]>> = {},
+): ReadStory<FakeData, readonly string[]> {
+  return {
+    noun: "thing",
+    verb: "list",
+    description: "List things",
+    toolDescription: "List things over MCP.",
+    params: [
+      { name: "flag", type: "boolean", description: "a flag", default: false },
+      { name: "hidden", type: "boolean", description: "mcp", surfaces: "mcp" },
+    ],
+    examples: ["pragma thing list"],
+    resolve: async (_rt, params) => ({
+      items: params.flag === true ? ["a", "b", "extra"] : ["a", "b"],
+    }),
+    toOutput: (data) => data.items,
+    formatters: {
+      plain: (items) => `plain:${items.join(",")}`,
+      llm: (items) => `llm:${items.join(",")}`,
+      json: (items) => JSON.stringify(items),
+    },
+    toEnvelope: (data) => ({ data: data.items }),
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: "/tmp",
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    ...overrides,
+  } as PragmaContext;
+}
+
+async function executeOutput(
+  story: ReadStory<FakeData, readonly string[]>,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<{ value: unknown; text: string }> {
+  const cmd = compileReadCommand(ctx, story);
+  const result = await cmd.execute(params, ctx);
+  if (result.tag !== "output") throw new Error("expected output result");
+  return { value: result.value, text: result.render.plain(result.value) };
+}
+
+describe("compileReadCommand", () => {
+  it("projects path, description, examples, and CLI parameters", () => {
+    const cmd = compileReadCommand(makeCtx(), makeStory());
+    expect(cmd.path).toEqual(["thing", "list"]);
+    expect(cmd.description).toBe("List things");
+    expect(cmd.meta?.examples).toEqual(["pragma thing list"]);
+    expect(cmd.parameters.map((p) => p.name)).toEqual(["flag"]);
+  });
+
+  it("resolves with parameters and renders the plain formatter", async () => {
+    const { value, text } = await executeOutput(
+      makeStory(),
+      { flag: true },
+      makeCtx(),
+    );
+    expect(value).toEqual(["a", "b", "extra"]);
+    expect(text).toBe("plain:a,b,extra");
+  });
+
+  it("selects the llm formatter under --llm", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text", verbose: false },
+    });
+    const { text } = await executeOutput(makeStory(), {}, ctx);
+    expect(text).toBe("llm:a,b");
+  });
+
+  it("throws the story's guardParams error before resolving", async () => {
+    const story = makeStory({
+      guardParams: (params) =>
+        params.bad === true
+          ? PragmaError.invalidInput("bad", "true")
+          : undefined,
+    });
+    const cmd = compileReadCommand(makeCtx(), story);
+    await expect(cmd.execute({ bad: true }, makeCtx())).rejects.toThrow(
+      PragmaError,
+    );
+  });
+
+  it("throws the story's emptyError after resolving", async () => {
+    const story = makeStory({
+      resolve: async () => ({ items: [] }),
+      emptyError: (data) =>
+        data.items.length === 0 ? PragmaError.emptyResults("thing") : undefined,
+    });
+    const cmd = compileReadCommand(makeCtx(), story);
+    await expect(cmd.execute({}, makeCtx())).rejects.toThrow(
+      "No things found.",
+    );
+  });
+
+  it("exposes an ink renderer only when the story defines one", async () => {
+    const withInk = makeStory({ renderInk: (items) => `ink:${items.length}` });
+    const cmd = compileReadCommand(makeCtx(), withInk);
+    const result = await cmd.execute({}, makeCtx());
+    if (result.tag !== "output") throw new Error("expected output result");
+    expect(result.render.ink?.(["a"])).toBe("ink:1");
+
+    const plainOnly = compileReadCommand(makeCtx(), makeStory());
+    const plainResult = await plainOnly.execute({}, makeCtx());
+    if (plainResult.tag !== "output") throw new Error("expected output");
+    expect(plainResult.render.ink).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,48 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../context.js";
+import { selectFormatter } from "../formatters.js";
+import projectCliParameters from "./projectCliParameters.js";
+import type { ReadStory } from "./types.js";
+
+/**
+ * Compile a read story into its CLI `CommandDefinition` projection.
+ *
+ * Owns the shared execute skeleton: guard parameters, resolve, reject
+ * empty results when the story defines a guard, then render through the
+ * story's formatters (plain/llm/json via global flags) and optional ink
+ * view.
+ */
+export default function compileReadCommand<TData, TOutput>(
+  ctx: PragmaContext,
+  story: ReadStory<TData, TOutput>,
+): CommandDefinition {
+  return {
+    path: [story.noun, story.verb],
+    description: story.description,
+    parameters: projectCliParameters(story.params),
+    meta: {
+      examples: story.examples,
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const guardError = story.guardParams?.(params);
+      if (guardError) throw guardError;
+
+      const data = await story.resolve(ctx, params);
+
+      const emptyError = story.emptyError?.(data, params);
+      if (emptyError) throw emptyError;
+
+      const renderInk = story.renderInk;
+      return createOutputResult(story.toOutput(data, params), {
+        plain: selectFormatter(ctx, story.formatters),
+        ...(renderInk && { ink: (output: TOutput) => renderInk(output) }),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import type { PragmaRuntime } from "../types/index.js";
+import compileReadTool from "./compileReadTool.js";
+import type { ReadStory } from "./types.js";
+
+interface FakeData {
+  readonly items: readonly string[];
+}
+
+const story: ReadStory<FakeData, readonly string[]> = {
+  noun: "thing",
+  verb: "show",
+  description: "Show things",
+  toolDescription: "Show things over MCP.",
+  params: [
+    { name: "flag", type: "boolean", description: "a flag" },
+    { name: "cliOnly", type: "boolean", description: "cli", surfaces: "cli" },
+  ],
+  examples: [],
+  resolve: async (_rt, params) => ({
+    items: params.flag === true ? ["a", "b", "extra"] : ["a", "b"],
+  }),
+  toOutput: (data) => data.items,
+  formatters: {
+    plain: (items) => `plain:${items.join(",")}`,
+    llm: (items) => `llm:${items.join(",")}`,
+    json: (items) => JSON.stringify(items),
+  },
+  toEnvelope: (data) => ({
+    data: data.items,
+    meta: { count: data.items.length },
+  }),
+};
+
+const rt = {} as PragmaRuntime;
+
+describe("compileReadTool", () => {
+  it("derives the tool name and projects MCP params plus condensed", () => {
+    const tool = compileReadTool(story);
+    expect(tool.name).toBe("thing_show");
+    expect(tool.description).toBe("Show things over MCP.");
+    expect(tool.readOnly).toBe(true);
+    expect(Object.keys(tool.params ?? {})).toEqual(["flag", "condensed"]);
+  });
+
+  it("returns the story envelope for plain calls", async () => {
+    const tool = compileReadTool(story);
+    const result = await tool.execute(rt, { flag: true });
+    expect(result).toEqual({
+      data: ["a", "b", "extra"],
+      meta: { count: 3 },
+    });
+  });
+
+  it("renders condensed output through the llm formatter", async () => {
+    const tool = compileReadTool(story);
+    const result = await tool.execute(rt, { condensed: true });
+    expect(result).toEqual({
+      condensed: true,
+      text: "llm:a,b",
+      tokens: `~${Math.ceil("llm:a,b".length / 4)}`,
+    });
+  });
+});

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

@@ -0,0 +1,38 @@
+import type { ToolSpec } from "../ToolSpec.js";
+import condense from "./condense.js";
+import projectToolParams from "./projectToolParams.js";
+import type { ReadStory } from "./types.js";
+
+/**
+ * Compile a read story into its MCP `ToolSpec` projection.
+ *
+ * The tool is named `<noun>_<verb>`. A `condensed` parameter is appended
+ * uniformly; condensed responses render through the story's llm formatter,
+ * so CLI `--llm` output and MCP condensed output agree by construction.
+ */
+export default function compileReadTool<TData, TOutput>(
+  story: ReadStory<TData, TOutput>,
+): ToolSpec {
+  return {
+    name: `${story.noun}_${story.verb}`,
+    description: story.toolDescription,
+    params: {
+      ...projectToolParams(story.params),
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, params) {
+      const data = await story.resolve(rt, params);
+
+      if (params.condensed) {
+        return condense(story.formatters.llm(story.toOutput(data, params)));
+      }
+
+      return story.toEnvelope(data);
+    },
+  };
+}

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

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import condense from "./condense.js";
+
+describe("condense", () => {
+  it("wraps text in the condensed envelope with a chars/4 token estimate", () => {
+    const result = condense("abcdefgh");
+    expect(result).toEqual({
+      condensed: true,
+      text: "abcdefgh",
+      tokens: "~2",
+    });
+  });
+
+  it("rounds the token estimate up", () => {
+    const result = condense("abcde");
+    expect(result).toEqual({ condensed: true, text: "abcde", tokens: "~2" });
+  });
+});

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

@@ -0,0 +1,15 @@
+import type { ToolResult } from "../ToolSpec.js";
+
+/**
+ * Wrap condensed Markdown text in the MCP condensed tool envelope.
+ *
+ * The token figure is the shared chars/4 heuristic — the single estimator
+ * for every read tool, replacing the per-spec inline copies.
+ */
+export default function condense(text: string): ToolResult {
+  return {
+    condensed: true,
+    text,
+    tokens: `~${Math.ceil(text.length / 4)}`,
+  };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Read-story kernel — declare a read story once, project it to CLI and MCP.
+ * @module
+ */
+
+export { default as compileLookupCommand } from "./compileLookupCommand.js";
+export { default as compileLookupTool } from "./compileLookupTool.js";
+export { default as compileReadCommand } from "./compileReadCommand.js";
+export { default as compileReadTool } from "./compileReadTool.js";
+export { default as condense } from "./condense.js";
+export { default as normalizeNames } from "./normalizeNames.js";
+export { default as requirePragmaContext } from "./requirePragmaContext.js";
+export type {
+  LookupStory,
+  LookupStoryView,
+  ReadStory,
+  StoryEnvelope,
+  StoryParam,
+  StorySurface,
+} from "./types.js";

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import normalizeNames from "./normalizeNames.js";
+
+describe("normalizeNames", () => {
+  it("keeps non-empty strings from an array", () => {
+    expect(normalizeNames(["Button", "", "Card", 3, null])).toEqual([
+      "Button",
+      "Card",
+    ]);
+  });
+
+  it("falls back to the legacy single name", () => {
+    expect(normalizeNames(undefined, "Button")).toEqual(["Button"]);
+  });
+
+  it("returns empty for missing input", () => {
+    expect(normalizeNames(undefined, undefined)).toEqual([]);
+    expect(normalizeNames(undefined, "")).toEqual([]);
+  });
+});

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

@@ -0,0 +1,22 @@
+/**
+ * Normalize a `names` parameter into a clean string array.
+ *
+ * Accepts the multiselect array form and the legacy single `name` string,
+ * dropping empty and non-string entries. Shared by every lookup story —
+ * replaces the per-domain copies that previously lived in each
+ * `commands/lookup.ts`.
+ */
+export default function normalizeNames(
+  names: unknown,
+  legacyName?: unknown,
+): string[] {
+  if (Array.isArray(names)) {
+    return names.filter(
+      (name): name is string => typeof name === "string" && name.length > 0,
+    );
+  }
+  if (typeof legacyName === "string" && legacyName.length > 0) {
+    return [legacyName];
+  }
+  return [];
+}