@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,80 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import type { FilterConfig } from "../../shared/types.js";
+import listBlocks 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());
+
+const noFilter: FilterConfig = { tier: undefined, channel: "prerelease" };
+const normalChannel: FilterConfig = { tier: undefined, channel: "normal" };
+const globalTier: FilterConfig = { tier: "global", channel: "prerelease" };
+const lxdTier: FilterConfig = { tier: "apps/lxd", channel: "normal" };
+
+describe("listBlocks", () => {
+  it("returns all blocks with no tier filter and prerelease channel", async () => {
+    const result = await listBlocks(store, noFilter);
+    const names = result.map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).toContain("Card");
+    expect(names).toContain("LXD Panel");
+    expect(names).toContain("Beta Widget");
+  });
+
+  it("excludes beta blocks with normal channel", async () => {
+    const result = await listBlocks(store, normalChannel);
+    const names = result.map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).toContain("Card");
+    expect(names).toContain("LXD Panel");
+    expect(names).not.toContain("Beta Widget");
+  });
+
+  it("filters by tier (global only)", async () => {
+    const result = await listBlocks(store, globalTier);
+    const names = result.map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).toContain("Card");
+    expect(names).toContain("Beta Widget");
+    expect(names).not.toContain("LXD Panel");
+  });
+
+  it("applies orthogonal tier + channel filters", async () => {
+    const result = await listBlocks(store, lxdTier);
+    const names = result.map((c) => c.name);
+    expect(names).toContain("Button");
+    expect(names).toContain("Card");
+    expect(names).toContain("LXD Panel");
+    expect(names).not.toContain("Beta Widget");
+  });
+
+  it("returns sorted by name", async () => {
+    const result = await listBlocks(store, noFilter);
+    const names = result.map((c) => c.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+
+  it("includes modifier names on Button", async () => {
+    const result = await listBlocks(store, noFilter);
+    const button = result.find((c) => c.name === "Button");
+    expect(button).toBeDefined();
+    expect(button?.modifiers).toContain("importance");
+    expect(button?.modifiers).toContain("density");
+  });
+
+  it("counts tokens on Button", async () => {
+    const result = await listBlocks(store, noFilter);
+    const button = result.find((c) => c.name === "Button");
+    expect(button?.tokenCount).toBe(1);
+  });
+});

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

@@ -0,0 +1,72 @@
+/**
+ * Lists all blocks visible under the given tier and channel filters.
+ *
+ * Returns summary-level data (name, tier, modifiers, node/token counts)
+ * for each matching block, ordered alphabetically by name.
+ *
+ * @param store - ke store to query
+ * @param filters - tier and channel filter configuration
+ * @returns array of block summaries, empty when none match
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import extractLocalName from "../../shared/extractLocalName.js";
+import { buildFilters } from "../../shared/filters/buildFilters.js";
+import { P } from "../../shared/prefixes.js";
+import type { BlockSummary, FilterConfig } from "../../shared/types.js";
+
+function normalizeBlockType(value: string | undefined): BlockSummary["type"] {
+  const localName = extractLocalName(value ?? "").toLowerCase();
+
+  switch (localName) {
+    case "pattern":
+    case "layout":
+    case "subcomponent":
+      return localName;
+    default:
+      return "component";
+  }
+}
+
+export default async function listBlocks(
+  store: Store,
+  filters: FilterConfig,
+): Promise<BlockSummary[]> {
+  const filterClauses = buildFilters(filters);
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?component ?type ?name ?tier
+             (GROUP_CONCAT(DISTINCT ?modName; separator="|") AS ?modifiers)
+             (COUNT(DISTINCT ?node) AS ?nodeCount)
+             (COUNT(DISTINCT ?token) AS ?tokenCount)
+      WHERE {
+        VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+        ?component a ?type ;
+                   ${P.ds}name ?name ;
+                   ${P.ds}tier ?tier .
+        ${filterClauses}
+        OPTIONAL { ?component ${P.ds}hasModifierFamily ?mod . ?mod ${P.ds}name ?modName }
+        OPTIONAL { ?component ${P.ds}anatomyNode ?node }
+        OPTIONAL { ?component ${P.ds}usesToken ?token }
+      }
+      GROUP BY ?component ?type ?name ?tier
+      ORDER BY ?name
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  return result.bindings.map((b) => ({
+    uri: (b.component ?? "") as URI,
+    name: b.name ?? "",
+    type: normalizeBlockType(b.type),
+    tier: extractLocalName(b.tier ?? ""),
+    modifiers: b.modifiers ? b.modifiers.split("|").filter(Boolean) : [],
+    implementations: [],
+    nodeCount: Number.parseInt(b.nodeCount ?? "0", 10) || 0,
+    tokenCount: Number.parseInt(b.tokenCount ?? "0", 10) || 0,
+  }));
+}

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

@@ -0,0 +1,108 @@
+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 { FilterConfig } from "../../shared/types.js";
+import lookupBlock 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());
+
+const noFilter: FilterConfig = { tier: undefined, channel: "prerelease" };
+const normalChannel: FilterConfig = { tier: undefined, channel: "normal" };
+
+describe("lookupBlock", () => {
+  it("returns detailed data for Button", async () => {
+    const result = await lookupBlock(store, "Button", noFilter);
+    expect(result.name).toBe("Button");
+    expect(result.tier).toBe("global");
+    expect(result.modifierValues.length).toBeGreaterThan(0);
+
+    const importance = result.modifierValues.find(
+      (m) => m.family === "importance",
+    );
+    expect(importance?.values).toContain("primary");
+    expect(importance?.values).toContain("secondary");
+  });
+
+  it("includes implementation paths", async () => {
+    const result = await lookupBlock(store, "Button", noFilter);
+    const react = result.implementationPaths.find(
+      (i) => i.framework === "react",
+    );
+    expect(react).toBeDefined();
+    expect(react?.path).toContain("Button.tsx");
+  });
+
+  it("includes token references", async () => {
+    const result = await lookupBlock(store, "Button", noFilter);
+    expect(result.tokens.length).toBe(1);
+    expect(result.tokens[0].name).toBe("color.primary");
+  });
+
+  it("populates nodeCount from anatomy nodes", async () => {
+    const result = await lookupBlock(store, "Button", noFilter);
+    expect(result.nodeCount).toBe(3);
+    expect(result.anatomy?.root.name).toBe("button");
+  });
+
+  it("returns enriched summary, properties, and subcomponents", async () => {
+    const result = await lookupBlock(store, "Button", noFilter);
+    expect(result.summary).toContain("Primary action trigger");
+    expect(result.whenToUse).toContain("high-priority actions");
+    expect(result.properties.map((property) => property.name)).toEqual(
+      expect.arrayContaining(["disabled", "loading"]),
+    );
+    expect(result.subcomponents[0]?.name).toBe("Button Icon");
+    expect(result.modifierFamilies.map((family) => family.name)).toEqual(
+      expect.arrayContaining(["importance", "density"]),
+    );
+  });
+
+  it("throws PragmaError.notFound for unknown block", async () => {
+    await expect(lookupBlock(store, "NonExistent", noFilter)).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await lookupBlock(store, "NonExistent", noFilter);
+    } catch (e) {
+      expect(e).toBeInstanceOf(PragmaError);
+      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
+    }
+  });
+
+  it("respects channel filter", async () => {
+    await expect(
+      lookupBlock(store, "Beta Widget", normalChannel),
+    ).rejects.toThrow(PragmaError);
+  });
+
+  it("resolves prefixed IRIs", async () => {
+    const result = await lookupBlock(
+      store,
+      "ds:global.component.button",
+      noFilter,
+    );
+    expect(result.name).toBe("Button");
+    expect(result.uri).toBe("https://ds.canonical.com/global.component.button");
+  });
+
+  it("resolves full IRIs", async () => {
+    const result = await lookupBlock(
+      store,
+      "https://ds.canonical.com/global.component.button",
+      noFilter,
+    );
+    expect(result.name).toBe("Button");
+    expect(result.uri).toBe("https://ds.canonical.com/global.component.button");
+  });
+});

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

@@ -0,0 +1,359 @@
+/**
+ * Look up detailed information for a single block.
+ *
+ * Queries the base block, then resolves related modifiers, implementations,
+ * tokens, anatomy nodes, blank-node properties, and direct subcomponents.
+ * The result is assembled into a {@link BlockDetailed} object.
+ *
+ * @param store - ke store to query
+ * @param name - block name (e.g. "Button")
+ * @param filters - tier and channel filter configuration
+ * @returns fully populated block detail
+ * @throws PragmaError.notFound if the block 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 extractLocalName from "../../shared/extractLocalName.js";
+import { buildFilters } from "../../shared/filters/buildFilters.js";
+import { P } from "../../shared/prefixes.js";
+import type {
+  BlockDetailed,
+  FilterConfig,
+  StandardRef,
+  TokenRef,
+} from "../../shared/types.js";
+
+function normalizeBlockType(value: string | undefined): BlockDetailed["type"] {
+  const localName = extractLocalName(value ?? "").toLowerCase();
+
+  switch (localName) {
+    case "pattern":
+    case "layout":
+    case "subcomponent":
+      return localName;
+    default:
+      return "component";
+  }
+}
+
+export default async function lookupBlock(
+  store: Store,
+  nameOrUri: string,
+  filters: FilterConfig,
+): Promise<BlockDetailed> {
+  const filterClauses = buildFilters(filters);
+  const subjectClause = buildLookupSubjectClause(nameOrUri, store.prefixes);
+  const bindClause =
+    subjectClause === null ? "" : `BIND(${subjectClause} AS ?component)`;
+  const matchClause =
+    subjectClause === null
+      ? `?component ${P.ds}name ${escapeSparqlValue(nameOrUri)} .`
+      : "";
+
+  // Base query: find the block
+  const baseResult = await store.query(
+    buildQuery(`
+      SELECT ?component ?name ?type ?tier ?summary ?whenToUse ?whenNotToUse ?guidelines ?anatomyDsl ?anatomyClassic ?figmaLink
+      WHERE {
+        VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+        ${bindClause}
+        ?component a ?type ;
+                   ${P.ds}name ?name ;
+                   ${P.ds}tier ?tier .
+        ${matchClause}
+        OPTIONAL { ?component ${P.ds}summary ?summary }
+        OPTIONAL { ?component ${P.ds}whenToUse ?whenToUse }
+        OPTIONAL { ?component ${P.ds}whenNotToUse ?whenNotToUse }
+        OPTIONAL { ?component ${P.ds}guidelines ?guidelines }
+        OPTIONAL { ?component ${P.ds}anatomyDsl ?anatomyDsl }
+        OPTIONAL { ?component ${P.ds}anatomyClassic ?anatomyClassic }
+        OPTIONAL { ?component ${P.ds}figmaLink ?figmaLink }
+        ${filterClauses}
+      }
+      LIMIT 1
+    `),
+  );
+
+  if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
+    throw PragmaError.notFound("block", nameOrUri, {
+      recovery: {
+        message: "List available blocks.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      },
+    });
+  }
+
+  // Safe: length check above guarantees bindings[0] exists
+  const base = baseResult.bindings[0] as (typeof baseResult.bindings)[number];
+  const componentUri = base.component;
+
+  // Modifier families with values
+  const modResult = await store.query(
+    buildQuery(`
+      SELECT ?family ?modName ?value
+      WHERE {
+        <${componentUri}> ${P.ds}hasModifierFamily ?family .
+        ?family ${P.ds}name ?modName .
+        OPTIONAL {
+          ?mod a ${P.ds}Modifier ;
+               ${P.ds}modifierFamily ?family ;
+               ${P.ds}name ?value .
+        }
+      }
+      ORDER BY ?modName ?value
+    `),
+  );
+
+  const modifierMap = new Map<string, string[]>();
+  const modifierFamilyUriMap = new Map<string, URI>();
+  if (modResult.type === "select") {
+    for (const b of modResult.bindings) {
+      const existing = modifierMap.get(b.modName ?? "") ?? [];
+      if (b.value) {
+        existing.push(b.value);
+      }
+      modifierMap.set(b.modName ?? "", existing);
+
+      if (b.modName && b.family) {
+        modifierFamilyUriMap.set(b.modName, b.family as URI);
+      }
+    }
+  }
+
+  const modifierFamilies = [...modifierMap.entries()].map(([name, values]) => ({
+    uri: modifierFamilyUriMap.get(name) ?? ("" as URI),
+    name,
+    values,
+  }));
+
+  // Implementations
+  const implResult = await store.query(
+    buildQuery(`
+      SELECT ?framework ?path
+      WHERE {
+        ?lib ${P.ds}hasImplementation ?impl .
+        ?impl ${P.ds}implementsBlock <${componentUri}> ;
+              ${P.ds}headLink ?path .
+        ?lib ${P.ds}platform ?framework .
+      }
+      ORDER BY ?framework
+    `),
+  );
+
+  const implementationPaths =
+    implResult.type === "select"
+      ? implResult.bindings.map((b) => ({
+          framework: b.framework ?? "",
+          path: b.path ?? "",
+        }))
+      : [];
+
+  // Build implementations summary (which frameworks are available)
+  const frameworkSet = new Set(implementationPaths.map((i) => i.framework));
+  const allFrameworks = await listAllFrameworks(store);
+  const implementations = allFrameworks.map((fw) => ({
+    framework: fw,
+    available: frameworkSet.has(fw),
+  }));
+
+  // Tokens
+  const tokenResult = await store.query(
+    buildQuery(`
+      SELECT ?token ?tokenId
+      WHERE {
+        <${componentUri}> ${P.ds}usesToken ?token .
+        ?token ${P.ds}tokenId ?tokenId .
+      }
+      ORDER BY ?tokenId
+    `),
+  );
+
+  const tokens: TokenRef[] =
+    tokenResult.type === "select"
+      ? tokenResult.bindings.map((b) => ({
+          uri: (b.token ?? "") as URI,
+          name: b.tokenId ?? "",
+        }))
+      : [];
+
+  // Anatomy nodes
+  const anatomyResult = await store.query(
+    buildQuery(`
+      SELECT DISTINCT ?node ?name
+      WHERE {
+        <${componentUri}> ${P.ds}anatomyNode ?node .
+        OPTIONAL { ?node ${P.ds}name ?name }
+      }
+      ORDER BY ?node
+    `),
+  );
+
+  const anatomyNodes =
+    anatomyResult.type === "select"
+      ? anatomyResult.bindings.map((binding) => ({
+          uri: (binding.node ?? "") as URI,
+          name: binding.name,
+        }))
+      : [];
+  const nodeCount = anatomyNodes.length;
+  const anatomy = buildAnatomyTree(anatomyNodes);
+
+  // Component properties from blank nodes
+  const propertiesResult = await store.query(
+    buildQuery(`
+      SELECT ?property ?name ?propertyType ?optional ?defaultValue ?constraints
+      WHERE {
+        <${componentUri}> ${P.ds}hasProperty ?property .
+        ?property ${P.ds}name ?name .
+        OPTIONAL { ?property ${P.ds}propertyType ?propertyType }
+        OPTIONAL { ?property ${P.ds}optional ?optional }
+        OPTIONAL { ?property ${P.ds}defaultValue ?defaultValue }
+        OPTIONAL { ?property ${P.ds}constraints ?constraints }
+      }
+      ORDER BY ?name
+    `),
+  );
+
+  const properties =
+    propertiesResult.type === "select"
+      ? propertiesResult.bindings.map((binding) => ({
+          name: binding.name ?? "",
+          propertyType: binding.propertyType ?? "",
+          optional: binding.optional === "true",
+          defaultValue: binding.defaultValue ?? null,
+          constraints: binding.constraints ?? null,
+        }))
+      : [];
+
+  // Direct subcomponents
+  const subcomponentsResult = await store.query(
+    buildQuery(`
+      SELECT ?subcomponent ?name
+      WHERE {
+        <${componentUri}> ${P.ds}hasSubcomponent ?subcomponent .
+        ?subcomponent ${P.ds}name ?name .
+      }
+      ORDER BY ?name
+    `),
+  );
+
+  const subcomponents =
+    subcomponentsResult.type === "select"
+      ? subcomponentsResult.bindings.map((binding) => ({
+          uri: (binding.subcomponent ?? "") as URI,
+          name: binding.name ?? "",
+        }))
+      : [];
+
+  // Standards (not linked directly to blocks in current ontology;
+  // will be populated via @follows in v0.3)
+  const standards: StandardRef[] = [];
+
+  return {
+    uri: (componentUri ?? "") as URI,
+    name: base.name ?? nameOrUri,
+    type: normalizeBlockType(base.type),
+    tier: extractLocalName(base.tier ?? ""),
+    modifiers: [...modifierMap.keys()],
+    implementations,
+    summary: base.summary ?? null,
+    nodeCount,
+    tokenCount: tokens.length,
+    whenToUse: base.whenToUse ?? null,
+    whenNotToUse: base.whenNotToUse ?? null,
+    guidelines: base.guidelines ?? null,
+    anatomyDsl: base.anatomyDsl ?? null,
+    anatomyClassic: base.anatomyClassic ?? null,
+    figmaLink: base.figmaLink ?? null,
+    anatomy,
+    modifierValues: [...modifierMap.entries()].map(([family, values]) => ({
+      family,
+      values,
+    })),
+    modifierFamilies,
+    properties,
+    subcomponents,
+    implementationPaths,
+    tokens,
+    standards,
+  };
+}
+
+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(":")
+  );
+}
+
+function buildAnatomyTree(
+  nodes: readonly { uri: URI; name?: string }[],
+): BlockDetailed["anatomy"] {
+  if (nodes.length === 0) {
+    return null;
+  }
+
+  const sorted = [...nodes].sort(
+    (left, right) => scoreAnatomyNode(right) - scoreAnatomyNode(left),
+  );
+  const [root, ...children] = sorted;
+  return {
+    root: {
+      name: root?.name ?? extractLocalName(root?.uri ?? "node"),
+      type: root?.name ? "named" : "anonymous",
+      children: children.map((node) => ({
+        name: node.name ?? extractLocalName(node.uri),
+        type: node.name ? "named" : "anonymous",
+        children: [],
+      })),
+    },
+  };
+}
+
+function scoreAnatomyNode(node: { uri: URI; name?: string }): number {
+  const uri = String(node.uri);
+  if (uri.endsWith(".root") || node.name === "button" || node.name === "card") {
+    return 2;
+  }
+  if (node.name) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Get all known implementation frameworks from the store.
+ */
+async function listAllFrameworks(store: Store): Promise<string[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT DISTINCT ?framework
+      WHERE {
+        ?lib a ${P.ds}ImplementationLibrary ;
+             ${P.ds}platform ?framework .
+      }
+      ORDER BY ?framework
+    `),
+  );
+
+  if (result.type !== "select") return [];
+  return result.bindings.map((b) => b.framework ?? "");
+}

package/src/domains/block/orchestration/blockEmptyError.ts

@@ -0,0 +1,19 @@
+import { PragmaError } from "#error";
+import { describeFilters } from "../../shared/filters/index.js";
+import type { FilterConfig } from "../../shared/types.js";
+
+export default function blockEmptyError(
+  filters: FilterConfig,
+  allTiers?: boolean,
+): PragmaError {
+  return PragmaError.emptyResults("block", {
+    filters: describeFilters(filters),
+    recovery: allTiers
+      ? undefined
+      : {
+          message: "Widen the search to show all tiers.",
+          cli: "pragma block list --all-tiers",
+          mcp: { tool: "block_list", params: { allTiers: true } },
+        },
+  });
+}

package/src/domains/block/orchestration/buildBlockFilters.ts

@@ -0,0 +1,12 @@
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { FilterConfig } from "../../shared/types.js";
+
+export default function buildBlockFilters(
+  rt: Pick<PragmaRuntime, "config">,
+  allTiers?: boolean,
+): FilterConfig {
+  return {
+    tier: allTiers ? undefined : rt.config.tier,
+    channel: rt.config.channel,
+  };
+}

package/src/domains/block/orchestration/enrichBlocks.ts

@@ -0,0 +1,37 @@
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type {
+  BlockDetailed,
+  BlockSummary,
+  Disclosure,
+  FilterConfig,
+} from "../../shared/types.js";
+import { lookupBlock } from "../operations/index.js";
+import type { BlockListDigest } from "../types.js";
+
+export default async function enrichBlocks(
+  summaries: readonly BlockSummary[],
+  store: Pick<PragmaRuntime, "store">["store"],
+  filters: FilterConfig,
+  disclosure: Disclosure,
+): Promise<readonly (BlockListDigest | BlockDetailed)[]> {
+  const details = await Promise.all(
+    summaries.map((summary) => lookupBlock(store, summary.name, filters)),
+  );
+
+  if (disclosure.level === "detailed") {
+    return details;
+  }
+
+  return details.map((detail) => ({
+    uri: detail.uri,
+    name: detail.name,
+    type: detail.type,
+    tier: detail.tier,
+    summary: detail.summary,
+    modifiers: detail.modifiers,
+    implementations: detail.implementations,
+    nodeCount: detail.nodeCount,
+    tokenCount: detail.tokenCount,
+    implementationPaths: detail.implementationPaths,
+  }));
+}

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

@@ -0,0 +1,5 @@
+export { default as blockEmptyError } from "./blockEmptyError.js";
+export { default as buildBlockFilters } from "./buildBlockFilters.js";
+export { default as enrichBlocks } from "./enrichBlocks.js";
+export { default as resolveBlockList } from "./resolveBlockList.js";
+export { default as resolveBlockLookup } from "./resolveBlockLookup.js";