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

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

@@ -7,12 +7,14 @@
 
 import { writeFileSync } from "node:fs";
 import { PragmaError } from "#error";
+import { lookupToolMeta } from "../../shared/lookupMany.js";
 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,
@@ -100,7 +102,10 @@ const specs: readonly ToolSpec[] = [
         };
       }
 
-      return { data: result, meta: { count: result.results.length } };
+      return {
+        data: { results: result.results, errors: result.errors },
+        meta: lookupToolMeta(result),
+      };
     },
   },
 
@@ -140,6 +145,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,23 @@ 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: [], meta: { internalErrorCount: 0 } };
+
+  const result: LookupResult<TokenDetailed> = {
+    results: lookupResult.results,
+    errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
+  };
+
   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;

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

@@ -0,0 +1,145 @@
+/**
+ * Wires the `pragma trace` CLI command.
+ *
+ * Shows query trace records from the latest (or specified) session.
+ * Supports `--follow` / `-f` for real-time tailing.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { traceDir } from "../../refs/operations/paths.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import {
+  noSessionsFormatters,
+  sessionNotFoundFormatters,
+  showFormatters,
+} from "../formatters/index.js";
+import {
+  followTraceLog,
+  listSessions,
+  readTraceLog,
+} from "../operations/index.js";
+
+function formatOneLine(r: import("../types.js").TraceRecord): string {
+  const d = new Date(r.ts);
+  const time = [
+    String(d.getHours()).padStart(2, "0"),
+    String(d.getMinutes()).padStart(2, "0"),
+    String(d.getSeconds()).padStart(2, "0"),
+  ].join(":");
+  const type = r.type.toUpperCase().padEnd(10);
+  // Match the non-follow formatter: ASK → true/false, CONSTRUCT → triples,
+  // SELECT (and anything else) → rows.
+  const plural = (n: number, word: string) =>
+    `${n} ${word}${n !== 1 ? "s" : ""}`;
+  const count = (
+    r.type === "ask"
+      ? r.ask
+        ? "true"
+        : "false"
+      : r.type === "construct"
+        ? plural(r.count, "triple")
+        : plural(r.count, "row")
+  ).padEnd(12);
+  const ms = `${r.ms}ms`.padEnd(9);
+  const q = r.q.replace(/\s+/g, " ").trim();
+  const query = q.length > 100 ? `${q.slice(0, 97)}...` : q;
+  return `#${String(r.seq).padEnd(4)} ${time}  ${type}${count}${ms} ${r.qh}  ${query}`;
+}
+
+const showCommand: CommandDefinition = {
+  path: ["trace"],
+  description: "View query access traces",
+  parameters: [
+    {
+      name: "follow",
+      description: "Tail the log in real time",
+      type: "boolean",
+      short: "f",
+      default: false,
+    },
+    {
+      name: "session",
+      description: "Session ID to view (default: latest)",
+      type: "string",
+    },
+    {
+      name: "limit",
+      description: "Maximum number of records to show",
+      type: "string",
+      default: "50",
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma trace",
+      "pragma trace -f",
+      "pragma trace --limit 20",
+      "pragma trace --session 20260512-143022-a7f3",
+    ],
+  },
+  async execute(params, ctx) {
+    const dir = traceDir();
+    const sessions = listSessions(dir);
+
+    if (sessions.length === 0) {
+      return createOutputResult(undefined, {
+        plain: selectFormatter(ctx, noSessionsFormatters),
+      });
+    }
+
+    const sessionId =
+      typeof params.session === "string"
+        ? params.session
+        : sessions[0]?.sessionId;
+    const target = sessions.find((s) => s.sessionId === sessionId);
+
+    if (!target) {
+      return createOutputResult(
+        {
+          requested: sessionId ?? "(unknown)",
+          available: sessions.map((s) => s.sessionId),
+        },
+        { plain: selectFormatter(ctx, sessionNotFoundFormatters) },
+      );
+    }
+
+    // Follow mode — stream new records to stdout and block
+    if (params.follow === true) {
+      process.stdout.write(
+        `Following session ${target.sessionId} (ctrl+c to stop)\n\n`,
+      );
+
+      const stop = followTraceLog(target.path, (record) => {
+        process.stdout.write(`${formatOneLine(record)}\n`);
+      });
+
+      // Block until interrupted
+      await new Promise<void>((resolve) => {
+        const handler = () => {
+          stop();
+          resolve();
+        };
+        process.once("SIGINT", handler);
+        process.once("SIGTERM", handler);
+      });
+
+      return createOutputResult("", { plain: () => "" });
+    }
+
+    // Normal mode — read and format
+    const limit =
+      typeof params.limit === "string" ? Number.parseInt(params.limit, 10) : 50;
+
+    const records = readTraceLog({ path: target.path, limit });
+    const data = { sessionId: target.sessionId, records };
+
+    return createOutputResult(data, {
+      plain: selectFormatter(ctx, showFormatters),
+    });
+  },
+};
+
+export default showCommand;

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

@@ -0,0 +1,9 @@
+/** @module Re-exports trace formatters. */
+
+export { default as sessionsFormatters } from "./sessions.js";
+export {
+  default as showFormatters,
+  noSessionsFormatters,
+  type ShowData,
+  sessionNotFoundFormatters,
+} from "./show.js";

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

@@ -0,0 +1,80 @@
+/**
+ * Three-mode formatter for `pragma trace sessions` output.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { TraceSession } from "../types.js";
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatAge(date: Date): string {
+  const diffMs = Date.now() - date.getTime();
+  const seconds = Math.floor(diffMs / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+const formatters: Formatters<TraceSession[]> = {
+  plain: (sessions) => {
+    if (sessions.length === 0) {
+      return "No trace sessions found.";
+    }
+
+    const lines: string[] = [];
+    const hdr = {
+      sid: "SESSION",
+      queries: "QUERIES",
+      size: "SIZE",
+      age: "AGE",
+    };
+    const sidW = Math.max(
+      hdr.sid.length,
+      ...sessions.map((s) => s.sessionId.length),
+    );
+
+    lines.push(
+      `${hdr.sid.padEnd(sidW)}  ${hdr.queries.padStart(7)}  ${hdr.size.padStart(8)}  ${hdr.age}`,
+    );
+
+    for (const s of sessions) {
+      lines.push(
+        `${s.sessionId.padEnd(sidW)}  ${String(s.queryCount).padStart(7)}  ${formatSize(s.sizeBytes).padStart(8)}  ${formatAge(s.createdAt)}`,
+      );
+    }
+
+    return lines.join("\n");
+  },
+
+  llm: (sessions) => {
+    if (sessions.length === 0) {
+      return "No trace sessions found.";
+    }
+
+    const lines: string[] = [];
+    lines.push("## Trace Sessions");
+    lines.push("");
+    lines.push("| Session | Queries | Size | Age |");
+    lines.push("|---------|---------|------|-----|");
+
+    for (const s of sessions) {
+      lines.push(
+        `| ${s.sessionId} | ${s.queryCount} | ${formatSize(s.sizeBytes)} | ${formatAge(s.createdAt)} |`,
+      );
+    }
+
+    return lines.join("\n");
+  },
+
+  json: (sessions) => JSON.stringify(sessions, null, 2),
+};
+
+export default formatters;