@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -10,9 +10,11 @@ import {
   createOutputResult,
 } from "@canonical/cli-core";
 import { createLookupView } from "#tui";
+import { PragmaError } from "../../../error/index.js";
 import type { PragmaContext } from "../../shared/context.js";
 import type { LookupResult } from "../../shared/contracts.js";
 import { renderLookupResults } from "../../shared/formatters.js";
+import resolveLookupExitCode from "../../shared/resolveLookupExitCode.js";
 import {
   createLookupFormatters,
   createTokenInkLookupOptions,
@@ -56,6 +58,15 @@ export default function buildLookupCommand(
     },
     async execute(params: Record<string, unknown>) {
       const names = normalizeNames(params.names, params.name);
+      if (names.length === 0) {
+        throw PragmaError.invalidInput("names", "(empty)", {
+          recovery: {
+            message: "List available tokens.",
+            cli: "pragma token list",
+            mcp: { tool: "token_list" },
+          },
+        });
+      }
       const detailed = (params.detailed as boolean) ?? false;
       const contract = await resolveTokenLookup(ctx.store, names);
 
@@ -77,6 +88,7 @@ export default function buildLookupCommand(
               options: createTokenInkLookupOptions({ detailed: isDetailed }),
             }),
         },
+        resolveLookupExitCode(contract.result),
       );
     },
   };

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

@@ -11,6 +11,7 @@ import {
 } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
+import parseSampleCount from "../../shared/parseSampleCount.js";
 import type { SampleOutput, TokenDetailed } from "../../shared/types/index.js";
 import { sampleFormatters } from "../formatters/index.js";
 import { sampleTokens } from "../operations/index.js";
@@ -37,7 +38,7 @@ export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
       examples: ["pragma token sample", "pragma token sample --count 3"],
     },
     async execute(params) {
-      const count = Number(params.count ?? 2);
+      const count = parseSampleCount(params.count);
       const result = await sampleTokens(ctx.store, count);
 
       const output: SampleOutput<TokenDetailed> = {

package/src/domains/token/featureFlag.ts

@@ -0,0 +1,17 @@
+/**
+ * Feature flag for the token *read* surface (`token list`, `token lookup`,
+ * `token sample` and their MCP twins `token_list`, `token_lookup`,
+ * `token_sample`).
+ *
+ * Disabled until token data ships in the semantic packages: the current
+ * `@canonical/design-system` data (bundled and `#main`) contains no token
+ * instances, so every read command returned EMPTY_RESULTS while the docs
+ * and LLM orientation advertised the surface. Flip this to `true` once the
+ * ontology publishes token data — commands, MCP tools, and the LLM
+ * orientation (tool catalog, command reference, decision trees) all key
+ * off this single constant.
+ *
+ * `pragma tokens add-config` is unaffected: it scaffolds Terrazzo config
+ * from package conventions and does not depend on store data.
+ */
+export const TOKEN_READ_SURFACE_ENABLED = false;

package/src/domains/token/index.ts

@@ -14,8 +14,12 @@ import {
   lookupCommand,
   sampleCommand,
 } from "./commands/index.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "./featureFlag.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
+  if (!TOKEN_READ_SURFACE_ENABLED) {
+    return [addConfigCommand()];
+  }
   return [
     listCommand(ctx),
     lookupCommand(ctx),
@@ -24,6 +28,7 @@ export function commands(ctx: PragmaContext): CommandDefinition[] {
   ];
 }
 
+export { TOKEN_READ_SURFACE_ENABLED } from "./featureFlag.js";
 export { specs as mcpSpecs } from "./mcp/index.js";
 export type { AddConfigResult, TokenListFilters } from "./operations/index.js";
 export {

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

@@ -7,7 +7,9 @@
 
 import { writeFileSync } from "node:fs";
 import { PragmaError } from "#error";
+import { lookupToolMeta } from "../../shared/lookupMany.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../featureFlag.js";
 import {
   createLookupFormatters as createTokenLookupFmt,
   listFormatters as tokenListFmt,
@@ -19,7 +21,7 @@ import {
   resolveTokenLookup,
 } from "../orchestration/index.js";
 
-const specs: readonly ToolSpec[] = [
+const allSpecs: readonly ToolSpec[] = [
   {
     name: "token_list",
     description:
@@ -101,7 +103,10 @@ const specs: readonly ToolSpec[] = [
         };
       }
 
-      return { data: result, meta: { count: result.results.length } };
+      return {
+        data: { results: result.results, errors: result.errors },
+        meta: lookupToolMeta(result),
+      };
     },
   },
 
@@ -188,4 +193,15 @@ const specs: readonly ToolSpec[] = [
   },
 ] as const;
 
+/** Token read tools gated by {@link TOKEN_READ_SURFACE_ENABLED}. */
+const TOKEN_READ_TOOLS = new Set([
+  "token_list",
+  "token_lookup",
+  "token_sample",
+]);
+
+const specs: readonly ToolSpec[] = TOKEN_READ_SURFACE_ENABLED
+  ? allSpecs
+  : allSpecs.filter((spec) => !TOKEN_READ_TOOLS.has(spec.name));
+
 export default specs;

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

@@ -18,11 +18,12 @@ export default async function resolveTokenLookup(
   const lookupResult: LookupResult<TokenDetailed> =
     names.length > 0
       ? await lookupMany(names, (query) => lookupToken(store, query))
-      : { results: [], errors: [] };
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
 
   const result: LookupResult<TokenDetailed> = {
     results: lookupResult.results,
     errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
   };
 
   return {

package/src/domains/trace/commands/resolveTraceLimit.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import { resolveTraceLimit } from "./show.js";
+
+describe("resolveTraceLimit", () => {
+  it("defaults to 50 when absent", () => {
+    expect(resolveTraceLimit(undefined)).toBe(50);
+    expect(resolveTraceLimit("")).toBe(50);
+  });
+
+  it("accepts a positive integer", () => {
+    expect(resolveTraceLimit("20")).toBe(20);
+    expect(resolveTraceLimit(" 5 ")).toBe(5);
+  });
+
+  it.each([
+    "notanumber",
+    "-5",
+    "0",
+    "3.5",
+    "1e1",
+    "0x5",
+  ])("rejects the non-positive-integer value %j", (value) => {
+    expect(() => resolveTraceLimit(value)).toThrowError(PragmaError);
+    try {
+      resolveTraceLimit(value);
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+});

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

@@ -9,6 +9,7 @@ import {
   type CommandDefinition,
   createOutputResult,
 } from "@canonical/cli-core";
+import { PragmaError } from "#error";
 import { traceDir } from "../../refs/operations/paths.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import {
@@ -22,6 +23,30 @@ import {
   readTraceLog,
 } from "../operations/index.js";
 
+/** Number of trace records shown when `--limit` is omitted. */
+const DEFAULT_TRACE_LIMIT = 50;
+
+/**
+ * Resolve the `--limit` value into a positive integer record count.
+ *
+ * @param raw - The raw param value.
+ * @returns The default when absent, else the validated positive integer.
+ * @throws PragmaError INVALID_INPUT when present but not a positive integer.
+ */
+export function resolveTraceLimit(raw: unknown): number {
+  if (raw === undefined || raw === null || raw === "") {
+    return DEFAULT_TRACE_LIMIT;
+  }
+  const text = String(raw).trim();
+  const parsed = Number(text);
+  if (!/^\d+$/.test(text) || parsed < 1) {
+    throw PragmaError.invalidInput("limit", String(raw), {
+      recovery: { message: "Provide a positive integer." },
+    });
+  }
+  return parsed;
+}
+
 function formatOneLine(r: import("../types.js").TraceRecord): string {
   const d = new Date(r.ts);
   const time = [
@@ -81,6 +106,10 @@ const showCommand: CommandDefinition = {
     ],
   },
   async execute(params, ctx) {
+    // Validate --limit up front so a bad value is rejected regardless of
+    // whether any sessions exist.
+    const limit = resolveTraceLimit(params.limit);
+
     const dir = traceDir();
     const sessions = listSessions(dir);
 
@@ -129,10 +158,7 @@ const showCommand: CommandDefinition = {
       return createOutputResult("", { plain: () => "" });
     }
 
-    // Normal mode — read and format
-    const limit =
-      typeof params.limit === "string" ? Number.parseInt(params.limit, 10) : 50;
-
+    // Normal mode — read and format (limit validated at the top of execute).
     const records = readTraceLog({ path: target.path, limit });
     const data = { sessionId: target.sessionId, records };
 

package/src/domains/trace/tracePlugin.test.ts

@@ -152,7 +152,7 @@ describe("createTracePlugin", () => {
 
     // bindings should be at most 2 (may be 0 with empty store)
     expect(record.bindings).toBeDefined();
-    expect(record.bindings!.length).toBeLessThanOrEqual(2);
+    expect(record.bindings?.length).toBeLessThanOrEqual(2);
   });
 
   it("generates a session ID when not provided", async () => {

package/src/index.ts

@@ -43,8 +43,6 @@ export type {
   BlockDetailed,
   BlockDigest,
   BlockSummary,
-  CategorySummary,
-  CodeBlock,
   Disclosure,
   FilterConfig,
   InspectResult,
@@ -54,10 +52,7 @@ export type {
   OntologyProperty,
   OntologySummary,
   PredicateGroup,
-  StandardDetailed,
-  StandardListFilters,
   StandardRef,
-  StandardSummary,
   TierEntry,
   TokenDetailed,
   TokenRef,
@@ -90,18 +85,11 @@ export {
   showOntology,
   showOntologyRaw,
 } from "./domains/ontology/operations/index.js";
+export { listTiers } from "./domains/shared/listTiers.js";
 export {
   discoverSkills,
   listSkills,
 } from "./domains/skill/operations/index.js";
-export {
-  listCategories,
-  listStandards,
-  lookupStandard,
-  resolveStandardList,
-  resolveStandardLookup,
-} from "./domains/standard/index.js";
-export { listTiers } from "./domains/tier/operations/index.js";
 export {
   listTokens,
   lookupToken,