@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,95 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { StandardDetailed } from "../../shared/types.js";
+import formatters from "./lookup.js";
+
+const DETAILED: StandardDetailed = {
+  uri: "http://example.com/s1" as URI,
+  name: "react/component/folder-structure",
+  category: "react",
+  description: "Components must follow the standard folder layout",
+  dos: [
+    { language: "typescript", code: "Place files in src/lib/" },
+    { language: "typescript", code: "Include index.ts barrel" },
+  ],
+  donts: [{ language: "typescript", code: "Use flat directory" }],
+};
+
+describe("formatters.plain", () => {
+  it("renders summary without dos/donts by default", () => {
+    const text = formatters.plain({ standard: DETAILED, detailed: false });
+    expect(text).toContain("react/component/folder-structure");
+    expect(text).toContain("URI: http://example.com/s1");
+    expect(text).toContain("Category: react");
+    expect(text).toContain("Description:");
+    expect(text).not.toContain("Do:");
+    expect(text).not.toContain("Don't:");
+  });
+
+  it("renders dos and donts when detailed", () => {
+    const text = formatters.plain({ standard: DETAILED, detailed: true });
+    expect(text).toContain("Do:");
+    expect(text).toContain("  Place files in src/lib/");
+    expect(text).toContain("Don't:");
+    expect(text).toContain("  Use flat directory");
+  });
+
+  it("renders dash for empty category", () => {
+    const text = formatters.plain({
+      standard: { ...DETAILED, category: "" },
+      detailed: false,
+    });
+    expect(text).toContain("Category: —");
+  });
+
+  it("renders extends when present", () => {
+    const text = formatters.plain({
+      standard: { ...DETAILED, extends: "react/component/base" },
+      detailed: false,
+    });
+    expect(text).toContain("Extends: react/component/base");
+  });
+});
+
+describe("formatters.llm", () => {
+  it("renders markdown heading", () => {
+    const text = formatters.llm({ standard: DETAILED, detailed: false });
+    expect(text).toContain("## react/component/folder-structure");
+    expect(text).toContain("URI: http://example.com/s1");
+    expect(text).not.toContain("### Do");
+  });
+
+  it("renders extends in llm output when present", () => {
+    const text = formatters.llm({
+      standard: { ...DETAILED, extends: "cs:react_base" },
+      detailed: false,
+    });
+    expect(text).toContain("Extends: cs:react_base");
+  });
+
+  it("renders do/dont sections when detailed", () => {
+    const text = formatters.llm({ standard: DETAILED, detailed: true });
+    expect(text).toContain("### Do");
+    expect(text).toContain("### Don't");
+    expect(text).toContain("- Place files in src/lib/");
+  });
+});
+
+describe("formatters.json", () => {
+  it("includes dos/donts when detailed", () => {
+    const parsed = JSON.parse(
+      formatters.json({ standard: DETAILED, detailed: true }),
+    );
+    expect(parsed.dos).toHaveLength(2);
+    expect(parsed.donts).toHaveLength(1);
+  });
+
+  it("omits dos/donts when not detailed", () => {
+    const parsed = JSON.parse(
+      formatters.json({ standard: DETAILED, detailed: false }),
+    );
+    expect(parsed.dos).toBeUndefined();
+    expect(parsed.donts).toBeUndefined();
+    expect(parsed.name).toBe("react/component/folder-structure");
+  });
+});

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

@@ -0,0 +1,86 @@
+/**
+ * Three-mode formatter for `pragma standard lookup` output.
+ *
+ * - **plain** — terminal text showing name, category, description, and
+ *   optional dos/donts when detailed.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON; omits dos/donts unless detailed.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { StandardLookupInput } from "./types.js";
+
+const formatters: Formatters<StandardLookupInput> = {
+  plain({ standard, detailed }) {
+    const lines: string[] = [];
+    lines.push(standard.name);
+    lines.push(`URI: ${standard.uri}`);
+    lines.push(`Category: ${standard.category || "—"}`);
+    lines.push(`Description: ${standard.description}`);
+    if (standard.extends) {
+      lines.push(`Extends: ${standard.extends}`);
+    }
+
+    if (detailed) {
+      if (standard.dos.length > 0) {
+        lines.push("");
+        lines.push("Do:");
+        for (const d of standard.dos) {
+          lines.push(`  ${d.code}`);
+        }
+      }
+
+      if (standard.donts.length > 0) {
+        lines.push("");
+        lines.push("Don't:");
+        for (const d of standard.donts) {
+          lines.push(`  ${d.code}`);
+        }
+      }
+    }
+
+    return lines.join("\n");
+  },
+
+  llm({ standard, detailed }) {
+    const lines: string[] = [];
+    lines.push(`## ${standard.name}`);
+    lines.push(`URI: ${standard.uri}`);
+    lines.push(`Category: ${standard.category || "—"}`);
+    if (standard.extends) {
+      lines.push(`Extends: ${standard.extends}`);
+    }
+    lines.push(standard.description);
+
+    if (detailed) {
+      if (standard.dos.length > 0) {
+        lines.push("");
+        lines.push("### Do");
+        for (const d of standard.dos) {
+          lines.push(`- ${d.code}`);
+        }
+      }
+
+      if (standard.donts.length > 0) {
+        lines.push("");
+        lines.push("### Don't");
+        for (const d of standard.donts) {
+          lines.push(`- ${d.code}`);
+        }
+      }
+    }
+
+    return lines.join("\n");
+  },
+
+  json({ standard, detailed }) {
+    if (detailed) {
+      return JSON.stringify(standard, null, 2);
+    }
+    const { dos: _dos, donts: _donts, ...summary } = standard;
+    return JSON.stringify(summary, null, 2);
+  },
+};
+
+export default formatters;

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

@@ -0,0 +1,31 @@
+/**
+ * Formatter input types for standard commands.
+ *
+ * Composite types that bundle the data with display options,
+ * so formatters conform to the `Formatters<T>` contract.
+ */
+
+import type {
+  Disclosure,
+  StandardDetailed,
+  StandardSummary,
+} from "../../shared/types.js";
+
+/** Input payload for the standard-lookup formatter, pairing data with a detail flag. */
+export interface StandardLookupInput {
+  readonly standard: StandardDetailed;
+  readonly detailed: boolean;
+}
+
+/**
+ * Input for the list formatter with progressive disclosure.
+ *
+ * - summary: items only (name + category + description)
+ * - digest: items enriched with first do example
+ * - detailed: items enriched with full dos/donts
+ */
+export interface StandardListOutput {
+  readonly items: readonly StandardSummary[];
+  readonly details?: readonly (StandardDetailed | null)[];
+  readonly disclosure: Disclosure;
+}

package/src/domains/standard/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @module Standard domain — CLI commands and operations.
+ *
+ * Commands: `pragma standard list`, `pragma standard lookup <name>`,
+ *           `pragma standard categories`.
+ * Operations: {@link lookupStandard}, {@link listStandards}, {@link listCategories}.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import {
+  categoriesCommand,
+  listCommand,
+  lookupCommand,
+} from "./commands/index.js";
+
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [listCommand(ctx), lookupCommand(ctx), categoriesCommand(ctx)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export {
+  listCategories,
+  listStandards,
+  lookupStandard,
+} from "./operations/index.js";
+export {
+  buildStandardFilters,
+  resolveStandardList,
+  resolveStandardLookup,
+  standardEmptyError,
+} from "./orchestration/index.js";

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

@@ -0,0 +1,2 @@
+/** @module Standard domain MCP barrel — standard_list, standard_lookup, standard_categories. */
+export { default as specs } from "./specs.js";

package/src/domains/standard/mcp/specs.ts

@@ -0,0 +1,197 @@
+/**
+ * MCP tool specs for the standard domain.
+ *
+ * Declarative definitions — no MCP imports. The adapter layer
+ * converts these into registered MCP tools via `registerFromSpec()`.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import {
+  type StandardListOutput,
+  categoriesFormatters as standardCatFmt,
+  listFormatters as standardListFmt,
+  lookupFormatters as standardLookupFmt,
+} from "../formatters/index.js";
+import { listCategories } from "../operations/index.js";
+import {
+  resolveStandardList,
+  resolveStandardLookup,
+} from "../orchestration/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "standard_list",
+    description:
+      "List code standards. Optionally filter by category or search term. Use digest/detailed for progressive disclosure.",
+    params: {
+      category: {
+        type: "string",
+        description: "Filter by category name",
+        optional: true,
+      },
+      search: {
+        type: "string",
+        description: "Search in name and description",
+        optional: true,
+      },
+      digest: {
+        type: "boolean",
+        description: "Show description and first example for each standard",
+        optional: true,
+      },
+      detailed: {
+        type: "boolean",
+        description: "Show full dos/donts for each standard",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { category, search, digest, detailed, condensed }) {
+      const resolution = await resolveStandardList(rt, {
+        category: category as string | undefined,
+        search: search as string | undefined,
+        digest: digest === true,
+        detailed: detailed === true,
+      });
+      const output: StandardListOutput = {
+        items: resolution.items,
+        details: resolution.details,
+        disclosure: resolution.disclosure,
+      };
+
+      if (condensed) {
+        const text = standardListFmt.llm(output);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      if (resolution.disclosure.level === "summary") {
+        return {
+          data: resolution.items,
+          meta: { count: resolution.items.length },
+        };
+      }
+
+      return {
+        data: JSON.parse(standardListFmt.json(output)),
+        meta: {
+          count: resolution.items.length,
+          disclosure: resolution.disclosure.level,
+        },
+      };
+    },
+  },
+
+  {
+    name: "standard_lookup",
+    description:
+      "Get detailed information about one or more code standards including dos and donts with code examples.",
+    params: {
+      names: {
+        type: "string[]",
+        description: "Standard names or IRIs to look up",
+        optional: false,
+      },
+      detailed: {
+        type: "boolean",
+        description:
+          "Return full details with dos/donts (default: true for MCP)",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { names, detailed, condensed }) {
+      const showDetailed = (detailed as boolean | undefined) ?? true;
+      const contract = await resolveStandardLookup(rt.store, names as string[]);
+      const result = contract.result;
+
+      if (condensed) {
+        const textParts = result.results.map((standard) =>
+          standardLookupFmt.llm({
+            standard,
+            detailed: showDetailed,
+          }),
+        );
+
+        if (result.errors.length > 0) {
+          textParts.push(
+            [
+              "### Errors",
+              ...result.errors.map(
+                (error) => `- ${error.query}: ${error.message}`,
+              ),
+            ].join("\n"),
+          );
+        }
+
+        const text = textParts.join("\n\n");
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      if (!showDetailed) {
+        return {
+          data: {
+            results: result.results.map(
+              ({ uri, name, category, description }) => ({
+                uri,
+                name,
+                category,
+                description,
+              }),
+            ),
+            errors: result.errors,
+          },
+          meta: { count: result.results.length },
+        };
+      }
+
+      return { data: result, meta: { count: result.results.length } };
+    },
+  },
+
+  {
+    name: "standard_categories",
+    description: "List all code standard categories.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { condensed }) {
+      const result = await listCategories(rt.store);
+
+      if (condensed) {
+        const text = standardCatFmt.llm(result);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: result, meta: { count: result.length } };
+    },
+  },
+];
+
+export default specs;

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

@@ -0,0 +1,61 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import listCategories from "./categories.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());
+
+describe("listCategories", () => {
+  it("returns categories with standard counts", async () => {
+    const result = await listCategories(store);
+    expect(result.length).toBe(2);
+
+    const react = result.find((c) => c.name === "react");
+    expect(react?.standardCount).toBe(2);
+
+    const code = result.find((c) => c.name === "code");
+    expect(code?.standardCount).toBe(1);
+  });
+
+  it("returns sorted by name", async () => {
+    const result = await listCategories(store);
+    const names = result.map((c) => c.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+
+  it("includes categories with zero standards", async () => {
+    const ttlWithEmptyCategory = `
+      @prefix cs: <${PREFIX_MAP.cs}> .
+      cs:empty_cat a cs:Category ; cs:slug "empty" .
+      cs:filled_cat a cs:Category ; cs:slug "filled" .
+      cs:s1 a cs:CodeStandard ;
+        cs:name "filled/one" ;
+        cs:hasCategory cs:filled_cat ;
+        cs:description "A standard" .
+    `;
+    const { store: testStore, cleanup: testCleanup } = await createTestStore({
+      ttl: ttlWithEmptyCategory,
+    });
+    try {
+      const result = await listCategories(testStore);
+      const empty = result.find((c) => c.name === "empty");
+      expect(empty).toBeDefined();
+      expect(empty?.standardCount).toBe(0);
+      const filled = result.find((c) => c.name === "filled");
+      expect(filled?.standardCount).toBe(1);
+    } finally {
+      testCleanup();
+    }
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * Lists all standard categories with the number of standards in each.
+ *
+ * @param store - ke store to query
+ * @returns array of category summaries ordered by name, empty when none exist
+ * @note Queries ke store
+ */
+
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { CategorySummary } from "../../shared/types.js";
+
+export default async function listCategories(
+  store: Store,
+): Promise<CategorySummary[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?categoryName (COUNT(?standard) AS ?count)
+      WHERE {
+        ?cat a ${P.cs}Category ;
+             ${P.cs}slug ?categoryName .
+        OPTIONAL {
+          ?standard a ${P.cs}CodeStandard ;
+                    ${P.cs}hasCategory ?cat .
+        }
+      }
+      GROUP BY ?categoryName
+      ORDER BY ?categoryName
+    `),
+  );
+
+  if (result.type !== "select") return [];
+  return result.bindings.map((b) => ({
+    name: b.categoryName ?? "",
+    standardCount: Number.parseInt(b.count ?? "0", 10) || 0,
+  }));
+}

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

@@ -0,0 +1,5 @@
+/** @module Re-exports standard operations (`listCategories`, `getStandard`, `listStandards`). */
+
+export { default as listCategories } from "./categories.js";
+export { default as listStandards } from "./list.js";
+export { default as lookupStandard } from "./lookup.js";

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

@@ -0,0 +1,75 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import listStandards from "./list.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());
+
+describe("listStandards", () => {
+  it("returns all standards", async () => {
+    const result = await listStandards(store);
+    expect(result.length).toBe(3);
+    const names = result.map((s) => s.name);
+    expect(names).toContain("react/component/folder-structure");
+    expect(names).toContain("react/component/props");
+    expect(names).toContain("code/function/purity");
+  });
+
+  it("includes category names", async () => {
+    const result = await listStandards(store);
+    const folder = result.find(
+      (s) => s.name === "react/component/folder-structure",
+    );
+    expect(folder?.category).toBe("react");
+  });
+
+  it("returns sorted by name", async () => {
+    const result = await listStandards(store);
+    const names = result.map((s) => s.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+
+  it("filters by category", async () => {
+    const result = await listStandards(store, { category: "react" });
+    expect(result.length).toBe(2);
+    for (const s of result) {
+      expect(s.category).toBe("react");
+    }
+  });
+
+  it("filters by search term in name", async () => {
+    const result = await listStandards(store, { search: "folder" });
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe("react/component/folder-structure");
+  });
+
+  it("filters by search term in description", async () => {
+    const result = await listStandards(store, { search: "pure" });
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe("code/function/purity");
+  });
+
+  it("returns empty for non-matching category", async () => {
+    const result = await listStandards(store, { category: "nonexistent" });
+    expect(result.length).toBe(0);
+  });
+
+  it("combines category and search filters", async () => {
+    const result = await listStandards(store, {
+      category: "react",
+      search: "props",
+    });
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe("react/component/props");
+  });
+});

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

@@ -0,0 +1,64 @@
+/**
+ * Lists all code standards, optionally filtered by category or search term.
+ *
+ * @param store - ke store to query
+ * @param filters - optional category and/or search text filters
+ * @returns array of standard summaries ordered by name, empty when none match
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type {
+  StandardListFilters,
+  StandardSummary,
+} from "../../shared/types.js";
+
+export default async function listStandards(
+  store: Store,
+  filters?: StandardListFilters,
+): Promise<StandardSummary[]> {
+  const filterClauses: string[] = [];
+
+  if (filters?.category) {
+    const escaped = escapeSparqlValue(filters.category.toLowerCase());
+    filterClauses.push(
+      `?standard ${P.cs}hasCategory ?filterCat . ?filterCat ${P.cs}slug ?catSlug . FILTER(?catSlug = ${escaped})`,
+    );
+  }
+
+  if (filters?.search) {
+    const escaped = escapeSparqlValue(filters.search.toLowerCase());
+    filterClauses.push(
+      `FILTER(CONTAINS(LCASE(?name), ${escaped}) || CONTAINS(LCASE(?description), ${escaped}))`,
+    );
+  }
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?standard ?name ?categoryName ?description
+      WHERE {
+        ?standard a ${P.cs}CodeStandard ;
+                  ${P.cs}name ?name ;
+                  ${P.cs}description ?description .
+        OPTIONAL {
+          ?standard ${P.cs}hasCategory ?cat .
+          ?cat ${P.cs}slug ?categoryName .
+        }
+        ${filterClauses.join("\n        ")}
+      }
+      ORDER BY ?name
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  return result.bindings.map((b) => ({
+    uri: (b.standard ?? "") as URI,
+    name: b.name ?? "",
+    category: b.categoryName ?? "",
+    description: b.description ?? "",
+  }));
+}