Initial commit with translated description

2026-03-29 10:19:19 +08:00
commit 5aa1f324c6
81 changed files with 27526 additions and 0 deletions
--- a/tests/actions.test.js
+++ b/tests/actions.test.js
@@ -0,0 +1,79 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { executeAction } = require("../src/actions");
+
+describe("actions module", () => {
+  describe("executeAction()", () => {
+    const mockDeps = {
+      runOpenClaw: (args) => `mock output for: ${args}`,
+      extractJSON: (output) => output,
+      PORT: 3333,
+    };
+
+    it("handles gateway-status action", () => {
+      const result = executeAction("gateway-status", mockDeps);
+      assert.strictEqual(result.success, true);
+      assert.strictEqual(result.action, "gateway-status");
+      assert.ok(result.output.includes("gateway status"));
+    });
+
+    it("handles gateway-restart action with safety message", () => {
+      const result = executeAction("gateway-restart", mockDeps);
+      assert.strictEqual(result.success, true);
+      assert.ok(result.note.includes("safety"));
+    });
+
+    it("handles sessions-list action", () => {
+      const result = executeAction("sessions-list", mockDeps);
+      assert.strictEqual(result.success, true);
+    });
+
+    it("handles cron-list action", () => {
+      const result = executeAction("cron-list", mockDeps);
+      assert.strictEqual(result.success, true);
+    });
+
+    it("handles health-check action", () => {
+      const result = executeAction("health-check", mockDeps);
+      assert.strictEqual(result.success, true);
+      assert.ok(result.output.includes("Dashboard"));
+      assert.ok(result.output.includes("3333"));
+    });
+
+    it("handles clear-stale-sessions action", () => {
+      const deps = {
+        ...mockDeps,
+        runOpenClaw: () => '{"sessions": []}',
+        extractJSON: (o) => o,
+      };
+      const result = executeAction("clear-stale-sessions", deps);
+      assert.strictEqual(result.success, true);
+      assert.ok(result.output.includes("stale sessions"));
+    });
+
+    it("returns error for unknown action", () => {
+      const result = executeAction("nonexistent-action", mockDeps);
+      assert.strictEqual(result.success, false);
+      assert.ok(result.error.includes("Unknown action"));
+    });
+
+    it("handles runOpenClaw returning null", () => {
+      const deps = { ...mockDeps, runOpenClaw: () => null };
+      const result = executeAction("gateway-status", deps);
+      assert.strictEqual(result.success, true);
+      assert.strictEqual(result.output, "Unknown");
+    });
+
+    it("catches exceptions and returns error", () => {
+      const deps = {
+        ...mockDeps,
+        runOpenClaw: () => {
+          throw new Error("command failed");
+        },
+      };
+      const result = executeAction("gateway-status", deps);
+      assert.strictEqual(result.success, false);
+      assert.ok(result.error.includes("command failed"));
+    });
+  });
+});
--- a/tests/auth.test.js
+++ b/tests/auth.test.js
@@ -0,0 +1,191 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { checkAuth, AUTH_HEADERS, getUnauthorizedPage } = require("../src/auth");
+
+describe("auth module", () => {
+  describe("AUTH_HEADERS", () => {
+    it("exports tailscale header names", () => {
+      assert.strictEqual(AUTH_HEADERS.tailscale.login, "tailscale-user-login");
+      assert.strictEqual(AUTH_HEADERS.tailscale.name, "tailscale-user-name");
+      assert.strictEqual(AUTH_HEADERS.tailscale.pic, "tailscale-user-profile-pic");
+    });
+
+    it("exports cloudflare header names", () => {
+      assert.strictEqual(AUTH_HEADERS.cloudflare.email, "cf-access-authenticated-user-email");
+    });
+  });
+
+  describe("checkAuth()", () => {
+    function mockReq(remoteAddress, headers = {}) {
+      return { socket: { remoteAddress }, headers };
+    }
+
+    it("allows localhost (127.0.0.1) regardless of auth mode", () => {
+      const result = checkAuth(mockReq("127.0.0.1"), { mode: "token", token: "secret" });
+      assert.strictEqual(result.authorized, true);
+      assert.strictEqual(result.user.type, "localhost");
+    });
+
+    it("allows localhost (::1) regardless of auth mode", () => {
+      const result = checkAuth(mockReq("::1"), { mode: "tailscale", allowedUsers: [] });
+      assert.strictEqual(result.authorized, true);
+    });
+
+    it("allows localhost (::ffff:127.0.0.1)", () => {
+      const result = checkAuth(mockReq("::ffff:127.0.0.1"), { mode: "token", token: "x" });
+      assert.strictEqual(result.authorized, true);
+    });
+
+    it("allows all when mode is 'none'", () => {
+      const result = checkAuth(mockReq("192.168.1.100"), { mode: "none" });
+      assert.strictEqual(result.authorized, true);
+      assert.strictEqual(result.user, null);
+    });
+
+    describe("token mode", () => {
+      const authConfig = { mode: "token", token: "my-secret-token" };
+
+      it("allows valid bearer token", () => {
+        const req = mockReq("10.0.0.1", { authorization: "Bearer my-secret-token" });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+        assert.strictEqual(result.user.type, "token");
+      });
+
+      it("rejects invalid token", () => {
+        const req = mockReq("10.0.0.1", { authorization: "Bearer wrong-token" });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+        assert.ok(result.reason.includes("Invalid"));
+      });
+
+      it("rejects missing authorization header", () => {
+        const req = mockReq("10.0.0.1", {});
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+      });
+    });
+
+    describe("tailscale mode", () => {
+      const authConfig = { mode: "tailscale", allowedUsers: ["user@example.com", "*@corp.com"] };
+
+      it("allows user in allowlist", () => {
+        const req = mockReq("100.64.0.1", { "tailscale-user-login": "user@example.com" });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+        assert.strictEqual(result.user.type, "tailscale");
+        assert.strictEqual(result.user.login, "user@example.com");
+      });
+
+      it("allows wildcard domain match", () => {
+        const req = mockReq("100.64.0.1", { "tailscale-user-login": "anyone@corp.com" });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+      });
+
+      it("rejects user not in allowlist", () => {
+        const req = mockReq("100.64.0.1", { "tailscale-user-login": "hacker@evil.com" });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+        assert.ok(result.reason.includes("not in allowlist"));
+      });
+
+      it("rejects when no tailscale header present", () => {
+        const req = mockReq("10.0.0.1", {});
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+        assert.ok(result.reason.includes("Tailscale"));
+      });
+
+      it("allows wildcard (*) user", () => {
+        const config = { mode: "tailscale", allowedUsers: ["*"] };
+        const req = mockReq("100.64.0.1", { "tailscale-user-login": "anyone@anywhere.com" });
+        const result = checkAuth(req, config);
+        assert.strictEqual(result.authorized, true);
+      });
+    });
+
+    describe("cloudflare mode", () => {
+      const authConfig = { mode: "cloudflare", allowedUsers: ["user@example.com"] };
+
+      it("allows user in allowlist", () => {
+        const req = mockReq("172.16.0.1", {
+          "cf-access-authenticated-user-email": "user@example.com",
+        });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+        assert.strictEqual(result.user.type, "cloudflare");
+      });
+
+      it("rejects user not in allowlist", () => {
+        const req = mockReq("172.16.0.1", {
+          "cf-access-authenticated-user-email": "other@example.com",
+        });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+      });
+
+      it("rejects when no cloudflare header present", () => {
+        const req = mockReq("172.16.0.1", {});
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+        assert.ok(result.reason.includes("Cloudflare"));
+      });
+    });
+
+    describe("allowlist mode", () => {
+      const authConfig = { mode: "allowlist", allowedIPs: ["10.0.0.5", "192.168.1.0/24"] };
+
+      it("allows exact IP match", () => {
+        const req = mockReq("10.0.0.5");
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+        assert.strictEqual(result.user.type, "ip");
+      });
+
+      it("allows /24 subnet match", () => {
+        const req = mockReq("192.168.1.42");
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+      });
+
+      it("rejects IP not in allowlist", () => {
+        const req = mockReq("10.0.0.99");
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, false);
+        assert.ok(result.reason.includes("not in allowlist"));
+      });
+
+      it("uses x-forwarded-for header when present", () => {
+        const req = mockReq("172.16.0.1", { "x-forwarded-for": "10.0.0.5, 172.16.0.1" });
+        const result = checkAuth(req, authConfig);
+        assert.strictEqual(result.authorized, true);
+      });
+    });
+
+    it("rejects unknown auth mode", () => {
+      const result = checkAuth(mockReq("10.0.0.1"), { mode: "kerberos" });
+      assert.strictEqual(result.authorized, false);
+      assert.ok(result.reason.includes("Unknown"));
+    });
+  });
+
+  describe("getUnauthorizedPage()", () => {
+    it("returns HTML string", () => {
+      const html = getUnauthorizedPage("test reason", null, { mode: "token" });
+      assert.ok(html.includes("<!DOCTYPE html>"));
+      assert.ok(html.includes("Access Denied"));
+      assert.ok(html.includes("test reason"));
+    });
+
+    it("includes user info when provided", () => {
+      const html = getUnauthorizedPage("denied", { login: "user@test.com" }, { mode: "tailscale" });
+      assert.ok(html.includes("user@test.com"));
+    });
+
+    it("includes auth mode in output", () => {
+      const html = getUnauthorizedPage("denied", null, { mode: "cloudflare" });
+      assert.ok(html.includes("cloudflare"));
+    });
+  });
+});
--- a/tests/config.test.js
+++ b/tests/config.test.js
@@ -0,0 +1,154 @@
+const { describe, it, afterEach } = require("node:test");
+const assert = require("node:assert");
+const os = require("os");
+const path = require("path");
+
+describe("config module", () => {
+  // Save original env to restore after tests
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    // Restore env vars after each test
+    for (const key of Object.keys(process.env)) {
+      if (!(key in originalEnv)) {
+        delete process.env[key];
+      }
+    }
+    Object.assign(process.env, originalEnv);
+
+    // Clear require cache so config reloads fresh
+    for (const key of Object.keys(require.cache)) {
+      if (key.includes("config.js")) {
+        delete require.cache[key];
+      }
+    }
+  });
+
+  describe("expandPath()", () => {
+    it("expands ~ to home directory", () => {
+      const { expandPath } = require("../src/config");
+      const result = expandPath("~/some/path");
+      assert.strictEqual(result, path.join(os.homedir(), "some", "path"));
+    });
+
+    it("expands $HOME to home directory", () => {
+      const { expandPath } = require("../src/config");
+      const result = expandPath("$HOME/docs");
+      assert.strictEqual(result, path.join(os.homedir(), "docs"));
+    });
+
+    it("expands ${HOME} to home directory", () => {
+      const { expandPath } = require("../src/config");
+      const result = expandPath("${HOME}/docs");
+      assert.strictEqual(result, path.join(os.homedir(), "docs"));
+    });
+
+    it("returns null/undefined as-is", () => {
+      const { expandPath } = require("../src/config");
+      assert.strictEqual(expandPath(null), null);
+      assert.strictEqual(expandPath(undefined), undefined);
+    });
+
+    it("returns path unchanged when no expansion needed", () => {
+      const { expandPath } = require("../src/config");
+      assert.strictEqual(expandPath("/absolute/path"), "/absolute/path");
+    });
+  });
+
+  describe("detectWorkspace()", () => {
+    it("returns a string path", () => {
+      const { detectWorkspace } = require("../src/config");
+      const result = detectWorkspace();
+      assert.strictEqual(typeof result, "string");
+      assert.ok(result.length > 0, "workspace path should not be empty");
+    });
+
+    it("returns an absolute path", () => {
+      const { detectWorkspace } = require("../src/config");
+      const result = detectWorkspace();
+      assert.ok(path.isAbsolute(result), `Expected absolute path, got: ${result}`);
+    });
+  });
+
+  describe("loadConfig()", () => {
+    it("returns an object with all required top-level keys", () => {
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.ok(config.server, "config should have server");
+      assert.ok(config.paths, "config should have paths");
+      assert.ok(config.auth, "config should have auth");
+      assert.ok(config.branding, "config should have branding");
+      assert.ok(config.integrations, "config should have integrations");
+    });
+
+    it("has default port of 3333", () => {
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.strictEqual(config.server.port, 3333);
+    });
+
+    it("has default auth mode of 'none'", () => {
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.strictEqual(config.auth.mode, "none");
+    });
+
+    it("has default host of localhost", () => {
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.strictEqual(config.server.host, "localhost");
+    });
+
+    it("has workspace path set", () => {
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.ok(config.paths.workspace, "workspace path should be set");
+      assert.strictEqual(typeof config.paths.workspace, "string");
+    });
+
+    it("has memory path set", () => {
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.ok(config.paths.memory, "memory path should be set");
+    });
+  });
+
+  describe("environment variable overrides", () => {
+    it("PORT env var overrides default port", () => {
+      process.env.PORT = "9999";
+      // Clear cache to force re-require
+      for (const key of Object.keys(require.cache)) {
+        if (key.includes("config.js")) {
+          delete require.cache[key];
+        }
+      }
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.strictEqual(config.server.port, 9999);
+    });
+
+    it("HOST env var overrides default host", () => {
+      process.env.HOST = "0.0.0.0";
+      for (const key of Object.keys(require.cache)) {
+        if (key.includes("config.js")) {
+          delete require.cache[key];
+        }
+      }
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.strictEqual(config.server.host, "0.0.0.0");
+    });
+
+    it("DASHBOARD_AUTH_MODE env var overrides auth mode", () => {
+      process.env.DASHBOARD_AUTH_MODE = "token";
+      for (const key of Object.keys(require.cache)) {
+        if (key.includes("config.js")) {
+          delete require.cache[key];
+        }
+      }
+      const { loadConfig } = require("../src/config");
+      const config = loadConfig();
+      assert.strictEqual(config.auth.mode, "token");
+    });
+  });
+});
--- a/tests/cron.test.js
+++ b/tests/cron.test.js
@@ -0,0 +1,79 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { cronToHuman } = require("../src/cron");
+
+describe("cron module", () => {
+  describe("cronToHuman()", () => {
+    it("returns null for null input", () => {
+      assert.strictEqual(cronToHuman(null), null);
+    });
+
+    it("returns null for dash", () => {
+      assert.strictEqual(cronToHuman("—"), null);
+    });
+
+    it("returns null for too few parts", () => {
+      assert.strictEqual(cronToHuman("* *"), null);
+    });
+
+    it("converts every-minute cron", () => {
+      assert.strictEqual(cronToHuman("* * * * *"), "Every minute");
+    });
+
+    it("converts every-N-minutes cron", () => {
+      assert.strictEqual(cronToHuman("*/5 * * * *"), "Every 5 minutes");
+      assert.strictEqual(cronToHuman("*/15 * * * *"), "Every 15 minutes");
+    });
+
+    it("converts every-N-hours cron", () => {
+      assert.strictEqual(cronToHuman("0 */2 * * *"), "Every 2 hours");
+    });
+
+    it("converts hourly at specific minute", () => {
+      assert.strictEqual(cronToHuman("30 * * * *"), "Hourly at :30");
+      assert.strictEqual(cronToHuman("0 * * * *"), "Hourly at :00");
+    });
+
+    it("converts daily at specific time", () => {
+      assert.strictEqual(cronToHuman("0 9 * * *"), "Daily at 9am");
+      assert.strictEqual(cronToHuman("30 14 * * *"), "Daily at 2:30pm");
+      assert.strictEqual(cronToHuman("0 0 * * *"), "Daily at 12am");
+      assert.strictEqual(cronToHuman("0 12 * * *"), "Daily at 12pm");
+    });
+
+    it("converts weekday cron", () => {
+      assert.strictEqual(cronToHuman("0 9 * * 1-5"), "Weekdays at 9am");
+      assert.strictEqual(cronToHuman("0 9 * * MON-FRI"), "Weekdays at 9am");
+    });
+
+    it("converts weekend cron", () => {
+      assert.strictEqual(cronToHuman("0 10 * * 0,6"), "Weekends at 10am");
+      assert.strictEqual(cronToHuman("0 10 * * 6,0"), "Weekends at 10am");
+    });
+
+    it("converts specific day of week", () => {
+      const result = cronToHuman("0 8 * * 1");
+      assert.strictEqual(result, "Monday at 8am");
+    });
+
+    it("converts specific day of month", () => {
+      const result = cronToHuman("0 9 1 * *");
+      assert.strictEqual(result, "1st of month at 9am");
+    });
+
+    it("handles ordinal suffixes correctly", () => {
+      assert.ok(cronToHuman("0 9 2 * *").includes("2nd"));
+      assert.ok(cronToHuman("0 9 3 * *").includes("3rd"));
+      assert.ok(cronToHuman("0 9 4 * *").includes("4th"));
+      assert.ok(cronToHuman("0 9 21 * *").includes("21st"));
+      assert.ok(cronToHuman("0 9 22 * *").includes("22nd"));
+      assert.ok(cronToHuman("0 9 23 * *").includes("23rd"));
+    });
+
+    it("returns original expression as fallback", () => {
+      const expr = "* * * 6 *";
+      const result = cronToHuman(expr);
+      assert.strictEqual(typeof result, "string");
+    });
+  });
+});
--- a/tests/data.test.js
+++ b/tests/data.test.js
@@ -0,0 +1,67 @@
+const { describe, it, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { migrateDataDir } = require("../src/data");
+
+describe("data module", () => {
+  let tmpDir;
+
+  afterEach(() => {
+    if (tmpDir && fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  describe("migrateDataDir()", () => {
+    it("does nothing when legacy dir does not exist", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "data-test-"));
+      const dataDir = path.join(tmpDir, "data");
+      // Should not throw
+      migrateDataDir(dataDir, "/nonexistent/legacy");
+      assert.ok(!fs.existsSync(dataDir));
+    });
+
+    it("copies files from legacy dir to data dir", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "data-test-"));
+      const legacyDir = path.join(tmpDir, "legacy");
+      const dataDir = path.join(tmpDir, "data");
+      fs.mkdirSync(legacyDir);
+      fs.writeFileSync(path.join(legacyDir, "settings.json"), '{"key":"value"}');
+
+      migrateDataDir(dataDir, legacyDir);
+
+      assert.ok(fs.existsSync(path.join(dataDir, "settings.json")));
+      const content = fs.readFileSync(path.join(dataDir, "settings.json"), "utf8");
+      assert.strictEqual(content, '{"key":"value"}');
+    });
+
+    it("does not overwrite existing files in data dir", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "data-test-"));
+      const legacyDir = path.join(tmpDir, "legacy");
+      const dataDir = path.join(tmpDir, "data");
+      fs.mkdirSync(legacyDir);
+      fs.mkdirSync(dataDir);
+      fs.writeFileSync(path.join(legacyDir, "config.json"), "legacy");
+      fs.writeFileSync(path.join(dataDir, "config.json"), "current");
+
+      migrateDataDir(dataDir, legacyDir);
+
+      const content = fs.readFileSync(path.join(dataDir, "config.json"), "utf8");
+      assert.strictEqual(content, "current");
+    });
+
+    it("does nothing when legacy dir is empty", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "data-test-"));
+      const legacyDir = path.join(tmpDir, "legacy");
+      const dataDir = path.join(tmpDir, "data");
+      fs.mkdirSync(legacyDir);
+
+      migrateDataDir(dataDir, legacyDir);
+
+      // data dir should not be created for empty legacy
+      // Actually the function creates it, let's check it doesn't crash
+    });
+  });
+});
--- a/tests/iostat-leak.test.js
+++ b/tests/iostat-leak.test.js
@@ -0,0 +1,127 @@
+const { describe, it, before, after } = require("node:test");
+const assert = require("node:assert");
+const http = require("http");
+const { spawn, execSync } = require("child_process");
+const os = require("os");
+const path = require("path");
+
+const isLinux = os.platform() === "linux";
+
+/**
+ * Count running iostat processes using pgrep (avoids self-match issues with ps|grep).
+ * Returns 0 if pgrep finds no matches (exit code 1).
+ */
+function countIostatProcesses() {
+  try {
+    return parseInt(execSync("pgrep -c iostat", { encoding: "utf8" }).trim(), 10) || 0;
+  } catch {
+    return 0; // pgrep exits 1 when no matches
+  }
+}
+
+/**
+ * Simple HTTP GET helper that returns a promise
+ */
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    http
+      .get(url, (res) => {
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () =>
+          resolve({
+            statusCode: res.statusCode,
+            headers: res.headers,
+            body,
+          }),
+        );
+      })
+      .on("error", reject);
+  });
+}
+
+describe(
+  "iostat resource leak (#31)",
+  { skip: !isLinux && "Linux-only test", timeout: 90000 },
+  () => {
+    const TEST_PORT = 10000 + Math.floor(Math.random() * 50000);
+    let serverProcess;
+
+    before(async () => {
+      // Kill any stale iostat processes from prior runs
+      try {
+        execSync("pkill iostat 2>/dev/null", { encoding: "utf8" });
+      } catch {
+        // No stale processes — expected
+      }
+
+      // Start the server
+      serverProcess = spawn(process.execPath, [path.join(__dirname, "..", "lib", "server.js")], {
+        env: { ...process.env, PORT: String(TEST_PORT) },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      // Wait for server to be ready by polling the health endpoint
+      const maxWait = 15000;
+      const start = Date.now();
+
+      while (Date.now() - start < maxWait) {
+        try {
+          await httpGet(`http://localhost:${TEST_PORT}/api/health`);
+          return; // Server is ready
+        } catch {
+          await new Promise((resolve) => setTimeout(resolve, 200));
+        }
+      }
+
+      throw new Error(`Server did not start within ${maxWait}ms`);
+    });
+
+    after(() => {
+      if (serverProcess) {
+        serverProcess.kill("SIGTERM");
+        serverProcess = null;
+      }
+    });
+
+    it("does not accumulate iostat processes over multiple vitals refreshes", async () => {
+      // Vitals refresh every 30s (plus once at startup). Wait long enough for
+      // at least two cycles, then sample multiple times to catch the peak count.
+      // With the fix, each iostat exits in ~1s so we should never see more than
+      // 1 running at a time. Without the fix, each cycle spawns an immortal
+      // process and the count grows unboundedly.
+      await new Promise((resolve) => setTimeout(resolve, 35000));
+
+      // Sample several times over 5s to get a reliable peak
+      let peak = 0;
+      for (let i = 0; i < 5; i++) {
+        peak = Math.max(peak, countIostatProcesses());
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+
+      // At most 2 concurrent: one finishing from a prior cycle, one just started
+      assert.ok(peak <= 2, `Peak iostat process count was ${peak} — leak detected`);
+    });
+
+    it("leaves no orphaned iostat processes after shutdown", async () => {
+      // Snapshot before shutdown (other test suites may also have servers running
+      // that spawn iostat, so we compare relative to this baseline)
+      const baseline = countIostatProcesses();
+
+      // Kill the server
+      if (serverProcess) {
+        serverProcess.kill("SIGTERM");
+        serverProcess = null;
+      }
+
+      // Give processes time to clean up (iostat -d 1 2 takes ~1s, plus timeout margin)
+      await new Promise((resolve) => setTimeout(resolve, 6000));
+
+      const remaining = countIostatProcesses();
+      assert.ok(
+        remaining <= baseline,
+        `iostat count grew after shutdown: ${baseline} before, ${remaining} after`,
+      );
+    });
+  },
+);
--- a/tests/jobs.test.js
+++ b/tests/jobs.test.js
@@ -0,0 +1,98 @@
+const { describe, it, afterEach } = require("node:test");
+const assert = require("node:assert");
+
+// We import the module to test its exports and pure functions.
+// The jobs module relies on dynamic ESM import of external jobs API,
+// so we focus on testing what's available without that dependency.
+const { handleJobsRequest, isJobsRoute, _resetForTesting } = require("../src/jobs");
+
+describe("jobs module", () => {
+  describe("exports", () => {
+    it("exports handleJobsRequest function", () => {
+      assert.strictEqual(typeof handleJobsRequest, "function");
+    });
+
+    it("exports isJobsRoute function", () => {
+      assert.strictEqual(typeof isJobsRoute, "function");
+    });
+  });
+
+  describe("isJobsRoute()", () => {
+    it("returns true for /api/jobs", () => {
+      assert.strictEqual(isJobsRoute("/api/jobs"), true);
+    });
+
+    it("returns true for /api/jobs/some-job", () => {
+      assert.strictEqual(isJobsRoute("/api/jobs/some-job"), true);
+    });
+
+    it("returns true for /api/jobs/some-job/history", () => {
+      assert.strictEqual(isJobsRoute("/api/jobs/some-job/history"), true);
+    });
+
+    it("returns true for /api/jobs/scheduler/status", () => {
+      assert.strictEqual(isJobsRoute("/api/jobs/scheduler/status"), true);
+    });
+
+    it("returns true for /api/jobs/stats", () => {
+      assert.strictEqual(isJobsRoute("/api/jobs/stats"), true);
+    });
+
+    it("returns false for /api/health", () => {
+      assert.strictEqual(isJobsRoute("/api/health"), false);
+    });
+
+    it("returns false for /api/sessions", () => {
+      assert.strictEqual(isJobsRoute("/api/sessions"), false);
+    });
+
+    it("returns false for /api/job (no trailing s)", () => {
+      assert.strictEqual(isJobsRoute("/api/job"), false);
+    });
+
+    it("returns false for empty string", () => {
+      assert.strictEqual(isJobsRoute(""), false);
+    });
+
+    it("returns false for /jobs (no /api prefix)", () => {
+      assert.strictEqual(isJobsRoute("/jobs"), false);
+    });
+  });
+
+  describe("handleJobsRequest()", () => {
+    afterEach(() => {
+      // Reset API state after each test
+      _resetForTesting();
+    });
+
+    it("returns 500 when jobs API is not available", async () => {
+      // Force API to be unavailable for this test
+      _resetForTesting({ forceUnavailable: true });
+
+      let statusCode = null;
+      let body = null;
+
+      const mockRes = {
+        writeHead(code, _headers) {
+          statusCode = code;
+        },
+        end(data) {
+          body = data;
+        },
+      };
+
+      const mockReq = {};
+      const query = new URLSearchParams();
+
+      await handleJobsRequest(mockReq, mockRes, "/api/jobs", query, "GET");
+
+      assert.strictEqual(statusCode, 500);
+      const parsed = JSON.parse(body);
+      assert.ok(parsed.error, "should have an error message");
+      assert.ok(
+        parsed.error.includes("not available"),
+        `Error should mention not available: ${parsed.error}`,
+      );
+    });
+  });
+});
--- a/tests/llm-usage.test.js
+++ b/tests/llm-usage.test.js
@@ -0,0 +1,88 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { transformLiveUsageData } = require("../src/llm-usage");
+
+describe("llm-usage module", () => {
+  describe("transformLiveUsageData()", () => {
+    it("transforms valid usage data with anthropic provider", () => {
+      const usage = {
+        providers: [
+          {
+            provider: "anthropic",
+            windows: [
+              { label: "5h", usedPercent: 25, resetAt: Date.now() + 3600000 },
+              { label: "Week", usedPercent: 10, resetAt: Date.now() + 86400000 * 3 },
+              { label: "Sonnet", usedPercent: 5, resetAt: Date.now() + 86400000 * 5 },
+            ],
+          },
+        ],
+      };
+
+      const result = transformLiveUsageData(usage);
+      assert.strictEqual(result.source, "live");
+      assert.strictEqual(result.claude.session.usedPct, 25);
+      assert.strictEqual(result.claude.session.remainingPct, 75);
+      assert.strictEqual(result.claude.weekly.usedPct, 10);
+      assert.strictEqual(result.claude.sonnet.usedPct, 5);
+    });
+
+    it("handles auth error from provider", () => {
+      const usage = {
+        providers: [{ provider: "anthropic", error: "403 Forbidden" }],
+      };
+
+      const result = transformLiveUsageData(usage);
+      assert.strictEqual(result.source, "error");
+      assert.strictEqual(result.errorType, "auth");
+      assert.ok(result.error.includes("403"));
+      assert.strictEqual(result.claude.session.usedPct, null);
+    });
+
+    it("handles missing windows gracefully", () => {
+      const usage = { providers: [{ provider: "anthropic", windows: [] }] };
+      const result = transformLiveUsageData(usage);
+      assert.strictEqual(result.source, "live");
+      assert.strictEqual(result.claude.session.usedPct, 0);
+      assert.strictEqual(result.claude.weekly.usedPct, 0);
+    });
+
+    it("handles codex provider data", () => {
+      const usage = {
+        providers: [
+          { provider: "anthropic", windows: [] },
+          {
+            provider: "openai-codex",
+            windows: [
+              { label: "5h", usedPercent: 30 },
+              { label: "Day", usedPercent: 15 },
+            ],
+          },
+        ],
+      };
+
+      const result = transformLiveUsageData(usage);
+      assert.strictEqual(result.codex.usage5hPct, 30);
+      assert.strictEqual(result.codex.usageDayPct, 15);
+    });
+
+    it("handles missing providers gracefully", () => {
+      const usage = { providers: [] };
+      const result = transformLiveUsageData(usage);
+      assert.strictEqual(result.source, "live");
+      assert.strictEqual(result.codex.usage5hPct, 0);
+    });
+
+    it("formats reset time correctly", () => {
+      const usage = {
+        providers: [
+          {
+            provider: "anthropic",
+            windows: [{ label: "5h", usedPercent: 50, resetAt: Date.now() + 30 * 60000 }],
+          },
+        ],
+      };
+      const result = transformLiveUsageData(usage);
+      assert.ok(result.claude.session.resetsIn.includes("m"));
+    });
+  });
+});
--- a/tests/openclaw.test.js
+++ b/tests/openclaw.test.js
@@ -0,0 +1,39 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { extractJSON } = require("../src/openclaw");
+
+describe("openclaw module", () => {
+  describe("extractJSON()", () => {
+    it("returns null for null input", () => {
+      assert.strictEqual(extractJSON(null), null);
+    });
+
+    it("returns null for empty string", () => {
+      assert.strictEqual(extractJSON(""), null);
+    });
+
+    it("returns null for non-JSON text", () => {
+      assert.strictEqual(extractJSON("no json here"), null);
+    });
+
+    it("extracts JSON object from clean input", () => {
+      const result = extractJSON('{"key": "value"}');
+      assert.strictEqual(result, '{"key": "value"}');
+    });
+
+    it("extracts JSON array from clean input", () => {
+      const result = extractJSON("[1, 2, 3]");
+      assert.strictEqual(result, "[1, 2, 3]");
+    });
+
+    it("strips non-JSON prefix from output", () => {
+      const result = extractJSON('Some warning text\n{"key": "value"}');
+      assert.strictEqual(result, '{"key": "value"}');
+    });
+
+    it("handles prefix with special characters", () => {
+      const result = extractJSON('Doctor warnings: OK\n[{"id": 1}]');
+      assert.strictEqual(result, '[{"id": 1}]');
+    });
+  });
+});
--- a/tests/privacy.test.js
+++ b/tests/privacy.test.js
@@ -0,0 +1,78 @@
+const { describe, it, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { loadPrivacySettings, savePrivacySettings } = require("../src/privacy");
+
+describe("privacy module", () => {
+  let tmpDir;
+
+  afterEach(() => {
+    if (tmpDir && fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  describe("loadPrivacySettings()", () => {
+    it("returns defaults when file does not exist", () => {
+      const settings = loadPrivacySettings("/nonexistent/path");
+      assert.strictEqual(settings.version, 1);
+      assert.deepStrictEqual(settings.hiddenTopics, []);
+      assert.deepStrictEqual(settings.hiddenSessions, []);
+      assert.deepStrictEqual(settings.hiddenCrons, []);
+      assert.strictEqual(settings.hideHostname, false);
+      assert.strictEqual(settings.updatedAt, null);
+    });
+
+    it("loads settings from file", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "privacy-test-"));
+      const data = {
+        version: 1,
+        hiddenTopics: ["secret"],
+        hiddenSessions: [],
+        hiddenCrons: [],
+        hideHostname: true,
+        updatedAt: "2024-01-01",
+      };
+      fs.writeFileSync(path.join(tmpDir, "privacy-settings.json"), JSON.stringify(data));
+      const settings = loadPrivacySettings(tmpDir);
+      assert.deepStrictEqual(settings.hiddenTopics, ["secret"]);
+      assert.strictEqual(settings.hideHostname, true);
+    });
+  });
+
+  describe("savePrivacySettings()", () => {
+    it("saves settings to file", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "privacy-test-"));
+      const data = {
+        version: 1,
+        hiddenTopics: ["topic1"],
+        hiddenSessions: [],
+        hiddenCrons: [],
+        hideHostname: false,
+      };
+      const result = savePrivacySettings(tmpDir, data);
+      assert.strictEqual(result, true);
+
+      const saved = JSON.parse(fs.readFileSync(path.join(tmpDir, "privacy-settings.json"), "utf8"));
+      assert.deepStrictEqual(saved.hiddenTopics, ["topic1"]);
+      assert.ok(saved.updatedAt);
+    });
+
+    it("creates directory if it does not exist", () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "privacy-test-"));
+      const nestedDir = path.join(tmpDir, "nested", "dir");
+      const data = {
+        version: 1,
+        hiddenTopics: [],
+        hiddenSessions: [],
+        hiddenCrons: [],
+        hideHostname: false,
+      };
+      const result = savePrivacySettings(nestedDir, data);
+      assert.strictEqual(result, true);
+      assert.ok(fs.existsSync(path.join(nestedDir, "privacy-settings.json")));
+    });
+  });
+});
--- a/tests/server.test.js
+++ b/tests/server.test.js
@@ -0,0 +1,95 @@
+const { describe, it, before, after } = require("node:test");
+const assert = require("node:assert");
+const http = require("http");
+const { spawn } = require("child_process");
+const path = require("path");
+
+describe("server", () => {
+  // Use a random high port to avoid conflicts
+  const TEST_PORT = 10000 + Math.floor(Math.random() * 50000);
+  let serverProcess;
+
+  before(async () => {
+    // Start the server as a child process with a custom PORT
+    serverProcess = spawn(process.execPath, [path.join(__dirname, "..", "lib", "server.js")], {
+      env: { ...process.env, PORT: String(TEST_PORT) },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    // Wait for server to be ready by polling the health endpoint
+    const maxWait = 10000;
+    const start = Date.now();
+
+    while (Date.now() - start < maxWait) {
+      try {
+        await httpGet(`http://localhost:${TEST_PORT}/api/health`);
+        return; // Server is ready
+      } catch (_e) {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      }
+    }
+
+    throw new Error(`Server did not start within ${maxWait}ms`);
+  });
+
+  after(() => {
+    if (serverProcess) {
+      serverProcess.kill("SIGTERM");
+      serverProcess = null;
+    }
+  });
+
+  it("responds to /api/health with status ok", async () => {
+    const { statusCode, body } = await httpGet(`http://localhost:${TEST_PORT}/api/health`);
+    assert.strictEqual(statusCode, 200);
+    const data = JSON.parse(body);
+    assert.strictEqual(data.status, "ok");
+    assert.strictEqual(data.port, TEST_PORT);
+    assert.ok(data.timestamp, "should have timestamp");
+  });
+
+  it("responds to /api/about with project info", async () => {
+    const { statusCode, body } = await httpGet(`http://localhost:${TEST_PORT}/api/about`);
+    assert.strictEqual(statusCode, 200);
+    const data = JSON.parse(body);
+    assert.ok(data.name || data.version, "should have project info");
+  });
+
+  it("returns JSON content type for API endpoints", async () => {
+    const { headers } = await httpGet(`http://localhost:${TEST_PORT}/api/health`);
+    assert.ok(
+      headers["content-type"].includes("application/json"),
+      `Expected JSON content type, got: ${headers["content-type"]}`,
+    );
+  });
+
+  it("serves static files for root path", async () => {
+    const { statusCode } = await httpGet(`http://localhost:${TEST_PORT}/`);
+    // Should return 200 (index.html) or similar
+    assert.ok(
+      statusCode >= 200 && statusCode < 500,
+      `Expected 2xx/3xx/4xx status for root, got: ${statusCode}`,
+    );
+  });
+});
+
+/**
+ * Simple HTTP GET helper that returns a promise
+ */
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    http
+      .get(url, (res) => {
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () =>
+          resolve({
+            statusCode: res.statusCode,
+            headers: res.headers,
+            body,
+          }),
+        );
+      })
+      .on("error", reject);
+  });
+}
--- a/tests/tokens.test.js
+++ b/tests/tokens.test.js
@@ -0,0 +1,80 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { TOKEN_RATES, emptyUsageBucket, calculateCostForBucket } = require("../src/tokens");
+
+describe("tokens module", () => {
+  describe("TOKEN_RATES", () => {
+    it("has input rate", () => {
+      assert.strictEqual(TOKEN_RATES.input, 15.0);
+    });
+
+    it("has output rate", () => {
+      assert.strictEqual(TOKEN_RATES.output, 75.0);
+    });
+
+    it("has cache read rate", () => {
+      assert.strictEqual(TOKEN_RATES.cacheRead, 1.5);
+    });
+
+    it("has cache write rate", () => {
+      assert.strictEqual(TOKEN_RATES.cacheWrite, 18.75);
+    });
+  });
+
+  describe("emptyUsageBucket()", () => {
+    it("returns object with zero values", () => {
+      const bucket = emptyUsageBucket();
+      assert.strictEqual(bucket.input, 0);
+      assert.strictEqual(bucket.output, 0);
+      assert.strictEqual(bucket.cacheRead, 0);
+      assert.strictEqual(bucket.cacheWrite, 0);
+      assert.strictEqual(bucket.cost, 0);
+      assert.strictEqual(bucket.requests, 0);
+    });
+
+    it("returns a new object each time", () => {
+      const a = emptyUsageBucket();
+      const b = emptyUsageBucket();
+      assert.notStrictEqual(a, b);
+      a.input = 100;
+      assert.strictEqual(b.input, 0);
+    });
+  });
+
+  describe("calculateCostForBucket()", () => {
+    it("calculates cost for given token counts", () => {
+      const bucket = {
+        input: 1_000_000,
+        output: 1_000_000,
+        cacheRead: 1_000_000,
+        cacheWrite: 1_000_000,
+      };
+      const result = calculateCostForBucket(bucket);
+      assert.strictEqual(result.inputCost, 15.0);
+      assert.strictEqual(result.outputCost, 75.0);
+      assert.strictEqual(result.cacheReadCost, 1.5);
+      assert.strictEqual(result.cacheWriteCost, 18.75);
+      assert.strictEqual(result.totalCost, 15.0 + 75.0 + 1.5 + 18.75);
+    });
+
+    it("returns zero cost for empty bucket", () => {
+      const bucket = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+      const result = calculateCostForBucket(bucket);
+      assert.strictEqual(result.totalCost, 0);
+    });
+
+    it("accepts custom rates", () => {
+      const bucket = { input: 1_000_000, output: 0, cacheRead: 0, cacheWrite: 0 };
+      const customRates = { input: 10, output: 0, cacheRead: 0, cacheWrite: 0 };
+      const result = calculateCostForBucket(bucket, customRates);
+      assert.strictEqual(result.inputCost, 10.0);
+      assert.strictEqual(result.totalCost, 10.0);
+    });
+
+    it("calculates proportionally for partial token counts", () => {
+      const bucket = { input: 500_000, output: 0, cacheRead: 0, cacheWrite: 0 };
+      const result = calculateCostForBucket(bucket);
+      assert.strictEqual(result.inputCost, 7.5);
+    });
+  });
+});
--- a/tests/topic-classifier.test.js
+++ b/tests/topic-classifier.test.js
@@ -0,0 +1,263 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+
+// Import the module under test (avoid side-effect heavy parts by importing functions directly)
+const {
+  classifyAndSuggestTopics,
+  extractKeyTerms,
+  matchTopics,
+  CONFIG,
+  TOPIC_PATTERNS,
+} = require("../scripts/topic-classifier");
+
+describe("topic-classifier module", () => {
+  describe("exports", () => {
+    it("exports classifyAndSuggestTopics function", () => {
+      assert.strictEqual(typeof classifyAndSuggestTopics, "function");
+    });
+
+    it("exports extractKeyTerms function", () => {
+      assert.strictEqual(typeof extractKeyTerms, "function");
+    });
+
+    it("exports matchTopics function", () => {
+      assert.strictEqual(typeof matchTopics, "function");
+    });
+
+    it("exports CONFIG object", () => {
+      assert.ok(CONFIG, "CONFIG should be exported");
+      assert.strictEqual(typeof CONFIG.matchThreshold, "number");
+      assert.strictEqual(typeof CONFIG.minTermScore, "number");
+    });
+
+    it("exports TOPIC_PATTERNS object", () => {
+      assert.ok(TOPIC_PATTERNS, "TOPIC_PATTERNS should be exported");
+      assert.strictEqual(typeof TOPIC_PATTERNS, "object");
+      assert.ok(Object.keys(TOPIC_PATTERNS).length > 0, "should have patterns");
+    });
+  });
+
+  describe("extractKeyTerms()", () => {
+    it("returns an array", () => {
+      const result = extractKeyTerms("some text about kubernetes deployment");
+      assert.ok(Array.isArray(result));
+    });
+
+    it("returns empty array for empty string", () => {
+      const result = extractKeyTerms("");
+      assert.deepStrictEqual(result, []);
+    });
+
+    it("returns empty array for null input", () => {
+      const result = extractKeyTerms(null);
+      assert.deepStrictEqual(result, []);
+    });
+
+    it("returns empty array for undefined input", () => {
+      const result = extractKeyTerms(undefined);
+      assert.deepStrictEqual(result, []);
+    });
+
+    it("filters out stop words", () => {
+      const result = extractKeyTerms("the and or but kubernetes kubernetes deployment deployment");
+      const terms = result.map((t) => t.term);
+      assert.ok(!terms.includes("the"));
+      assert.ok(!terms.includes("and"));
+    });
+
+    it("each result has term and score properties", () => {
+      const result = extractKeyTerms(
+        "docker container docker container kubernetes kubernetes pod pod",
+      );
+      for (const entry of result) {
+        assert.ok("term" in entry, `entry should have 'term' property: ${JSON.stringify(entry)}`);
+        assert.ok("score" in entry, `entry should have 'score' property: ${JSON.stringify(entry)}`);
+        assert.strictEqual(typeof entry.term, "string");
+        assert.strictEqual(typeof entry.score, "number");
+      }
+    });
+
+    it("scores are sorted descending", () => {
+      const result = extractKeyTerms(
+        "kubernetes kubernetes kubernetes docker docker terraform terraform terraform terraform deploy deploy deploy deploy",
+      );
+      for (let i = 1; i < result.length; i++) {
+        assert.ok(
+          result[i - 1].score >= result[i].score,
+          `Score at index ${i - 1} (${result[i - 1].score}) should be >= score at index ${i} (${result[i].score})`,
+        );
+      }
+    });
+
+    it("strips code blocks from text", () => {
+      const result = extractKeyTerms(
+        "kubernetes kubernetes ```const x = kubernetes;``` kubernetes deployment deployment",
+      );
+      // The code block content should be stripped, so only tokens from outside code blocks
+      const terms = result.map((t) => t.term);
+      // 'const' from code block should not appear
+      assert.ok(!terms.includes("const"), "should not include tokens from code blocks");
+    });
+
+    it("strips URLs from text", () => {
+      const result = extractKeyTerms(
+        "kubernetes kubernetes https://example.com/kubernetes kubernetes deployment deployment",
+      );
+      const terms = result.map((t) => t.term);
+      assert.ok(!terms.includes("https"), "should not include URL protocol as token");
+    });
+  });
+
+  describe("matchTopics()", () => {
+    const existingTopics = [
+      "version-control",
+      "deployment",
+      "database",
+      "testing",
+      "ai-ml",
+      "containers",
+    ];
+
+    it("returns an array", () => {
+      const result = matchTopics("some text about deploying code", existingTopics);
+      assert.ok(Array.isArray(result));
+    });
+
+    it("returns empty array for empty text", () => {
+      const result = matchTopics("", existingTopics);
+      assert.deepStrictEqual(result, []);
+    });
+
+    it("matches deployment topic for deploy-related text", () => {
+      const result = matchTopics(
+        "deploying to production staging pipeline deploy deploy",
+        existingTopics,
+      );
+      const topics = result.map((r) => r.topic);
+      assert.ok(
+        topics.includes("deployment"),
+        `Expected 'deployment' in ${JSON.stringify(topics)}`,
+      );
+    });
+
+    it("matches database topic for SQL-related text", () => {
+      const result = matchTopics(
+        "postgres database query sql optimization postgres query",
+        existingTopics,
+      );
+      const topics = result.map((r) => r.topic);
+      assert.ok(topics.includes("database"), `Expected 'database' in ${JSON.stringify(topics)}`);
+    });
+
+    it("matches containers topic for docker/k8s text", () => {
+      const result = matchTopics(
+        "docker container kubernetes pod k8s container docker",
+        existingTopics,
+      );
+      const topics = result.map((r) => r.topic);
+      assert.ok(
+        topics.includes("containers"),
+        `Expected 'containers' in ${JSON.stringify(topics)}`,
+      );
+    });
+
+    it("results have topic and confidence properties", () => {
+      const result = matchTopics("git commit branch merge pull push github", existingTopics);
+      for (const entry of result) {
+        assert.ok("topic" in entry);
+        assert.ok("confidence" in entry);
+        assert.strictEqual(typeof entry.confidence, "number");
+        assert.ok(entry.confidence >= 0 && entry.confidence <= 1);
+      }
+    });
+
+    it("results are sorted by confidence descending", () => {
+      const result = matchTopics(
+        "git commit branch merge deploy production staging",
+        existingTopics,
+      );
+      for (let i = 1; i < result.length; i++) {
+        assert.ok(
+          result[i - 1].confidence >= result[i].confidence,
+          `Confidence at index ${i - 1} should be >= index ${i}`,
+        );
+      }
+    });
+  });
+
+  describe("classifyAndSuggestTopics()", () => {
+    it("returns object with matched, suggested, keyTerms", () => {
+      const result = classifyAndSuggestTopics(
+        "kubernetes deployment docker container kubernetes docker deployment",
+        ["containers", "deployment"],
+        { persist: false },
+      );
+      assert.ok(Array.isArray(result.matched));
+      assert.ok(Array.isArray(result.suggested));
+      assert.ok(Array.isArray(result.keyTerms));
+    });
+
+    it("returns empty results for very short text", () => {
+      const result = classifyAndSuggestTopics("hi", [], { persist: false });
+      assert.deepStrictEqual(result.matched, []);
+      assert.deepStrictEqual(result.suggested, []);
+      assert.deepStrictEqual(result.keyTerms, []);
+    });
+
+    it("returns empty results for null input", () => {
+      const result = classifyAndSuggestTopics(null, [], { persist: false });
+      assert.deepStrictEqual(result.matched, []);
+    });
+
+    it("handles array transcript input", () => {
+      const transcript = [
+        "kubernetes deployment docker container",
+        "kubernetes docker deployment staging production",
+        "more kubernetes docker content here deploy",
+      ];
+      const result = classifyAndSuggestTopics(transcript, ["deployment"], {
+        persist: false,
+      });
+      assert.ok(Array.isArray(result.matched));
+    });
+
+    it("handles array of message objects", () => {
+      const transcript = [
+        { text: "kubernetes deployment docker container" },
+        { text: "kubernetes docker deployment staging" },
+        { text: "more content about kubernetes docker" },
+      ];
+      const result = classifyAndSuggestTopics(transcript, ["deployment"], {
+        persist: false,
+      });
+      assert.ok(Array.isArray(result.matched));
+    });
+
+    it("provides confidence score", () => {
+      const result = classifyAndSuggestTopics(
+        "kubernetes deployment docker container kubernetes docker deployment pod staging",
+        ["containers", "deployment"],
+        { persist: false },
+      );
+      assert.strictEqual(typeof result.confidence, "number");
+    });
+  });
+
+  describe("TOPIC_PATTERNS", () => {
+    it("maps git to version-control", () => {
+      assert.strictEqual(TOPIC_PATTERNS["git"], "version-control");
+    });
+
+    it("maps docker to containers", () => {
+      assert.strictEqual(TOPIC_PATTERNS["docker"], "containers");
+    });
+
+    it("maps claude to ai-ml", () => {
+      assert.strictEqual(TOPIC_PATTERNS["claude"], "ai-ml");
+    });
+
+    it("maps postgres to database", () => {
+      assert.strictEqual(TOPIC_PATTERNS["postgres"], "database");
+    });
+  });
+});
--- a/tests/topics.test.js
+++ b/tests/topics.test.js
@@ -0,0 +1,85 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { TOPIC_PATTERNS, detectTopics } = require("../src/topics");
+
+describe("topics module", () => {
+  describe("TOPIC_PATTERNS", () => {
+    it("is an object with topic keys", () => {
+      assert.strictEqual(typeof TOPIC_PATTERNS, "object");
+      assert.ok(Object.keys(TOPIC_PATTERNS).length > 0);
+    });
+
+    it("each topic has an array of keywords", () => {
+      for (const [topic, keywords] of Object.entries(TOPIC_PATTERNS)) {
+        assert.ok(Array.isArray(keywords), `${topic} should have array of keywords`);
+        assert.ok(keywords.length > 0, `${topic} should have at least one keyword`);
+      }
+    });
+
+    it("contains expected topics", () => {
+      const topics = Object.keys(TOPIC_PATTERNS);
+      assert.ok(topics.includes("dashboard"));
+      assert.ok(topics.includes("coding"));
+      assert.ok(topics.includes("git"));
+      assert.ok(topics.includes("Slack"));
+    });
+  });
+
+  describe("detectTopics()", () => {
+    it("returns empty array for null input", () => {
+      assert.deepStrictEqual(detectTopics(null), []);
+    });
+
+    it("returns empty array for empty string", () => {
+      assert.deepStrictEqual(detectTopics(""), []);
+    });
+
+    it("returns empty array for undefined", () => {
+      assert.deepStrictEqual(detectTopics(undefined), []);
+    });
+
+    it("detects git topic from git-related text", () => {
+      const topics = detectTopics("git commit branch merge push pull");
+      assert.ok(topics.includes("git"), `Expected 'git' in ${JSON.stringify(topics)}`);
+    });
+
+    it("detects coding topic", () => {
+      const topics = detectTopics("debug the function and fix the error in the code");
+      assert.ok(topics.includes("coding"), `Expected 'coding' in ${JSON.stringify(topics)}`);
+    });
+
+    it("detects Slack topic", () => {
+      const topics = detectTopics("send a slack message to the channel thread");
+      assert.ok(topics.includes("Slack"), `Expected 'Slack' in ${JSON.stringify(topics)}`);
+    });
+
+    it("returns topics sorted by score descending", () => {
+      // Heavily git-focused text with a minor coding mention
+      const topics = detectTopics("git commit branch merge push pull repository github code");
+      if (topics.length >= 2) {
+        // git should score higher than coding since more keywords match
+        const gitIdx = topics.indexOf("git");
+        assert.ok(gitIdx >= 0, "git should be detected");
+      }
+    });
+
+    it("returns array of strings", () => {
+      const topics = detectTopics("kubernetes docker container deploy");
+      assert.ok(Array.isArray(topics));
+      topics.forEach((t) => assert.strictEqual(typeof t, "string"));
+    });
+
+    it("detects scheduling topic", () => {
+      const topics = detectTopics("set up a cron schedule timer for periodic interval");
+      assert.ok(
+        topics.includes("scheduling"),
+        `Expected 'scheduling' in ${JSON.stringify(topics)}`,
+      );
+    });
+
+    it("detects subagent topic", () => {
+      const topics = detectTopics("spawn a subagent to delegate the work in parallel");
+      assert.ok(topics.includes("subagent"), `Expected 'subagent' in ${JSON.stringify(topics)}`);
+    });
+  });
+});
--- a/tests/utils.test.js
+++ b/tests/utils.test.js
@@ -0,0 +1,85 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const { formatBytes, formatTimeAgo, formatNumber, formatTokens } = require("../src/utils");
+
+describe("utils module", () => {
+  describe("formatBytes()", () => {
+    it("formats bytes", () => {
+      assert.strictEqual(formatBytes(500), "500 B");
+    });
+
+    it("formats kilobytes", () => {
+      assert.strictEqual(formatBytes(1024), "1.0 KB");
+      assert.strictEqual(formatBytes(1536), "1.5 KB");
+    });
+
+    it("formats megabytes", () => {
+      assert.strictEqual(formatBytes(1048576), "1.0 MB");
+    });
+
+    it("formats gigabytes", () => {
+      assert.strictEqual(formatBytes(1073741824), "1.0 GB");
+    });
+
+    it("formats terabytes", () => {
+      assert.strictEqual(formatBytes(1099511627776), "1.0 TB");
+    });
+  });
+
+  describe("formatTimeAgo()", () => {
+    it("formats just now", () => {
+      assert.strictEqual(formatTimeAgo(new Date()), "just now");
+    });
+
+    it("formats minutes ago", () => {
+      const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000);
+      assert.strictEqual(formatTimeAgo(fiveMinAgo), "5m ago");
+    });
+
+    it("formats hours ago", () => {
+      const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000);
+      assert.strictEqual(formatTimeAgo(twoHoursAgo), "2h ago");
+    });
+
+    it("formats days ago", () => {
+      const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000);
+      assert.strictEqual(formatTimeAgo(threeDaysAgo), "3d ago");
+    });
+  });
+
+  describe("formatNumber()", () => {
+    it("formats with 2 decimal places", () => {
+      assert.strictEqual(formatNumber(1234.5), "1,234.50");
+    });
+
+    it("formats zero", () => {
+      assert.strictEqual(formatNumber(0), "0.00");
+    });
+
+    it("formats small numbers", () => {
+      assert.strictEqual(formatNumber(0.1), "0.10");
+    });
+  });
+
+  describe("formatTokens()", () => {
+    it("formats millions", () => {
+      assert.strictEqual(formatTokens(1500000), "1.5M");
+    });
+
+    it("formats thousands", () => {
+      assert.strictEqual(formatTokens(2500), "2.5k");
+    });
+
+    it("formats small numbers as-is", () => {
+      assert.strictEqual(formatTokens(42), "42");
+    });
+
+    it("formats exactly 1M", () => {
+      assert.strictEqual(formatTokens(1000000), "1.0M");
+    });
+
+    it("formats exactly 1k", () => {
+      assert.strictEqual(formatTokens(1000), "1.0k");
+    });
+  });
+});