@canonical/pragma-cli 0.31.0 → 0.33.0

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

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

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

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

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

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

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

@@ -1,20 +0,0 @@
-/**
- * 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

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

@@ -1,22 +0,0 @@
-/**
- * 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 [];
-}

package/src/domains/shared/stories/pack/applyPackFilters.test.ts

@@ -1,151 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import applyPackFilters from "./applyPackFilters.js";
-import type { StoryPackFilter } from "./types.js";
-
-const ROWS = [
-  { name: "Gazpacho", category: "soup" },
-  { name: "Pancakes", category: "breakfast" },
-];
-const FILTERS: StoryPackFilter[] = [
-  { param: "category", variable: "category", values: ["breakfast", "soup"] },
-];
-
-describe("applyPackFilters", () => {
-  it("returns rows unchanged when no filter value is provided", () => {
-    expect(applyPackFilters(ROWS, FILTERS, {})).toEqual(ROWS);
-  });
-
-  it("returns rows unchanged when no filters are declared", () => {
-    expect(applyPackFilters(ROWS, undefined, { category: "soup" })).toEqual(
-      ROWS,
-    );
-  });
-
-  it("keeps only rows matching the provided value", () => {
-    const rows = applyPackFilters(ROWS, FILTERS, { category: "soup" });
-    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("rejects values outside the declared set", () => {
-    expect(() =>
-      applyPackFilters(ROWS, FILTERS, { category: "dinner" }),
-    ).toThrowError(PragmaError);
-    try {
-      applyPackFilters(ROWS, FILTERS, { category: "dinner" });
-    } catch (error) {
-      expect((error as PragmaError).code).toBe("INVALID_INPUT");
-      expect((error as PragmaError).recovery?.message).toContain("breakfast");
-    }
-  });
-
-  it("rejects non-string values and suggests the declared set", () => {
-    expect(() => applyPackFilters(ROWS, FILTERS, { category: 3 })).toThrowError(
-      PragmaError,
-    );
-    try {
-      applyPackFilters(ROWS, FILTERS, { category: ["soup"] });
-    } catch (error) {
-      expect((error as PragmaError).validOptions).toEqual([
-        "breakfast",
-        "soup",
-      ]);
-    }
-  });
-
-  it("canonicalizes case-insensitive input to the declared value", () => {
-    const rows = applyPackFilters(ROWS, FILTERS, { category: "SOUP" });
-    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("trims surrounding whitespace from the provided value", () => {
-    const rows = applyPackFilters(ROWS, FILTERS, { category: "  soup " });
-    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("matches unicode values across NFC/NFD normalization forms", () => {
-    const filters: StoryPackFilter[] = [
-      { param: "kind", variable: "kind", values: ["entr\u00e9e"] },
-    ];
-    const rows = [{ name: "Salad", kind: "entre\u0301e" }];
-    expect(
-      applyPackFilters(rows, filters, { kind: "entre\u0301e" }),
-    ).toHaveLength(1);
-  });
-
-  it("never matches rows without a binding for the variable", () => {
-    const rows = [{ name: "Mystery" }, ...ROWS];
-    const filtered = applyPackFilters(rows, FILTERS, { category: "soup" });
-    expect(filtered.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("carries the declared values as valid options on rejection", () => {
-    try {
-      applyPackFilters(ROWS, FILTERS, { category: "sopu" });
-    } catch (error) {
-      expect((error as PragmaError).code).toBe("INVALID_INPUT");
-      expect((error as PragmaError).validOptions).toContain("soup");
-    }
-  });
-
-  it("applies several filters conjunctively", () => {
-    const filters: StoryPackFilter[] = [
-      ...FILTERS,
-      { param: "name", variable: "name", values: ["Gazpacho", "Pancakes"] },
-    ];
-    const rows = applyPackFilters(ROWS, filters, {
-      category: "soup",
-      name: "Pancakes",
-    });
-    expect(rows).toEqual([]);
-  });
-});
-
-// Value-free filters (pack v1): no declared value set, case-insensitive
-// equality against the variable — the valid values live in the data.
-describe("applyPackFilters — value-free filters", () => {
-  const FREE_FILTERS: StoryPackFilter[] = [
-    { param: "category", variable: "category" },
-  ];
-
-  it("matches on case-insensitive equality with the variable", () => {
-    const rows = applyPackFilters(ROWS, FREE_FILTERS, { category: "SOUP" });
-    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("trims surrounding whitespace from the provided value", () => {
-    const rows = applyPackFilters(ROWS, FREE_FILTERS, { category: " soup " });
-    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("returns no rows for an unknown value instead of rejecting", () => {
-    expect(
-      applyPackFilters(ROWS, FREE_FILTERS, { category: "dinner" }),
-    ).toEqual([]);
-  });
-
-  it("matches unicode values across NFC/NFD normalization forms", () => {
-    const rows = [{ name: "Salad", kind: "entr\u00e9e" }];
-    const filters: StoryPackFilter[] = [{ param: "kind", variable: "kind" }];
-    expect(
-      applyPackFilters(rows, filters, { kind: "entre\u0301e" }),
-    ).toHaveLength(1);
-  });
-
-  it("never matches rows without a binding for the variable", () => {
-    const rows = [{ name: "Mystery" }, ...ROWS];
-    const filtered = applyPackFilters(rows, FREE_FILTERS, { category: "soup" });
-    expect(filtered.map((row) => row.name)).toEqual(["Gazpacho"]);
-  });
-
-  it("rejects non-string values with INVALID_INPUT", () => {
-    expect(() =>
-      applyPackFilters(ROWS, FREE_FILTERS, { category: 3 }),
-    ).toThrowError(PragmaError);
-    try {
-      applyPackFilters(ROWS, FREE_FILTERS, { category: ["soup"] });
-    } catch (error) {
-      expect((error as PragmaError).code).toBe("INVALID_INPUT");
-    }
-  });
-});

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

@@ -1,111 +0,0 @@
-import { PragmaError } from "#error";
-import type { StoryPackFilter } from "./types.js";
-
-/**
- * Apply declared pack filters to resolved list rows.
- *
- * Filters are row predicates on projected SELECT variables — the author
- * query is never modified, so user input cannot inject SPARQL and the
- * query's ordering is preserved.
- *
- * Matching semantics:
- * - With declared `values`: input is trimmed, unicode-normalized (NFC),
- *   and matched against the declared values case-insensitively; the
- *   DECLARED value is canonical and rows are compared against it exactly
- *   (NFC on both sides).
- * - Without `values` (value-free filter): the input itself is the term —
- *   trimmed, NFC-normalized — and rows match on case-insensitive equality
- *   with the variable's value. Nothing is rejected up front because the
- *   valid set lives in the data.
- * - ke bindings carry lexical forms — language tags and datatypes are
- *   already stripped — so plain string comparison is sound.
- * - A row without a binding for the variable (e.g. from OPTIONAL) never
- *   matches an active filter.
- * - Several provided filters combine conjunctively.
- *
- * @param rows - Rows produced by the pack's list query.
- * @param filters - Declared filters (absent means no filtering).
- * @param params - Story parameters as provided by the surface.
- * @returns Rows matching every provided filter.
- * @throws PragmaError with code `INVALID_INPUT` (carrying the declared
- *         values as valid options) when a provided value is not in the
- *         filter's declared set, or when a value-free filter receives a
- *         non-string value.
- */
-export default function applyPackFilters(
-  rows: Record<string, string>[],
-  filters: readonly StoryPackFilter[] | undefined,
-  params: Record<string, unknown>,
-): Record<string, string>[] {
-  // Start from the caller's array; each active filter's `.filter()` yields a
-  // fresh array, so with no active filter the rows pass through unmodified —
-  // no defensive clone (the caller owns the query result).
-  let result = rows;
-  for (const filter of filters ?? []) {
-    const provided = params[filter.param];
-    if (provided === undefined) continue;
-    const values = filter.values;
-    if (values === undefined) {
-      // Value-free filter: case-insensitive equality against the variable.
-      const term = requireStringValue(provided, filter).toLowerCase();
-      result = result.filter(
-        (row) => row[filter.variable]?.normalize("NFC").toLowerCase() === term,
-      );
-      continue;
-    }
-    const canonical = canonicalizeFilterValue(provided, filter, values);
-    result = result.filter(
-      (row) => row[filter.variable]?.normalize("NFC") === canonical,
-    );
-  }
-  return result;
-}
-
-/**
- * Require a value-free filter's input to be a trimmed, NFC-normalized
- * string.
- *
- * @throws PragmaError with code `INVALID_INPUT` when it is not a string.
- */
-function requireStringValue(
-  provided: unknown,
-  filter: StoryPackFilter,
-): string {
-  if (typeof provided !== "string") {
-    throw PragmaError.invalidInput(filter.param, String(provided), {
-      recovery: {
-        message: `Provide a string value for --${filter.param}.`,
-      },
-    });
-  }
-  return provided.trim().normalize("NFC");
-}
-
-/**
- * Resolve a provided filter value to its declared canonical form.
- *
- * @throws PragmaError with code `INVALID_INPUT` when the value is not a
- *         string or not in the declared set.
- */
-function canonicalizeFilterValue(
-  provided: unknown,
-  filter: StoryPackFilter,
-  values: readonly string[],
-): string {
-  if (typeof provided === "string") {
-    const normalized = provided.trim().normalize("NFC");
-    const match = values.find(
-      (value) =>
-        value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
-    );
-    if (match !== undefined) {
-      return match.normalize("NFC");
-    }
-  }
-  throw PragmaError.invalidInput(filter.param, String(provided), {
-    validOptions: [...values],
-    recovery: {
-      message: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
-    },
-  });
-}