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

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

@@ -1,173 +1,14 @@
-/**
- * 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 { createLookupView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import type { BlockDetailed } from "../../shared/types/index.js";
-import { createLookupOptions, lookupFormatters } from "../formatters/index.js";
-import { resolveAspects } from "../helpers/index.js";
-import { listBlocks } from "../operations/index.js";
-import {
-  buildBlockFilters,
-  resolveBlockLookup,
-} from "../orchestration/index.js";
-import type { AspectFlags } from "../types.js";
-
-interface BlockLookupOutput {
-  readonly result: LookupResult<BlockDetailed>;
-  readonly detailed: boolean;
-  readonly aspects: AspectFlags;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { blockLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma block lookup <name-or-uri...>` CLI command from the
+ * block lookup story.
+ */
 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: ({ result, detailed: isDetailed, aspects: selectedAspects }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (block) => ({
-                block,
-                detailed: isDetailed,
-                aspects: selectedAspects,
-              }),
-            }),
-          ink: ({ result, detailed: isDetailed, aspects: selectedAspects }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "block",
-              options: createLookupOptions(isDetailed, selectedAspects),
-            }),
-        },
-      );
-    },
-  };
-}
-
-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 [];
+  return compileLookupCommand(ctx, blockLookupStory);
 }

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

@@ -1,40 +1,34 @@
 /**
- * MCP tool specs for the block domain — block_list, block_lookup.
+ * MCP tool specs for the block domain — block_list, block_lookup,
+ * block_sample.
  *
- * Declarative definitions — no MCP imports. The adapter layer
- * converts these into registered MCP tools via `registerFromSpec()`.
+ * The list and lookup tools are compiled from the block read stories in
+ * `../stories.ts`; only the sample tool is spec'd by hand. 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";
+  compileLookupTool,
+  compileReadTool,
+  condense,
+} from "../../shared/stories/index.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { sampleFormatters as blockSampleFmt } from "../formatters/index.js";
+import { sampleBlocks } from "../operations/index.js";
+import { buildBlockFilters } from "../orchestration/index.js";
+import { blockListStory, blockLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
+  compileReadTool(blockListStory),
+  compileLookupTool(blockLookupStory),
   {
-    name: "block_list",
+    name: "block_sample",
     description:
-      "List design system blocks visible under current tier and channel configuration.",
+      "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: {
-      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",
+      count: {
+        type: "string",
+        description: "Number of samples (1–5, default 2)",
         optional: true,
       },
       condensed: {
@@ -44,156 +38,30 @@ const specs: readonly ToolSpec[] = [
       },
     },
     readOnly: true,
-    async execute(rt, { allTiers, digest, detailed, condensed }) {
-      const contract = await resolveBlockList(rt, {
-        allTiers: allTiers === true,
-        digest: digest === true,
-        detailed: detailed === 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 = 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 condense(blockSampleFmt.llm({ ...result, nextSteps }));
       }
 
       return {
-        data: contract.result.items,
-        meta: {
-          count: contract.result.items.length,
-          filters: contract.result.filters,
+        data: {
+          samples: result.samples,
+          totalCount: result.totalCount,
+          nextSteps,
         },
+        meta: { count: result.samples.length },
       };
     },
   },
-
-  {
-    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

@@ -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,22 @@ 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: [], meta: { internalErrorCount: 0 } };
+
   // lookupBlock returns BlockDetailed[] (multiple matches per name) — flatten
   const result: LookupResult<BlockDetailed> = {
     results: nested.results.flat(),
-    errors: nested.errors,
+    errors: [...nested.errors, ...globErrors],
+    meta: nested.meta ?? { internalErrorCount: 0 },
   };
 
   return {