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

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

@@ -0,0 +1,122 @@
+/**
+ * Three-mode formatter for `pragma trace` output.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { TraceRecord } from "../types.js";
+
+export interface ShowData {
+  sessionId: string;
+  records: TraceRecord[];
+}
+
+function formatTime(isoString: string): string {
+  const d = new Date(isoString);
+  return [
+    String(d.getHours()).padStart(2, "0"),
+    String(d.getMinutes()).padStart(2, "0"),
+    String(d.getSeconds()).padStart(2, "0"),
+  ].join(":");
+}
+
+function formatResultSummary(record: TraceRecord): string {
+  switch (record.type) {
+    case "select":
+      return `${record.count} row${record.count !== 1 ? "s" : ""}`;
+    case "construct":
+      return `${record.count} triple${record.count !== 1 ? "s" : ""}`;
+    case "ask":
+      return record.ask ? "true" : "false";
+  }
+}
+
+function totalDuration(records: TraceRecord[]): string {
+  const total = records.reduce((sum, r) => sum + r.ms, 0);
+  if (total < 1000) return `${Math.round(total)}ms`;
+  return `${(total / 1000).toFixed(1)}s`;
+}
+
+function truncateQuery(query: string, maxLen = 120): string {
+  // Collapse whitespace for display
+  const collapsed = query.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= maxLen) return collapsed;
+  return `${collapsed.slice(0, maxLen - 3)}...`;
+}
+
+const formatters: Formatters<ShowData> = {
+  plain: ({ sessionId, records }) => {
+    if (records.length === 0) {
+      return `Session ${sessionId}  (no queries)`;
+    }
+
+    const lines: string[] = [];
+    lines.push(
+      `Session ${sessionId}  (${records.length} quer${records.length === 1 ? "y" : "ies"}, ${totalDuration(records)})`,
+    );
+    lines.push("");
+
+    for (const r of records) {
+      const seqStr = `#${r.seq}`.padEnd(5);
+      const time = formatTime(r.ts);
+      const type = r.type.toUpperCase().padEnd(10);
+      const summary = formatResultSummary(r).padEnd(12);
+      const ms = `${r.ms}ms`.padEnd(9);
+
+      lines.push(`${seqStr} ${time}  ${type}${summary}${ms} ${r.qh}`);
+      lines.push(`      ${truncateQuery(r.q)}`);
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  },
+
+  llm: ({ sessionId, records }) => {
+    if (records.length === 0) {
+      return `## Trace: ${sessionId}\n\nNo queries recorded.`;
+    }
+
+    const lines: string[] = [];
+    lines.push(
+      `## Trace: ${sessionId} (${records.length} queries, ${totalDuration(records)})`,
+    );
+    lines.push("");
+    lines.push("| # | Type | Count | ms | Hash | Query |");
+    lines.push("|---|------|-------|----|------|-------|");
+
+    for (const r of records) {
+      lines.push(
+        `| ${r.seq} | ${r.type} | ${formatResultSummary(r)} | ${r.ms} | ${r.qh} | \`${truncateQuery(r.q, 80)}\` |`,
+      );
+    }
+
+    return lines.join("\n");
+  },
+
+  json: ({ sessionId, records }) =>
+    JSON.stringify({ sessionId, records }, null, 2),
+};
+
+/** Formatters for the "no trace sessions exist yet" state (all three modes). */
+export const noSessionsFormatters: Formatters<void> = {
+  plain: () =>
+    "No trace sessions found.\n\nEnable tracing: PRAGMA_TRACE=1 pragma <command>\n                 or: pragma config trace on",
+  llm: () =>
+    "No trace sessions found. Enable tracing with `PRAGMA_TRACE=1 pragma <command>` or `pragma config trace on`.",
+  json: () =>
+    JSON.stringify({ sessions: [], hint: "enable tracing to record queries" }),
+};
+
+/** Formatters for the "requested session does not exist" state (all three modes). */
+export const sessionNotFoundFormatters: Formatters<{
+  requested: string;
+  available: string[];
+}> = {
+  plain: ({ requested, available }) =>
+    `Session not found: ${requested}\n\nAvailable sessions: ${available.join(", ")}`,
+  llm: ({ requested, available }) =>
+    `Session not found: \`${requested}\`. Available sessions: ${available.map((s) => `\`${s}\``).join(", ")}.`,
+  json: ({ requested, available }) =>
+    JSON.stringify({ error: "session_not_found", requested, available }),
+};
+
+export default formatters;

package/src/domains/trace/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @module Trace domain — CLI commands for query access tracing.
+ *
+ * Commands: `pragma trace`, `pragma trace sessions`, `pragma trace clear`.
+ * Plugin: {@link createTracePlugin} (wired in bootStore when PRAGMA_TRACE=1).
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import {
+  clearCommand,
+  sessionsCommand,
+  showCommand,
+} from "./commands/index.js";
+
+export function commands(): CommandDefinition[] {
+  return [showCommand, sessionsCommand, clearCommand];
+}

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

@@ -0,0 +1,8 @@
+/** @module Re-exports trace operations. */
+
+export { listSessions } from "./listSessions.js";
+export {
+  followTraceLog,
+  type ReadTraceLogOptions,
+  readTraceLog,
+} from "./readTraceLog.js";

package/src/domains/trace/operations/listSessions.test.ts

@@ -0,0 +1,55 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { listSessions } from "./listSessions.js";
+
+describe("listSessions", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-trace-sessions-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns empty array for nonexistent directory", () => {
+    const result = listSessions("/nonexistent/path");
+    expect(result).toEqual([]);
+  });
+
+  it("returns empty array for empty directory", () => {
+    const result = listSessions(dir);
+    expect(result).toEqual([]);
+  });
+
+  it("lists .ndjson files as sessions", () => {
+    writeFileSync(join(dir, "20260512-143022-a7f3.ndjson"), '{"seq":0}\n');
+    writeFileSync(
+      join(dir, "20260512-140100-b8e2.ndjson"),
+      '{"seq":0}\n{"seq":1}\n',
+    );
+    // Non-ndjson file should be ignored
+    writeFileSync(join(dir, "notes.txt"), "ignore me");
+
+    const result = listSessions(dir);
+
+    expect(result).toHaveLength(2);
+    // Sorted newest first
+    expect(result[0].sessionId).toBe("20260512-143022-a7f3");
+    expect(result[1].sessionId).toBe("20260512-140100-b8e2");
+    expect(result[0].queryCount).toBe(1);
+    expect(result[1].queryCount).toBe(2);
+    expect(result[0].sizeBytes).toBeGreaterThan(0);
+  });
+
+  it("ignores non-ndjson files", () => {
+    writeFileSync(join(dir, "readme.md"), "# traces");
+    writeFileSync(join(dir, ".hidden"), "secret");
+
+    const result = listSessions(dir);
+    expect(result).toEqual([]);
+  });
+});

package/src/domains/trace/operations/listSessions.ts

@@ -0,0 +1,52 @@
+/**
+ * List available trace sessions from the trace directory.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { TraceSession } from "../types.js";
+
+export function listSessions(traceDir: string): TraceSession[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(traceDir);
+  } catch {
+    return [];
+  }
+
+  const sessions: TraceSession[] = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".ndjson")) continue;
+
+    const sessionId = entry.replace(/\.ndjson$/, "");
+    const filePath = join(traceDir, entry);
+
+    try {
+      const stat = statSync(filePath);
+      // Count records by counting newline bytes on the raw Buffer. Each NDJSON
+      // record is one newline-terminated line, so this avoids decoding the
+      // whole file to a string and allocating a large split() array.
+      const buf = readFileSync(filePath);
+      let lineCount = 0;
+      for (let i = 0; i < buf.length; i++) {
+        if (buf[i] === 0x0a) lineCount++;
+      }
+
+      sessions.push({
+        sessionId,
+        path: filePath,
+        queryCount: lineCount,
+        sizeBytes: stat.size,
+        createdAt: stat.birthtime,
+      });
+    } catch {
+      // Skip files we can't stat/read
+    }
+  }
+
+  // Sort by session ID descending (newest first — IDs are timestamp-based)
+  sessions.sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+
+  return sessions;
+}

package/src/domains/trace/operations/readTraceLog.test.ts

@@ -0,0 +1,100 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { TraceRecord } from "../types.js";
+import { readTraceLog } from "./readTraceLog.js";
+
+function makeRecord(seq: number): TraceRecord {
+  return {
+    ts: new Date().toISOString(),
+    sid: "test-session",
+    seq,
+    qh: "abcd1234",
+    q: `SELECT ?x WHERE { ?x ?p ?o } LIMIT ${seq + 1}`,
+    ms: seq * 1.5,
+    type: "select",
+    count: seq + 1,
+    vars: ["x"],
+    bindings: [{ x: `http://example.org/${seq}` }],
+  };
+}
+
+describe("readTraceLog", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-trace-read-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("parses NDJSON records", () => {
+    const path = join(dir, "test.ndjson");
+    const records = [makeRecord(0), makeRecord(1), makeRecord(2)];
+    writeFileSync(path, records.map((r) => JSON.stringify(r)).join("\n"));
+
+    const result = readTraceLog({ path });
+
+    expect(result).toHaveLength(3);
+    expect(result[0].seq).toBe(0);
+    expect(result[1].seq).toBe(1);
+    expect(result[2].seq).toBe(2);
+  });
+
+  it("returns empty array for missing file", () => {
+    const result = readTraceLog({ path: join(dir, "nonexistent.ndjson") });
+    expect(result).toEqual([]);
+  });
+
+  it("skips malformed lines", () => {
+    const path = join(dir, "malformed.ndjson");
+    writeFileSync(
+      path,
+      [
+        JSON.stringify(makeRecord(0)),
+        "not json",
+        JSON.stringify(makeRecord(1)),
+      ].join("\n"),
+    );
+
+    const result = readTraceLog({ path });
+
+    expect(result).toHaveLength(2);
+    expect(result[0].seq).toBe(0);
+    expect(result[1].seq).toBe(1);
+  });
+
+  it("respects limit (returns last N records)", () => {
+    const path = join(dir, "limited.ndjson");
+    const records = Array.from({ length: 10 }, (_, i) => makeRecord(i));
+    writeFileSync(path, records.map((r) => JSON.stringify(r)).join("\n"));
+
+    const result = readTraceLog({ path, limit: 3 });
+
+    expect(result).toHaveLength(3);
+    expect(result[0].seq).toBe(7);
+    expect(result[1].seq).toBe(8);
+    expect(result[2].seq).toBe(9);
+  });
+
+  it("returns all records when limit exceeds count", () => {
+    const path = join(dir, "small.ndjson");
+    writeFileSync(path, JSON.stringify(makeRecord(0)));
+
+    const result = readTraceLog({ path, limit: 100 });
+
+    expect(result).toHaveLength(1);
+  });
+
+  it("returns empty array when limit is 0", () => {
+    const path = join(dir, "zero.ndjson");
+    writeFileSync(path, JSON.stringify(makeRecord(0)));
+
+    const result = readTraceLog({ path, limit: 0 });
+
+    expect(result).toHaveLength(0);
+  });
+});

package/src/domains/trace/operations/readTraceLog.ts

@@ -0,0 +1,104 @@
+/**
+ * Read and parse an NDJSON trace log file.
+ */
+
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import type { TraceRecord } from "../types.js";
+
+export interface ReadTraceLogOptions {
+  /** Absolute path to the NDJSON file. */
+  path: string;
+  /** Maximum number of records to return (from the tail). */
+  limit?: number;
+}
+
+/** Parse NDJSON lines into TraceRecord array, skipping malformed lines. */
+function parseNdjson(content: string): TraceRecord[] {
+  const lines = content.split("\n").filter((line) => line.length > 0);
+  const records: TraceRecord[] = [];
+  for (const line of lines) {
+    try {
+      records.push(JSON.parse(line) as TraceRecord);
+    } catch {
+      // Skip malformed lines
+    }
+  }
+  return records;
+}
+
+export function readTraceLog(options: ReadTraceLogOptions): TraceRecord[] {
+  const { path, limit } = options;
+
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const records = parseNdjson(content);
+
+  if (limit !== undefined) {
+    // A non-positive or non-finite limit returns no records. Guard explicitly:
+    // `slice(-0)` is `slice(0)` (the whole array) and `slice(NaN)` likewise
+    // returns everything, so the naive `slice(-limit)` mishandles both.
+    if (!Number.isFinite(limit) || limit <= 0) {
+      return [];
+    }
+    return records.slice(-limit);
+  }
+
+  return records;
+}
+
+/**
+ * Tail a trace log file, calling `onRecord` for each new record.
+ * Returns a cleanup function that stops the polling loop.
+ */
+export function followTraceLog(
+  path: string,
+  onRecord: (record: TraceRecord) => void,
+): () => void {
+  let offset = 0;
+  let stopped = false;
+
+  try {
+    const stat = statSync(path);
+    offset = stat.size;
+  } catch {
+    // File doesn't exist yet — start from 0
+  }
+
+  const poll = () => {
+    if (stopped) return;
+
+    try {
+      const stat = statSync(path);
+      if (stat.size > offset) {
+        const buf = Buffer.alloc(stat.size - offset);
+        const fd = openSync(path, "r");
+        readSync(fd, buf, 0, buf.length, offset);
+        closeSync(fd);
+
+        const chunk = buf.toString("utf-8");
+        for (const record of parseNdjson(chunk)) {
+          onRecord(record);
+        }
+        offset = stat.size;
+      }
+    } catch {
+      // File may not exist yet or be temporarily unavailable
+    }
+
+    if (!stopped) {
+      setTimeout(poll, 250);
+    }
+  };
+
+  // Start polling on next tick
+  setTimeout(poll, 0);
+
+  return () => {
+    stopped = true;
+  };
+}

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();
+  });
+});