@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,58 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import lookupStandard 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());
+
+describe("lookupStandard", () => {
+  it("returns detailed data with dos and donts", async () => {
+    const result = await lookupStandard(
+      store,
+      "react/component/folder-structure",
+    );
+    expect(result.name).toBe("react/component/folder-structure");
+    expect(result.category).toBe("react");
+    expect(result.dos.length).toBeGreaterThan(0);
+    expect(result.donts.length).toBeGreaterThan(0);
+  });
+
+  it("throws PragmaError.notFound for unknown standard", async () => {
+    await expect(lookupStandard(store, "nonexistent")).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await lookupStandard(store, "nonexistent");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
+    }
+  });
+
+  it("resolves prefixed IRIs and compacts extends", async () => {
+    const result = await lookupStandard(store, "cs:react_props");
+    expect(result.name).toBe("react/component/props");
+    expect(result.extends).toBe("cs:react_folder");
+  });
+
+  it("resolves full IRIs", async () => {
+    const result = await lookupStandard(
+      store,
+      "http://pragma.canonical.com/codestandards#react_props",
+    );
+    expect(result.name).toBe("react/component/props");
+    expect(result.uri).toBe(
+      "http://pragma.canonical.com/codestandards#react_props",
+    );
+  });
+});

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

@@ -0,0 +1,142 @@
+/**
+ * Look up detailed information for a single code standard by name.
+ *
+ * Queries the base standard data plus its dos and donts code blocks,
+ * then assembles a {@link StandardDetailed} object.
+ *
+ * @param store - ke store to query
+ * @param name - standard name (e.g. "react/component/folder-structure")
+ * @returns full standard detail including dos/donts code blocks
+ * @throws PragmaError.notFound if the standard does not exist
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { PragmaError } from "#error";
+import resolveUri from "../../graph/helpers/resolveUri.js";
+import { buildQuery } from "../../shared/buildQuery.js";
+import compactUri from "../../shared/compactUri.js";
+import { P } from "../../shared/prefixes.js";
+import type { CodeBlock, StandardDetailed } from "../../shared/types.js";
+
+export default async function lookupStandard(
+  store: Store,
+  nameOrUri: string,
+): Promise<StandardDetailed> {
+  const subjectClause = buildLookupSubjectClause(nameOrUri, store.prefixes);
+  const bindClause =
+    subjectClause === null ? "" : `BIND(${subjectClause} AS ?standard)`;
+  const matchClause =
+    subjectClause === null
+      ? `?standard ${P.cs}name ${escapeSparqlValue(nameOrUri)} .`
+      : "";
+
+  const baseResult = await store.query(
+    buildQuery(`
+      SELECT ?standard ?name ?categoryName ?description ?extends
+      WHERE {
+        ${bindClause}
+        ?standard a ${P.cs}CodeStandard ;
+                  ${P.cs}name ?name ;
+                  ${P.cs}description ?description .
+        ${matchClause}
+        OPTIONAL {
+          ?standard ${P.cs}hasCategory ?cat .
+          ?cat ${P.cs}slug ?categoryName .
+        }
+        OPTIONAL { ?standard ${P.cs}extends ?extends }
+      }
+      LIMIT 1
+    `),
+  );
+
+  if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
+    throw PragmaError.notFound("standard", nameOrUri, {
+      recovery: {
+        message: "List available standards.",
+        cli: "pragma standard list",
+        mcp: { tool: "standard_list" },
+      },
+    });
+  }
+
+  // Safe: length check above guarantees bindings[0] exists
+  const base = baseResult.bindings[0] as (typeof baseResult.bindings)[number];
+  const standardUri = base.standard;
+
+  // Fetch dos (cs:do → cs:Example with cs:description, cs:language, cs:code)
+  const dosResult = await store.query(
+    buildQuery(`
+      SELECT ?description ?language ?code
+      WHERE {
+        <${standardUri}> ${P.cs}do ?example .
+        OPTIONAL { ?example ${P.cs}description ?description }
+        OPTIONAL { ?example ${P.cs}language ?language }
+        OPTIONAL { ?example ${P.cs}code ?code }
+      }
+    `),
+  );
+
+  const dos: CodeBlock[] =
+    dosResult.type === "select"
+      ? dosResult.bindings.map((b) => ({
+          language: b.language ?? "typescript",
+          code: b.code ?? "",
+          caption: b.description,
+        }))
+      : [];
+
+  // Fetch donts (cs:dont → cs:Example with cs:description, cs:language, cs:code)
+  const dontsResult = await store.query(
+    buildQuery(`
+      SELECT ?description ?language ?code
+      WHERE {
+        <${standardUri}> ${P.cs}dont ?example .
+        OPTIONAL { ?example ${P.cs}description ?description }
+        OPTIONAL { ?example ${P.cs}language ?language }
+        OPTIONAL { ?example ${P.cs}code ?code }
+      }
+    `),
+  );
+
+  const donts: CodeBlock[] =
+    dontsResult.type === "select"
+      ? dontsResult.bindings.map((b) => ({
+          language: b.language ?? "typescript",
+          code: b.code ?? "",
+          caption: b.description,
+        }))
+      : [];
+
+  return {
+    uri: (standardUri ?? "") as URI,
+    name: base.name ?? nameOrUri,
+    category: base.categoryName ?? "",
+    description: base.description ?? "",
+    extends: base.extends
+      ? compactUri(base.extends, store.prefixes)
+      : undefined,
+    dos,
+    donts,
+  };
+}
+
+function buildLookupSubjectClause(
+  query: string,
+  prefixes: Readonly<Record<string, string>>,
+): string | null {
+  if (!looksLikeUri(query)) {
+    return null;
+  }
+
+  return `<${resolveUri(query, prefixes)}>`;
+}
+
+function looksLikeUri(query: string): boolean {
+  return (
+    query.startsWith("http://") ||
+    query.startsWith("https://") ||
+    query.includes(":")
+  );
+}

package/src/domains/standard/orchestration/buildStandardFilters.ts

@@ -0,0 +1,11 @@
+import type { StandardListFilters } from "../../shared/types.js";
+
+export default function buildStandardFilters(params: {
+  category?: string;
+  search?: string;
+}): StandardListFilters {
+  return {
+    category: params.category,
+    search: params.search,
+  };
+}

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

@@ -0,0 +1,4 @@
+export { default as buildStandardFilters } from "./buildStandardFilters.js";
+export { default as resolveStandardList } from "./resolveStandardList.js";
+export { default as resolveStandardLookup } from "./resolveStandardLookup.js";
+export { default as standardEmptyError } from "./standardEmptyError.js";

package/src/domains/standard/orchestration/resolveStandardList.ts

@@ -0,0 +1,42 @@
+import type { ListParams } from "../../shared/contracts.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { Disclosure, StandardListFilters } from "../../shared/types.js";
+import { listStandards, lookupStandard } from "../operations/index.js";
+import type { StandardListResolution } from "../types.js";
+import buildStandardFilters from "./buildStandardFilters.js";
+import standardEmptyError from "./standardEmptyError.js";
+
+export default async function resolveStandardList(
+  rt: Pick<PragmaRuntime, "store">,
+  params: ListParams & StandardListFilters,
+): Promise<StandardListResolution> {
+  const filters = buildStandardFilters(params);
+  const items = await listStandards(rt.store, filters);
+
+  if (items.length === 0) {
+    throw standardEmptyError(filters);
+  }
+
+  const disclosure: Disclosure = params.detailed
+    ? { level: "detailed" }
+    : params.digest
+      ? { level: "digest" }
+      : { level: "summary" };
+
+  const details =
+    disclosure.level === "summary"
+      ? undefined
+      : await Promise.all(
+          items.map((item) =>
+            lookupStandard(rt.store, item.name).catch(() => null),
+          ),
+        );
+
+  return {
+    params,
+    items,
+    filters,
+    disclosure,
+    details,
+  };
+}

package/src/domains/standard/orchestration/resolveStandardLookup.ts

@@ -0,0 +1,20 @@
+import type { LookupContract, LookupResult } from "../../shared/contracts.js";
+import lookupMany from "../../shared/lookupMany.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { StandardDetailed } from "../../shared/types.js";
+import { lookupStandard } from "../operations/index.js";
+
+export default async function resolveStandardLookup(
+  store: Pick<PragmaRuntime, "store">["store"],
+  queries: readonly string[],
+): Promise<LookupContract<StandardDetailed>> {
+  const result: LookupResult<StandardDetailed> = await lookupMany(
+    queries,
+    (query) => lookupStandard(store, query),
+  );
+
+  return {
+    params: { names: queries },
+    result,
+  };
+}

package/src/domains/standard/orchestration/standardEmptyError.ts

@@ -0,0 +1,19 @@
+import { PragmaError } from "#error";
+import type { StandardListFilters } from "../../shared/types.js";
+
+export default function standardEmptyError(
+  filters: StandardListFilters,
+): PragmaError {
+  const active: Record<string, string> = {};
+  if (filters.category) active.category = filters.category;
+  if (filters.search) active.search = filters.search;
+
+  return PragmaError.emptyResults("standard", {
+    filters: Object.keys(active).length > 0 ? active : undefined,
+    recovery: {
+      message: "List all standards without filters.",
+      cli: "pragma standard list",
+      mcp: { tool: "standard_list" },
+    },
+  });
+}

package/src/domains/standard/types.ts

@@ -0,0 +1,15 @@
+import type { ListParams } from "../shared/contracts.js";
+import type {
+  Disclosure,
+  StandardDetailed,
+  StandardListFilters,
+  StandardSummary,
+} from "../shared/types.js";
+
+export interface StandardListResolution {
+  readonly params: ListParams & StandardListFilters;
+  readonly items: readonly StandardSummary[];
+  readonly filters: StandardListFilters;
+  readonly disclosure: Disclosure;
+  readonly details?: readonly (StandardDetailed | null)[];
+}

package/src/domains/tier/commands/index.ts

@@ -0,0 +1,3 @@
+/** @module Re-exports tier command builders (`list`). */
+
+export { default as listCommand } from "./list.js";

package/src/domains/tier/commands/list.test.ts

@@ -0,0 +1,67 @@
+import type { CommandOutputResult } 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 listCommand 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());
+
+function makeCtx(
+  overrides?: Partial<PragmaContext["globalFlags"]>,
+): PragmaContext {
+  return {
+    cwd: "/tmp",
+    store,
+    config: { tier: undefined, channel: "normal" },
+    globalFlags: {
+      llm: false,
+      format: "text",
+      verbose: false,
+      ...overrides,
+    },
+  };
+}
+
+describe("tier list command", () => {
+  it("returns tiers with hierarchy", async () => {
+    const ctx = makeCtx();
+    const cmd = listCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+    expect(result.tag).toBe("output");
+
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    expect(text).toContain("global");
+    expect(text).toContain("apps");
+    expect(text).toContain("apps/lxd");
+  });
+
+  it("renders flat tier list without parent references", async () => {
+    const ctx = makeCtx();
+    const cmd = listCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    expect(text).not.toContain("(parent:");
+  });
+
+  it("renders LLM format with --llm", async () => {
+    const ctx = makeCtx({ llm: true });
+    const cmd = listCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    expect(text).toContain("## Tiers");
+    expect(text).toContain("**global**");
+  });
+});

package/src/domains/tier/commands/list.ts

@@ -0,0 +1,43 @@
+/**
+ * Wires the `pragma tier list` CLI command.
+ *
+ * Lists all tiers defined in the design system ontology. Throws a
+ * structured recovery error when no tiers are found.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { listFormatters } from "../formatters/index.js";
+import { listTiers } from "../operations/index.js";
+
+export default function listCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["tier", "list"],
+    description: "List all tiers in the design system ontology",
+    parameters: [],
+    meta: {
+      examples: ["pragma tier list", "pragma tier list --llm"],
+    },
+    async execute() {
+      const tiers = await listTiers(ctx.store);
+
+      if (tiers.length === 0) {
+        throw PragmaError.emptyResults("tier", {
+          recovery: {
+            message:
+              "Ensure design system packages are installed: bun add -D @canonical/ds-global",
+          },
+        });
+      }
+
+      return createOutputResult(tiers, {
+        plain: selectFormatter(ctx, listFormatters),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,3 @@
+/** @module Re-exports tier formatters (`listFormatters`). */
+
+export { default as listFormatters } from "./list.js";

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

@@ -0,0 +1,33 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { TierEntry } from "../../shared/types.js";
+import formatters from "./list.js";
+
+const TIERS: TierEntry[] = [
+  { uri: "http://example.com/t1" as URI, path: "apps", depth: 0 },
+  { uri: "http://example.com/t2" as URI, path: "apps/lxd", depth: 0 },
+  { uri: "http://example.com/t3" as URI, path: "global", depth: 0 },
+];
+
+describe("tier list formatters", () => {
+  it("plain renders flat tier names", () => {
+    const text = formatters.plain(TIERS);
+    expect(text).toContain("global");
+    expect(text).toContain("apps");
+    expect(text).toContain("apps/lxd");
+  });
+
+  it("plain renders one tier per line", () => {
+    const text = formatters.plain(TIERS);
+    const lines = text.split("\n").filter(Boolean);
+    expect(lines).toHaveLength(3);
+  });
+
+  it("llm renders markdown heading and bold paths", () => {
+    const text = formatters.llm(TIERS);
+    expect(text).toContain("## Tiers");
+    expect(text).toContain("- **global**");
+    expect(text).toContain("- **apps**");
+    expect(text).toContain("- **apps/lxd**");
+  });
+});

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

@@ -0,0 +1,40 @@
+/**
+ * Three-mode formatter for `pragma tier list` output.
+ *
+ * - **plain** — indented terminal text showing tier hierarchy with
+ *   optional parent annotations.
+ * - **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 { TierEntry } from "../../shared/types.js";
+
+const formatters: Formatters<TierEntry[]> = {
+  plain: (tiers) => {
+    const lines: string[] = [];
+    for (const t of tiers) {
+      const indent = "  ".repeat(t.depth);
+      const parent = t.parent ? ` (parent: ${t.parent})` : "";
+      lines.push(`${indent}${t.path}${parent}`);
+    }
+    return lines.join("\n");
+  },
+
+  llm: (tiers) => {
+    const lines: string[] = [];
+    lines.push("## Tiers");
+    lines.push("");
+    for (const t of tiers) {
+      const indent = "  ".repeat(t.depth);
+      const parent = t.parent ? ` (parent: ${t.parent})` : "";
+      lines.push(`${indent}- **${t.path}**${parent}`);
+    }
+    return lines.join("\n");
+  },
+
+  json: (tiers) => JSON.stringify(tiers, null, 2),
+};
+
+export default formatters;

package/src/domains/tier/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @module Tier domain — CLI commands and operations.
+ *
+ * Commands: `pragma tier list`.
+ * Operations: {@link listTiers}.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import { listCommand } from "./commands/index.js";
+
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [listCommand(ctx)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export { listTiers } from "./operations/index.js";

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

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

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

@@ -0,0 +1,38 @@
+/**
+ * MCP tool specs for the tier domain.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { listFormatters as tierListFmt } from "../formatters/index.js";
+import { listTiers } from "../operations/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "tier_list",
+    description: "List all tiers in the design system ontology with hierarchy.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { condensed }) {
+      const result = await listTiers(rt.store);
+
+      if (condensed) {
+        const text = tierListFmt.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/tier/operations/index.ts

@@ -0,0 +1,3 @@
+/** @module Re-exports tier operations (`listTiers`). */
+
+export { default as listTiers } from "./list.js";

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

@@ -0,0 +1,32 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import listTiers 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("listTiers", () => {
+  it("returns all tiers from the ontology", async () => {
+    const result = await listTiers(store);
+    const paths = result.map((t) => t.path);
+    expect(paths).toContain("global");
+    expect(paths).toContain("apps");
+    expect(paths).toContain("apps/lxd");
+  });
+
+  it("returns sorted by name", async () => {
+    const result = await listTiers(store);
+    const paths = result.map((t) => t.path);
+    const sorted = [...paths].sort();
+    expect(paths).toEqual(sorted);
+  });
+});

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

@@ -0,0 +1,33 @@
+/**
+ * Lists all tiers defined in the design system ontology, ordered by name.
+ *
+ * @param store - ke store to query
+ * @returns array of tier entries, empty when none exist
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { TierEntry } from "../../shared/types.js";
+
+export default async function listTiers(store: Store): Promise<TierEntry[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?tier ?name
+      WHERE {
+        ?tier a ${P.ds}Tier ;
+              ${P.ds}name ?name .
+      }
+      ORDER BY ?name
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  return result.bindings.map((b) => ({
+    uri: (b.tier ?? "") as URI,
+    path: b.name ?? "",
+    depth: 0,
+  }));
+}