@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/shared/types/ontology.ts

@@ -2,49 +2,144 @@
 
 /** Summary of a loaded ontology namespace from `ontology list`. */
 export interface OntologySummary {
-  /** Short prefix alias (e.g., `"ds"`, `"cs"`). */
+  /** Short prefix alias (e.g., `"ds"`), or `""` when none is registered. */
   readonly prefix: string;
   /** Full namespace URI the prefix expands to. */
   readonly namespace: string;
+  /** rdfs:label of the namespace's owl:Ontology header, when declared. */
+  readonly title?: string;
+  /** owl:versionInfo of the namespace's owl:Ontology header, when declared. */
+  readonly version?: string;
   /** Number of OWL/RDFS classes defined in this namespace. */
   readonly classCount: number;
-  /** Number of properties (object + datatype) defined in this namespace. */
-  readonly propertyCount: number;
+  /** Number of object properties (class-to-class relations). */
+  readonly relationCount: number;
+  /** Number of datatype properties (literal-valued attributes). */
+  readonly attributeCount: number;
+  /** Number of SHACL node shapes constraining this namespace. */
+  readonly shapeCount: number;
   readonly anatomyCount: number;
 }
 
-/** A class in an ontology's class hierarchy. */
+/**
+ * A property in an ontology namespace.
+ *
+ * All IRIs are compact (`ds:tier`); the owning {@link OntologyDetailed}
+ * carries the `prefixes` map needed to expand them.
+ */
+export interface OntologyProperty {
+  /** Compact IRI of the property. */
+  readonly iri: string;
+  /** Human-readable label (rdfs:label, falling back to the local name). */
+  readonly label: string;
+  /** Whether this is an object property (links classes) or datatype property (links to literals). */
+  readonly kind: "object" | "datatype";
+  /** Compact IRI of the domain class this property applies to, if declared. */
+  readonly domain?: string;
+  /** Compact IRI of the range class or datatype, if declared. */
+  readonly range?: string;
+  /** Present (true) when the property is an owl:FunctionalProperty. */
+  readonly functional?: true;
+}
+
+/**
+ * A class in an ontology's class hierarchy.
+ *
+ * Classes arrive in deterministic topological order (roots first,
+ * alphabetical among siblings) with their direct properties attached.
+ */
 export interface OntologyClass {
-  /** Full URI of the class. */
-  readonly uri: string;
-  /** Human-readable label (rdfs:label). */
+  /** Compact IRI of the class. */
+  readonly iri: string;
+  /** Human-readable label (rdfs:label, falling back to the local name). */
   readonly label: string;
-  /** URI of the direct superclass, if declared. */
-  readonly superclass?: string;
+  /** Class documentation (rdfs:comment), omitted when absent. */
+  readonly comment?: string;
+  /** Compact IRIs of all direct superclasses (empty for roots). */
+  readonly subClassOf: readonly string[];
+  /** Number of instances typed with this class, omitted when zero. */
+  readonly instances?: number;
+  /** Properties whose rdfs:domain is this class. */
+  readonly properties: readonly OntologyProperty[];
 }
 
-/** A property in an ontology namespace. */
-export interface OntologyProperty {
-  /** Full URI of the property. */
-  readonly uri: string;
-  /** Human-readable label (rdfs:label). */
+/** Summary of a SHACL node shape constraining a class. */
+export interface OntologyConstraint {
+  /** Compact IRI of the sh:NodeShape. */
+  readonly shape: string;
+  /** Compact IRI of the sh:targetClass, if declared. */
+  readonly targetClass?: string;
+  /** Number of sh:property constraints on the shape. */
+  readonly propertyCount: number;
+}
+
+/** owl:Ontology header metadata, when the namespace declares one. */
+export interface OntologyMeta {
+  /** rdfs:label / dcterms:title of the ontology node. */
+  readonly title?: string;
+  /** owl:versionInfo. */
+  readonly version?: string;
+  /** Compact IRIs of owl:imports. */
+  readonly imports?: readonly string[];
+}
+
+/** A ready-to-run SPARQL hint for follow-up querying. */
+export interface OntologyQueryHint {
+  /** What the query answers (e.g. "instances of ds:Component"). */
   readonly label: string;
-  /** URI of the domain class this property applies to, if declared. */
-  readonly domain?: string;
-  /** URI of the range class or datatype, if declared. */
-  readonly range?: string;
-  /** Whether this is an object property (links classes) or datatype property (links to literals). */
-  readonly type: "object" | "datatype";
+  /**
+   * SPARQL using compact IRIs — runnable as-is via `pragma graph query`,
+   * which resolves the store's prefix map.
+   */
+  readonly sparql: string;
 }
 
-/** Detailed view of a single ontology namespace from `ontology show`. */
+/** Deep-dive view of one class, produced by `ontology show <ns> --class <C>`. */
+export interface OntologyClassFocus {
+  /** Compact IRI of the focused class. */
+  readonly iri: string;
+  readonly label: string;
+  readonly comment?: string;
+  /** Superclass chain within the namespace, nearest first. */
+  readonly superChain: readonly string[];
+  /** Compact IRIs of direct subclasses. */
+  readonly subclasses: readonly string[];
+  /** Number of instances typed with this class. */
+  readonly instances: number;
+  /** Properties declared directly on this class. */
+  readonly directProperties: readonly OntologyProperty[];
+  /** Properties inherited from the super chain. */
+  readonly inheritedProperties: readonly OntologyProperty[];
+  /** Properties elsewhere in the namespace whose range is this class. */
+  readonly referencedBy: readonly OntologyProperty[];
+  /** Up to a few instance IRIs, as entry points for `graph inspect` / lookups. */
+  readonly sampleInstances: readonly string[];
+  /** Ready-to-run SPARQL for the natural follow-up questions. */
+  readonly queries: readonly OntologyQueryHint[];
+}
+
+/**
+ * Detailed view of a single ontology namespace from `ontology show`.
+ *
+ * This is the single complete structure every output mode projects:
+ * plain, `--llm`, `--format json`, and the MCP `ontology_show` envelope
+ * all render from this shape and nothing else.
+ */
 export interface OntologyDetailed {
   /** Short prefix alias (e.g., `"ds"`). */
   readonly prefix: string;
   /** Full namespace URI the prefix expands to. */
   readonly namespace: string;
-  /** All classes defined in this namespace. */
+  /** Prefix map covering every compact IRI used in this structure. */
+  readonly prefixes: Readonly<Record<string, string>>;
+  /** owl:Ontology header metadata, omitted when the namespace declares none. */
+  readonly meta?: OntologyMeta;
+  /** All classes, topologically ordered, with direct properties attached. */
   readonly classes: readonly OntologyClass[];
-  /** All properties defined in this namespace. */
-  readonly properties: readonly OntologyProperty[];
+  /** Properties with no domain, or a domain outside this namespace's classes. */
+  readonly unattached: readonly OntologyProperty[];
+  /** SHACL node-shape summaries, omitted when none exist. */
+  readonly constraints?: readonly OntologyConstraint[];
+  /** Per-class deep dive, present when a class filter was requested. */
+  readonly focus?: OntologyClassFocus;
 }

package/src/domains/shared/types/standard.ts

@@ -1,58 +1,15 @@
-/** Standard domain return types. */
+/**
+ * Standard cross-reference type.
+ *
+ * The hand-written standard domain's return types (StandardSummary,
+ * StandardDetailed, CodeBlock, …) were deleted with the domain — the
+ * `standard` noun is served by the bundled story pack, whose rows and
+ * entities are generic string records. Only {@link StandardRef} remains:
+ * block lookups still cross-reference standards by name/URI/category.
+ */
 
 import type { URI } from "@canonical/ke";
 
-/** Summary view of a design-system standard (guideline or rule). */
-export interface StandardSummary {
-  /** Full RDF URI identifying this standard in the ke store. */
-  readonly uri: URI;
-  /** Human-readable name of the standard. */
-  readonly name: string;
-  /** Category grouping (e.g., `"accessibility"`, `"layout"`). */
-  readonly category: string;
-  /** Brief prose description of what the standard prescribes. */
-  readonly description: string;
-  /** URI of the parent standard this one extends, if any. */
-  readonly extends?: string;
-}
-
-/** Digest view of a standard for generic list contracts. */
-export type StandardDigest = StandardSummary;
-
-/** Fenced code block used in standard do/don't examples. */
-export interface CodeBlock {
-  /** Programming language identifier for syntax highlighting. */
-  readonly language: string;
-  /** Source code content of the example. */
-  readonly code: string;
-  /** Optional explanatory caption displayed alongside the code. */
-  readonly caption?: string;
-}
-
-/** Detailed view of a standard, extending the summary with code examples. */
-export interface StandardDetailed extends StandardSummary {
-  /** Positive examples demonstrating correct usage. */
-  readonly dos: readonly CodeBlock[];
-  /** Negative examples demonstrating incorrect usage. */
-  readonly donts: readonly CodeBlock[];
-}
-
-/** Summary of a standards category with its member count. */
-export interface CategorySummary {
-  /** Category name (e.g., `"accessibility"`, `"layout"`). */
-  readonly name: string;
-  /** Number of standards belonging to this category. */
-  readonly standardCount: number;
-}
-
-/** Optional filters for narrowing the standards list. */
-export interface StandardListFilters {
-  /** Restrict results to a single category name. */
-  readonly category?: string;
-  /** Free-text search term matched against standard names and descriptions. */
-  readonly search?: string;
-}
-
 /** Lightweight reference to a standard, used in block cross-references. */
 export interface StandardRef {
   /** Human-readable standard name. */

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

@@ -122,4 +122,12 @@ describe("token lookup command", () => {
     expect(text).toContain("color.primary");
     expect(text).toContain("spacing.sm");
   });
+
+  it("rejects an empty names list with INVALID_INPUT", async () => {
+    const ctx = makeCtx();
+    const cmd = lookupCommand(ctx);
+    await expect(cmd.execute({ names: [] }, ctx)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+    });
+  });
 });

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

@@ -9,6 +9,7 @@ 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,
@@ -20,7 +21,7 @@ import {
   resolveTokenLookup,
 } from "../orchestration/index.js";
 
-const specs: readonly ToolSpec[] = [
+const allSpecs: readonly ToolSpec[] = [
   {
     name: "token_list",
     description:
@@ -192,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/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/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,

package/src/mcp/registerResources.test.ts

@@ -1,7 +1,7 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { createTestMcpClient, createTestStore } from "#testing";
-import { P, PREFIX_MAP } from "../domains/shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP, P } from "../domains/shared/prefixes.js";
 import type { PragmaRuntime } from "../domains/shared/runtime.js";
 import createClientFromRuntime from "../testing/helpers/createTestMcpClient.js";
 import {
@@ -227,7 +227,7 @@ describe("resource listing — capping", () => {
       { length: overflow },
       (_, i) => `ds:widget_${i} a ds:Gadget ; ds:name "Widget ${i}" .`,
     ).join("\n");
-    const ttl = `@prefix ds: <${PREFIX_MAP.ds}> .
+    const ttl = `@prefix ds: <${DEFAULT_PREFIX_MAP.ds}> .
 @prefix owl: <http://www.w3.org/2002/07/owl#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 

package/src/mcp/resources/pickPrimaryType.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { PREFIX_MAP } from "../../domains/shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../domains/shared/prefixes.js";
 import pickPrimaryType from "./pickPrimaryType.js";
 
-const COMPONENT = `${PREFIX_MAP.ds}Component`;
-const BLOCK = `${PREFIX_MAP.ds}Block`;
-const NAMED_INDIVIDUAL = `${PREFIX_MAP.owl}NamedIndividual`;
-const OWL_THING = `${PREFIX_MAP.owl}Thing`;
+const COMPONENT = `${DEFAULT_PREFIX_MAP.ds}Component`;
+const BLOCK = `${DEFAULT_PREFIX_MAP.ds}Block`;
+const NAMED_INDIVIDUAL = `${DEFAULT_PREFIX_MAP.owl}NamedIndividual`;
+const OWL_THING = `${DEFAULT_PREFIX_MAP.owl}Thing`;
 
 describe("pickPrimaryType", () => {
   it("returns null for no types", () => {

package/src/mcp/tools/index.ts

@@ -18,20 +18,26 @@ import { specs as orientationSpecs } from "../../domains/llm/mcp/index.js";
 import { specs as modifierSpecs } from "../../domains/modifier/mcp/index.js";
 import { specs as ontologySpecs } from "../../domains/ontology/mcp/index.js";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
-import { compilePackToolSpecs } from "../../domains/shared/stories/pack/index.js";
+import {
+  compilePackToolSpecs,
+  deriveReservedVerbs,
+  nounVerbFromToolName,
+} from "../../domains/shared/stories/pack/index.js";
 import type { ToolSpec } from "../../domains/shared/ToolSpec.js";
 import { specs as skillSpecs } from "../../domains/skill/mcp/index.js";
-import { specs as standardSpecs } from "../../domains/standard/mcp/index.js";
-import { specs as tierSpecs } from "../../domains/tier/mcp/index.js";
 import { specs as tokenSpecs } from "../../domains/token/mcp/index.js";
 import registerFromSpec from "./registerFromSpec.js";
 
-const allSpecs: readonly ToolSpec[] = [
+/**
+ * The full built-in MCP tool surface, in registration order.
+ *
+ * Exported so tests can derive the reserved-verb map from the identical
+ * array production consumes (see the cross-surface reservation invariant).
+ */
+export const allSpecs: readonly ToolSpec[] = [
   ...blockSpecs,
-  ...standardSpecs,
   ...modifierSpecs,
   ...tokenSpecs,
-  ...tierSpecs,
   ...configSpecs,
   ...ontologySpecs,
   ...graphSpecs,
@@ -56,11 +62,13 @@ export default function registerAllTools(
     registerFromSpec(server, runtime, spec);
   }
 
-  // Story packs project onto the same surface; built-in nouns are reserved.
-  const reservedNouns = new Set(
-    allSpecs.map((spec) => spec.name.split("_").at(0) ?? ""),
+  // Story packs project onto the same surface. Leaf read nouns reserve only
+  // the (noun, verb) pairs they own, so a pack can add a verb no built-in
+  // owns; operational nouns (config, graph, …) stay reserved wholesale.
+  const reserved = deriveReservedVerbs(
+    allSpecs.map((spec) => nounVerbFromToolName(spec.name)),
   );
-  for (const spec of compilePackToolSpecs(runtime, reservedNouns)) {
+  for (const spec of compilePackToolSpecs(runtime, reserved)) {
     registerFromSpec(server, runtime, spec);
   }
 }