@canonical/pragma-cli 0.31.0 → 0.32.0

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

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

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

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

@@ -1,65 +0,0 @@
-/**
- * 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/embedWasm.ts

@@ -1,42 +0,0 @@
-/**
- * Embed oxigraph WASM for `bun build --compile`.
- *
- * Bun's bundler does not automatically embed WASM files loaded via
- * `readFileSync(path.join(__dirname, 'node_bg.wasm'))` — the `__dirname`
- * is hardcoded to the build-time path and `readFileSync` is not
- * intercepted for embedded data at runtime.
- *
- * This module dynamically imports the WASM file with `{ type: "file" }`,
- * which bun embeds into the compiled binary's `$bunfs` virtual filesystem.
- * It then patches CJS `readFileSync` so that oxigraph's WASM loader
- * returns the pre-loaded bytes instead of reading from a stale path.
- *
- * In interpreted mode the dynamic import resolves to the real filesystem
- * path and the patch is effectively a no-op (reads the same bytes).
- *
- * This module MUST be imported before any code that loads oxigraph.
- */
-
-import { readFileSync } from "node:fs";
-
-// @ts-expect-error — bun-specific import attribute for file embedding
-const { default: wasmPath } = await import("oxigraph/node_bg.wasm", {
-  with: { type: "file" },
-});
-const wasmBytes = readFileSync(wasmPath);
-
-// Oxigraph's CJS wrapper uses require("fs").readFileSync(...) to load
-// the WASM. Patch the CJS fs module (mutable, unlike ESM bindings) so
-// reads targeting node_bg.wasm return the pre-loaded bytes.
-const cjsFs = import.meta.require("fs");
-const origReadFileSync = cjsFs.readFileSync;
-
-cjsFs.readFileSync = function patchedReadFileSync(
-  path: string,
-  ...args: unknown[]
-) {
-  if (typeof path === "string" && path.endsWith("/node_bg.wasm")) {
-    return wasmBytes;
-  }
-  return origReadFileSync(path, ...args);
-};

package/src/error/PragmaError.test.ts

@@ -1,121 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "./PragmaError.js";
-
-describe("PragmaError", () => {
-  describe("notFound", () => {
-    it("creates an ENTITY_NOT_FOUND error with entity info", () => {
-      const err = PragmaError.notFound("component", "Buton", {
-        suggestions: ["Button", "ButtonGroup"],
-        recovery: {
-          message: "List available components.",
-          cli: "pragma block list",
-          mcp: { tool: "block_list" },
-        },
-      });
-
-      expect(err).toBeInstanceOf(PragmaError);
-      expect(err.code).toBe("ENTITY_NOT_FOUND");
-      expect(err.message).toBe('component "Buton" not found.');
-      expect(err.entity).toEqual({ type: "component", name: "Buton" });
-      expect(err.suggestions).toEqual(["Button", "ButtonGroup"]);
-      expect(err.recovery).toEqual({
-        message: "List available components.",
-        cli: "pragma block list",
-        mcp: { tool: "block_list" },
-      });
-    });
-
-    it("defaults suggestions to empty array", () => {
-      const err = PragmaError.notFound("standard", "react/fold");
-      expect(err.suggestions).toEqual([]);
-      expect(err.recovery).toBeUndefined();
-    });
-  });
-
-  describe("emptyResults", () => {
-    it("creates an EMPTY_RESULTS error with filters", () => {
-      const err = PragmaError.emptyResults("component", {
-        filters: { tier: "apps/lxd", channel: "normal" },
-        recovery: {
-          message: "Widen the search to show all tiers.",
-          cli: "pragma block list --all-tiers",
-          mcp: { tool: "block_list", params: { allTiers: true } },
-        },
-      });
-
-      expect(err.code).toBe("EMPTY_RESULTS");
-      expect(err.message).toBe("No components found.");
-      expect(err.filters).toEqual({ tier: "apps/lxd", channel: "normal" });
-      expect(err.recovery).toEqual({
-        message: "Widen the search to show all tiers.",
-        cli: "pragma block list --all-tiers",
-        mcp: { tool: "block_list", params: { allTiers: true } },
-      });
-    });
-  });
-
-  describe("invalidInput", () => {
-    it("creates an INVALID_INPUT error with valid options", () => {
-      const err = PragmaError.invalidInput("channel", "aggressive", {
-        validOptions: ["normal", "experimental", "prerelease"],
-      });
-
-      expect(err.code).toBe("INVALID_INPUT");
-      expect(err.message).toBe('Invalid channel "aggressive".');
-      expect(err.validOptions).toEqual([
-        "normal",
-        "experimental",
-        "prerelease",
-      ]);
-    });
-  });
-
-  describe("storeError", () => {
-    it("creates a STORE_ERROR with reason and recovery", () => {
-      const err = PragmaError.storeError("WASM module failed to load", {
-        recovery: {
-          message: "Run pragma doctor to diagnose.",
-          cli: "pragma doctor",
-        },
-      });
-
-      expect(err.code).toBe("STORE_ERROR");
-      expect(err.message).toContain("WASM module failed to load");
-      expect(err.recovery).toEqual({
-        message: "Run pragma doctor to diagnose.",
-        cli: "pragma doctor",
-      });
-    });
-  });
-
-  describe("configError", () => {
-    it("creates a CONFIG_ERROR with valid options", () => {
-      const err = PragmaError.configError(
-        'Tier "apps/nonexistent" not found in ontology.',
-        { validOptions: ["global", "apps", "apps/lxd"] },
-      );
-
-      expect(err.code).toBe("CONFIG_ERROR");
-      expect(err.message).toContain("apps/nonexistent");
-      expect(err.validOptions).toEqual(["global", "apps", "apps/lxd"]);
-    });
-  });
-
-  describe("internalError", () => {
-    it("creates an INTERNAL_ERROR with recovery", () => {
-      const err = PragmaError.internalError("Unexpected null in query result");
-
-      expect(err.code).toBe("INTERNAL_ERROR");
-      expect(err.message).toContain("Unexpected null");
-      expect(err.recovery).toEqual({
-        message: "Please report this issue.",
-      });
-    });
-  });
-
-  it("is an instance of Error", () => {
-    const err = PragmaError.notFound("component", "Foo");
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("PragmaError");
-  });
-});