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

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

@@ -0,0 +1,145 @@
+/**
+ * Wires the `pragma trace` CLI command.
+ *
+ * Shows query trace records from the latest (or specified) session.
+ * Supports `--follow` / `-f` for real-time tailing.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { traceDir } from "../../refs/operations/paths.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import {
+  noSessionsFormatters,
+  sessionNotFoundFormatters,
+  showFormatters,
+} from "../formatters/index.js";
+import {
+  followTraceLog,
+  listSessions,
+  readTraceLog,
+} from "../operations/index.js";
+
+function formatOneLine(r: import("../types.js").TraceRecord): string {
+  const d = new Date(r.ts);
+  const time = [
+    String(d.getHours()).padStart(2, "0"),
+    String(d.getMinutes()).padStart(2, "0"),
+    String(d.getSeconds()).padStart(2, "0"),
+  ].join(":");
+  const type = r.type.toUpperCase().padEnd(10);
+  // Match the non-follow formatter: ASK → true/false, CONSTRUCT → triples,
+  // SELECT (and anything else) → rows.
+  const plural = (n: number, word: string) =>
+    `${n} ${word}${n !== 1 ? "s" : ""}`;
+  const count = (
+    r.type === "ask"
+      ? r.ask
+        ? "true"
+        : "false"
+      : r.type === "construct"
+        ? plural(r.count, "triple")
+        : plural(r.count, "row")
+  ).padEnd(12);
+  const ms = `${r.ms}ms`.padEnd(9);
+  const q = r.q.replace(/\s+/g, " ").trim();
+  const query = q.length > 100 ? `${q.slice(0, 97)}...` : q;
+  return `#${String(r.seq).padEnd(4)} ${time}  ${type}${count}${ms} ${r.qh}  ${query}`;
+}
+
+const showCommand: CommandDefinition = {
+  path: ["trace"],
+  description: "View query access traces",
+  parameters: [
+    {
+      name: "follow",
+      description: "Tail the log in real time",
+      type: "boolean",
+      short: "f",
+      default: false,
+    },
+    {
+      name: "session",
+      description: "Session ID to view (default: latest)",
+      type: "string",
+    },
+    {
+      name: "limit",
+      description: "Maximum number of records to show",
+      type: "string",
+      default: "50",
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma trace",
+      "pragma trace -f",
+      "pragma trace --limit 20",
+      "pragma trace --session 20260512-143022-a7f3",
+    ],
+  },
+  async execute(params, ctx) {
+    const dir = traceDir();
+    const sessions = listSessions(dir);
+
+    if (sessions.length === 0) {
+      return createOutputResult(undefined, {
+        plain: selectFormatter(ctx, noSessionsFormatters),
+      });
+    }
+
+    const sessionId =
+      typeof params.session === "string"
+        ? params.session
+        : sessions[0]?.sessionId;
+    const target = sessions.find((s) => s.sessionId === sessionId);
+
+    if (!target) {
+      return createOutputResult(
+        {
+          requested: sessionId ?? "(unknown)",
+          available: sessions.map((s) => s.sessionId),
+        },
+        { plain: selectFormatter(ctx, sessionNotFoundFormatters) },
+      );
+    }
+
+    // Follow mode — stream new records to stdout and block
+    if (params.follow === true) {
+      process.stdout.write(
+        `Following session ${target.sessionId} (ctrl+c to stop)\n\n`,
+      );
+
+      const stop = followTraceLog(target.path, (record) => {
+        process.stdout.write(`${formatOneLine(record)}\n`);
+      });
+
+      // Block until interrupted
+      await new Promise<void>((resolve) => {
+        const handler = () => {
+          stop();
+          resolve();
+        };
+        process.once("SIGINT", handler);
+        process.once("SIGTERM", handler);
+      });
+
+      return createOutputResult("", { plain: () => "" });
+    }
+
+    // Normal mode — read and format
+    const limit =
+      typeof params.limit === "string" ? Number.parseInt(params.limit, 10) : 50;
+
+    const records = readTraceLog({ path: target.path, limit });
+    const data = { sessionId: target.sessionId, records };
+
+    return createOutputResult(data, {
+      plain: selectFormatter(ctx, showFormatters),
+    });
+  },
+};
+
+export default showCommand;

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

@@ -0,0 +1,9 @@
+/** @module Re-exports trace formatters. */
+
+export { default as sessionsFormatters } from "./sessions.js";
+export {
+  default as showFormatters,
+  noSessionsFormatters,
+  type ShowData,
+  sessionNotFoundFormatters,
+} from "./show.js";

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

@@ -0,0 +1,80 @@
+/**
+ * Three-mode formatter for `pragma trace sessions` output.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { TraceSession } from "../types.js";
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatAge(date: Date): string {
+  const diffMs = Date.now() - date.getTime();
+  const seconds = Math.floor(diffMs / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+const formatters: Formatters<TraceSession[]> = {
+  plain: (sessions) => {
+    if (sessions.length === 0) {
+      return "No trace sessions found.";
+    }
+
+    const lines: string[] = [];
+    const hdr = {
+      sid: "SESSION",
+      queries: "QUERIES",
+      size: "SIZE",
+      age: "AGE",
+    };
+    const sidW = Math.max(
+      hdr.sid.length,
+      ...sessions.map((s) => s.sessionId.length),
+    );
+
+    lines.push(
+      `${hdr.sid.padEnd(sidW)}  ${hdr.queries.padStart(7)}  ${hdr.size.padStart(8)}  ${hdr.age}`,
+    );
+
+    for (const s of sessions) {
+      lines.push(
+        `${s.sessionId.padEnd(sidW)}  ${String(s.queryCount).padStart(7)}  ${formatSize(s.sizeBytes).padStart(8)}  ${formatAge(s.createdAt)}`,
+      );
+    }
+
+    return lines.join("\n");
+  },
+
+  llm: (sessions) => {
+    if (sessions.length === 0) {
+      return "No trace sessions found.";
+    }
+
+    const lines: string[] = [];
+    lines.push("## Trace Sessions");
+    lines.push("");
+    lines.push("| Session | Queries | Size | Age |");
+    lines.push("|---------|---------|------|-----|");
+
+    for (const s of sessions) {
+      lines.push(
+        `| ${s.sessionId} | ${s.queryCount} | ${formatSize(s.sizeBytes)} | ${formatAge(s.createdAt)} |`,
+      );
+    }
+
+    return lines.join("\n");
+  },
+
+  json: (sessions) => JSON.stringify(sessions, null, 2),
+};
+
+export default formatters;

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