@canonical/pragma-cli 0.27.0 → 0.29.0

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,22 @@ 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: [] };
+
+  const result: LookupResult<StandardDetailed> = {
+    results: lookupResult.results,
+    errors: [...lookupResult.errors, ...globErrors],
+  };
+
   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/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,

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

@@ -11,8 +11,9 @@ import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
   createLookupFormatters as createTokenLookupFmt,
   listFormatters as tokenListFmt,
+  sampleFormatters as tokenSampleFmt,
 } from "../formatters/index.js";
-import { resolveAddConfig } from "../operations/index.js";
+import { resolveAddConfig, sampleTokens } from "../operations/index.js";
 import {
   resolveTokenList,
   resolveTokenLookup,
@@ -140,6 +141,51 @@ const specs: readonly ToolSpec[] = [
       };
     },
   },
+  {
+    name: "token_sample",
+    description:
+      "Return 1–5 randomly selected complete token 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 result = await sampleTokens(rt.store, n);
+      const nextSteps = [
+        `These are ${result.samples.length} of ${result.totalCount} total tokens.`,
+        "Use token_lookup to inspect specific tokens by name.",
+        "Use token_list with category param to filter by type.",
+      ];
+
+      if (condensed) {
+        const text = tokenSampleFmt.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/token/operations/index.ts

@@ -1,7 +1,8 @@
-/** @module Re-exports token operations and types (`resolveAddConfig`, `getToken`, `listTokens`). */
+/** @module Re-exports token operations and types (`resolveAddConfig`, `listTokens`, `lookupToken`, `sampleTokens`). */
 
 export type { AddConfigResult } from "./add-config.js";
 export { default as resolveAddConfig } from "./add-config.js";
 export type { TokenListFilters } from "./list.js";
 export { default as listTokens } from "./list.js";
 export { default as lookupToken } from "./lookup.js";
+export { default as sampleTokens } from "./sample.js";

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

@@ -15,6 +15,11 @@ import { escapeSparqlValue } from "@canonical/ke";
 import { PragmaError } from "#error";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
+import {
+  detectCrossDomain,
+  listDomainNames,
+  suggestNames,
+} from "../../shared/suggestions/index.js";
 import type { TokenDetailed } from "../../shared/types/index.js";
 
 export default async function lookupToken(
@@ -41,12 +46,16 @@ export default async function lookupToken(
   );
 
   if (result.type !== "select" || result.bindings.length === 0) {
+    const candidates = await listDomainNames(store, "token");
+    const crossDomain = await detectCrossDomain(name, "token", store);
     throw PragmaError.notFound("token", name, {
+      suggestions: suggestNames(name, candidates),
       recovery: {
         message: "List available tokens.",
         cli: "pragma token list",
         mcp: { tool: "token_list" },
       },
+      crossDomain: crossDomain ?? undefined,
     });
   }
 

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

@@ -0,0 +1,32 @@
+/**
+ * Returns a small number of complete token 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 tokens and total count
+ * @note Queries ke store
+ */
+
+import type { Store } from "@canonical/ke";
+import pickRandom from "../../shared/pickRandom.js";
+import type { SampleResult, TokenDetailed } from "../../shared/types/index.js";
+import listTokens from "./list.js";
+import lookupToken from "./lookup.js";
+
+export default async function sampleTokens(
+  store: Store,
+  count = 2,
+): Promise<SampleResult<TokenDetailed>> {
+  const clamped = Math.max(1, Math.min(5, count));
+  const all = await listTokens(store);
+  const selected = pickRandom(all, clamped);
+
+  const samples = await Promise.all(
+    selected.map((t) => lookupToken(store, t.name)),
+  );
+
+  return { samples, totalCount: all.length };
+}

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

package/src/domains/token/orchestration/tokenEmptyError.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import tokenEmptyError from "./tokenEmptyError.js";
+
+describe("tokenEmptyError", () => {
+  it("filter-narrowing: a category was active → clear it and re-list", () => {
+    const err = tokenEmptyError("color");
+
+    expect(err.filters).toEqual({ category: "color" });
+    expect(err.recovery).toEqual({
+      message: "List all tokens without category filter.",
+      cli: "pragma token list",
+      mcp: { tool: "token_list" },
+    });
+  });
+
+  it("store-empty: no category active → runnable install, no mcp retry", () => {
+    const err = tokenEmptyError();
+
+    expect(err.filters).toBeUndefined();
+    expect(err.recovery).toEqual({
+      message: "Install the design system packages that provide tokens.",
+      cli: "bun add -D @canonical/design-system",
+    });
+    // No mcp: re-calling token_list on an absent store returns empty again.
+    expect(err.recovery?.mcp).toBeUndefined();
+  });
+
+  it("install branch cites a real default package, not @canonical/ds-global", () => {
+    const err = tokenEmptyError();
+    expect(err.recovery?.cli).toContain("@canonical/design-system");
+    expect(err.recovery?.cli).not.toContain("ds-global");
+  });
+});

package/src/domains/token/orchestration/tokenEmptyError.ts

@@ -5,13 +5,16 @@ export default function tokenEmptyError(category?: string): PragmaError {
     filters: category ? { category } : undefined,
     recovery: category
       ? {
+          // Filter-narrowing: a category was active — clear it and re-list.
           message: "List all tokens without category filter.",
           cli: "pragma token list",
           mcp: { tool: "token_list" },
         }
       : {
-          message:
-            "Ensure design system packages are installed: bun add -D @canonical/ds-global",
+          // Store-empty: no category was active, so the token-supplying
+          // packages are absent. No mcp retry — re-listing returns empty.
+          message: "Install the design system packages that provide tokens.",
+          cli: "bun add -D @canonical/design-system",
         },
   });
 }

package/src/domains/trace/commands/clear.ts

@@ -0,0 +1,71 @@
+/**
+ * Wires the `pragma trace clear` CLI command.
+ *
+ * Deletes all trace log files.
+ */
+
+import { readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { traceDir } from "../../refs/operations/paths.js";
+
+const clearCommand: CommandDefinition = {
+  path: ["trace", "clear"],
+  description: "Delete all trace log files",
+  parameters: [
+    {
+      name: "yes",
+      description: "Skip confirmation",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  meta: {
+    examples: ["pragma trace clear", "pragma trace clear --yes"],
+  },
+  async execute(params) {
+    const dir = traceDir();
+
+    let entries: string[];
+    try {
+      entries = readdirSync(dir).filter((e) => e.endsWith(".ndjson"));
+    } catch {
+      return createOutputResult("No trace directory found.\n", {
+        plain: (s) => s,
+      });
+    }
+
+    if (entries.length === 0) {
+      return createOutputResult("No trace files to delete.\n", {
+        plain: (s) => s,
+      });
+    }
+
+    if (params.yes !== true) {
+      return createOutputResult(
+        `Would delete ${entries.length} trace file${entries.length !== 1 ? "s" : ""}. Pass --yes to confirm.\n`,
+        { plain: (s) => s },
+      );
+    }
+
+    let deleted = 0;
+    for (const entry of entries) {
+      try {
+        unlinkSync(join(dir, entry));
+        deleted++;
+      } catch {
+        // Skip files we can't delete
+      }
+    }
+
+    return createOutputResult(
+      `Deleted ${deleted} trace file${deleted !== 1 ? "s" : ""}.\n`,
+      { plain: (s) => s },
+    );
+  },
+};
+
+export default clearCommand;

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

@@ -0,0 +1,5 @@
+/** @module Re-exports trace command builders. */
+
+export { default as clearCommand } from "./clear.js";
+export { default as sessionsCommand } from "./sessions.js";
+export { default as showCommand } from "./show.js";

package/src/domains/trace/commands/sessions.ts

@@ -0,0 +1,32 @@
+/**
+ * Wires the `pragma trace sessions` CLI command.
+ *
+ * Lists all available trace sessions with metadata.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { traceDir } from "../../refs/operations/paths.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { sessionsFormatters } from "../formatters/index.js";
+import { listSessions } from "../operations/index.js";
+
+const sessionsCommand: CommandDefinition = {
+  path: ["trace", "sessions"],
+  description: "List available trace sessions",
+  parameters: [],
+  meta: {
+    examples: ["pragma trace sessions"],
+  },
+  async execute(_params, ctx) {
+    const sessions = listSessions(traceDir());
+
+    return createOutputResult(sessions, {
+      plain: selectFormatter(ctx, sessionsFormatters),
+    });
+  },
+};
+
+export default sessionsCommand;