@canonical/pragma-cli 0.18.0

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

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

@@ -0,0 +1,127 @@
+/**
+ * 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 type { PragmaContext } from "../../shared/context.js";
+import type { LookupResult } from "../../shared/contracts.js";
+import { 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: renderStandardLookupOutput(ctx) },
+      );
+    },
+  };
+}
+
+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 [];
+}
+
+function renderStandardLookupOutput(
+  ctx: PragmaContext,
+): (data: StandardLookupOutput) => string {
+  return ({ result, detailed }) => {
+    const formatOne =
+      ctx.globalFlags.format === "json"
+        ? lookupFormatters.json
+        : ctx.globalFlags.llm
+          ? lookupFormatters.llm
+          : lookupFormatters.plain;
+
+    if (ctx.globalFlags.format === "json") {
+      if (result.results.length === 1 && result.errors.length === 0) {
+        const only = result.results[0];
+        return only
+          ? lookupFormatters.json({ standard: only, detailed })
+          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
+      }
+
+      return JSON.stringify(
+        {
+          results: result.results.map((standard) =>
+            JSON.parse(lookupFormatters.json({ standard, detailed })),
+          ),
+          errors: result.errors,
+        },
+        null,
+        2,
+      );
+    }
+
+    const parts = result.results.map((standard) =>
+      formatOne({ standard, detailed }),
+    );
+
+    if (result.errors.length > 0) {
+      parts.push(
+        [
+          "Errors:",
+          ...result.errors.map((error) => `- ${error.query}: ${error.message}`),
+        ].join("\n"),
+      );
+    }
+
+    return parts.join("\n\n");
+  };
+}

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

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import type { CategorySummary } from "../../shared/types.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

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

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

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

@@ -0,0 +1,166 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { StandardDetailed, StandardSummary } from "../../shared/types.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);
+  });
+});

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

@@ -0,0 +1,156 @@
+/**
+ * Three-mode formatter for `pragma standard list` output.
+ *
+ * - **plain** — terminal text with progressive disclosure.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON; enrichment varies by disclosure level.
+ *
+ * Disclosure levels:
+ *   - summary  — name + category + description (default)
+ *   - digest   — summary + first do example (truncated)
+ *   - detailed — summary + full dos/donts
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { CodeBlock, StandardDetailed } from "../../shared/types.js";
+import type { StandardListOutput } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_EXAMPLE_LENGTH = 120;
+
+function truncate(text: string, max: number): string {
+  const oneLine = text.replace(/\n/g, " ").trim();
+  return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}
+
+function firstDoExample(
+  detail: StandardDetailed | null | undefined,
+  maxLen: number,
+): string | undefined {
+  if (!detail || detail.dos.length === 0) return undefined;
+  // Safe — length check above guarantees dos[0] exists
+  return truncate((detail.dos[0] as CodeBlock).code, maxLen);
+}
+
+// ---------------------------------------------------------------------------
+// Plain
+// ---------------------------------------------------------------------------
+
+function plain({ items, details, disclosure }: StandardListOutput): string {
+  const lines: string[] = [];
+
+  for (const [i, s] of items.entries()) {
+    const cat = s.category ? ` [${s.category}]` : "";
+    lines.push(`${s.name}${cat}`);
+    lines.push(`  ${s.description}`);
+
+    if (disclosure.level === "digest") {
+      const maxLen = disclosure.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH;
+      const example = firstDoExample(details?.[i], maxLen);
+      if (example) {
+        lines.push(`  Example: ${example}`);
+      }
+    }
+
+    if (disclosure.level === "detailed") {
+      const detail = details?.[i];
+      if (detail) {
+        if (detail.dos.length > 0) {
+          lines.push("  Do:");
+          for (const d of detail.dos) {
+            lines.push(`    ${d.code}`);
+          }
+        }
+        if (detail.donts.length > 0) {
+          lines.push("  Don't:");
+          for (const d of detail.donts) {
+            lines.push(`    ${d.code}`);
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// LLM
+// ---------------------------------------------------------------------------
+
+function llm({ items, details, disclosure }: StandardListOutput): string {
+  const lines: string[] = [];
+  lines.push("## Standards");
+  lines.push("");
+
+  for (const [i, s] of items.entries()) {
+    const cat = s.category ? ` [${s.category}]` : "";
+    lines.push(`- **${s.name}**${cat}: ${s.description}`);
+
+    if (disclosure.level === "digest") {
+      const maxLen = disclosure.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH;
+      const example = firstDoExample(details?.[i], maxLen);
+      if (example) {
+        lines.push(`  - Example: \`${example}\``);
+      }
+    }
+
+    if (disclosure.level === "detailed") {
+      const detail = details?.[i];
+      if (detail) {
+        if (detail.dos.length > 0) {
+          lines.push("  - **Do**:");
+          for (const d of detail.dos) {
+            lines.push(`    - ${d.code}`);
+          }
+        }
+        if (detail.donts.length > 0) {
+          lines.push("  - **Don't**:");
+          for (const d of detail.donts) {
+            lines.push(`    - ${d.code}`);
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// JSON
+// ---------------------------------------------------------------------------
+
+function json({ items, details, disclosure }: StandardListOutput): string {
+  if (disclosure.level === "summary" || !details) {
+    return JSON.stringify(items, null, 2);
+  }
+
+  if (disclosure.level === "digest") {
+    const maxLen = disclosure.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH;
+    const enriched = items.map((s, i) => {
+      const example = firstDoExample(details[i], maxLen);
+      return example ? { ...s, example } : s;
+    });
+    return JSON.stringify(enriched, null, 2);
+  }
+
+  // detailed — merge full detail into each item
+  const enriched = items.map((s, i) => {
+    const detail = details[i];
+    return detail ? { ...s, dos: detail.dos, donts: detail.donts } : s;
+  });
+  return JSON.stringify(enriched, null, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+const formatters: Formatters<StandardListOutput> = { plain, llm, json };
+
+export default formatters;