@canonical/pragma-cli 0.27.0 → 0.29.0

package/src/mcp/registerResources.ts

@@ -135,6 +135,53 @@ async function listAllSubjects(store: Store): Promise<string[]> {
   return result.bindings.map((b) => b.s ?? "").filter((s) => isUri(s));
 }
 
+const RDFS_LABEL = "http://www.w3.org/2000/01/rdf-schema#label";
+
+/**
+ * Fetch the rdfs:label of the entity's rdf:type class.
+ *
+ * Returns the label of the first typed class that has one, or null.
+ */
+async function fetchTypeLabel(
+  store: Store,
+  fullUri: string,
+): Promise<string | null> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?typeLabel
+      WHERE {
+        <${fullUri}> <${RDF_TYPE}> ?type .
+        ?type <${RDFS_LABEL}> ?typeLabel .
+      }
+      LIMIT 1
+    `),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) return null;
+  return result.bindings[0]?.typeLabel ?? null;
+}
+
+/**
+ * Build a resource description from type label and graph description.
+ *
+ * Produces: "Component — Buttons are used to trigger…" or just "Component"
+ * when no description exists, or just the truncated description when no
+ * type is recognized.
+ */
+function buildResourceDescription(
+  typeLabel: string | null,
+  description: string | null,
+): string | undefined {
+  if (!typeLabel && !description) return undefined;
+  const truncated =
+    description && description.length > 120
+      ? `${description.slice(0, 117)}...`
+      : description;
+  if (!typeLabel) return truncated ?? undefined;
+  if (!truncated) return typeLabel;
+  return `${typeLabel} — ${truncated}`;
+}
+
 /**
  * Read a single entity: all its triples with level-1 object summaries.
  */
@@ -234,17 +281,23 @@ export default function registerResources(
   const { store } = runtime;
   const prefixes = store.prefixes;
 
-  const template = new ResourceTemplate("pragma:{+uri}", {
+  const template = new ResourceTemplate("{+uri}", {
     list: async () => {
       const subjects = await listAllSubjects(store);
       const resources = await Promise.all(
         subjects.map(async (fullUri) => {
           const prefixed = compactUri(fullUri, prefixes);
-          const label = await fetchLabel(store, fullUri, prefixes);
+          const [label, typeLabel, desc] = await Promise.all([
+            fetchLabel(store, fullUri, prefixes),
+            fetchTypeLabel(store, fullUri),
+            fetchDescription(store, fullUri, prefixes),
+          ]);
           return {
-            uri: `pragma:${prefixed}`,
+            uri: prefixed,
             name: label ?? prefixed,
+            description: buildResourceDescription(typeLabel, desc),
             mimeType: "application/json" as const,
+            annotations: { audience: ["assistant" as const] },
           };
         }),
       );
@@ -264,11 +317,7 @@ export default function registerResources(
   server.registerResource(
     "graph-entity",
     template,
-    {
-      description:
-        "An entity in the pragma knowledge graph. Returns all properties with level-1 relation summaries.",
-      mimeType: "application/json",
-    },
+    { mimeType: "application/json" },
     async (url, variables) => {
       try {
         const prefixedUri = variables.uri as string;

package/src/mcp/tools/registerTools.test.ts

@@ -52,9 +52,9 @@ function parseData(result: Record<string, unknown>): unknown {
 // =============================================================================
 
 describe("tool listing", () => {
-  it("registers 25 tools", async () => {
+  it("registers 29 tools", async () => {
     const { tools } = await client.listTools();
-    expect(tools).toHaveLength(25);
+    expect(tools).toHaveLength(29);
   });
 
   it("all tools have descriptions", async () => {
@@ -94,6 +94,11 @@ describe("tool listing", () => {
     expect(names).toContain("doctor");
     expect(names).toContain("info");
     expect(names).toContain("capabilities");
+    // Sample tools
+    expect(names).toContain("block_sample");
+    expect(names).toContain("standard_sample");
+    expect(names).toContain("token_sample");
+    expect(names).toContain("modifier_sample");
   });
 
   it("no tool names contain pragma_ prefix", async () => {
@@ -1020,13 +1025,16 @@ describe("info", () => {
 // =============================================================================
 
 describe("capabilities", () => {
-  it("returns accurate tool list and counts", async () => {
+  it("returns enriched tool catalog with counts", async () => {
     const result = await client.callTool({
       name: "capabilities",
       arguments: {},
     });
     const data = parseData(result) as {
-      tools: string[];
+      version: string;
+      conventions: Record<string, string>;
+      discovery_sequence: { stage: number; tool: string; purpose: string }[];
+      tools: { name: string; category: string; use_when: string }[];
       counts: {
         total: number;
         read: number;
@@ -1034,14 +1042,21 @@ describe("capabilities", () => {
         orientation: number;
         diagnostic: number;
       };
+      limits: Record<string, unknown>;
     };
-    expect(data.tools).toContain("block_list");
-    expect(data.tools).toContain("capabilities");
-    expect(data.counts.total).toBe(25);
+    const toolNames = data.tools.map((t) => t.name);
+    expect(toolNames).toContain("block_list");
+    expect(toolNames).toContain("capabilities");
+    expect(data.tools.every((t) => t.use_when.length > 0)).toBe(true);
+    expect(data.counts.total).toBe(29);
     expect(data.counts.read).toBeGreaterThan(0);
     expect(data.counts.write).toBe(5);
     expect(data.counts.orientation).toBe(2);
     expect(data.counts.diagnostic).toBe(2);
+    expect(data.version).toBeDefined();
+    expect(data.conventions).toBeDefined();
+    expect(data.discovery_sequence.length).toBe(3);
+    expect(data.limits).toBeDefined();
   });
 });
 

package/src/mcp/utils/wrapTool.test.ts

@@ -7,6 +7,7 @@ const stubRuntime = {
   store: {} as PragmaRuntime["store"],
   config: { tier: undefined, channel: "normal" },
   cwd: "/test",
+  packages: [],
   dispose: () => {},
 } as PragmaRuntime;
 

package/src/pipeline/collectCommands.ts

@@ -4,8 +4,12 @@ import { commands as configCommands } from "../domains/config/index.js";
 import { commands as createCommands } from "../domains/create/index.js";
 import { doctorCommand } from "../domains/doctor/commands/index.js";
 import { commands as graphCommands } from "../domains/graph/index.js";
+import { commands as graphqlCommands } from "../domains/graphql/index.js";
 import { infoCommand, upgradeCommand } from "../domains/info/index.js";
-import { buildLlmCommand } from "../domains/llm/index.js";
+import {
+  buildCapabilitiesCommand,
+  buildLlmCommand,
+} from "../domains/llm/index.js";
 import { commands as modifierCommands } from "../domains/modifier/index.js";
 import { commands as ontologyCommands } from "../domains/ontology/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
@@ -38,10 +42,12 @@ export default function collectCommands(
     ...blockCommands(ctx),
     ...ontologyCommands(ctx),
     ...graphCommands(ctx),
+    ...graphqlCommands(),
     ...skillCommands(ctx),
     doctorCommand,
     infoCommand,
     upgradeCommand,
     buildLlmCommand(ctx),
+    buildCapabilitiesCommand(),
   ];
 }

package/src/pipeline/renderError.ts

@@ -43,6 +43,14 @@ function renderErrorPlain(error: PragmaError): string {
     lines.push(`Valid options: ${error.validOptions.join(", ")}`);
   }
 
+  if (error.crossDomain) {
+    lines.push("");
+    lines.push(
+      `"${error.entity?.name ?? ""}" exists as a ${error.crossDomain.entityType}.`,
+    );
+    lines.push(`Run \`${error.crossDomain.cli}\``);
+  }
+
   if (error.recovery) {
     lines.push("");
     if (error.recovery.cli) {
@@ -82,6 +90,12 @@ function renderErrorLlm(error: PragmaError): string {
     lines.push(`Valid options: ${error.validOptions.join(", ")}`);
   }
 
+  if (error.crossDomain) {
+    lines.push(
+      `Cross-domain: "${error.entity?.name ?? ""}" exists as a ${error.crossDomain.entityType}. \`${error.crossDomain.cli}\``,
+    );
+  }
+
   if (error.recovery) {
     if (error.recovery.cli) {
       lines.push(`Recovery: \`${error.recovery.cli}\``);
@@ -106,6 +120,7 @@ function renderErrorJson(error: PragmaError): string {
     entity: error.entity,
     suggestions: error.suggestions,
     recovery: error.recovery,
+    crossDomain: error.crossDomain,
     filters: error.filters,
     validOptions: error.validOptions,
   });

package/src/pipeline/resolveCommandKind.ts

@@ -8,7 +8,14 @@
 import type { CommandKind } from "./types.js";
 
 /** Commands that do not require the ke store to be booted. */
-const STORE_SKIP_COMMANDS = new Set(["setup", "mcp", "update-refs"]);
+const STORE_SKIP_COMMANDS = new Set([
+  "setup",
+  "mcp",
+  "update-refs",
+  "capabilities",
+  "trace",
+  "graphql",
+]);
 
 function findCommandArg(argv: readonly string[]): string | undefined {
   const args = argv.slice(2);

package/src/pipeline/runCli.ts

@@ -1,10 +1,13 @@
 import type { GlobalFlags } from "@canonical/cli-core";
 import { CommanderError } from "commander";
+import { commands as graphqlCommands } from "../domains/graphql/index.js";
+import { buildCapabilitiesCommand } from "../domains/llm/index.js";
 import { commands as refsCommands } from "../domains/refs/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
 import type { PragmaContext } from "../domains/shared/context.js";
 import type { PragmaRuntime } from "../domains/shared/runtime.js";
 import { bootPragma } from "../domains/shared/runtime.js";
+import { commands as traceCommands } from "../domains/trace/index.js";
 import { PragmaError } from "../error/index.js";
 import collectCommands from "./collectCommands.js";
 import createProgram from "./createProgram.js";
@@ -78,6 +81,7 @@ async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
     store: {} as PragmaRuntime["store"],
     config: { tier: undefined, channel: "normal" },
     cwd: process.cwd(),
+    packages: [],
     dispose: () => {},
     globalFlags,
     interactive: runInteractiveCommand,
@@ -137,11 +141,18 @@ async function runStoreSkip(
     store: {} as PragmaRuntime["store"],
     config: { tier: undefined, channel: "normal" },
     cwd: process.cwd(),
+    packages: [],
     dispose: () => {},
     globalFlags,
     interactive: runInteractiveCommand,
   };
-  const commands = [...setupCommands(), ...refsCommands()];
+  const commands = [
+    ...setupCommands(),
+    ...refsCommands(),
+    ...traceCommands(),
+    ...graphqlCommands(),
+    buildCapabilitiesCommand(),
+  ];
   const program = createProgram(commands, stubCtx);
 
   try {

package/src/testing/createTestMcpClient.ts

@@ -37,6 +37,7 @@ export default async function createTestMcpClient(options?: {
     store,
     config,
     cwd,
+    packages: [],
     dispose: () => cleanupStore(),
   };
 

package/src/testing/graphqlFixtures.ts

@@ -0,0 +1,72 @@
+/**
+ * TTL fixtures for graphql domain tests.
+ *
+ * Three compile outcomes: a clean ontology (no diagnostics), an ontology
+ * with an unresolvable field-name collision (M001 error diagnostic, schema
+ * still composes), and an ontology whose reserved `__` field name fails
+ * schema composition entirely (C003 → CompilationError).
+ */
+
+/** Namespace used by all graphql fixtures. */
+export const EX_NAMESPACE = "http://example.org/";
+
+/** `--prefix` entry registering {@link EX_NAMESPACE}. */
+export const EX_PREFIX_ENTRY = `ex=${EX_NAMESPACE}`;
+
+const prefixBlock = `@prefix ex: <${EX_NAMESPACE}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .`;
+
+/** Compiles to `type Thing` with zero diagnostics. */
+export const GRAPHQL_CLEAN_TTL = `${prefixBlock}
+
+ex:Thing a owl:Class ;
+  rdfs:label "Thing" .
+
+ex:name a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string ;
+  rdfs:label "name" .
+
+ex:widget a ex:Thing ;
+  ex:name "Widget" .
+`;
+
+/**
+ * Produces an M001 error diagnostic (three properties collapse to
+ * `Thing.name` and the namespace-prefixed rename collides too), but the
+ * schema still composes — no CompilationError.
+ */
+export const GRAPHQL_ERROR_TTL = `${prefixBlock}
+
+ex:Thing a owl:Class ;
+  rdfs:label "Thing" .
+
+ex:name a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+
+ex:hasName a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+
+ex:isName a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+`;
+
+/**
+ * Fails schema composition (C003): `__bad` survives name sanitization but
+ * `__` is reserved by GraphQL introspection, so compile() throws
+ * CompilationError.
+ */
+export const GRAPHQL_FATAL_TTL = `${prefixBlock}
+
+ex:Thing a owl:Class ;
+  rdfs:label "Thing" .
+
+ex:__bad a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+`;

package/src/testing/index.ts

@@ -3,6 +3,13 @@ export type { CommandResult } from "./cli.js";
 export { runCommand } from "./cli.js";
 export { default as createTestMcpClient } from "./createTestMcpClient.js";
 export { DS_ALL_TTL, DS_ONTOLOGY_TTL, DS_TIERS_TTL } from "./dsFixtures.js";
+export {
+  EX_NAMESPACE,
+  EX_PREFIX_ENTRY,
+  GRAPHQL_CLEAN_TTL,
+  GRAPHQL_ERROR_TTL,
+  GRAPHQL_FATAL_TTL,
+} from "./graphqlFixtures.js";
 export type { PragmaTestStoreOptions } from "./store.js";
 export { createTestStore } from "./store.js";
 export type { TestMcpClientResult } from "./types.js";

package/src/testing/integration/mcp-surface.test.ts

@@ -41,17 +41,23 @@ function parseEnvelope(
 // ---------------------------------------------------------------------------
 
 describe("capabilities", () => {
-  it("returns tool list with counts", async () => {
+  it("returns enriched tool catalog with conventions", async () => {
     const res = await client.callTool({ name: "capabilities", arguments: {} });
     const body = parseEnvelope(res);
     expect(body.ok).toBe(true);
     const data = body.data as {
-      tools: string[];
+      version: string;
+      conventions: Record<string, string>;
+      tools: { name: string; category: string; use_when: string }[];
       counts: Record<string, number>;
     };
-    expect(data.tools).toContain("block_list");
-    expect(data.tools).toContain("capabilities");
-    expect(data.counts.total).toBe(25);
+    const toolNames = data.tools.map((t) => t.name);
+    expect(toolNames).toContain("block_list");
+    expect(toolNames).toContain("capabilities");
+    expect(data.tools.every((t) => t.use_when.length > 0)).toBe(true);
+    expect(data.counts.total).toBe(29);
+    expect(data.conventions).toBeDefined();
+    expect(data.version).toBeDefined();
   });
 });