cisco-perfmon 1.6.0 → 2.0.0

package/cli/commands/doctor.js

@@ -0,0 +1,115 @@
+const config = require("../utils/config.js");
+const { resolveConfig } = require("../utils/connection.js");
+
+module.exports = function (program) {
+  program.command("doctor")
+    .description("Check PerfMon connectivity and configuration health")
+    .action(async (opts, command) => {
+      const globalOpts = command.optsWithGlobals();
+      let passed = 0;
+      let warned = 0;
+      let failed = 0;
+
+      const ok = (msg) => { console.log(`  \u2713 ${msg}`); passed++; };
+      const warn = (msg) => { console.log(`  \u26A0 ${msg}`); warned++; };
+      const fail = (msg) => { console.log(`  \u2717 ${msg}`); failed++; };
+
+      console.log("\n  cisco-perfmon doctor");
+      console.log("  " + "\u2500".repeat(50));
+
+      // 1. Configuration
+      console.log("\n  Configuration");
+      let conn;
+      try {
+        const data = config.loadConfig();
+        if (!data.activeCluster) {
+          fail("No active cluster configured");
+          console.log("    Run: cisco-perfmon config add <name> --host <host> --username <user> --password <pass>");
+          printSummary(passed, warned, failed);
+          return;
+        }
+        ok(`Active cluster: ${data.activeCluster}`);
+        const cluster = data.clusters[data.activeCluster];
+        ok(`Host: ${cluster.host}`);
+        ok(`Username: ${cluster.username}`);
+
+        if (cluster.insecure) warn("TLS verification: disabled (--insecure)");
+        else ok("TLS verification: enabled");
+
+        conn = resolveConfig(globalOpts);
+      } catch (err) {
+        fail(`Config error: ${err.message}`);
+        printSummary(passed, warned, failed);
+        return;
+      }
+
+      // 2. PerfMon API connectivity
+      console.log("\n  PerfMon API");
+      try {
+        if (conn.insecure) { process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; }
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(conn.host, conn.username, conn.password);
+
+        const result = await svc.listCounter(conn.host);
+        ok("PerfMon API: connected");
+
+        const count = Array.isArray(result.results) ? result.results.length : 0;
+        ok(`Counter objects available: ${count}`);
+      } catch (err) {
+        const msg = err.message || String(err);
+        if (msg.includes("401") || msg.includes("Authentication")) {
+          fail("PerfMon API: authentication failed \u2014 check username/password");
+        } else if (msg.includes("ECONNREFUSED")) {
+          fail("PerfMon API: connection refused \u2014 check host and port");
+        } else if (msg.includes("ENOTFOUND")) {
+          fail("PerfMon API: hostname not found \u2014 check host");
+        } else if (msg.includes("certificate")) {
+          fail("PerfMon API: TLS certificate error \u2014 try adding --insecure to the cluster config");
+        } else {
+          fail(`PerfMon API: ${msg}`);
+        }
+      }
+
+      // 3. Security
+      console.log("\n  Security");
+      try {
+        const fs = require("node:fs");
+        const configPath = config.getConfigPath();
+        const stats = fs.statSync(configPath);
+        const mode = (stats.mode & 0o777).toString(8);
+        if (mode === "600") ok(`Config file permissions: ${mode} (secure)`);
+        else warn(`Config file permissions: ${mode} \u2014 should be 600. Run: chmod 600 ${configPath}`);
+      } catch { /* config file may not exist yet */ }
+
+      // 4. Audit trail
+      try {
+        const fs = require("node:fs");
+        const path = require("node:path");
+        const auditPath = path.join(config.getConfigDir(), "audit.jsonl");
+        if (fs.existsSync(auditPath)) {
+          const stats = fs.statSync(auditPath);
+          const sizeMB = (stats.size / 1024 / 1024).toFixed(1);
+          ok(`Audit trail: ${sizeMB}MB`);
+          if (stats.size > 8 * 1024 * 1024) warn("Audit trail approaching 10MB rotation limit");
+        } else {
+          ok("Audit trail: empty (no operations logged yet)");
+        }
+      } catch { /* ignore */ }
+
+      printSummary(passed, warned, failed);
+    });
+
+  function printSummary(passed, warned, failed) {
+    console.log("\n  " + "\u2500".repeat(50));
+    console.log(`  Results: ${passed} passed, ${warned} warning${warned !== 1 ? "s" : ""}, ${failed} failed`);
+    if (failed > 0) {
+      process.exitCode = 1;
+      console.log("  Status:  issues found \u2014 review failures above");
+    } else if (warned > 0) {
+      console.log("  Status:  healthy with warnings");
+    } else {
+      console.log("  Status:  all systems healthy");
+    }
+    console.log("");
+  }
+};

package/cli/commands/list-instances.js

@@ -0,0 +1,39 @@
+const { resolveConfig } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+
+module.exports = function (program) {
+  program
+    .command("list-instances <object>")
+    .description("List instances of a perfmon object")
+    .action(async (object, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.listInstance(connConfig.host, object);
+
+        let instances = Array.isArray(result.results) ? result.results : [];
+        const rows = instances.map((item) => {
+          if (typeof item === "string") return { instance: item };
+          return { instance: item.Name || item.name || JSON.stringify(item) };
+        });
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "list-instances", args: object, duration_ms: Date.now() - start, status: "success", rows: rows.length });
+        }
+
+        await printResult(rows, globalOpts.format);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "list-instances", args: object, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+};

package/cli/commands/list-objects.js

@@ -0,0 +1,45 @@
+const { resolveConfig } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+
+module.exports = function (program) {
+  program
+    .command("list-objects")
+    .description("List available perfmon objects")
+    .option("--search <keyword>", "filter objects by keyword (case-insensitive)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.listCounter(connConfig.host);
+
+        let objects = Array.isArray(result.results) ? result.results : [];
+
+        // Extract unique object names from counter list
+        const objectNames = [...new Set(objects.map((item) => item.Name || item.name).filter(Boolean))];
+        let rows = objectNames.map((name) => ({ name }));
+
+        if (opts.search) {
+          const keyword = opts.search.toLowerCase();
+          rows = rows.filter((r) => r.name.toLowerCase().includes(keyword));
+        }
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "list-objects", args: opts.search || "", duration_ms: Date.now() - start, status: "success", rows: rows.length });
+        }
+
+        await printResult(rows, globalOpts.format);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "list-objects", duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+};

package/cli/commands/session.js

@@ -0,0 +1,162 @@
+const { resolveConfig } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+
+module.exports = function (program) {
+  const session = program.command("session").description("Manage perfmon sessions");
+
+  session
+    .command("open")
+    .description("Open a new perfmon session")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.openSession();
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "session open", duration_ms: Date.now() - start, status: "success" });
+        }
+
+        const handle = result.results;
+        if (globalOpts.format === "json") {
+          await printResult({ sessionHandle: handle }, globalOpts.format);
+        } else {
+          console.log(`Session handle: ${handle}`);
+        }
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "session open", duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+
+  session
+    .command("add <handle>")
+    .description("Add counters to a session")
+    .option("--counters <json>", "JSON array of counter objects [{host,object,counter,instance?}]")
+    .action(async (handle, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        if (!opts.counters) throw new Error("Missing required option: --counters (JSON array of counter objects)");
+        const counters = JSON.parse(opts.counters);
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.addCounter(handle, counters);
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "session add", args: handle, duration_ms: Date.now() - start, status: "success" });
+        }
+
+        console.log(`Counters added to session ${handle}: ${result.results}`);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "session add", args: handle, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+
+  session
+    .command("collect <handle>")
+    .description("Collect data from a session")
+    .action(async (handle, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.collectSessionData(handle);
+
+        let rows = Array.isArray(result.results) ? result.results : result.results ? [result.results] : [];
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "session collect", args: handle, duration_ms: Date.now() - start, status: "success", rows: rows.length });
+        }
+
+        await printResult(rows, globalOpts.format);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "session collect", args: handle, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+
+  session
+    .command("remove <handle>")
+    .description("Remove counters from a session")
+    .option("--counters <json>", "JSON array of counter objects [{host,object,counter,instance?}]")
+    .action(async (handle, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        if (!opts.counters) throw new Error("Missing required option: --counters (JSON array of counter objects)");
+        const counters = JSON.parse(opts.counters);
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.removeCounter(handle, counters);
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "session remove", args: handle, duration_ms: Date.now() - start, status: "success" });
+        }
+
+        console.log(`Counters removed from session ${handle}: ${result.results}`);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "session remove", args: handle, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+
+  session
+    .command("close <handle>")
+    .description("Close a perfmon session")
+    .action(async (handle, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.closeSession(handle);
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "session close", args: handle, duration_ms: Date.now() - start, status: "success" });
+        }
+
+        console.log(`Session ${handle} closed: ${result.results}`);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "session close", args: handle, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+};

package/cli/commands/watch.js

@@ -0,0 +1,163 @@
+const { resolveConfig } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+
+const SPARK_CHARS = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+
+function sparkline(values) {
+  if (values.length === 0) return "";
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min || 1;
+  return values.map((v) => SPARK_CHARS[Math.min(Math.floor(((v - min) / range) * 7), 7)]).join("");
+}
+
+function avg(values) {
+  if (values.length === 0) return 0;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+function watchCommand(program) {
+  program
+    .command("watch <object>")
+    .description("Continuously poll perfmon counters with live sparklines")
+    .option("--counter <names>", "comma-separated counter names to watch")
+    .option("--instance <name>", "filter by instance name")
+    .option("--interval <seconds>", "polling interval in seconds", "10")
+    .option("--duration <seconds>", "stop after N seconds (default: indefinite)")
+    .action(async (object, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const interval = parseInt(opts.interval, 10) * 1000;
+      const duration = opts.duration ? parseInt(opts.duration, 10) * 1000 : 0;
+      const counterFilter = opts.counter ? opts.counter.split(",").map((c) => c.trim()) : null;
+      const start = Date.now();
+      let iterations = 0;
+
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+
+        // Rolling history: key = "object|instance|counter", value = number[]
+        const history = {};
+        const MAX_SAMPLES = 12;
+        let running = true;
+
+        const cleanup = () => {
+          running = false;
+          // Print final summary
+          console.log("\n");
+          console.log("Watch stopped. Final summary:");
+          console.log(`  Iterations: ${iterations}`);
+          console.log(`  Duration: ${((Date.now() - start) / 1000).toFixed(1)}s`);
+
+          if (globalOpts.audit !== false) {
+            try { audit.log({ cluster: connConfig.host, command: "watch", args: object, duration_ms: Date.now() - start, status: "success", iterations }); } catch {}
+          }
+
+          process.exit(0);
+        };
+
+        process.on("SIGINT", cleanup);
+        process.on("SIGTERM", cleanup);
+
+        const poll = async () => {
+          try {
+            const result = await svc.collectCounterData(connConfig.host, object);
+            let rows = Array.isArray(result.results) ? result.results : result.results ? [result.results] : [];
+
+            if (counterFilter) {
+              rows = rows.filter((r) => counterFilter.includes(r.counter));
+            }
+            if (opts.instance) {
+              rows = rows.filter((r) => r.instance === opts.instance);
+            }
+
+            // Update history
+            for (const row of rows) {
+              const key = `${row.object}|${row.instance || ""}|${row.counter}`;
+              if (!history[key]) history[key] = [];
+              const numVal = parseFloat(row.value);
+              if (!isNaN(numVal)) {
+                history[key].push(numVal);
+                if (history[key].length > MAX_SAMPLES) history[key].shift();
+              }
+            }
+
+            iterations++;
+
+            if (globalOpts.format !== "table") {
+              // Non-table formats: print timestamped blocks
+              console.log(`\n--- ${new Date().toISOString()} (sample ${iterations}) ---`);
+              await printResult(rows, globalOpts.format);
+            } else {
+              // Table format: clear and redraw with sparklines
+              process.stdout.write("\x1b[2J\x1b[0f");
+              console.log(`cisco-perfmon watch: ${object} | interval: ${opts.interval}s | sample: ${iterations} | ${new Date().toISOString()}\n`);
+
+              const Table = require("cli-table3");
+              const table = new Table({ head: ["counter", "instance", "value", "sparkline", "min", "max", "avg"] });
+
+              for (const row of rows) {
+                const key = `${row.object}|${row.instance || ""}|${row.counter}`;
+                const values = history[key] || [];
+                const numVal = parseFloat(row.value);
+                const numValues = values.filter((v) => !isNaN(v));
+
+                table.push([
+                  row.counter,
+                  row.instance || "",
+                  row.value,
+                  sparkline(numValues),
+                  numValues.length > 0 ? Math.min(...numValues).toFixed(1) : "-",
+                  numValues.length > 0 ? Math.max(...numValues).toFixed(1) : "-",
+                  numValues.length > 0 ? avg(numValues).toFixed(1) : "-",
+                ]);
+              }
+
+              console.log(table.toString());
+              console.log(`\n${rows.length} counter${rows.length !== 1 ? "s" : ""} | Press Ctrl+C to stop`);
+            }
+          } catch (err) {
+            process.stderr.write(`\nPoll error: ${err.message || err}\n`);
+          }
+        };
+
+        // Initial poll
+        await poll();
+
+        // Set up interval
+        const pollTimer = setInterval(async () => {
+          if (!running) return;
+          if (duration > 0 && Date.now() - start >= duration) {
+            clearInterval(pollTimer);
+            cleanup();
+            return;
+          }
+          await poll();
+        }, interval);
+
+        // If duration is set, schedule exit
+        if (duration > 0) {
+          setTimeout(() => {
+            clearInterval(pollTimer);
+            cleanup();
+          }, duration);
+        }
+
+        // Keep process alive
+        await new Promise(() => {});
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "watch", args: object, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+}
+
+module.exports = watchCommand;
+module.exports.sparkline = sparkline;

package/cli/formatters/csv.js

@@ -0,0 +1,10 @@
+const { stringify } = require("csv-stringify/sync");
+
+function formatCsv(data) {
+  const rows = Array.isArray(data) ? data : [data];
+  if (rows.length === 0) return "";
+  const columns = Object.keys(rows[0]);
+  return stringify(rows, { header: true, columns });
+}
+
+module.exports = formatCsv;

package/cli/formatters/json.js

@@ -0,0 +1,5 @@
+function formatJson(data) {
+  return JSON.stringify(data, null, 2);
+}
+
+module.exports = formatJson;

package/cli/formatters/table.js

@@ -0,0 +1,25 @@
+const Table = require("cli-table3");
+
+function formatTable(data) {
+  if (Array.isArray(data)) return formatListTable(data);
+  return formatItemTable(data);
+}
+
+function formatListTable(rows) {
+  if (rows.length === 0) return "No results found";
+  const columns = Object.keys(rows[0]);
+  const table = new Table({ head: columns });
+  for (const row of rows) table.push(columns.map((col) => String(row[col] ?? "")));
+  return `${table.toString()}\n${rows.length} result${rows.length !== 1 ? "s" : ""} found`;
+}
+
+function formatItemTable(item) {
+  const table = new Table();
+  for (const [key, value] of Object.entries(item)) {
+    const displayValue = typeof value === "object" && value !== null ? JSON.stringify(value, null, 2) : String(value ?? "");
+    table.push({ [key]: displayValue });
+  }
+  return table.toString();
+}
+
+module.exports = formatTable;

package/cli/formatters/toon.js

@@ -0,0 +1,6 @@
+async function formatToon(data) {
+  const { encode } = await import("@toon-format/toon");
+  return encode(data);
+}
+
+module.exports = formatToon;

package/cli/index.js

@@ -0,0 +1,40 @@
+const { Command } = require("commander");
+const pkg = require("../package.json");
+
+// Suppress Node.js TLS warning when --insecure is used
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = (warning, ...args) => {
+  if (typeof warning === "string" && warning.includes("NODE_TLS_REJECT_UNAUTHORIZED")) return;
+  originalEmitWarning.call(process, warning, ...args);
+};
+
+try {
+  const updateNotifier = require("update-notifier").default || require("update-notifier");
+  updateNotifier({ pkg }).notify();
+} catch {}
+
+const program = new Command();
+
+program
+  .name("cisco-perfmon")
+  .description("CLI for Cisco CUCM Performance Monitoring via PerfMon API")
+  .version(pkg.version)
+  .option("--format <type>", "output format: table, json, toon, csv", "table")
+  .option("--host <host>", "CUCM hostname (overrides config/env)")
+  .option("--username <user>", "CUCM username (overrides config/env)")
+  .option("--password <pass>", "CUCM password (overrides config/env)")
+  .option("--cluster <name>", "use a specific named cluster")
+  .option("--insecure", "skip TLS certificate verification")
+  .option("--no-audit", "disable audit logging for this command")
+  .option("--debug", "enable debug logging");
+
+require("./commands/config.js")(program);
+require("./commands/list-objects.js")(program);
+require("./commands/list-instances.js")(program);
+require("./commands/describe.js")(program);
+require("./commands/collect.js")(program);
+require("./commands/session.js")(program);
+require("./commands/watch.js")(program);
+require("./commands/doctor.js")(program);
+
+program.parse();

package/cli/utils/audit.js

@@ -0,0 +1,30 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { getConfigDir } = require("./config.js");
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
+
+function getAuditPath() {
+  return path.join(getConfigDir(), "audit.jsonl");
+}
+
+function rotateIfNeeded(auditPath) {
+  try {
+    const stats = fs.statSync(auditPath);
+    if (stats.size >= MAX_FILE_SIZE) {
+      const rotated = auditPath + ".1";
+      if (fs.existsSync(rotated)) fs.unlinkSync(rotated);
+      fs.renameSync(auditPath, rotated);
+    }
+  } catch { /* file doesn't exist yet */ }
+}
+
+function log(entry) {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const auditPath = getAuditPath();
+  rotateIfNeeded(auditPath);
+  fs.appendFileSync(auditPath, JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + "\n");
+}
+
+module.exports = { log, getAuditPath };