@canonical/pragma-cli 0.18.0

package/src/constants.ts

@@ -0,0 +1,78 @@
+/**
+ * Package-level constants for the pragma CLI.
+ *
+ * Groups program metadata (name, version, description), release channel
+ * definitions, and the cross-ontology property resolution map shared
+ * by MCP resources and domain operations.
+ */
+
+import pkg from "../package.json" with { type: "json" };
+import { PREFIX_MAP } from "./domains/shared/prefixes.js";
+
+/** CLI program name used in help text and error messages. */
+const PROGRAM_NAME = "pragma";
+
+/** One-line program description for help text. */
+const PROGRAM_DESCRIPTION = "CLI and MCP server for Canonical's design system.";
+
+/** Semver version string read from package.json. */
+const VERSION = pkg.version;
+
+/** Allowed release channel values for the `channel` config field. */
+const VALID_CHANNELS = ["normal", "experimental", "prerelease"] as const;
+
+/** A release channel name. */
+type Channel = (typeof VALID_CHANNELS)[number];
+
+/**
+ * Per-namespace property URIs for semantically equivalent fields.
+ * Each ontology uses different property names for the same concept
+ * (name/label, description/summary/comment).
+ */
+interface OntologyPropertyMap {
+  readonly label: string;
+  readonly description?: string;
+  readonly definition?: string;
+}
+
+/**
+ * Maps namespace prefix → property URIs for human-readable label and
+ * description. Used by MCP resource handlers and domain operations to
+ * resolve cross-ontology properties uniformly.
+ */
+const PROPERTY_MAP: Record<string, OntologyPropertyMap> = {
+  ds: {
+    label: `${PREFIX_MAP.ds}name`,
+    description: `${PREFIX_MAP.ds}summary`,
+    definition: `${PREFIX_MAP.ds}definition`,
+  },
+  cs: {
+    label: `${PREFIX_MAP.cs}name`,
+    description: `${PREFIX_MAP.cs}description`,
+    definition: `${PREFIX_MAP.cs}definition`,
+  },
+  rdfs: {
+    label: `${PREFIX_MAP.rdfs}label`,
+    description: `${PREFIX_MAP.rdfs}comment`,
+  },
+  owl: {
+    label: `${PREFIX_MAP.rdfs}label`,
+    description: `${PREFIX_MAP.rdfs}comment`,
+  },
+  skos: {
+    label: `${PREFIX_MAP.skos}prefLabel`,
+    definition: `${PREFIX_MAP.skos}definition`,
+  },
+  anatomy: {
+    label: `${PREFIX_MAP.ds}name`,
+  },
+};
+
+export {
+  PROGRAM_DESCRIPTION,
+  PROGRAM_NAME,
+  PROPERTY_MAP,
+  VALID_CHANNELS,
+  VERSION,
+};
+export type { Channel, OntologyPropertyMap };

package/src/domains/block/blockConfig.ts

@@ -0,0 +1,53 @@
+import type { EntityDisplayConfig } from "../shared/contracts.js";
+import { P } from "../shared/prefixes.js";
+import type {
+  BlockDetailed,
+  BlockDigest,
+  BlockSummary,
+  FilterConfig,
+} from "../shared/types.js";
+
+export const blockConfig: EntityDisplayConfig<
+  BlockSummary,
+  BlockDigest,
+  BlockDetailed
+> = {
+  domain: "block",
+  entityName: "block",
+  rdfTypes: [
+    `${P.ds}Component`,
+    `${P.ds}Pattern`,
+    `${P.ds}Layout`,
+    `${P.ds}Subcomponent`,
+  ],
+  listColumns: [
+    { key: "uri", label: "IRI" },
+    { key: "name", label: "Name" },
+    { key: "type", label: "Type" },
+    { key: "tier", label: "Tier" },
+  ],
+  digestColumns: [{ key: "summary", label: "Summary", showWhenEmpty: false }],
+  lookupSections: [
+    { key: "summary", heading: "Summary", kind: "field" },
+    { key: "whenToUse", heading: "When to use", kind: "field" },
+    { key: "whenNotToUse", heading: "When not to use", kind: "field" },
+    { key: "guidelines", heading: "Guidelines", kind: "field" },
+    { key: "anatomyDsl", heading: "Anatomy (DSL)", kind: "code" },
+    { key: "anatomyClassic", heading: "Anatomy (classic)", kind: "field" },
+    { key: "modifierFamilies", heading: "Modifier Families", kind: "table" },
+    { key: "properties", heading: "Properties", kind: "nested-table" },
+    { key: "subcomponents", heading: "Subcomponents", kind: "list" },
+    { key: "implementationPaths", heading: "Implementations", kind: "list" },
+    { key: "tokens", heading: "Tokens", kind: "list" },
+  ],
+  emptyRecovery: (_filters: FilterConfig) => ({
+    message: "List visible blocks.",
+    cli: "pragma block list",
+    mcp: { tool: "block_list" },
+  }),
+  notFoundRecovery: (_query: string) => ({
+    message: "List visible blocks.",
+    cli: "pragma block list",
+    mcp: { tool: "block_list" },
+  }),
+};

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

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

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

@@ -0,0 +1,111 @@
+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 type { BlockSummary } from "../../shared/types.js";
+import buildListCommand 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> = {}): 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("buildListCommand", () => {
+  it("returns output result with block data", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { value } = await executeOutput(cmd, {}, ctx);
+    const names = (value as BlockSummary[]).map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).toContain("Card");
+  });
+
+  it("renders plain text output", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("Button");
+    expect(text).toContain("Card");
+  });
+
+  it("renders LLM markdown", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("## Blocks");
+    expect(text).toContain("**Button**");
+  });
+
+  it("renders JSON output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    const parsed = JSON.parse(text);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.some((c: BlockSummary) => c.name === "Button")).toBe(true);
+  });
+
+  it("respects tier filter from config", async () => {
+    const ctx = makeCtx({
+      config: { tier: "global", channel: "normal" },
+    });
+    const cmd = buildListCommand(ctx);
+    const { value } = await executeOutput(cmd, {}, ctx);
+    const names = (value as BlockSummary[]).map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).not.toContain("LXD Panel");
+  });
+
+  it("--all-tiers ignores tier filter", async () => {
+    const ctx = makeCtx({
+      config: { tier: "global", channel: "prerelease" },
+    });
+    const cmd = buildListCommand(ctx);
+    const { value } = await executeOutput(cmd, { allTiers: true }, ctx);
+    const names = (value as BlockSummary[]).map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).toContain("LXD Panel");
+  });
+
+  it("returns results with combined tier + channel", async () => {
+    const ctx = makeCtx({
+      config: { tier: "apps/lxd", channel: "normal" },
+    });
+    const cmd = buildListCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+    expect(result.tag).toBe("output");
+  });
+});

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

@@ -0,0 +1,69 @@
+/**
+ * Wires the `pragma block list` CLI command.
+ *
+ * Lists all blocks visible under the current tier and channel filters.
+ * Supports progressive disclosure via `--digest` and `--detailed` flags,
+ * and an `--all-tiers` flag to widen the search.
+ */
+
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { listFormatters } from "../formatters/index.js";
+import { resolveBlockList } from "../orchestration/index.js";
+
+export default function buildListCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["block", "list"],
+    description: "List blocks in the design system",
+    parameters: [
+      {
+        name: "allTiers",
+        description: "Show blocks from all tiers",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "digest",
+        description: "Show enriched summary with implementations",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "detailed",
+        description: "Show full details for each block",
+        type: "boolean",
+        default: false,
+      },
+    ],
+    meta: {
+      examples: [
+        "pragma block list",
+        "pragma block list --all-tiers",
+        "pragma block list --digest",
+        "pragma block list --detailed",
+        "pragma block list --llm",
+        "pragma block list --format json",
+      ],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const contract = await resolveBlockList(ctx, {
+        allTiers: params.allTiers === true,
+        digest: params.digest === true,
+        detailed: params.detailed === true,
+      });
+
+      return createOutputResult(contract.result.items, {
+        plain: selectFormatter(ctx, listFormatters),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,187 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+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 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: ["Button"] }, ctx);
+    expect(text).toContain("Button");
+    expect(text).toContain("global");
+  });
+
+  it("returns detailed view with --detailed", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(
+      cmd,
+      { names: ["Button"], detailed: true },
+      ctx,
+    );
+    expect(text).toContain("Button");
+    expect(text).toContain("Modifiers");
+    expect(text).toContain("importance");
+  });
+
+  it("shows only selected aspects (--modifiers)", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(
+      cmd,
+      { names: ["Button"], modifiers: true },
+      ctx,
+    );
+    expect(text).toContain("Modifiers");
+    expect(text).toContain("importance");
+    // Summary field "Tokens: 1" is always shown, but token details should not appear
+    expect(text).not.toContain("color.primary");
+  });
+
+  it("composes aspect flags (--modifiers --tokens)", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(
+      cmd,
+      { names: ["Button"], modifiers: true, tokens: true },
+      ctx,
+    );
+    expect(text).toContain("Modifiers");
+    expect(text).toContain("Tokens");
+  });
+
+  it("renders LLM markdown", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(cmd, { names: ["Button"] }, ctx);
+    expect(text).toContain("## Button");
+    expect(text).toContain("Tier: global");
+  });
+
+  it("renders JSON", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(cmd, { names: ["Button"] }, ctx);
+    const parsed = JSON.parse(text);
+    expect(parsed.name).toBe("Button");
+    expect(parsed.tier).toBe("global");
+  });
+
+  it("renders JSON with detailed aspects", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(
+      cmd,
+      { names: ["Button"], detailed: true },
+      ctx,
+    );
+    const parsed = JSON.parse(text);
+    expect(parsed.modifierValues).toBeDefined();
+    expect(parsed.tokens).toBeDefined();
+  });
+
+  it("populates nodeCount from anatomy nodes", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(cmd, { names: ["Button"] }, ctx);
+    const parsed = JSON.parse(text);
+    expect(parsed.nodeCount).toBe(3);
+  });
+
+  it("renders multiple lookup results together", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    const { text } = await executeOutput(
+      cmd,
+      { names: ["Button", "Card"] },
+      ctx,
+    );
+    expect(text).toContain("Button");
+    expect(text).toContain("Card");
+  });
+
+  it("throws ENTITY_NOT_FOUND for unknown block", 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");
+    }
+
+    const text = result.render.plain(result.value);
+    expect(text).toContain("Errors:");
+    expect(text).toContain("NonExistent");
+  });
+
+  it("throws INVALID_INPUT for empty name", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    await expect(cmd.execute({ names: [] }, ctx)).rejects.toThrow(PragmaError);
+
+    try {
+      await cmd.execute({ names: [] }, ctx);
+    } catch (e) {
+      expect(e).toBeInstanceOf(PragmaError);
+      expect((e as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+
+  it("provides tab completion candidates", async () => {
+    const ctx = makeCtx();
+    const cmd = buildLookupCommand(ctx);
+    const nameParam = cmd.parameters.find((p) => p.name === "names");
+    expect(nameParam?.complete).toBeDefined();
+
+    if (nameParam?.complete) {
+      const candidates = await nameParam.complete("Bu", ctx);
+      expect(candidates).toContain("Button");
+    }
+  });
+});

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

@@ -0,0 +1,199 @@
+/**
+ * Wires the `pragma block lookup <name-or-uri...>` CLI command.
+ *
+ * Accepts a positional block name or IRI and optional aspect flags (anatomy,
+ * modifiers, tokens, implementations). Delegates to {@link lookupBlock} for
+ * data retrieval and {@link lookupFormatters} for output rendering.
+ */
+
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../../shared/context.js";
+import type { LookupResult } from "../../shared/contracts.js";
+import { lookupFormatters } from "../formatters/index.js";
+import { resolveAspects } from "../helpers/index.js";
+import { listBlocks, type lookupBlock } from "../operations/index.js";
+import {
+  buildBlockFilters,
+  resolveBlockLookup,
+} from "../orchestration/index.js";
+import type { AspectFlags } from "../types.js";
+
+interface BlockLookupOutput {
+  readonly result: LookupResult<Awaited<ReturnType<typeof lookupBlock>>>;
+  readonly detailed: boolean;
+  readonly aspects: AspectFlags;
+}
+
+export default function buildLookupCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["block", "lookup"],
+    description: "Look up block details",
+    parameters: [
+      {
+        name: "names",
+        description: "Block names or IRIs",
+        type: "multiselect",
+        positional: true,
+        required: true,
+        complete: async (partial: string) => {
+          const all = await listBlocks(ctx.store, ctx.config);
+          return all
+            .map((c) => c.name)
+            .filter((n) => n.toLowerCase().startsWith(partial.toLowerCase()));
+        },
+      },
+      {
+        name: "detailed",
+        description:
+          "Show full details including anatomy, modifiers, tokens, and implementations",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "anatomy",
+        description: "Show anatomy tree",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "modifiers",
+        description: "Show modifier values",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "tokens",
+        description: "Show token references",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "implementations",
+        description: "Show implementation paths",
+        type: "boolean",
+        default: false,
+      },
+    ],
+    parameterGroups: {
+      "Aspect filters": ["anatomy", "modifiers", "tokens", "implementations"],
+    },
+    meta: {
+      examples: [
+        "pragma block lookup Button",
+        "pragma block lookup Button Card",
+        "pragma block lookup Button --detailed",
+        "pragma block lookup Button --anatomy --modifiers",
+        "pragma block lookup Button --detailed --llm",
+        "pragma block lookup ds:global.component.button",
+      ],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const names = normalizeNames(params.names, params.name);
+      if (names.length === 0) {
+        throw PragmaError.invalidInput("names", "(empty)", {
+          recovery: {
+            message: "List available blocks.",
+            cli: "pragma block list",
+            mcp: { tool: "block_list" },
+          },
+        });
+      }
+
+      const detailed = params.detailed === true;
+      const aspectInput: Partial<AspectFlags> = {
+        anatomy: params.anatomy === true,
+        modifiers: params.modifiers === true,
+        tokens: params.tokens === true,
+        implementations: params.implementations === true,
+      };
+
+      const isAspectSelected =
+        aspectInput.anatomy ||
+        aspectInput.modifiers ||
+        aspectInput.tokens ||
+        aspectInput.implementations;
+      const showDetailed = detailed || (isAspectSelected ?? false);
+      const aspects = resolveAspects(aspectInput);
+
+      const contract = await resolveBlockLookup(
+        ctx.store,
+        names,
+        buildBlockFilters(ctx),
+      );
+
+      return createOutputResult<BlockLookupOutput>(
+        { result: contract.result, detailed: showDetailed, aspects },
+        { plain: renderBlockLookupOutput(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 renderBlockLookupOutput(
+  ctx: PragmaContext,
+): (data: BlockLookupOutput) => string {
+  return ({ result, detailed, aspects }) => {
+    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({ block: only, detailed, aspects })
+          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
+      }
+
+      return JSON.stringify(
+        {
+          results: result.results.map((block) =>
+            JSON.parse(lookupFormatters.json({ block, detailed, aspects })),
+          ),
+          errors: result.errors,
+        },
+        null,
+        2,
+      );
+    }
+
+    const parts = result.results.map((block) =>
+      formatOne({ block, detailed, aspects }),
+    );
+
+    if (result.errors.length > 0) {
+      parts.push(
+        [
+          "Errors:",
+          ...result.errors.map((error) => `- ${error.query}: ${error.message}`),
+        ].join("\n"),
+      );
+    }
+
+    return parts.join("\n\n");
+  };
+}