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

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

@@ -1,5 +1,6 @@
-/** @module Re-exports standard operations (`listCategories`, `getStandard`, `listStandards`). */
+/** @module Re-exports standard operations (`listCategories`, `listStandards`, `lookupStandard`, `sampleStandards`). */
 
 export { default as listCategories } from "./categories.js";
 export { default as listStandards } from "./list.js";
 export { default as lookupStandard } from "./lookup.js";
+export { default as sampleStandards } from "./sample.js";

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

@@ -18,6 +18,11 @@ import resolveUri from "../../graph/helpers/resolveUri.js";
 import { buildQuery } from "../../shared/buildQuery.js";
 import compactUri from "../../shared/compactUri.js";
 import { P } from "../../shared/prefixes.js";
+import {
+  detectCrossDomain,
+  listDomainNames,
+  suggestNames,
+} from "../../shared/suggestions/index.js";
 import type { CodeBlock, StandardDetailed } from "../../shared/types/index.js";
 
 export default async function lookupStandard(
@@ -52,12 +57,16 @@ export default async function lookupStandard(
   );
 
   if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
+    const candidates = await listDomainNames(store, "standard");
+    const crossDomain = await detectCrossDomain(nameOrUri, "standard", store);
     throw PragmaError.notFound("standard", nameOrUri, {
+      suggestions: suggestNames(nameOrUri, candidates),
       recovery: {
         message: "List available standards.",
         cli: "pragma standard list",
         mcp: { tool: "standard_list" },
       },
+      crossDomain: crossDomain ?? undefined,
     });
   }
 

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

@@ -0,0 +1,35 @@
+/**
+ * Returns a small number of complete standard 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 count - number of samples (clamped 1–5, default 2)
+ * @returns sample result with detailed standards and total count
+ * @note Queries ke store
+ */
+
+import type { Store } from "@canonical/ke";
+import pickRandom from "../../shared/pickRandom.js";
+import type {
+  SampleResult,
+  StandardDetailed,
+} from "../../shared/types/index.js";
+import listStandards from "./list.js";
+import lookupStandard from "./lookup.js";
+
+export default async function sampleStandards(
+  store: Store,
+  count = 2,
+): Promise<SampleResult<StandardDetailed>> {
+  const clamped = Math.max(1, Math.min(5, count));
+  const all = await listStandards(store);
+  const selected = pickRandom(all, clamped);
+
+  const samples = await Promise.all(
+    selected.map((s) => lookupStandard(store, s.name)),
+  );
+
+  return { samples, totalCount: all.length };
+}

package/src/domains/standard/orchestration/resolveStandardLookup.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 { StandardDetailed } from "../../shared/types/index.js";
 import { lookupStandard } from "../operations/index.js";
 
@@ -8,11 +9,23 @@ export default async function resolveStandardLookup(
   store: Pick<PragmaRuntime, "store">["store"],
   queries: readonly string[],
 ): Promise<LookupContract<StandardDetailed>> {
-  const result: LookupResult<StandardDetailed> = await lookupMany(
+  const { names, globErrors } = await expandLookupQueries(
     queries,
-    (query) => lookupStandard(store, query),
+    store,
+    "standard",
   );
 
+  const lookupResult: LookupResult<StandardDetailed> =
+    names.length > 0
+      ? await lookupMany(names, (query) => lookupStandard(store, query))
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
+
+  const result: LookupResult<StandardDetailed> = {
+    results: lookupResult.results,
+    errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
+  };
+
   return {
     params: { names: queries },
     result,

package/src/domains/standard/orchestration/standardEmptyError.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import standardEmptyError from "./standardEmptyError.js";
+
+describe("standardEmptyError", () => {
+  it("filter-narrowing: a category/search was active → clear filters and re-list", () => {
+    const err = standardEmptyError({ category: "react", search: "fold" });
+
+    expect(err.filters).toEqual({ category: "react", search: "fold" });
+    expect(err.recovery).toEqual({
+      message: "List all standards without filters.",
+      cli: "pragma standard list",
+      mcp: { tool: "standard_list" },
+    });
+  });
+
+  it("store-empty: no filter active → install, not a self-looping list", () => {
+    const err = standardEmptyError({});
+
+    expect(err.filters).toBeUndefined();
+    // Must NOT suggest `pragma standard list` again — that just re-returns empty.
+    expect(err.recovery).toEqual({
+      message: "Install the code standards packages that provide standards.",
+      cli: "bun add -D @canonical/code-standards",
+    });
+    expect(err.recovery?.mcp).toBeUndefined();
+  });
+
+  it("install branch cites the code-standards package", () => {
+    const err = standardEmptyError({});
+    expect(err.recovery?.cli).toContain("@canonical/code-standards");
+    expect(err.recovery?.cli).not.toContain("ds-global");
+  });
+});

package/src/domains/standard/orchestration/standardEmptyError.ts

@@ -7,13 +7,23 @@ export default function standardEmptyError(
   const active: Record<string, string> = {};
   if (filters.category) active.category = filters.category;
   if (filters.search) active.search = filters.search;
+  const hasFilter = Object.keys(active).length > 0;
 
   return PragmaError.emptyResults("standard", {
-    filters: Object.keys(active).length > 0 ? active : undefined,
-    recovery: {
-      message: "List all standards without filters.",
-      cli: "pragma standard list",
-      mcp: { tool: "standard_list" },
-    },
+    filters: hasFilter ? active : undefined,
+    recovery: hasFilter
+      ? {
+          // Filter-narrowing: clear the active category/search and re-list.
+          message: "List all standards without filters.",
+          cli: "pragma standard list",
+          mcp: { tool: "standard_list" },
+        }
+      : {
+          // Store-empty with no filter active: suggesting `standard list`
+          // again would just re-return empty, so route to the install.
+          message:
+            "Install the code standards packages that provide standards.",
+          cli: "bun add -D @canonical/code-standards",
+        },
   });
 }

package/src/domains/standard/stories.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { standardListStory, standardLookupStory } from "./stories.js";
+
+describe("standardListStory", () => {
+  it("renders the ink list view", () => {
+    const view = standardListStory.renderInk?.({
+      items: [],
+      details: undefined,
+      disclosure: { level: "summary" },
+    });
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Standards");
+  });
+});
+
+describe("standardLookupStory", () => {
+  it("renders the ink lookup view", () => {
+    const view = standardLookupStory.renderInk?.(
+      { results: [], errors: [] },
+      { surface: "cli", detailed: false, params: {} },
+    );
+    expect(typeof view).toBe("string");
+  });
+});

package/src/domains/standard/stories.ts

@@ -0,0 +1,151 @@
+/**
+ * Standard read stories — the single declaration of `standard list` and
+ * `standard lookup` for both surfaces.
+ *
+ * The story kernel compiles these into the CLI commands and MCP tools,
+ * so descriptions, parameters, resolution, and rendering live here once.
+ */
+
+import { createListView, createLookupView } from "#tui";
+import type { LookupStory, ReadStory } from "../shared/stories/index.js";
+import type { StandardDetailed } from "../shared/types/index.js";
+import {
+  createInkLookupOptions,
+  listFormatters,
+  lookupFormatters,
+  type StandardListOutput,
+  type StandardLookupInput,
+} from "./formatters/index.js";
+import {
+  resolveStandardList,
+  resolveStandardLookup,
+} from "./orchestration/index.js";
+import { standardConfig } from "./standardConfig.js";
+import type { StandardListResolution } from "./types.js";
+
+/** The `standard list` / `standard_list` read story. */
+export const standardListStory: ReadStory<
+  StandardListResolution,
+  StandardListOutput
+> = {
+  noun: "standard",
+  verb: "list",
+  description: "List all code standards",
+  toolDescription:
+    "List code standards. Optionally filter by category or search term. Use digest/detailed for progressive disclosure.",
+  params: [
+    {
+      name: "category",
+      type: "string",
+      description: "Filter by category",
+      toolDescription: "Filter by category name",
+    },
+    {
+      name: "search",
+      type: "string",
+      description: "Search in name and description",
+    },
+    {
+      name: "digest",
+      type: "boolean",
+      description: "Show description and first example for each standard",
+      default: false,
+    },
+    {
+      name: "detailed",
+      type: "boolean",
+      description: "Show full dos/donts for each standard",
+      default: false,
+    },
+  ],
+  examples: [
+    "pragma standard list",
+    "pragma standard list --category react",
+    'pragma standard list --search "folder"',
+    "pragma standard list --digest",
+    "pragma standard list --detailed",
+    "pragma standard list --llm",
+  ],
+  resolve: (rt, params) =>
+    resolveStandardList(rt, {
+      category: params.category as string | undefined,
+      search: params.search as string | undefined,
+      digest: params.digest === true,
+      detailed: params.detailed === true,
+    }),
+  toOutput: (resolution) => ({
+    items: resolution.items,
+    details: resolution.details,
+    disclosure: resolution.disclosure,
+  }),
+  formatters: listFormatters,
+  toEnvelope: (resolution) => {
+    if (resolution.disclosure.level === "summary") {
+      return {
+        data: resolution.items,
+        meta: { count: resolution.items.length },
+      };
+    }
+    const output: StandardListOutput = {
+      items: resolution.items,
+      details: resolution.details,
+      disclosure: resolution.disclosure,
+    };
+    return {
+      data: JSON.parse(listFormatters.json(output)),
+      meta: {
+        count: resolution.items.length,
+        disclosure: resolution.disclosure.level,
+      },
+    };
+  },
+  renderInk: (output) =>
+    createListView({
+      heading: "Standards",
+      domain: "standard",
+      items: output.items,
+      columns: standardConfig.listColumns,
+    }),
+};
+
+/** The `standard lookup` / `standard_lookup` read story. */
+export const standardLookupStory: LookupStory<
+  StandardDetailed,
+  StandardLookupInput
+> = {
+  noun: "standard",
+  description: "Look up detailed information for a standard by name or IRI",
+  toolDescription:
+    "Get detailed information about one or more code standards including dos and donts with code examples.",
+  namesDescription: "Standard names or IRIs",
+  namesToolDescription: "Standard names or IRIs to look up",
+  detailedParam: {
+    description: "Include dos and donts with code blocks",
+    toolDescription:
+      "Return full details with dos/donts (default: true for MCP)",
+  },
+  examples: [
+    "pragma standard lookup react/component/folder-structure",
+    "pragma standard lookup react/component/folder-structure react/component/props",
+    "pragma standard lookup react/component/folder-structure --detailed",
+    "pragma standard lookup react/component/folder-structure --llm",
+    "pragma standard lookup cs:react_props",
+  ],
+  resolve: async (rt, names) => {
+    const contract = await resolveStandardLookup(rt.store, names);
+    return contract.result;
+  },
+  toFmtInput: (standard, view) => ({ standard, detailed: view.detailed }),
+  formatters: lookupFormatters,
+  project: (standard) => {
+    const { uri, name, category, description } = standard;
+    return { uri, name, category, description };
+  },
+  renderInk: (result, view) =>
+    createLookupView({
+      results: result.results,
+      errors: result.errors,
+      domain: "standard",
+      options: createInkLookupOptions(view.detailed),
+    }),
+};

package/src/domains/tier/commands/list.ts

@@ -1,59 +1,9 @@
-/**
- * Wires the `pragma tier list` CLI command.
- *
- * Lists all tiers defined in the design system ontology. Throws a
- * structured recovery error when no tiers are found.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { ColumnDef } from "../../shared/contracts.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import type { TierEntry } from "../../shared/types/tier.js";
-import { listFormatters } from "../formatters/index.js";
-import { listTiers } from "../operations/index.js";
-
-const tierListColumns: readonly ColumnDef<TierEntry>[] = [
-  { key: "uri", label: "IRI" },
-  { key: "path", label: "Path" },
-  { key: "parent", label: "Parent" },
-];
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { tierListStory } from "../stories.js";
 
+/** Wire the `pragma tier list` CLI command from the tier list story. */
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["tier", "list"],
-    description: "List all tiers in the design system ontology",
-    parameters: [],
-    meta: {
-      examples: ["pragma tier list", "pragma tier list --llm"],
-    },
-    async execute() {
-      const tiers = await listTiers(ctx.store);
-
-      if (tiers.length === 0) {
-        throw PragmaError.emptyResults("tier", {
-          recovery: {
-            message:
-              "Ensure design system packages are installed: bun add -D @canonical/ds-global",
-          },
-        });
-      }
-
-      return createOutputResult(tiers, {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Tiers",
-            domain: "tier",
-            items: data,
-            columns: tierListColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, tierListStory);
 }

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

@@ -1,38 +1,12 @@
 /**
- * MCP tool specs for the tier domain.
+ * MCP tool specs for the tier domain — tier_list, compiled from the tier
+ * read story in `../stories.ts`.
  */
 
+import { compileReadTool } from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { listFormatters as tierListFmt } from "../formatters/index.js";
-import { listTiers } from "../operations/index.js";
+import { tierListStory } from "../stories.js";
 
-const specs: readonly ToolSpec[] = [
-  {
-    name: "tier_list",
-    description: "List all tiers in the design system ontology with hierarchy.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const result = await listTiers(rt.store);
-
-      if (condensed) {
-        const text = tierListFmt.llm(result);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.length } };
-    },
-  },
-];
+const specs: readonly ToolSpec[] = [compileReadTool(tierListStory)];
 
 export default specs;

package/src/domains/tier/stories.test.ts

@@ -0,0 +1,22 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import { tierListStory } from "./stories.js";
+
+const tier = {
+  uri: "https://ds.example/global" as URI,
+  path: "global",
+  depth: 0,
+};
+
+describe("tierListStory", () => {
+  it("renders the ink list view", () => {
+    const view = tierListStory.renderInk?.([tier]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Tiers");
+  });
+
+  it("rejects only empty results", () => {
+    expect(tierListStory.emptyError?.([], {})).toBeDefined();
+    expect(tierListStory.emptyError?.([tier], {})).toBeUndefined();
+  });
+});

package/src/domains/tier/stories.ts

@@ -0,0 +1,52 @@
+/**
+ * Tier read story — the single declaration of `tier list` for both
+ * surfaces.
+ *
+ * The story kernel compiles this into the CLI command and MCP tool,
+ * so description, resolution, and rendering live here once.
+ */
+
+import { PragmaError } from "#error";
+import { createListView } from "#tui";
+import type { ColumnDef } from "../shared/contracts.js";
+import type { ReadStory } from "../shared/stories/index.js";
+import type { TierEntry } from "../shared/types/index.js";
+import { listFormatters } from "./formatters/index.js";
+import { listTiers } from "./operations/index.js";
+
+const tierListColumns: readonly ColumnDef<TierEntry>[] = [
+  { key: "uri", label: "IRI" },
+  { key: "path", label: "Path" },
+  { key: "parent", label: "Parent" },
+];
+
+/** The `tier list` / `tier_list` read story. */
+export const tierListStory: ReadStory<TierEntry[], TierEntry[]> = {
+  noun: "tier",
+  verb: "list",
+  description: "List all tiers in the design system ontology",
+  toolDescription:
+    "List all tiers in the design system ontology with hierarchy.",
+  params: [],
+  examples: ["pragma tier list", "pragma tier list --llm"],
+  resolve: (rt) => listTiers(rt.store),
+  toOutput: (tiers) => tiers,
+  formatters: listFormatters,
+  toEnvelope: (tiers) => ({ data: tiers, meta: { count: tiers.length } }),
+  emptyError: (tiers) =>
+    tiers.length === 0
+      ? PragmaError.emptyResults("tier", {
+          recovery: {
+            message:
+              "Ensure semantic packages are resolvable — run `pragma doctor` to inspect package refs.",
+          },
+        })
+      : undefined,
+  renderInk: (tiers) =>
+    createListView({
+      heading: "Tiers",
+      domain: "tier",
+      items: tiers,
+      columns: tierListColumns,
+    }),
+};

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

@@ -1,5 +1,6 @@
-/** @module Re-exports token command builders (`addConfig`, `get`, `list`). */
+/** @module Re-exports token command builders (`addConfig`, `list`, `lookup`, `sample`). */
 
 export { default as addConfigCommand } from "./add-config.js";
 export { default as listCommand } from "./list.js";
 export { default as lookupCommand } from "./lookup.js";
+export { default as sampleCommand } from "./sample.js";

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

@@ -0,0 +1,53 @@
+/**
+ * Wires the `pragma token sample` CLI command.
+ *
+ * Returns 1–5 complete token 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 { SampleOutput, TokenDetailed } from "../../shared/types/index.js";
+import { sampleFormatters } from "../formatters/index.js";
+import { sampleTokens } from "../operations/index.js";
+
+const NEXT_STEPS = [
+  "Use token_lookup to inspect specific tokens by name.",
+  "Use token_list to see all available tokens with filtering.",
+];
+
+export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["token", "sample"],
+    description:
+      "Return randomly selected complete token 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 token sample", "pragma token sample --count 3"],
+    },
+    async execute(params) {
+      const count = Number(params.count ?? 2);
+      const result = await sampleTokens(ctx.store, count);
+
+      const output: SampleOutput<TokenDetailed> = {
+        ...result,
+        nextSteps: NEXT_STEPS,
+      };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx, sampleFormatters),
+      });
+    },
+  };
+}

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

@@ -1,7 +1,8 @@
-/** @module Re-exports token formatters (`createLookupFormatters`, `listFormatters`). */
+/** @module Re-exports token formatters (`createLookupFormatters`, `listFormatters`, `sampleFormatters`). */
 
 export { default as listFormatters } from "./list.js";
 export {
   createInkLookupOptions as createTokenInkLookupOptions,
   default as createLookupFormatters,
 } from "./lookup.js";
+export { default as sampleFormatters } from "./sample.js";

package/src/domains/token/formatters/sample.ts

@@ -0,0 +1,16 @@
+/**
+ * Sample formatter for the token domain.
+ *
+ * Delegates to the shared factory, rendering each item via the
+ * existing token lookup formatter with full detail.
+ */
+
+import createSampleFormatters from "../../shared/sampleFormatters.js";
+import type { TokenDetailed } from "../../shared/types/index.js";
+import createLookupFormatters from "./lookup.js";
+
+const lookupFmt = createLookupFormatters({ detailed: true });
+
+export default createSampleFormatters<TokenDetailed>("tokens", (token, mode) =>
+  lookupFmt[mode](token),
+);

package/src/domains/token/index.ts

@@ -12,10 +12,16 @@ import {
   addConfigCommand,
   listCommand,
   lookupCommand,
+  sampleCommand,
 } from "./commands/index.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx), addConfigCommand()];
+  return [
+    listCommand(ctx),
+    lookupCommand(ctx),
+    addConfigCommand(),
+    sampleCommand(ctx),
+  ];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
@@ -24,6 +30,7 @@ export {
   listTokens,
   lookupToken,
   resolveAddConfig,
+  sampleTokens,
 } from "./operations/index.js";
 export {
   resolveTokenList,