@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,354 @@
+/**
+ * Three-mode formatter for `pragma block lookup` output.
+ *
+ * - **plain** — styled terminal output with chalk; shows summary or
+ *   detailed view depending on the `detailed` / aspect flags.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON for programmatic consumption.
+ *
+ * Supports aspect filtering (anatomy, modifiers, tokens, implementations)
+ * via the `aspects` field on {@link BlockLookupInput}.
+ */
+
+import chalk from "chalk";
+import {
+  formatField,
+  formatHeading,
+  formatList,
+  formatSection,
+} from "#pipeline";
+import type { Formatters } from "../../shared/formatters.js";
+import type { AnatomyNode, BlockDetailed } from "../../shared/types.js";
+import type { AspectFlags } from "../types.js";
+import type { BlockLookupInput } from "./types.js";
+
+const formatters: Formatters<BlockLookupInput> = {
+  plain({ block: component, detailed, aspects }) {
+    if (!detailed) return formatSummary(component);
+    return formatDetailed(component, aspects);
+  },
+
+  llm({ block: component, detailed, aspects }) {
+    const lines: string[] = [];
+
+    lines.push(`## ${component.name}`);
+    lines.push("");
+    lines.push(`- URI: ${component.uri}`);
+    lines.push(`- Tier: ${component.tier}`);
+
+    if (component.summary) {
+      lines.push(`- Summary: ${component.summary}`);
+    }
+
+    if (component.modifiers.length > 0) {
+      lines.push(`- Modifiers: ${component.modifiers.join(", ")}`);
+    }
+
+    const impl = component.implementations
+      .filter((i) => i.available)
+      .map((i) => i.framework);
+    if (impl.length > 0) {
+      lines.push(`- Implementations: ${impl.join(", ")}`);
+    }
+
+    lines.push(`- Anatomy nodes: ${component.nodeCount}`);
+    lines.push(`- Tokens: ${component.tokenCount}`);
+
+    if (!detailed) return lines.join("\n");
+
+    if (component.whenToUse) {
+      lines.push("");
+      lines.push("### When to use");
+      lines.push(component.whenToUse);
+    }
+
+    if (component.whenNotToUse) {
+      lines.push("");
+      lines.push("### When not to use");
+      lines.push(component.whenNotToUse);
+    }
+
+    if (component.guidelines) {
+      lines.push("");
+      lines.push("### Guidelines");
+      lines.push(component.guidelines);
+    }
+
+    if (aspects.modifiers && component.modifierValues.length > 0) {
+      lines.push("");
+      lines.push("### Modifiers");
+      for (const m of component.modifierValues) {
+        lines.push(`- **${m.family}**: ${m.values.join(", ")}`);
+      }
+    }
+
+    if (component.properties.length > 0) {
+      lines.push("");
+      lines.push("### Properties");
+      for (const property of component.properties) {
+        const bits = [property.propertyType || "unknown"];
+        bits.push(property.optional ? "optional" : "required");
+        if (property.defaultValue) {
+          bits.push(`default=${property.defaultValue}`);
+        }
+        if (property.constraints) {
+          bits.push(property.constraints);
+        }
+        lines.push(`- **${property.name}**: ${bits.join("; ")}`);
+      }
+    }
+
+    if (component.subcomponents.length > 0) {
+      lines.push("");
+      lines.push("### Subcomponents");
+      for (const subcomponent of component.subcomponents) {
+        lines.push(`- ${subcomponent.name} (${subcomponent.uri})`);
+      }
+    }
+
+    if (aspects.implementations && component.implementationPaths.length > 0) {
+      lines.push("");
+      lines.push("### Implementations");
+      for (const i of component.implementationPaths) {
+        lines.push(`- ${i.framework}: \`${i.path}\``);
+      }
+    }
+
+    if (aspects.tokens && component.tokens.length > 0) {
+      lines.push("");
+      lines.push("### Tokens");
+      for (const t of component.tokens) {
+        lines.push(`- ${t.name}`);
+      }
+    }
+
+    if (aspects.anatomy && component.anatomy) {
+      lines.push("");
+      lines.push("### Anatomy");
+      lines.push(formatAnatomyTreeLlm(component.anatomy.root, 0));
+    } else if (aspects.anatomy && component.anatomyDsl) {
+      lines.push("");
+      lines.push("### Anatomy DSL");
+      lines.push(component.anatomyDsl);
+    }
+
+    return lines.join("\n");
+  },
+
+  json({ block: component, detailed, aspects }) {
+    if (!detailed) {
+      return JSON.stringify(
+        {
+          uri: component.uri,
+          name: component.name,
+          summary: component.summary,
+          tier: component.tier,
+          modifiers: component.modifiers,
+          implementations: component.implementations,
+          nodeCount: component.nodeCount,
+          tokenCount: component.tokenCount,
+        },
+        null,
+        2,
+      );
+    }
+
+    const result: Record<string, unknown> = { ...component };
+
+    if (!aspects.modifiers) {
+      delete result.modifierValues;
+      delete result.modifierFamilies;
+    }
+    if (!aspects.implementations) {
+      delete result.implementationPaths;
+    }
+    if (!aspects.tokens) {
+      delete result.tokens;
+    }
+    if (!aspects.anatomy) {
+      delete result.anatomy;
+      delete result.anatomyDsl;
+      delete result.anatomyClassic;
+    }
+
+    return JSON.stringify(result, null, 2);
+  },
+};
+
+export default formatters;
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function formatSummary(component: BlockDetailed): string {
+  const lines: string[] = [];
+
+  lines.push(formatHeading(component.name));
+  lines.push("");
+  lines.push(formatField("URI:", component.uri));
+  lines.push(formatField("Tier:", component.tier));
+
+  if (component.summary) {
+    lines.push(formatField("Summary:", component.summary));
+  }
+
+  if (component.modifiers.length > 0) {
+    lines.push(formatField("Modifiers:", component.modifiers.join(", ")));
+  }
+
+  const impl = component.implementations
+    .filter((i) => i.available)
+    .map((i) => i.framework);
+  if (impl.length > 0) {
+    lines.push(formatField("Implementations:", impl.join(", ")));
+  }
+
+  lines.push(formatField("Anatomy nodes:", String(component.nodeCount)));
+  lines.push(formatField("Tokens:", String(component.tokenCount)));
+
+  return lines.join("\n");
+}
+
+function formatDetailed(
+  component: BlockDetailed,
+  aspects: AspectFlags,
+): string {
+  const lines: string[] = [];
+
+  lines.push(formatHeading(component.name));
+  lines.push("");
+  lines.push(formatField("URI:", component.uri));
+  lines.push(formatField("Tier:", component.tier));
+  if (component.summary) {
+    lines.push(formatField("Summary:", component.summary));
+  }
+  lines.push(formatField("Anatomy nodes:", String(component.nodeCount)));
+  lines.push(formatField("Tokens:", String(component.tokenCount)));
+
+  if (component.whenToUse) {
+    lines.push("");
+    lines.push(formatSection("When to use", component.whenToUse));
+  }
+
+  if (component.whenNotToUse) {
+    lines.push("");
+    lines.push(formatSection("When not to use", component.whenNotToUse));
+  }
+
+  if (component.guidelines) {
+    lines.push("");
+    lines.push(formatSection("Guidelines", component.guidelines));
+  }
+
+  if (aspects.modifiers && component.modifierValues.length > 0) {
+    lines.push("");
+    lines.push(
+      formatSection(
+        "Modifiers",
+        component.modifierValues
+          .map((m) => `  ${chalk.bold(m.family)}: ${m.values.join(", ")}`)
+          .join("\n"),
+      ),
+    );
+  }
+
+  if (aspects.implementations && component.implementationPaths.length > 0) {
+    lines.push("");
+    lines.push(
+      formatSection(
+        "Implementations",
+        formatList(
+          component.implementationPaths.map(
+            (i) => `${chalk.bold(i.framework)}: ${i.path}`,
+          ),
+        ),
+      ),
+    );
+  }
+
+  if (aspects.tokens && component.tokens.length > 0) {
+    lines.push("");
+    lines.push(
+      formatSection("Tokens", formatList(component.tokens.map((t) => t.name))),
+    );
+  }
+
+  if (component.properties.length > 0) {
+    lines.push("");
+    lines.push(
+      formatSection(
+        "Properties",
+        formatList(
+          component.properties.map((property) => {
+            const parts = [
+              chalk.bold(property.name),
+              property.propertyType || "unknown",
+              property.optional ? "optional" : "required",
+            ];
+            if (property.defaultValue) {
+              parts.push(`default=${property.defaultValue}`);
+            }
+            if (property.constraints) {
+              parts.push(property.constraints);
+            }
+            return parts.join(" — ");
+          }),
+        ),
+      ),
+    );
+  }
+
+  if (component.subcomponents.length > 0) {
+    lines.push("");
+    lines.push(
+      formatSection(
+        "Subcomponents",
+        formatList(
+          component.subcomponents.map(
+            (subcomponent) => `${subcomponent.name}: ${subcomponent.uri}`,
+          ),
+        ),
+      ),
+    );
+  }
+
+  if (aspects.anatomy && component.anatomy) {
+    lines.push("");
+    lines.push(
+      formatSection("Anatomy", formatAnatomyTree(component.anatomy.root, 0)),
+    );
+  } else if (aspects.anatomy && component.anatomyDsl) {
+    lines.push("");
+    lines.push(formatSection("Anatomy (DSL)", component.anatomyDsl));
+  }
+
+  return lines.join("\n");
+}
+
+function formatAnatomyTree(node: AnatomyNode, depth: number): string {
+  const indent = "  ".repeat(depth);
+  const typeTag = node.type === "anonymous" ? chalk.dim(" (anon)") : "";
+  const slotTag = node.slot ? chalk.dim(` slot=${node.slot}`) : "";
+  let result = `${indent}${node.name}${typeTag}${slotTag}`;
+
+  for (const child of node.children) {
+    result += `\n${formatAnatomyTree(child, depth + 1)}`;
+  }
+
+  return result;
+}
+
+function formatAnatomyTreeLlm(node: AnatomyNode, depth: number): string {
+  const indent = "  ".repeat(depth);
+  const typeTag = node.type === "anonymous" ? " (anonymous)" : "";
+  const slotTag = node.slot ? ` [slot: ${node.slot}]` : "";
+  let result = `${indent}- ${node.name}${typeTag}${slotTag}`;
+
+  for (const child of node.children) {
+    result += `\n${formatAnatomyTreeLlm(child, depth + 1)}`;
+  }
+
+  return result;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Formatter input types for block commands.
+ *
+ * Composite types that bundle the data with display options,
+ * so formatters conform to the `Formatters<T>` contract.
+ */
+
+import type { BlockDetailed } from "../../shared/types.js";
+import type { AspectFlags } from "../types.js";
+
+/** Input payload for the block-lookup formatter, pairing data with display flags. */
+export interface BlockLookupInput {
+  readonly block: BlockDetailed;
+  readonly detailed: boolean;
+  readonly aspects: AspectFlags;
+}

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

@@ -0,0 +1,4 @@
+/** @module Re-exports block helpers (`extractLocalName`, `resolveAspects`). */
+
+export { default as extractLocalName } from "../../shared/extractLocalName.js";
+export { default as resolveAspects } from "./resolveAspects.js";

package/src/domains/block/helpers/resolveAspects.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import resolveAspects from "./resolveAspects.js";
+
+describe("resolveAspects", () => {
+  it("returns all aspects when none are set", () => {
+    const result = resolveAspects({});
+    expect(result).toEqual({
+      anatomy: true,
+      modifiers: true,
+      tokens: true,
+      implementations: true,
+    });
+  });
+
+  it("returns all aspects when all are explicitly false", () => {
+    const result = resolveAspects({
+      anatomy: false,
+      modifiers: false,
+      tokens: false,
+      implementations: false,
+    });
+    expect(result).toEqual({
+      anatomy: true,
+      modifiers: true,
+      tokens: true,
+      implementations: true,
+    });
+  });
+
+  it("returns only selected aspects when one is set", () => {
+    const result = resolveAspects({ modifiers: true });
+    expect(result).toEqual({
+      anatomy: false,
+      modifiers: true,
+      tokens: false,
+      implementations: false,
+    });
+  });
+
+  it("returns multiple selected aspects", () => {
+    const result = resolveAspects({ modifiers: true, tokens: true });
+    expect(result).toEqual({
+      anatomy: false,
+      modifiers: true,
+      tokens: true,
+      implementations: false,
+    });
+  });
+
+  it("returns all selected when all are true", () => {
+    const result = resolveAspects({
+      anatomy: true,
+      modifiers: true,
+      tokens: true,
+      implementations: true,
+    });
+    expect(result).toEqual({
+      anatomy: true,
+      modifiers: true,
+      tokens: true,
+      implementations: true,
+    });
+  });
+});

package/src/domains/block/helpers/resolveAspects.ts

@@ -0,0 +1,35 @@
+/**
+ * Resolves partial aspect flags into a complete {@link AspectFlags} object.
+ *
+ * When no individual aspect is selected, all aspects default to `true` so
+ * the full detail view is shown. When at least one aspect is explicitly
+ * selected, only the selected aspects are enabled.
+ *
+ * @param flags - partial aspect selection from CLI flags
+ * @returns fully resolved aspect flags
+ */
+
+import type { AspectFlags } from "../types.js";
+
+const ALL_ASPECTS: AspectFlags = {
+  anatomy: true,
+  modifiers: true,
+  tokens: true,
+  implementations: true,
+};
+
+export default function resolveAspects(
+  flags: Partial<AspectFlags>,
+): AspectFlags {
+  const anySet =
+    flags.anatomy || flags.modifiers || flags.tokens || flags.implementations;
+
+  if (!anySet) return ALL_ASPECTS;
+
+  return {
+    anatomy: flags.anatomy ?? false,
+    modifiers: flags.modifiers ?? false,
+    tokens: flags.tokens ?? false,
+    implementations: flags.implementations ?? false,
+  };
+}

package/src/domains/block/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @module Block domain — CLI commands and operations.
+ *
+ * Commands: `pragma block list`, `pragma block lookup <name>`.
+ * Operations: {@link lookupBlock}, {@link listBlocks}.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import { listCommand, lookupCommand } from "./commands/index.js";
+
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [listCommand(ctx), lookupCommand(ctx)];
+}
+
+export { blockConfig } from "./blockConfig.js";
+export { specs as mcpSpecs } from "./mcp/index.js";
+export { listBlocks, lookupBlock } from "./operations/index.js";
+export {
+  blockEmptyError,
+  buildBlockFilters,
+  enrichBlocks,
+  resolveBlockList,
+  resolveBlockLookup,
+} from "./orchestration/index.js";

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

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

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

@@ -0,0 +1,199 @@
+/**
+ * MCP tool specs for the block domain — block_list, block_lookup.
+ *
+ * Declarative definitions — no MCP imports. The adapter layer
+ * converts these into registered MCP tools via `registerFromSpec()`.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import {
+  listFormatters as blockListFmt,
+  lookupFormatters as blockLookupFmt,
+} from "../formatters/index.js";
+import {
+  buildBlockFilters,
+  resolveBlockList,
+  resolveBlockLookup,
+} from "../orchestration/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "block_list",
+    description:
+      "List design system blocks visible under current tier and channel configuration.",
+    params: {
+      allTiers: {
+        type: "boolean",
+        description: "Show blocks from all tiers, ignoring tier filter",
+        optional: true,
+      },
+      digest: {
+        type: "boolean",
+        description: "Include implementations per block",
+        optional: true,
+      },
+      detailed: {
+        type: "boolean",
+        description: "Include full details per block",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { allTiers, digest, detailed, condensed }) {
+      const contract = await resolveBlockList(rt, {
+        allTiers: allTiers === true,
+        digest: digest === true,
+        detailed: detailed === true,
+      });
+
+      if (condensed) {
+        const text = blockListFmt.llm(contract.result.items);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      if (contract.result.disclosure.level === "detailed") {
+        return {
+          data: contract.result.items,
+          meta: {
+            count: contract.result.items.length,
+            disclosure: "detailed",
+            filters: contract.result.filters,
+          },
+        };
+      }
+
+      if (contract.result.disclosure.level === "digest") {
+        return {
+          data: contract.result.items,
+          meta: {
+            count: contract.result.items.length,
+            disclosure: "digest",
+            filters: contract.result.filters,
+          },
+        };
+      }
+
+      return {
+        data: contract.result.items,
+        meta: {
+          count: contract.result.items.length,
+          filters: contract.result.filters,
+        },
+      };
+    },
+  },
+
+  {
+    name: "block_lookup",
+    description:
+      "Get detailed information about one or more design system blocks including anatomy, modifiers, tokens, and applicable standards.",
+    params: {
+      names: {
+        type: "string[]",
+        description:
+          "Block names or IRIs to look up (e.g. ['Button', 'ds:global.component.card'])",
+        optional: false,
+      },
+      detailed: {
+        type: "boolean",
+        description: "Return full details (default: true for MCP)",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { names, detailed, condensed }) {
+      const queries = names as string[];
+      const showDetailed = (detailed as boolean | undefined) ?? true;
+      const contract = await resolveBlockLookup(
+        rt.store,
+        queries,
+        buildBlockFilters(rt),
+      );
+      const result = contract.result;
+
+      if (condensed) {
+        const textParts = result.results.map((block) =>
+          blockLookupFmt.llm({
+            block,
+            detailed: showDetailed,
+            aspects: {
+              anatomy: true,
+              modifiers: true,
+              tokens: true,
+              implementations: true,
+            },
+          }),
+        );
+
+        if (result.errors.length > 0) {
+          textParts.push(
+            [
+              "### Errors",
+              ...result.errors.map(
+                (error) => `- ${error.query}: ${error.message}`,
+              ),
+            ].join("\n"),
+          );
+        }
+
+        return {
+          condensed: true,
+          text: textParts.join("\n\n"),
+          tokens: `~${Math.ceil(textParts.join("\n\n").length / 4)}`,
+        };
+      }
+
+      if (!showDetailed) {
+        const summaries = result.results.map(
+          ({
+            uri,
+            name,
+            type,
+            tier,
+            modifiers,
+            implementations,
+            nodeCount,
+            tokenCount,
+            summary,
+          }) => ({
+            uri,
+            name,
+            type,
+            tier,
+            modifiers,
+            implementations,
+            nodeCount,
+            tokenCount,
+            summary,
+          }),
+        );
+
+        return {
+          data: {
+            results: summaries,
+            errors: result.errors,
+          },
+          meta: { count: summaries.length },
+        };
+      }
+
+      return { data: result, meta: { count: result.results.length } };
+    },
+  },
+] as const;
+
+export default specs;

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

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