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

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

@@ -0,0 +1,171 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStore, sparql } from "@canonical/ke";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createTracePlugin } from "./tracePlugin.js";
+import type { TraceRecord } from "./types.js";
+
+describe("createTracePlugin", () => {
+  let traceDir: string;
+
+  beforeEach(() => {
+    traceDir = mkdtempSync(join(tmpdir(), "pragma-trace-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(traceDir, { recursive: true, force: true });
+  });
+
+  it("records SELECT queries as NDJSON", async () => {
+    const plugin = createTracePlugin({
+      traceDir,
+      sessionId: "test-session",
+    });
+
+    const store = await createStore({
+      sources: [],
+      plugins: [plugin],
+    });
+
+    await store.query(sparql`SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5`);
+
+    store.dispose();
+
+    const logPath = join(traceDir, "test-session.ndjson");
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.trim().split("\n");
+
+    expect(lines.length).toBe(1);
+
+    const record = JSON.parse(lines[0]) as TraceRecord;
+    expect(record.sid).toBe("test-session");
+    expect(record.seq).toBe(0);
+    expect(record.type).toBe("select");
+    expect(record.qh).toMatch(/^[0-9a-f]{8}$/);
+    expect(record.ms).toBeGreaterThanOrEqual(0);
+    expect(record.vars).toBeDefined();
+    expect(record.count).toBeGreaterThanOrEqual(0);
+    expect(record.bindings).toBeDefined();
+  });
+
+  it("records ASK queries", async () => {
+    const plugin = createTracePlugin({
+      traceDir,
+      sessionId: "test-ask",
+    });
+
+    const store = await createStore({
+      sources: [],
+      plugins: [plugin],
+    });
+
+    await store.query(
+      sparql`ASK { <http://example.org/x> <http://example.org/p> <http://example.org/y> }`,
+    );
+
+    store.dispose();
+
+    const logPath = join(traceDir, "test-ask.ndjson");
+    const content = readFileSync(logPath, "utf-8");
+    const record = JSON.parse(content.trim()) as TraceRecord;
+
+    expect(record.type).toBe("ask");
+    expect(record.count).toBe(1);
+    expect(record.ask).toBe(false);
+  });
+
+  it("increments seq across queries", async () => {
+    const plugin = createTracePlugin({
+      traceDir,
+      sessionId: "test-seq",
+    });
+
+    const store = await createStore({
+      sources: [],
+      plugins: [plugin],
+    });
+
+    await store.query(sparql`SELECT ?s WHERE { ?s ?p ?o } LIMIT 1`);
+    await store.query(sparql`SELECT ?p WHERE { ?s ?p ?o } LIMIT 1`);
+    await store.query(sparql`SELECT ?o WHERE { ?s ?p ?o } LIMIT 1`);
+
+    store.dispose();
+
+    const logPath = join(traceDir, "test-seq.ndjson");
+    const content = readFileSync(logPath, "utf-8");
+    const records = content
+      .trim()
+      .split("\n")
+      .map((l) => JSON.parse(l) as TraceRecord);
+
+    expect(records).toHaveLength(3);
+    expect(records[0].seq).toBe(0);
+    expect(records[1].seq).toBe(1);
+    expect(records[2].seq).toBe(2);
+  });
+
+  it("exposes TraceApi via store.api()", async () => {
+    const plugin = createTracePlugin({
+      traceDir,
+      sessionId: "test-api",
+    });
+
+    const store = await createStore({
+      sources: [],
+      plugins: [plugin],
+    });
+
+    const api = store.api<import("./types.js").TraceApi>("trace");
+    expect(api).toBeDefined();
+    expect(api?.sessionId).toBe("test-api");
+    expect(api?.logPath).toBe(join(traceDir, "test-api.ndjson"));
+    expect(api?.queryCount).toBe(0);
+
+    await store.query(sparql`SELECT ?s WHERE { ?s ?p ?o } LIMIT 1`);
+    expect(api?.queryCount).toBe(1);
+
+    store.dispose();
+  });
+
+  it("caps bindings at maxBindings", async () => {
+    const plugin = createTracePlugin({
+      traceDir,
+      sessionId: "test-cap",
+      maxBindings: 2,
+    });
+
+    const store = await createStore({
+      sources: [],
+      plugins: [plugin],
+    });
+
+    // Load some data so we get results
+    // Even with empty store, the record should respect the cap
+    await store.query(sparql`SELECT ?s ?p ?o WHERE { ?s ?p ?o }`);
+
+    store.dispose();
+
+    const logPath = join(traceDir, "test-cap.ndjson");
+    const content = readFileSync(logPath, "utf-8");
+    const record = JSON.parse(content.trim()) as TraceRecord;
+
+    // bindings should be at most 2 (may be 0 with empty store)
+    expect(record.bindings).toBeDefined();
+    expect(record.bindings!.length).toBeLessThanOrEqual(2);
+  });
+
+  it("generates a session ID when not provided", async () => {
+    const plugin = createTracePlugin({ traceDir });
+
+    const store = await createStore({
+      sources: [],
+      plugins: [plugin],
+    });
+
+    const api = store.api<import("./types.js").TraceApi>("trace");
+    expect(api?.sessionId).toMatch(/^\d{8}-\d{6}-[0-9a-f]{4}$/);
+
+    store.dispose();
+  });
+});

package/src/domains/trace/tracePlugin.ts

@@ -0,0 +1,159 @@
+/**
+ * KE plugin for query access tracing.
+ *
+ * Intercepts `onQuery` and `onResult` hooks to record every
+ * `store.query()` call as an NDJSON line in a session-scoped log file.
+ *
+ * Activation: conditional — only instantiated when `PRAGMA_TRACE=1` or
+ * `trace: true` in pragma.config.json.
+ * Correlation: closure variable `pending` — safe because KE calls
+ * `onQuery` → Oxigraph WASM (sync) → `onResult` with no interleaving.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { definePlugin } from "@canonical/ke";
+import type { TraceApi, TracePluginOptions, TraceRecord } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// FNV-1a 32-bit hash
+// ---------------------------------------------------------------------------
+
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+
+function fnv1a(input: string): string {
+  let hash = FNV_OFFSET;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// ---------------------------------------------------------------------------
+// Session ID generation
+// ---------------------------------------------------------------------------
+
+function generateSessionId(): string {
+  const now = new Date();
+  const date = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+  ].join("");
+  const time = [
+    String(now.getHours()).padStart(2, "0"),
+    String(now.getMinutes()).padStart(2, "0"),
+    String(now.getSeconds()).padStart(2, "0"),
+  ].join("");
+  const rand = Math.random().toString(16).slice(2, 6);
+  return `${date}-${time}-${rand}`;
+}
+
+// ---------------------------------------------------------------------------
+// Record builder
+// ---------------------------------------------------------------------------
+
+function buildRecord(
+  sessionId: string,
+  seq: number,
+  sparql: string,
+  startMs: number,
+  result: import("@canonical/ke").QueryResult,
+  maxBindings: number,
+): TraceRecord {
+  const ms = Math.round((performance.now() - startMs) * 100) / 100;
+  const qh = fnv1a(sparql);
+
+  const base = {
+    ts: new Date().toISOString(),
+    sid: sessionId,
+    seq,
+    qh,
+    q: sparql,
+    ms,
+  };
+
+  switch (result.type) {
+    case "select":
+      return {
+        ...base,
+        type: "select",
+        count: result.bindings.length,
+        vars: result.variables,
+        bindings: result.bindings.slice(0, maxBindings),
+      };
+    case "construct":
+      return {
+        ...base,
+        type: "construct",
+        count: result.triples.length,
+        triples: result.triples.slice(0, maxBindings).map((t) => ({
+          s: t.subject,
+          p: t.predicate,
+          o: t.object,
+        })),
+      };
+    case "ask":
+      return {
+        ...base,
+        type: "ask",
+        count: 1,
+        ask: result.result,
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin factory
+// ---------------------------------------------------------------------------
+
+export function createTracePlugin(options: TracePluginOptions) {
+  const maxBindings = options.maxBindings ?? 200;
+  const sessionId = options.sessionId ?? generateSessionId();
+  const logPath = join(options.traceDir, `${sessionId}.ndjson`);
+
+  let seq = 0;
+  let pendingQuery: string | undefined;
+  let pendingStart: number | undefined;
+
+  return definePlugin<TraceApi>({
+    name: "trace",
+
+    onReady() {
+      mkdirSync(options.traceDir, { recursive: true });
+      return {
+        sessionId,
+        logPath,
+        get queryCount() {
+          return seq;
+        },
+      };
+    },
+
+    onQuery(sparql) {
+      pendingQuery = sparql;
+      pendingStart = performance.now();
+      return undefined;
+    },
+
+    onResult(result) {
+      if (pendingQuery !== undefined && pendingStart !== undefined) {
+        const record = buildRecord(
+          sessionId,
+          seq,
+          pendingQuery,
+          pendingStart,
+          result,
+          maxBindings,
+        );
+        appendFileSync(logPath, `${JSON.stringify(record)}\n`);
+        seq++;
+        pendingQuery = undefined;
+        pendingStart = undefined;
+      }
+      return undefined;
+    },
+  });
+}

package/src/domains/trace/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Types for query access tracing.
+ *
+ * One NDJSON record per `store.query()` call. The trace plugin writes
+ * these to session-scoped log files; the CLI reads them back.
+ */
+
+/** A single trace record — one per store.query() call. */
+export interface TraceRecord {
+  /** ISO-8601 timestamp. */
+  ts: string;
+  /** Session identifier. */
+  sid: string;
+  /** Monotonic query index within the session. */
+  seq: number;
+  /** FNV-1a hash of the query string (8 hex chars). */
+  qh: string;
+  /** SPARQL query string (after prefix expansion). */
+  q: string;
+  /** Execution duration in milliseconds. */
+  ms: number;
+  /** Result type discriminant. */
+  type: "select" | "construct" | "ask";
+  /** True result count (bindings / triples / 1). */
+  count: number;
+  /** SELECT variable names. */
+  vars?: string[];
+  /** SELECT result rows (capped at maxBindings). */
+  bindings?: Record<string, string>[];
+  /** CONSTRUCT triples (capped at maxBindings). */
+  triples?: { s: string; p: string; o: string }[];
+  /** ASK result. */
+  ask?: boolean;
+}
+
+/** API exposed via `store.api<TraceApi>("trace")`. */
+export interface TraceApi {
+  readonly sessionId: string;
+  readonly logPath: string;
+  readonly queryCount: number;
+}
+
+/** Options for creating the trace plugin. */
+export interface TracePluginOptions {
+  /** Directory for trace log files. */
+  traceDir: string;
+  /** Session identifier (generated if omitted). */
+  sessionId?: string;
+  /** Max bindings/triples to record per query. Default: 200. */
+  maxBindings?: number;
+}
+
+/** A trace session on disk. */
+export interface TraceSession {
+  /** Session identifier (derived from filename). */
+  sessionId: string;
+  /** Absolute path to the NDJSON file. */
+  path: string;
+  /** Number of query records in the file. */
+  queryCount: number;
+  /** File size in bytes. */
+  sizeBytes: number;
+  /** File creation time. */
+  createdAt: Date;
+}

package/src/error/PragmaError.ts

@@ -1,4 +1,9 @@
-import type { ErrorCode, PragmaErrorData, Recovery } from "./types.js";
+import type {
+  CrossDomainRecovery,
+  ErrorCode,
+  PragmaErrorData,
+  Recovery,
+} from "./types.js";
 
 /**
  * Structured error for all pragma domain operations.
@@ -16,6 +21,8 @@ class PragmaError extends Error {
   readonly suggestions: string[];
   /** Structured recovery hint with optional CLI command or MCP tool call. */
   readonly recovery: Recovery | undefined;
+  /** Cross-domain redirect when name exists in another domain. */
+  readonly crossDomain: CrossDomainRecovery | undefined;
   /** Active filters at the time of the error, for diagnostic context. */
   readonly filters: Record<string, string> | undefined;
   /** Enumerated valid options when input was rejected. */
@@ -31,6 +38,7 @@ class PragmaError extends Error {
     this.entity = data.entity;
     this.suggestions = data.suggestions ?? [];
     this.recovery = data.recovery;
+    this.crossDomain = data.crossDomain;
     this.filters = data.filters;
     this.validOptions = data.validOptions;
   }
@@ -49,6 +57,7 @@ class PragmaError extends Error {
     opts: {
       suggestions?: string[];
       recovery?: Recovery;
+      crossDomain?: CrossDomainRecovery;
     } = {},
   ): PragmaError {
     return new PragmaError({
@@ -57,6 +66,7 @@ class PragmaError extends Error {
       entity: { type: entityType, name: entityName },
       suggestions: opts.suggestions,
       recovery: opts.recovery,
+      crossDomain: opts.crossDomain,
     });
   }
 
@@ -70,15 +80,18 @@ class PragmaError extends Error {
   static emptyResults(
     entityType: string,
     opts: {
+      message?: string;
       filters?: Record<string, string>;
       recovery?: Recovery;
+      validOptions?: string[];
     } = {},
   ): PragmaError {
     return new PragmaError({
       code: "EMPTY_RESULTS",
-      message: `No ${entityType}s found.`,
+      message: opts.message ?? `No ${entityType}s found.`,
       filters: opts.filters,
       recovery: opts.recovery,
+      validOptions: opts.validOptions,
     });
   }
 

package/src/error/types.ts

@@ -20,6 +20,18 @@ interface Recovery {
   mcp?: { tool: string; params?: Record<string, unknown> };
 }
 
+/** Hint pointing the user/agent to a different domain when a name exists there. */
+interface CrossDomainRecovery {
+  /** Domain where the name was found (e.g., "modifier"). */
+  domain: string;
+  /** Entity type label for messages. */
+  entityType: string;
+  /** CLI command to run. */
+  cli: string;
+  /** MCP tool invocation. */
+  mcp: { tool: string; params: Record<string, unknown> };
+}
+
 /** Raw data payload used to construct a PragmaError. */
 interface PragmaErrorData {
   /** Machine-readable error classification. */
@@ -32,10 +44,12 @@ interface PragmaErrorData {
   suggestions?: string[];
   /** Recovery hint for CLI and MCP adapters. */
   recovery?: Recovery;
+  /** Cross-domain redirect when name exists in another domain. */
+  crossDomain?: CrossDomainRecovery;
   /** Active filters at the time of the error. */
   filters?: Record<string, string>;
   /** Enumerated valid options when input was rejected. */
   validOptions?: string[];
 }
 
-export type { ErrorCode, PragmaErrorData, Recovery };
+export type { CrossDomainRecovery, ErrorCode, PragmaErrorData, Recovery };

package/src/mcp/error/serializeErrorPayload.ts

@@ -21,6 +21,13 @@ export default function serializeErrorPayload(
     message: error.message,
     ...(error.suggestions.length > 0 && { suggestions: error.suggestions }),
     ...(recovery && { recovery }),
+    ...(error.crossDomain && {
+      crossDomain: {
+        domain: error.crossDomain.domain,
+        tool: error.crossDomain.mcp.tool,
+        params: error.crossDomain.mcp.params,
+      },
+    }),
     ...(error.filters && { filters: error.filters }),
     ...(error.validOptions && { validOptions: error.validOptions }),
   };

package/src/mcp/error/types.ts

@@ -28,11 +28,19 @@ export interface McpRecovery {
  * Structured MCP error payload embedded in tool response content.
  * Returned as JSON text content with `isError: true`.
  */
+/** Cross-domain redirect hint for agents. */
+export interface McpCrossDomainHint {
+  readonly domain: string;
+  readonly tool: string;
+  readonly params: Record<string, unknown>;
+}
+
 export interface McpErrorPayload {
   readonly code: ErrorCode;
   readonly message: string;
   readonly suggestions?: readonly string[];
   readonly recovery?: McpRecovery;
+  readonly crossDomain?: McpCrossDomainHint;
   readonly filters?: Record<string, string>;
   readonly validOptions?: readonly string[];
 }

package/src/mcp/registerResources.test.ts

@@ -35,38 +35,60 @@ describe("resource listing", () => {
   it("registers 1 resource template", async () => {
     const { resourceTemplates } = await client.listResourceTemplates();
     expect(resourceTemplates).toHaveLength(1);
-    expect(resourceTemplates[0]?.uriTemplate).toBe("pragma:{+uri}");
+    expect(resourceTemplates[0]?.uriTemplate).toBe("{+uri}");
   });
 
   it("lists resources including known entities", async () => {
     const { resources } = await client.listResources();
     const uris = resources.map((r) => r.uri);
-    expect(uris).toContain(`pragma:${P.ds}global.component.button`);
-    expect(uris).toContain(`pragma:${P.ds}global.component.card`);
-    expect(uris).toContain(`pragma:${P.ds}global`);
+    expect(uris).toContain(`${P.ds}global.component.button`);
+    expect(uris).toContain(`${P.ds}global.component.card`);
+    expect(uris).toContain(`${P.ds}global`);
   });
 
   it("lists OWL classes as resources", async () => {
     const { resources } = await client.listResources();
     const uris = resources.map((r) => r.uri);
-    expect(uris).toContain(`pragma:${P.ds}UIBlock`);
-    expect(uris).toContain(`pragma:${P.ds}Component`);
+    expect(uris).toContain(`${P.ds}UIBlock`);
+    expect(uris).toContain(`${P.ds}Component`);
   });
 
   it("lists code standards as resources", async () => {
     const { resources } = await client.listResources();
     const uris = resources.map((r) => r.uri);
-    expect(uris).toContain(`pragma:${P.cs}react_folder`);
-    expect(uris).toContain(`pragma:${P.cs}code_purity`);
+    expect(uris).toContain(`${P.cs}react_folder`);
+    expect(uris).toContain(`${P.cs}code_purity`);
   });
 
   it("uses label as resource name when available", async () => {
     const { resources } = await client.listResources();
     const button = resources.find(
-      (r) => r.uri === `pragma:${P.ds}global.component.button`,
+      (r) => r.uri === `${P.ds}global.component.button`,
     );
     expect(button?.name).toBe("Button");
   });
+
+  it("includes type-aware description for components", async () => {
+    const { resources } = await client.listResources();
+    const button = resources.find(
+      (r) => r.uri === `${P.ds}global.component.button`,
+    );
+    expect(button?.description).toMatch(/^Component/);
+  });
+
+  it("includes type-aware description for code standards", async () => {
+    const { resources } = await client.listResources();
+    const standard = resources.find((r) => r.uri === `${P.cs}code_purity`);
+    expect(standard?.description).toMatch(/^Code Standard/);
+  });
+
+  it("marks resources with assistant audience", async () => {
+    const { resources } = await client.listResources();
+    const button = resources.find(
+      (r) => r.uri === `${P.ds}global.component.button`,
+    );
+    expect(button?.annotations?.audience).toEqual(["assistant"]);
+  });
 });
 
 // =============================================================================
@@ -76,7 +98,7 @@ describe("resource listing", () => {
 describe("read component instance", () => {
   it("returns entity with types and label", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.ds}global.component.button`,
+      uri: `${P.ds}global.component.button`,
     });
     const entity = parseContents(result) as {
       uri: string;
@@ -92,7 +114,7 @@ describe("read component instance", () => {
 
   it("resolves level-1 URI objects to summaries", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.ds}global.component.button`,
+      uri: `${P.ds}global.component.button`,
     });
     const entity = parseContents(result) as {
       properties: {
@@ -117,7 +139,7 @@ describe("read component instance", () => {
 
   it("includes literal values", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.ds}global.component.button`,
+      uri: `${P.ds}global.component.button`,
     });
     const entity = parseContents(result) as {
       properties: {
@@ -142,7 +164,7 @@ describe("read component instance", () => {
 describe("read OWL class", () => {
   it("returns class with rdfs:label", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.ds}UIBlock`,
+      uri: `${P.ds}UIBlock`,
     });
     const entity = parseContents(result) as {
       types: string[];
@@ -167,7 +189,7 @@ describe("read OWL class", () => {
 describe("read code standard", () => {
   it("returns standard with properties", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.cs}code_purity`,
+      uri: `${P.cs}code_purity`,
     });
     const entity = parseContents(result) as {
       types: string[];
@@ -202,7 +224,7 @@ describe("read code standard", () => {
 describe("read tier", () => {
   it("returns tier with name", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.ds}apps_lxd`,
+      uri: `${P.ds}apps_lxd`,
     });
     const entity = parseContents(result) as {
       types: string[];
@@ -227,7 +249,7 @@ describe("read tier", () => {
 describe("error handling", () => {
   it("returns text/plain error for unknown entity", async () => {
     const result = await client.readResource({
-      uri: `pragma:${P.ds}nonexistent`,
+      uri: `${P.ds}nonexistent`,
     });
     const first = result.contents[0] as ResourceContent;
     expect(first.mimeType).toBe("text/plain");