@canonical/pragma-cli 0.27.1-experimental.0 → 0.29.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
   "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.27.1-experimental.0",
+  "version": "0.29.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
+    "build": "bun run scripts/build.ts",
     "build:compile": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
     "prepublishOnly": "bun run build",
     "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
@@ -60,9 +60,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.27.1-experimental.0",
-    "@canonical/typescript-config": "^0.27.1-experimental.0",
-    "@canonical/webarchitect": "^0.27.1-experimental.0",
+    "@canonical/biome-config": "^0.29.0",
+    "@canonical/typescript-config": "^0.29.0",
+    "@canonical/webarchitect": "^0.29.0",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
@@ -70,19 +70,18 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "optionalDependencies": {
+  "dependencies": {
     "@canonical/anatomy-dsl": "^0.2.2",
+    "@canonical/cli-core": "^0.29.0",
     "@canonical/code-standards": "^0.1.2",
-    "@canonical/design-system": "^0.1.2"
-  },
-  "dependencies": {
-    "@canonical/cli-core": "^0.27.1-experimental.0",
-    "@canonical/harnesses": "^0.27.1-experimental.0",
-    "@canonical/ke": "^0.27.1-experimental.0",
-    "@canonical/summon-component": "^0.27.1-experimental.0",
-    "@canonical/summon-core": "^0.27.1-experimental.0",
-    "@canonical/summon-package": "^0.27.1-experimental.0",
-    "@canonical/task": "^0.27.1-experimental.0",
+    "@canonical/design-system": "^0.1.2",
+    "@canonical/harnesses": "^0.29.0",
+    "@canonical/ke": "^0.29.0",
+    "@canonical/ke-graphql": "^0.29.0",
+    "@canonical/summon-component": "^0.29.0",
+    "@canonical/summon-core": "^0.29.0",
+    "@canonical/summon-package": "^0.29.0",
+    "@canonical/task": "^0.29.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -91,5 +90,5 @@
     "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "d3f5b9aab7bec07fce40a12b45097d28d3cf0201"
+  "gitHead": "7c96ac31ff350a3bd099168d249680a8f9632568"
 }

package/src/config/readConfig.ts

@@ -1,5 +1,10 @@
 import { readFileSync } from "node:fs";
-import { type Channel, VALID_CHANNELS } from "../constants.js";
+import {
+  type Channel,
+  type Framework,
+  VALID_CHANNELS,
+  VALID_FRAMEWORKS,
+} from "../constants.js";
 import {
   parsePackageEntry,
   type RawPackageEntry,
@@ -18,6 +23,18 @@ function isValidChannel(value: unknown): value is Channel {
   return typeof value === "string" && VALID_CHANNELS.includes(value as Channel);
 }
 
+/**
+ * Type guard: check whether a value is a recognized framework string.
+ *
+ * @param value - Candidate value.
+ * @returns `true` if value is a valid Framework.
+ */
+function isValidFramework(value: unknown): value is Framework {
+  return (
+    typeof value === "string" && VALID_FRAMEWORKS.includes(value as Framework)
+  );
+}
+
 /**
  * Read pragma config from `pragma.config.json` in the given directory.
  *
@@ -64,9 +81,28 @@ export default function readConfig(cwd: string = process.cwd()): PragmaConfig {
     channel = parsed.channel;
   }
 
+  const trace = typeof parsed.trace === "boolean" ? parsed.trace : undefined;
+
+  let framework: Framework | undefined;
+  if (parsed.framework !== undefined) {
+    if (!isValidFramework(parsed.framework)) {
+      throw PragmaError.configError(
+        `Invalid framework "${String(parsed.framework)}".`,
+        { validOptions: [...VALID_FRAMEWORKS] },
+      );
+    }
+    framework = parsed.framework;
+  }
+
   const packages = parsePackagesField(parsed.packages);
 
-  return packages ? { tier, channel, packages } : { tier, channel };
+  return {
+    tier,
+    channel,
+    ...(packages ? { packages } : {}),
+    ...(trace !== undefined ? { trace } : {}),
+    ...(framework !== undefined ? { framework } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------

package/src/config/types.ts

@@ -5,7 +5,7 @@
  * so consumers can import types without pulling in filesystem code.
  */
 
-import type { Channel } from "../constants.js";
+import type { Channel, Framework } from "../constants.js";
 import type { RawPackageEntry } from "../domains/refs/operations/parseRef.js";
 
 /** Parsed contents of pragma.config.json. */
@@ -20,6 +20,13 @@ interface PragmaConfig {
    * When absent, the hardcoded defaults are used.
    */
   packages?: ReadonlyArray<RawPackageEntry> | undefined;
+  /** Whether query access tracing is enabled. Overridden by PRAGMA_TRACE env var. */
+  trace?: boolean | undefined;
+  /**
+   * Preferred UI framework (`react` | `svelte` | `lit`). Currently advisory
+   * only — no behaviour reads it yet; reserved for future framework defaulting.
+   */
+  framework?: Framework | undefined;
 }
 
 /** Partial update payload for writing config changes. */
@@ -30,6 +37,10 @@ interface ConfigUpdate {
   channel?: Channel | undefined;
   /** New packages list, `undefined` to remove the field. */
   packages?: ReadonlyArray<RawPackageEntry> | undefined;
+  /** Enable/disable query tracing, `undefined` to remove the field. */
+  trace?: boolean | undefined;
+  /** New preferred framework, `undefined` to remove the field. */
+  framework?: Framework | undefined;
 }
 
 export type { ConfigUpdate, PragmaConfig };

package/src/config/writeConfig.ts

@@ -50,6 +50,18 @@ export default function writeConfig(cwd: string, update: ConfigUpdate): void {
     delete existing.packages;
   }
 
+  if (update.trace !== undefined) {
+    existing.trace = update.trace;
+  } else if ("trace" in update) {
+    delete existing.trace;
+  }
+
+  if (update.framework !== undefined) {
+    existing.framework = update.framework;
+  } else if ("framework" in update) {
+    delete existing.framework;
+  }
+
   writeFileSync(tempPath, `${JSON.stringify(existing, null, 2)}\n`);
   renameSync(tempPath, configPath);
 }

package/src/constants.ts

@@ -24,6 +24,16 @@ const VALID_CHANNELS = ["normal", "experimental", "prerelease"] as const;
 /** A release channel name. */
 type Channel = (typeof VALID_CHANNELS)[number];
 
+/** Allowed values for the `framework` config field. */
+const VALID_FRAMEWORKS = ["react", "svelte", "lit"] as const;
+
+/**
+ * A preferred UI framework. Currently advisory only (a no-op); reserved for
+ * future use to default framework-specific behaviour (e.g. which generator
+ * `pragma`/`summon` scaffolds, which component tier is surfaced).
+ */
+type Framework = (typeof VALID_FRAMEWORKS)[number];
+
 /**
  * Per-namespace property URIs for semantically equivalent fields.
  * Each ontology uses different property names for the same concept
@@ -68,11 +78,12 @@ const PROPERTY_MAP: Record<string, OntologyPropertyMap> = {
   },
 };
 
-export type { Channel, OntologyPropertyMap };
+export type { Channel, Framework, OntologyPropertyMap };
 export {
   PROGRAM_DESCRIPTION,
   PROGRAM_NAME,
   PROPERTY_MAP,
   VALID_CHANNELS,
+  VALID_FRAMEWORKS,
   VERSION,
 };

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

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

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

@@ -0,0 +1,55 @@
+/**
+ * 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 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 = Number(params.count ?? 2);
+      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,4 +1,5 @@
-/** @module Re-exports block formatters (`lookupFormatters`, `listFormatters`). */
+/** @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/sample.ts

@@ -0,0 +1,21 @@
+/**
+ * Sample formatter for the block domain.
+ *
+ * Delegates to the shared factory, rendering each item via the
+ * existing block lookup formatter with all aspects enabled.
+ */
+
+import createSampleFormatters from "../../shared/sampleFormatters.js";
+import type { BlockDetailed } from "../../shared/types/index.js";
+import lookupFormatters from "./lookup.js";
+
+const ALL_ASPECTS = {
+  anatomy: true,
+  modifiers: true,
+  tokens: true,
+  implementations: true,
+} as const;
+
+export default createSampleFormatters<BlockDetailed>("blocks", (block, mode) =>
+  lookupFormatters[mode]({ block, detailed: true, aspects: ALL_ASPECTS }),
+);

package/src/domains/block/index.ts

@@ -7,15 +7,15 @@
 
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../shared/context.js";
-import { listCommand, lookupCommand } from "./commands/index.js";
+import { listCommand, lookupCommand, sampleCommand } from "./commands/index.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx)];
+  return [listCommand(ctx), lookupCommand(ctx), sampleCommand(ctx)];
 }
 
 export { blockConfig } from "./blockConfig.js";
 export { specs as mcpSpecs } from "./mcp/index.js";
-export { listBlocks, lookupBlock } from "./operations/index.js";
+export { listBlocks, lookupBlock, sampleBlocks } from "./operations/index.js";
 export {
   blockEmptyError,
   buildBlockFilters,

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

@@ -9,7 +9,9 @@ import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
   listFormatters as blockListFmt,
   lookupFormatters as blockLookupFmt,
+  sampleFormatters as blockSampleFmt,
 } from "../formatters/index.js";
+import { sampleBlocks } from "../operations/index.js";
 import {
   buildBlockFilters,
   resolveBlockList,
@@ -194,6 +196,52 @@ const specs: readonly ToolSpec[] = [
       return { data: result, meta: { count: result.results.length } };
     },
   },
+  {
+    name: "block_sample",
+    description:
+      "Return 1–5 randomly selected complete block instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
+    params: {
+      count: {
+        type: "string",
+        description: "Number of samples (1–5, default 2)",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { count, condensed }) {
+      const n = Number(count ?? 2);
+      const filters = buildBlockFilters(rt);
+      const result = await sampleBlocks(rt.store, filters, n);
+      const nextSteps = [
+        `These are ${result.samples.length} of ${result.totalCount} total blocks.`,
+        "Use block_lookup to inspect specific blocks by name.",
+        "Use block_list to see all available blocks with filtering.",
+      ];
+
+      if (condensed) {
+        const text = blockSampleFmt.llm({ ...result, nextSteps });
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return {
+        data: {
+          samples: result.samples,
+          totalCount: result.totalCount,
+          nextSteps,
+        },
+        meta: { count: result.samples.length },
+      };
+    },
+  },
 ] as const;
 
 export default specs;

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

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

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

@@ -21,6 +21,11 @@ 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 {
+  detectCrossDomain,
+  listDomainNames,
+  suggestNames,
+} from "../../shared/suggestions/index.js";
 import type {
   BlockDetailed,
   BlockSubcomponent,
@@ -80,12 +85,16 @@ export default async function lookupBlock(
   );
 
   if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
+    const candidates = await listDomainNames(store, "block");
+    const crossDomain = await detectCrossDomain(nameOrUri, "block", store);
     throw PragmaError.notFound("block", nameOrUri, {
+      suggestions: suggestNames(nameOrUri, candidates),
       recovery: {
         message: "List available blocks.",
         cli: "pragma block list",
         mcp: { tool: "block_list" },
       },
+      crossDomain: crossDomain ?? undefined,
     });
   }
 

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

@@ -0,0 +1,41 @@
+/**
+ * Returns a small number of complete block instances as exemplars.
+ *
+ * Composes the existing list and lookup operations to avoid duplicating
+ * any SPARQL logic. Agents use this to learn the data shape before querying.
+ *
+ * @param store - ke store to query
+ * @param filters - tier and channel filter configuration
+ * @param count - number of samples (clamped 1–5, default 2)
+ * @returns sample result with detailed blocks and total count
+ * @note Queries ke store
+ */
+
+import type { Store } from "@canonical/ke";
+import pickRandom from "../../shared/pickRandom.js";
+import type {
+  BlockDetailed,
+  FilterConfig,
+  SampleResult,
+} from "../../shared/types/index.js";
+import listBlocks from "./list.js";
+import lookupBlock from "./lookup.js";
+
+export default async function sampleBlocks(
+  store: Store,
+  filters: FilterConfig,
+  count = 2,
+): Promise<SampleResult<BlockDetailed>> {
+  const clamped = Math.max(1, Math.min(5, count));
+  const all = await listBlocks(store, filters);
+  const selected = pickRandom(all, clamped);
+
+  const samples = await Promise.all(
+    selected.map(async (b) => {
+      const results = await lookupBlock(store, b.name, filters);
+      return results[0] as BlockDetailed;
+    }),
+  );
+
+  return { samples, totalCount: all.length };
+}

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import type { FilterConfig } from "../../shared/types/index.js";
+import blockEmptyError from "./blockEmptyError.js";
+
+const filters: FilterConfig = { tier: "Apps/WPE", channel: "normal" };
+
+describe("blockEmptyError", () => {
+  it("filter-narrowing: a tier was active → widen to all tiers", () => {
+    const err = blockEmptyError(filters, false);
+
+    expect(err.filters).toEqual({ tier: "Apps/WPE", channel: "normal" });
+    expect(err.recovery).toEqual({
+      message: "Widen the search to show all tiers.",
+      cli: "pragma block list --all-tiers",
+      mcp: { tool: "block_list", params: { allTiers: true } },
+    });
+  });
+
+  it("honest terminal: already at all-tiers → no recovery (no self-loop)", () => {
+    const err = blockEmptyError({ tier: undefined, channel: "normal" }, true);
+
+    // The widest tier query already returned empty; suggesting --all-tiers
+    // again would loop. recovery: undefined is the correct terminal state.
+    expect(err.recovery).toBeUndefined();
+  });
+});

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

@@ -1,6 +1,7 @@
 import type { LookupContract, LookupResult } from "../../shared/contracts.js";
 import lookupMany from "../../shared/lookupMany.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
+import { expandLookupQueries } from "../../shared/suggestions/index.js";
 import type { BlockDetailed, FilterConfig } from "../../shared/types/index.js";
 import { lookupBlock } from "../operations/index.js";
 
@@ -9,15 +10,21 @@ export default async function resolveBlockLookup(
   queries: readonly string[],
   filters: FilterConfig,
 ): Promise<LookupContract<BlockDetailed>> {
-  const nested: LookupResult<BlockDetailed[]> = await lookupMany(
+  const { names, globErrors } = await expandLookupQueries(
     queries,
-    (query) => lookupBlock(store, query, filters),
+    store,
+    "block",
   );
 
+  const nested: LookupResult<BlockDetailed[]> =
+    names.length > 0
+      ? await lookupMany(names, (query) => lookupBlock(store, query, filters))
+      : { results: [], errors: [] };
+
   // lookupBlock returns BlockDetailed[] (multiple matches per name) — flatten
   const result: LookupResult<BlockDetailed> = {
     results: nested.results.flat(),
-    errors: nested.errors,
+    errors: [...nested.errors, ...globErrors],
   };
 
   return {

package/src/domains/config/commands/framework.test.ts

@@ -0,0 +1,88 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Store } from "@canonical/ke";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readConfig } from "#config";
+import type { PragmaContext } from "../../shared/context.js";
+import buildFrameworkCommand from "./framework.js";
+
+function makeCtx(cwd: string): PragmaContext {
+  return {
+    cwd,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as Store,
+    config: { tier: undefined, channel: "normal" },
+  };
+}
+
+describe("config framework command", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-cmd-framework-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("sets framework to react", async () => {
+    const ctx = makeCtx(dir);
+    const result = await buildFrameworkCommand(ctx).execute(
+      { value: "react" },
+      ctx,
+    );
+    expect(result.tag).toBe("output");
+    expect(readConfig(dir).framework).toBe("react");
+  });
+
+  it("accepts svelte and lit", async () => {
+    const ctx = makeCtx(dir);
+    await buildFrameworkCommand(ctx).execute({ value: "svelte" }, ctx);
+    expect(readConfig(dir).framework).toBe("svelte");
+    await buildFrameworkCommand(ctx).execute({ value: "lit" }, ctx);
+    expect(readConfig(dir).framework).toBe("lit");
+  });
+
+  it("rejects an invalid framework", async () => {
+    const ctx = makeCtx(dir);
+    await expect(
+      buildFrameworkCommand(ctx).execute({ value: "angular" }, ctx),
+    ).rejects.toThrow(/framework/i);
+  });
+
+  it("reports 'none' when unset", async () => {
+    const ctx = makeCtx(dir);
+    const result = await buildFrameworkCommand(ctx).execute({}, ctx);
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.value).toBe("none");
+    }
+  });
+
+  it("resets framework via --reset (removes the field)", async () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"framework":"react"}');
+    const ctx = makeCtx(dir);
+    await buildFrameworkCommand(ctx).execute({ reset: true }, ctx);
+    expect(readConfig(dir).framework).toBeUndefined();
+    // The field is removed, not left as a stale value.
+    const raw = JSON.parse(
+      readFileSync(join(dir, "pragma.config.json"), "utf-8"),
+    ) as Record<string, unknown>;
+    expect(raw).not.toHaveProperty("framework");
+  });
+
+  it("preserves other config fields when setting framework", async () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      JSON.stringify({ tier: "Apps/WPE", trace: true }),
+    );
+    const ctx = makeCtx(dir);
+    await buildFrameworkCommand(ctx).execute({ value: "lit" }, ctx);
+    const config = readConfig(dir);
+    expect(config.framework).toBe("lit");
+    expect(config.tier).toBe("Apps/WPE");
+    expect(config.trace).toBe(true);
+  });
+});