@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/standard/commands/lookup.test.ts

@@ -1,135 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import type { PragmaContext } from "../../shared/context.js";
-import buildLookupCommand from "./lookup.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    cwd: "/tmp",
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    store,
-    config: { tier: undefined, channel: "prerelease" },
-    ...overrides,
-  };
-}
-
-async function executeOutput(
-  cmd: CommandDefinition,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<{ value: unknown; text: string }> {
-  const result = await cmd.execute(params, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  const text = result.render.plain(result.value);
-  return { value: result.value, text };
-}
-
-describe("buildLookupCommand", () => {
-  it("returns summary by default", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLookupCommand(ctx);
-    const { text } = await executeOutput(
-      cmd,
-      { names: ["react/component/folder-structure"] },
-      ctx,
-    );
-    expect(text).toContain("react/component/folder-structure");
-    expect(text).toContain("Category: react");
-    expect(text).not.toContain("Do:");
-  });
-
-  it("returns dos and donts with --detailed", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLookupCommand(ctx);
-    const { text } = await executeOutput(
-      cmd,
-      { names: ["react/component/folder-structure"], detailed: true },
-      ctx,
-    );
-    expect(text).toContain("Do:");
-    expect(text).toContain("Don't:");
-  });
-
-  it("throws ENTITY_NOT_FOUND for unknown standard", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLookupCommand(ctx);
-    const result = await cmd.execute({ names: ["nonexistent"] }, ctx);
-    expect(result.tag).toBe("output");
-    if (result.tag !== "output") {
-      expect.fail("Expected output result");
-    }
-    expect(result.render.plain(result.value)).toContain("Errors:");
-  });
-
-  it("renders LLM format with --llm", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text" as const, verbose: false },
-    });
-    const cmd = buildLookupCommand(ctx);
-    const { text } = await executeOutput(
-      cmd,
-      { names: ["react/component/folder-structure"], detailed: true },
-      ctx,
-    );
-    expect(text).toContain("## react/component/folder-structure");
-    expect(text).toContain("### Do");
-  });
-
-  it("renders JSON with --detailed", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    });
-    const cmd = buildLookupCommand(ctx);
-    const { text } = await executeOutput(
-      cmd,
-      { names: ["react/component/folder-structure"], detailed: true },
-      ctx,
-    );
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("react/component/folder-structure");
-    expect(parsed.dos).toBeDefined();
-    expect(parsed.donts).toBeDefined();
-  });
-
-  it("renders JSON without --detailed (omits dos/donts)", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    });
-    const cmd = buildLookupCommand(ctx);
-    const { text } = await executeOutput(
-      cmd,
-      { names: ["react/component/folder-structure"] },
-      ctx,
-    );
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("react/component/folder-structure");
-    expect(parsed.dos).toBeUndefined();
-    expect(parsed.donts).toBeUndefined();
-  });
-
-  it("renders multiple standards together", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLookupCommand(ctx);
-    const { text } = await executeOutput(
-      cmd,
-      { names: ["react/component/folder-structure", "react/component/props"] },
-      ctx,
-    );
-    expect(text).toContain("react/component/folder-structure");
-    expect(text).toContain("react/component/props");
-  });
-});

package/src/domains/standard/commands/lookup.ts

@@ -1,99 +0,0 @@
-/**
- * Wires the `pragma standard lookup <name-or-uri...>` CLI command.
- *
- * Retrieves detailed information for a single code standard, including
- * optional dos/donts code blocks when `--detailed` is passed.
- */
-
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createLookupView } from "#tui";
-import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import {
-  createInkLookupOptions,
-  lookupFormatters,
-} from "../formatters/index.js";
-import type { lookupStandard } from "../operations/index.js";
-import { resolveStandardLookup } from "../orchestration/index.js";
-
-interface StandardLookupOutput {
-  readonly result: LookupResult<Awaited<ReturnType<typeof lookupStandard>>>;
-  readonly detailed: boolean;
-}
-
-export default function buildLookupCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return {
-    path: ["standard", "lookup"],
-    description: "Look up detailed information for a standard by name or IRI",
-    parameters: [
-      {
-        name: "names",
-        description: "Standard names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-      },
-      {
-        name: "detailed",
-        description: "Include dos and donts with code blocks",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma standard lookup react/component/folder-structure",
-        "pragma standard lookup react/component/folder-structure react/component/props",
-        "pragma standard lookup react/component/folder-structure --detailed",
-        "pragma standard lookup react/component/folder-structure --llm",
-        "pragma standard lookup cs:react_props",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const names = normalizeNames(params.names, params.name);
-      const detailed = (params.detailed as boolean) ?? false;
-      const contract = await resolveStandardLookup(ctx.store, names);
-
-      return createOutputResult<StandardLookupOutput>(
-        { result: contract.result, detailed },
-        {
-          plain: ({ result, detailed: isDetailed }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (standard) => ({ standard, detailed: isDetailed }),
-            }),
-          ink: ({ result, detailed: isDetailed }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "standard",
-              options: createInkLookupOptions(isDetailed),
-            }),
-        },
-      );
-    },
-  };
-}
-
-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/standard/commands/sample.ts

@@ -1,57 +0,0 @@
-/**
- * Wires the `pragma standard sample` CLI command.
- *
- * Returns 1–5 complete standard instances as exemplars so agents
- * can learn the data shape before writing queries.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import type {
-  SampleOutput,
-  StandardDetailed,
-} from "../../shared/types/index.js";
-import { sampleFormatters } from "../formatters/index.js";
-import { sampleStandards } from "../operations/index.js";
-
-const NEXT_STEPS = [
-  "Use standard_lookup to inspect specific standards by name.",
-  "Use standard_list with --category to filter by category.",
-  "Use standard_categories to see all available categories.",
-];
-
-export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["standard", "sample"],
-    description:
-      "Return randomly selected complete standard instances as exemplars for shape discovery",
-    parameters: [
-      {
-        name: "count",
-        type: "string",
-        description: "Number of samples to return (1–5, default 2)",
-        required: false,
-      },
-    ],
-    meta: {
-      examples: ["pragma standard sample", "pragma standard sample --count 3"],
-    },
-    async execute(params) {
-      const count = Number(params.count ?? 2);
-      const result = await sampleStandards(ctx.store, count);
-
-      const output: SampleOutput<StandardDetailed> = {
-        ...result,
-        nextSteps: NEXT_STEPS,
-      };
-
-      return createOutputResult(output, {
-        plain: selectFormatter(ctx, sampleFormatters),
-      });
-    },
-  };
-}

package/src/domains/standard/formatters/categories.test.ts

@@ -1,44 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { CategorySummary } from "../../shared/types/index.js";
-import formatters from "./categories.js";
-
-const CATEGORIES: CategorySummary[] = [
-  { name: "code", standardCount: 1 },
-  { name: "react", standardCount: 2 },
-];
-
-describe("formatters.plain", () => {
-  it("renders singular for count 1", () => {
-    const text = formatters.plain(CATEGORIES);
-    expect(text).toContain("code (1 standard)");
-  });
-
-  it("renders plural for count > 1", () => {
-    const text = formatters.plain(CATEGORIES);
-    expect(text).toContain("react (2 standards)");
-  });
-});
-
-describe("formatters.llm", () => {
-  it("renders markdown heading and bold names", () => {
-    const text = formatters.llm(CATEGORIES);
-    expect(text).toContain("## Standard Categories");
-    expect(text).toContain("**react** (2)");
-  });
-});
-
-describe("formatters.json", () => {
-  it("returns valid JSON array", () => {
-    const text = formatters.json(CATEGORIES);
-    const parsed = JSON.parse(text);
-    expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed).toHaveLength(2);
-    expect(parsed[0].name).toBe("code");
-    expect(parsed[0].standardCount).toBe(1);
-  });
-
-  it("returns empty array for empty list", () => {
-    const text = formatters.json([]);
-    expect(JSON.parse(text)).toEqual([]);
-  });
-});

package/src/domains/standard/formatters/categories.ts

@@ -1,38 +0,0 @@
-/**
- * Three-mode formatter for `pragma standard categories` output.
- *
- * - **plain** — one line per category with standard count.
- * - **llm** — condensed Markdown consumed by LLM agents and reused
- *   by the MCP adapter when `condensed: true`.
- * - **json** — structured JSON array for programmatic consumption.
- */
-
-import type { Formatters } from "../../shared/formatters.js";
-import type { CategorySummary } from "../../shared/types/index.js";
-
-const formatters: Formatters<readonly CategorySummary[]> = {
-  plain(categories) {
-    const lines: string[] = [];
-    for (const c of categories) {
-      const plural = c.standardCount === 1 ? "standard" : "standards";
-      lines.push(`${c.name} (${c.standardCount} ${plural})`);
-    }
-    return lines.join("\n");
-  },
-
-  llm(categories) {
-    const lines: string[] = [];
-    lines.push("## Standard Categories");
-    lines.push("");
-    for (const c of categories) {
-      lines.push(`- **${c.name}** (${c.standardCount})`);
-    }
-    return lines.join("\n");
-  },
-
-  json(data) {
-    return JSON.stringify(data, null, 2);
-  },
-};
-
-export default formatters;

package/src/domains/standard/formatters/index.ts

@@ -1,10 +0,0 @@
-/** @module Re-exports standard formatters (`categoriesFormatters`, `listFormatters`, `lookupFormatters`, `sampleFormatters`). */
-
-export { default as categoriesFormatters } from "./categories.js";
-export { default as listFormatters } from "./list.js";
-export {
-  createInkLookupOptions,
-  default as lookupFormatters,
-} from "./lookup.js";
-export { default as sampleFormatters } from "./sample.js";
-export type { StandardListOutput, StandardLookupInput } from "./types.js";

package/src/domains/standard/formatters/list.test.ts

@@ -1,169 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import type {
-  StandardDetailed,
-  StandardSummary,
-} from "../../shared/types/index.js";
-import formatters from "./list.js";
-import type { StandardListOutput } from "./types.js";
-
-const SUMMARY: StandardSummary = {
-  uri: "http://example.com/s1" as URI,
-  name: "react/component/folder-structure",
-  category: "react",
-  description: "Components must follow the standard folder layout",
-};
-
-const DETAIL: StandardDetailed = {
-  ...SUMMARY,
-  dos: [
-    { language: "typescript", code: "export function Button() { ... }" },
-    { language: "typescript", code: "export function Input() { ... }" },
-  ],
-  donts: [
-    { language: "typescript", code: "export default class Button { ... }" },
-  ],
-};
-
-function summaryOutput(items: readonly StandardSummary[]): StandardListOutput {
-  return { items, disclosure: { level: "summary" } };
-}
-
-function digestOutput(
-  items: readonly StandardSummary[],
-  details: readonly (StandardDetailed | null)[],
-  maxExampleLength?: number,
-): StandardListOutput {
-  return {
-    items,
-    details,
-    disclosure: { level: "digest", maxExampleLength },
-  };
-}
-
-function detailedOutput(
-  items: readonly StandardSummary[],
-  details: readonly (StandardDetailed | null)[],
-): StandardListOutput {
-  return { items, details, disclosure: { level: "detailed" } };
-}
-
-// ---------------------------------------------------------------------------
-// Summary (default)
-// ---------------------------------------------------------------------------
-
-describe("formatters.plain — summary", () => {
-  it("renders name with category and description", () => {
-    const text = formatters.plain(summaryOutput([SUMMARY]));
-    expect(text).toContain("react/component/folder-structure [react]");
-    expect(text).toContain("  Components must follow");
-  });
-
-  it("omits category brackets when empty", () => {
-    const text = formatters.plain(
-      summaryOutput([{ ...SUMMARY, category: "" }]),
-    );
-    expect(text).not.toContain("[");
-  });
-});
-
-describe("formatters.llm — summary", () => {
-  it("renders markdown heading and bold names", () => {
-    const text = formatters.llm(summaryOutput([SUMMARY]));
-    expect(text).toContain("## Standards");
-    expect(text).toContain("**react/component/folder-structure**");
-  });
-});
-
-describe("formatters.json — summary", () => {
-  it("returns valid JSON array", () => {
-    const text = formatters.json(summaryOutput([SUMMARY]));
-    const parsed = JSON.parse(text);
-    expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed).toHaveLength(1);
-    expect(parsed[0].name).toBe("react/component/folder-structure");
-  });
-
-  it("returns empty array for empty list", () => {
-    const text = formatters.json(summaryOutput([]));
-    expect(JSON.parse(text)).toEqual([]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Digest
-// ---------------------------------------------------------------------------
-
-describe("formatters.plain — digest", () => {
-  it("includes first do example", () => {
-    const text = formatters.plain(digestOutput([SUMMARY], [DETAIL]));
-    expect(text).toContain("Example: export function Button()");
-  });
-
-  it("truncates long examples", () => {
-    const text = formatters.plain(digestOutput([SUMMARY], [DETAIL], 20));
-    expect(text).toContain("Example: ");
-    // Truncated to 20 chars (19 + ellipsis)
-    const exampleLine = text.split("\n").find((l) => l.includes("Example:"));
-    expect(exampleLine).toBeDefined();
-    if (!exampleLine) {
-      throw new Error("Expected example line");
-    }
-    // 20 char max means the example text portion is at most 20 chars
-    const exampleText = exampleLine.replace(/.*Example: /, "");
-    expect(exampleText.length).toBeLessThanOrEqual(20);
-  });
-
-  it("omits example when detail is null", () => {
-    const text = formatters.plain(digestOutput([SUMMARY], [null]));
-    expect(text).not.toContain("Example:");
-  });
-});
-
-describe("formatters.llm — digest", () => {
-  it("includes first do example in backticks", () => {
-    const text = formatters.llm(digestOutput([SUMMARY], [DETAIL]));
-    expect(text).toContain("Example: `export function Button()");
-  });
-});
-
-describe("formatters.json — digest", () => {
-  it("includes example field in enriched items", () => {
-    const text = formatters.json(digestOutput([SUMMARY], [DETAIL]));
-    const parsed = JSON.parse(text);
-    expect(parsed[0].example).toBeDefined();
-    expect(parsed[0].example).toContain("export function Button()");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Detailed
-// ---------------------------------------------------------------------------
-
-describe("formatters.plain — detailed", () => {
-  it("includes full dos and donts", () => {
-    const text = formatters.plain(detailedOutput([SUMMARY], [DETAIL]));
-    expect(text).toContain("Do:");
-    expect(text).toContain("export function Button()");
-    expect(text).toContain("export function Input()");
-    expect(text).toContain("Don't:");
-    expect(text).toContain("export default class Button");
-  });
-});
-
-describe("formatters.llm — detailed", () => {
-  it("includes dos and donts in markdown", () => {
-    const text = formatters.llm(detailedOutput([SUMMARY], [DETAIL]));
-    expect(text).toContain("**Do**:");
-    expect(text).toContain("**Don't**:");
-  });
-});
-
-describe("formatters.json — detailed", () => {
-  it("includes dos and donts arrays", () => {
-    const text = formatters.json(detailedOutput([SUMMARY], [DETAIL]));
-    const parsed = JSON.parse(text);
-    expect(parsed[0].dos).toHaveLength(2);
-    expect(parsed[0].donts).toHaveLength(1);
-  });
-});