@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,56 +0,0 @@
-/**
- * Wires the `pragma block sample` CLI command.
- *
- * Returns 1–5 complete block instances as exemplars so agents
- * can learn the data shape before writing queries.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import parseSampleCount from "../../shared/parseSampleCount.js";
-import type { BlockDetailed, SampleOutput } from "../../shared/types/index.js";
-import { sampleFormatters } from "../formatters/index.js";
-import { sampleBlocks } from "../operations/index.js";
-import { buildBlockFilters } from "../orchestration/index.js";
-
-const NEXT_STEPS = [
-  "Use block_lookup to inspect specific blocks by name.",
-  "Use block_list to see all available blocks with filtering.",
-];
-
-export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["block", "sample"],
-    description:
-      "Return randomly selected complete block instances as exemplars for shape discovery",
-    parameters: [
-      {
-        name: "count",
-        type: "string",
-        description: "Number of samples to return (1–5, default 2)",
-        required: false,
-      },
-    ],
-    meta: {
-      examples: ["pragma block sample", "pragma block sample --count 3"],
-    },
-    async execute(params) {
-      const count = parseSampleCount(params.count);
-      const filters = buildBlockFilters(ctx);
-      const result = await sampleBlocks(ctx.store, filters, count);
-
-      const output: SampleOutput<BlockDetailed> = {
-        ...result,
-        nextSteps: NEXT_STEPS,
-      };
-
-      return createOutputResult(output, {
-        plain: selectFormatter(ctx, sampleFormatters),
-      });
-    },
-  };
-}

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

@@ -1,5 +0,0 @@
-/** @module Re-exports block formatters (`listFormatters`, `lookupFormatters`, `sampleFormatters`). */
-
-export { default as listFormatters } from "./list.js";
-export { createLookupOptions, default as lookupFormatters } from "./lookup.js";
-export { default as sampleFormatters } from "./sample.js";

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

@@ -1,107 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
-import type { BlockSummary } from "../../shared/types/index.js";
-import formatters from "./list.js";
-
-const BUTTON: BlockSummary = {
-  uri: `${DEFAULT_PREFIX_MAP.ds}button` as URI,
-  name: "Button",
-  tier: "global",
-  modifiers: ["importance", "density"],
-  implementations: [
-    { framework: "react", available: true },
-    { framework: "svelte", available: false },
-  ],
-  nodeCount: 3,
-  tokenCount: 1,
-};
-
-const CARD: BlockSummary = {
-  uri: `${DEFAULT_PREFIX_MAP.ds}card` as URI,
-  name: "Card",
-  tier: "global",
-  modifiers: [],
-  implementations: [],
-  nodeCount: 0,
-  tokenCount: 0,
-};
-
-const components = [BUTTON, CARD];
-
-describe("formatters.plain", () => {
-  it("includes block names", () => {
-    const text = formatters.plain(components);
-    expect(text).toContain("Button");
-    expect(text).toContain("Card");
-  });
-
-  it("includes tier info", () => {
-    const text = formatters.plain(components);
-    expect(text).toContain("global");
-  });
-
-  it("includes modifiers for Button", () => {
-    const text = formatters.plain(components);
-    expect(text).toContain("importance");
-    expect(text).toContain("density");
-  });
-
-  it("includes available implementations", () => {
-    const text = formatters.plain(components);
-    expect(text).toContain("react");
-    // svelte is not available
-    expect(text).not.toContain("svelte");
-  });
-
-  it("returns empty string for empty list", () => {
-    expect(formatters.plain([])).toBe("");
-  });
-});
-
-describe("formatters.llm", () => {
-  it("starts with heading", () => {
-    const text = formatters.llm(components);
-    expect(text).toContain("## Blocks");
-  });
-
-  it("bolds block names", () => {
-    const text = formatters.llm(components);
-    expect(text).toContain("**Button**");
-    expect(text).toContain("**Card**");
-  });
-
-  it("includes tier and modifier info", () => {
-    const text = formatters.llm(components);
-    expect(text).toContain("tier: global");
-    expect(text).toContain("modifiers: importance, density");
-  });
-
-  it("includes node and token counts when non-zero", () => {
-    const text = formatters.llm(components);
-    expect(text).toContain("nodes: 3");
-    expect(text).toContain("tokens: 1");
-  });
-});
-
-describe("formatters.json", () => {
-  it("returns valid JSON array", () => {
-    const text = formatters.json(components);
-    const parsed = JSON.parse(text);
-    expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed).toHaveLength(2);
-  });
-
-  it("preserves block structure", () => {
-    const text = formatters.json(components);
-    const parsed = JSON.parse(text);
-    expect(parsed[0].name).toBe("Button");
-    expect(parsed[0].tier).toBe("global");
-    expect(parsed[0].modifiers).toEqual(["importance", "density"]);
-  });
-
-  it("returns empty array for empty list", () => {
-    const text = formatters.json([]);
-    expect(JSON.parse(text)).toEqual([]);
-  });
-});

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

@@ -1,50 +0,0 @@
-import type { Formatters } from "../../shared/formatters.js";
-import { renderListPlain } from "../../shared/renderers.js";
-import type { BlockSummary } from "../../shared/types/index.js";
-import { blockConfig } from "../blockConfig.js";
-
-/** Three-mode formatter for `pragma block list` output. */
-const formatters: Formatters<readonly BlockSummary[]> = {
-  plain: (blocks) =>
-    renderListPlain(blocks, {
-      heading: "Blocks",
-      columns: blockConfig.listColumns,
-    }),
-
-  llm(blocks) {
-    const lines = ["## Blocks", ""];
-
-    for (const block of blocks) {
-      const parts = [`**${block.name}**`, `tier: ${block.tier}`];
-
-      if (block.modifiers.length > 0) {
-        parts.push(`modifiers: ${block.modifiers.join(", ")}`);
-      }
-
-      const implementations = block.implementations
-        .filter((implementation) => implementation.available)
-        .map((implementation) => implementation.framework);
-      if (implementations.length > 0) {
-        parts.push(`implementations: ${implementations.join(", ")}`);
-      }
-
-      if (block.nodeCount > 0) {
-        parts.push(`nodes: ${block.nodeCount}`);
-      }
-
-      if (block.tokenCount > 0) {
-        parts.push(`tokens: ${block.tokenCount}`);
-      }
-
-      lines.push(`- ${parts.join(" | ")}`);
-    }
-
-    return lines.join("\n");
-  },
-
-  json(components) {
-    return JSON.stringify(components, null, 2);
-  },
-};
-
-export default formatters;

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

@@ -1,318 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
-import type { BlockDetailed } from "../../shared/types/index.js";
-import type { AspectFlags } from "../types.js";
-import formatters from "./lookup.js";
-
-const BUTTON_DETAILED: BlockDetailed = {
-  uri: `${DEFAULT_PREFIX_MAP.ds}global.component.button` as URI,
-  name: "Button",
-  type: "component",
-  tier: "global",
-  modifiers: ["importance", "density"],
-  summary: "Primary action trigger with optional icon and label.",
-  implementations: [
-    { framework: "react", available: true },
-    { framework: "svelte", available: false },
-  ],
-  nodeCount: 3,
-  tokenCount: 1,
-  whenToUse: "Use for high-priority actions in forms and flows.",
-  whenNotToUse: "Avoid for low-emphasis tertiary actions.",
-  guidelines: "Keep labels concise and pair icons with text when possible.",
-  anatomyDsl: "root: button; children: label, icon",
-  anatomyClassic: "button > label + icon",
-  figmaLink: "https://figma.com/design/example/Button",
-  anatomy: {
-    root: {
-      name: "button",
-      type: "named",
-      children: [
-        { name: "label", type: "named", children: [] },
-        { name: "icon", type: "anonymous", children: [], slot: "start" },
-      ],
-    },
-  },
-  modifierValues: [
-    { family: "importance", values: ["default", "primary", "secondary"] },
-    { family: "density", values: ["default", "compact"] },
-  ],
-  modifierFamilies: [
-    {
-      uri: `${DEFAULT_PREFIX_MAP.ds}modifier_family.importance` as URI,
-      name: "importance",
-      values: ["default", "primary", "secondary"],
-    },
-  ],
-  properties: [
-    {
-      name: "disabled",
-      propertyType: "boolean",
-      optional: true,
-      defaultValue: "false",
-      constraints: "Disables click and keyboard activation.",
-    },
-  ],
-  subcomponents: [
-    {
-      uri: `${DEFAULT_PREFIX_MAP.ds}global.subcomponent.button.icon` as URI,
-      name: "Button Icon",
-    },
-  ],
-  implementationPaths: [
-    { framework: "react", path: "src/lib/Button/Button.tsx" },
-  ],
-  tokens: [
-    {
-      uri: `${DEFAULT_PREFIX_MAP.ds}token.color.primary` as URI,
-      name: "color.primary",
-    },
-  ],
-  standards: [],
-};
-
-const ALL_ASPECTS: AspectFlags = {
-  anatomy: true,
-  modifiers: true,
-  tokens: true,
-  implementations: true,
-};
-
-describe("formatters.plain (summary)", () => {
-  it("includes block name and tier", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("Button");
-    expect(text).toContain("global");
-  });
-
-  it("includes summary when present", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain(
-      "Primary action trigger with optional icon and label.",
-    );
-  });
-
-  it("includes modifier names", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("importance, density");
-  });
-
-  it("includes available implementations", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("react");
-  });
-
-  it("includes node and token counts", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("3");
-    expect(text).toContain("1");
-  });
-});
-
-describe("formatters.plain (detailed)", () => {
-  it("includes summary counts in detailed view", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("3");
-    expect(text).toContain("1");
-  });
-
-  it("shows modifiers section with values", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("Modifiers");
-    expect(text).toContain("importance");
-    expect(text).toContain("primary");
-    expect(text).toContain("secondary");
-  });
-
-  it("shows implementations section", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("Implementations");
-    expect(text).toContain("react");
-    expect(text).toContain("Button.tsx");
-  });
-
-  it("shows tokens section", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("Tokens");
-    expect(text).toContain("color.primary");
-  });
-
-  it("shows anatomy section", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("Anatomy");
-    expect(text).toContain("button");
-    expect(text).toContain("label");
-    expect(text).toContain("icon");
-  });
-
-  it("shows guidance, properties, and subcomponents", () => {
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("When to use");
-    expect(text).toContain("Guidelines");
-    expect(text).toContain("Properties");
-    expect(text).toContain("disabled");
-    expect(text).toContain("Subcomponents");
-    expect(text).toContain("Button Icon");
-  });
-
-  it("respects aspect filter — modifiers only", () => {
-    const aspects: AspectFlags = {
-      anatomy: false,
-      modifiers: true,
-      tokens: false,
-      implementations: false,
-    };
-    const text = formatters.plain({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects,
-    });
-    expect(text).toContain("Modifiers");
-    // Summary field "Tokens: 1" is always shown, but the Tokens section should not appear
-    expect(text).not.toContain("color.primary");
-    expect(text).not.toContain("Anatomy\n");
-    expect(text).not.toContain("Button.tsx");
-  });
-});
-
-describe("formatters.llm", () => {
-  it("formats summary as markdown", () => {
-    const text = formatters.llm({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("## Button");
-    expect(text).toContain("- Tier: global");
-    expect(text).toContain(
-      "- Summary: Primary action trigger with optional icon and label.",
-    );
-    expect(text).not.toContain("### Modifiers");
-  });
-
-  it("formats detailed with all sections", () => {
-    const text = formatters.llm({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    expect(text).toContain("### Modifiers");
-    expect(text).toContain("### Implementations");
-    expect(text).toContain("### Tokens");
-    expect(text).toContain("### Anatomy");
-    expect(text).toContain("### Properties");
-    expect(text).toContain("### Subcomponents");
-  });
-
-  it("formats detailed with aspect filter", () => {
-    const aspects: AspectFlags = {
-      anatomy: false,
-      modifiers: true,
-      tokens: true,
-      implementations: false,
-    };
-    const text = formatters.llm({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects,
-    });
-    expect(text).toContain("### Modifiers");
-    expect(text).toContain("### Tokens");
-    expect(text).toContain("### Anatomy (DSL)");
-    expect(text).not.toContain("### Anatomy\n");
-  });
-});
-
-describe("formatters.json", () => {
-  it("returns valid JSON for summary", () => {
-    const text = formatters.json({
-      block: BUTTON_DETAILED,
-      detailed: false,
-      aspects: ALL_ASPECTS,
-    });
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("Button");
-    expect(parsed.tier).toBe("global");
-    expect(parsed.modifierValues).toBeUndefined();
-  });
-
-  it("returns valid JSON for detailed with all aspects", () => {
-    const text = formatters.json({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects: ALL_ASPECTS,
-    });
-    const parsed = JSON.parse(text);
-    expect(parsed.name).toBe("Button");
-    expect(parsed.nodeCount).toBe(3);
-    expect(parsed.tokenCount).toBe(1);
-    expect(parsed.modifiers).toBeDefined();
-    expect(parsed.implementations).toBeDefined();
-    expect(parsed.modifierValues).toBeDefined();
-    expect(parsed.tokens).toBeDefined();
-    expect(parsed.anatomy).toBeDefined();
-  });
-
-  it("returns JSON with filtered aspects", () => {
-    const aspects: AspectFlags = {
-      anatomy: false,
-      modifiers: true,
-      tokens: false,
-      implementations: false,
-    };
-    const text = formatters.json({
-      block: BUTTON_DETAILED,
-      detailed: true,
-      aspects,
-    });
-    const parsed = JSON.parse(text);
-    expect(parsed.modifierValues).toBeDefined();
-    expect(parsed.tokens).toBeUndefined();
-    expect(parsed.anatomy).toBeUndefined();
-  });
-});

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

@@ -1,149 +0,0 @@
-import type { RenderLookupOptions } from "../../shared/contracts.js";
-import type { Formatters } from "../../shared/formatters.js";
-import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
-import type { BlockDetailed } from "../../shared/types/index.js";
-import { blockConfig } from "../blockConfig.js";
-import type { AspectFlags } from "../types.js";
-import type { BlockLookupInput } from "./types.js";
-
-/** Three-mode formatter for `pragma block lookup` output. */
-const formatters: Formatters<BlockLookupInput> = {
-  plain: ({ block, detailed, aspects }) =>
-    renderLookupPlain(block, createLookupOptions(detailed, aspects)),
-
-  llm: ({ block, detailed, aspects }) =>
-    renderLookupLlm(block, createLookupOptions(detailed, aspects)),
-
-  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;
-
-export function createLookupOptions(
-  detailed: boolean,
-  aspects: AspectFlags,
-): RenderLookupOptions<BlockDetailed> {
-  return {
-    title: (block) => block.name,
-    fields: [
-      { label: "IRI", value: (block) => block.uri },
-      { label: "Type", value: (block) => block.type },
-      { label: "Tier", value: (block) => block.tier },
-      ...(detailed
-        ? []
-        : ([
-            {
-              label: "Summary",
-              value: (block: BlockDetailed) => block.summary,
-            },
-          ] as const)),
-      { label: "Modifiers", value: (block) => block.modifiers },
-      {
-        label: "Implementations",
-        value: (block) =>
-          block.implementations
-            .filter((implementation) => implementation.available)
-            .map((implementation) => implementation.framework),
-      },
-      { label: "Anatomy nodes", value: (block) => block.nodeCount || null },
-      { label: "Tokens", value: (block) => block.tokenCount || null },
-    ],
-    sections: selectLookupSections(detailed, aspects),
-    sectionOverrides: {
-      modifierFamilies: {
-        plain: (block) =>
-          block.modifierValues.length > 0
-            ? block.modifierValues
-                .map(
-                  (modifier) =>
-                    `  ${modifier.family}: ${modifier.values.join(", ")}`,
-                )
-                .join("\n")
-            : null,
-        llm: (block) =>
-          block.modifierValues.length > 0
-            ? block.modifierValues
-                .map(
-                  (modifier) =>
-                    `- **${modifier.family}**: ${modifier.values.join(", ")}`,
-                )
-                .join("\n")
-            : null,
-      },
-    },
-    codeLanguage: (_section, value) =>
-      typeof value === "string" && value.includes("@prefix") ? "ttl" : "yaml",
-  };
-}
-
-function selectLookupSections(
-  detailed: boolean,
-  aspects: AspectFlags,
-): typeof blockConfig.lookupSections {
-  const sections = detailed
-    ? blockConfig.lookupSections
-    : blockConfig.lookupSections.filter(
-        (section) =>
-          section.key === "subcomponents" || section.key === "anatomyDsl",
-      );
-
-  return sections.filter((section) => {
-    if (
-      !aspects.anatomy &&
-      ["anatomy", "anatomyClassic"].includes(section.key)
-    ) {
-      return false;
-    }
-
-    if (!aspects.modifiers && section.key === "modifierFamilies") {
-      return false;
-    }
-
-    if (!aspects.implementations && section.key === "implementationPaths") {
-      return false;
-    }
-
-    if (!aspects.tokens && section.key === "tokens") {
-      return false;
-    }
-
-    return true;
-  });
-}