@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -1,171 +0,0 @@
-/**
- * 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 { PragmaError } from "#error";
-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";
-
-/** 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 = [
-    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) {
-    // 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);
-
-    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 (limit validated at the top of execute).
-    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

@@ -1,9 +0,0 @@
-/** @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

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1,122 +0,0 @@
-/**
- * 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

@@ -1,17 +0,0 @@
-/**
- * @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

@@ -1,8 +0,0 @@
-/** @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

@@ -1,55 +0,0 @@
-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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-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);
-  });
-});