@mingxy/cerebro 1.20.3 → 1.20.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingxy/cerebro",
-  "version": "1.20.3",
+  "version": "1.20.5",
   "description": "Cerebro persistent memory plugin for OpenCode — auto-recall, auto-capture, 9 memory tools with clustering, project-scoped memory isolation",
   "type": "module",
   "main": "src/index.ts",

package/src/web-server.ts

@@ -1,21 +1,17 @@
-/**
- * web-server.ts — Cerebro Web Server Manager (spawn mode)
- *
- * 不再直接创建 HTTP server，而是 fork 独立子进程 (web-server-child.ts)。
- * 多窗口共享一个 server，任一窗口关闭不影响其他窗口。
- * 子进程通过心跳文件 mtime 探测 plugin 存活状态，全部退出后自动关闭。
- */
-import { fork } from "node:child_process";
+import * as http from "node:http";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as os from "node:os";
 import { fileURLToPath } from "node:url";
 import { logInfo, logWarn, logError } from "./logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// ── Types ────────────────────────────────────────────────────────────────
+const DEFAULT_PORT = 5212;
+const TAKEOVER_INTERVAL_MS = 5000;
+const TAKEOVER_JITTER_MIN_MS = 500;
+const TAKEOVER_JITTER_RANGE_MS = 1000;
+const TAKEOVER_MAX_RETRIES = 60;
 
 export interface WebServerConfig {
   apiUrl: string;
@@ -24,32 +20,40 @@ export interface WebServerConfig {
 
 export interface WebServerHandle {
   address(): { port: number; family: string; address: string } | string | null;
+  isOwner(): boolean;
+  stop(): Promise<void>;
 }
 
-// ── Helpers ──────────────────────────────────────────────────────────────
-
-/** Touch a file — update mtime or create if missing */
-function touchFile(filePath: string): void {
-  try {
-    fs.utimesSync(filePath, new Date(), new Date());
-  } catch {
-    try {
-      fs.writeFileSync(filePath, "");
-    } catch { /* ignore */ }
-  }
-}
-
-/** Check if a process with the given PID is still running */
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".webp": "image/webp",
+  ".map": "application/json",
+};
+
+const COMMON_HEADERS: Record<string, string> = {
+  "X-Content-Type-Options": "nosniff",
+};
+
+function resolveSafe(baseDir: string, pathname: string): string | null {
+  const relative = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+  const resolved = path.resolve(baseDir, relative || ".");
+  if (!resolved.startsWith(baseDir + path.sep) && resolved !== baseDir) {
+    return null;
   }
+  return resolved;
 }
 
-/** Probe an existing server's /health endpoint */
 async function probeExistingServer(port: number): Promise<boolean> {
   try {
     const resp = await fetch(`http://127.0.0.1:${port}/health`);
@@ -57,48 +61,18 @@ async function probeExistingServer(port: number): Promise<boolean> {
       const body = await resp.text();
       return body.includes("cerebro");
     }
-  } catch { /* connection refused → port free */ }
+  } catch {}
   return false;
 }
 
-// ── Start / Stop ─────────────────────────────────────────────────────────
+let activeServerHandle: WebServerHandle | null = null;
+let takeoverTimer: ReturnType<typeof setInterval> | null = null;
+let takeoverRetries = 0;
 
-export async function startWebServer(
-  config: WebServerConfig,
-): Promise<WebServerHandle | null> {
-  const port =
-    config.port || parseInt(process.env.OMEM_LOCAL_PORT || "", 10) || 5212;
-  const pidFilePath = path.join(os.tmpdir(), `cerebro-web-${port}.pid`);
-  const heartbeatFilePath = path.join(
-    os.tmpdir(),
-    `cerebro-web-${port}.heartbeat`,
-  );
-
-  // ── Step 1: 检查端口是否已有 cerebro server ──
-  if (await probeExistingServer(port)) {
-    logInfo("web-server: reusing existing server", { port });
-    return createHandle(port, heartbeatFilePath);
-  }
-
-  // ── Step 2: 检查 PID 文件（可能有其他进程正在 fork） ──
-  try {
-    const pidStr = fs.readFileSync(pidFilePath, "utf-8").trim();
-    const pid = parseInt(pidStr, 10);
-    if (pid > 0 && isProcessAlive(pid)) {
-      // 有其他进程正在 fork 或运行，等待 200ms 后重试
-      await new Promise((r) => setTimeout(r, 200));
-      if (await probeExistingServer(port)) {
-        logInfo("web-server: reusing server after PID check", { port });
-        return createHandle(port, heartbeatFilePath);
-      }
-    } else {
-      // 进程已死亡，清理 PID 文件
-      try { fs.unlinkSync(pidFilePath); } catch { /* ignore */ }
-    }
-  } catch { /* PID 文件不存在，继续 */ }
-
-  // ── Step 3: 检查 web 目录 ──
+export async function startWebServer(config: WebServerConfig): Promise<WebServerHandle | null> {
+  const port = config.port || parseInt(process.env.OMEM_LOCAL_PORT || "", 10) || DEFAULT_PORT;
   const webDir = path.resolve(__dirname, "..", "web");
+
   if (!fs.existsSync(webDir)) {
     logWarn("web-server: web directory not found, skipping", { webDir });
     return null;
@@ -108,96 +82,172 @@ export async function startWebServer(
     return null;
   }
 
-  // ── Step 4: 写 PID 文件（标记正在 fork） ──
-  try {
-    fs.writeFileSync(pidFilePath, String(process.pid));
-  } catch { /* ignore */ }
-
-  // ── Step 5: Fork 子进程 ──
-  // TS runtime: .ts exists; compiled: .js exists
-  const childTs = path.resolve(__dirname, "web-server-child.ts");
-  const childJs = path.resolve(__dirname, "web-server-child.js");
-  const childPath = fs.existsSync(childTs) ? childTs : childJs;
-
-  // Use the same executor as the parent process (tsx, node, etc.)
-  // so the child can run .ts files. Also inherit execArgv (--import tsx, etc.)
-  const child = fork(childPath, [], {
-    detached: true,
-    stdio: ["pipe", "pipe", "pipe", "ipc"],
-    execPath: process.execPath,
-    execArgv: process.execArgv,
-  });
+  if (await probeExistingServer(port)) {
+    logInfo("web-server: reusing existing server", { port });
+    startTakeoverWatch(port, webDir, config.apiUrl);
+    return createHandle(port);
+  }
 
-  // Drain stdout/stderr to prevent pipe buffer from blocking the child
-  child.stdout?.on("data", () => {});
-  child.stderr?.on("data", () => {});
+  const handle = await tryBind(port, webDir, config.apiUrl);
+  if (handle) {
+    activeServerHandle = handle;
+    return createHandle(port);
+  }
 
-  child.unref();
+  logInfo("web-server: port busy, starting takeover watch", { port });
+  startTakeoverWatch(port, webDir, config.apiUrl);
+  return createHandle(port);
+}
 
-  // 发送配置给子进程
-  child.send({ port, webDir, apiUrl: config.apiUrl });
+function tryBind(port: number, webDir: string, apiUrl: string): Promise<WebServerHandle | null> {
+  return new Promise((resolve) => {
+    const indexPath = path.join(webDir, "index.html");
 
-  // ── Step 6: 等待 ready 或超时 5s ──
-  const ready = await new Promise<boolean>((resolve) => {
-    const timeout = setTimeout(() => resolve(false), 5000);
+    const server = http.createServer((req: http.IncomingMessage, res: http.ServerResponse) => {
+      if (req.url === "/health" || req.url === "/health/") {
+        res.writeHead(200, { ...COMMON_HEADERS, "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok", service: "cerebro", port }));
+        return;
+      }
 
-    child.on("message", (msg: { type: string }) => {
-      if (msg.type === "ready") {
-        clearTimeout(timeout);
-        resolve(true);
-      } else if (msg.type === "error") {
-        clearTimeout(timeout);
-        resolve(false);
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        res.writeHead(405, { ...COMMON_HEADERS, "Content-Type": "text/plain" });
+        res.end("Method Not Allowed");
+        return;
       }
+
+      const url = new URL(req.url || "/", `http://localhost:${port}`);
+      const safePath = resolveSafe(webDir, url.pathname);
+
+      if (!safePath) {
+        res.writeHead(403, { ...COMMON_HEADERS, "Content-Type": "text/plain" });
+        res.end("Forbidden");
+        return;
+      }
+
+      fs.stat(safePath, (statErr, stats) => {
+        if (!statErr && stats.isFile()) {
+          serveFile(res, safePath, apiUrl);
+          return;
+        }
+        fs.stat(indexPath, (idxErr, idxStats) => {
+          if (idxErr || !idxStats.isFile()) {
+            res.writeHead(404, { ...COMMON_HEADERS, "Content-Type": "text/plain" });
+            res.end("Not Found");
+            return;
+          }
+          serveFile(res, indexPath, apiUrl);
+        });
+      });
     });
 
-    child.on("error", () => {
-      clearTimeout(timeout);
-      resolve(false);
+    server.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EADDRINUSE") {
+        resolve(null);
+      } else {
+        logError("web-server: bind error", { error: err.message });
+        resolve(null);
+      }
     });
 
-    child.on("exit", () => {
-      clearTimeout(timeout);
-      resolve(false);
+    server.listen(port, "127.0.0.1", () => {
+      logInfo("web-server: server started", { port });
+      resolve({
+        address: () => ({ port, family: "IPv4", address: "127.0.0.1" }),
+        isOwner: () => true,
+        stop: () => new Promise<void>((r) => server.close(() => r())),
+      });
     });
   });
+}
 
-  if (!ready) {
-    logError("web-server: failed to start child process", { port });
-    try { child.kill(); } catch { /* ignore */ }
-    try { fs.unlinkSync(pidFilePath); } catch { /* ignore */ }
-    return null;
-  }
+function serveFile(res: http.ServerResponse, filePath: string, apiUrl: string): void {
+  const ext = path.extname(filePath).toLowerCase();
+  const contentType = MIME_TYPES[ext] || "application/octet-stream";
+
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      logError("web-server: file read failed", { filePath, error: err.message });
+      res.writeHead(500, { ...COMMON_HEADERS, "Content-Type": "text/plain" });
+      res.end("Internal Server Error");
+      return;
+    }
+
+    let body: Buffer | string = data;
+    if (ext === ".html" && data.includes("__OMEM_API_URL__")) {
+      body = data.toString("utf-8").replace(
+        /window\.__OMEM_API_URL__\s*=\s*["']__OMEM_API_URL__["']/,
+        `window.__OMEM_API_URL__ = ${JSON.stringify(apiUrl)}`,
+      );
+    }
 
-  logInfo("web-server: child process started", { port, pid: child.pid });
-  return createHandle(port, heartbeatFilePath);
+    res.writeHead(200, {
+      ...COMMON_HEADERS,
+      "Content-Type": contentType,
+      "Cache-Control": ext === ".html" ? "no-cache, no-store, must-revalidate" : "public, max-age=86400",
+    });
+    res.end(body);
+  });
+}
+
+function clearTakeoverTimer(): void {
+  if (takeoverTimer) {
+    clearInterval(takeoverTimer);
+    takeoverTimer = null;
+  }
 }
 
-/** Create a handle with address() compat + heartbeat keep-alive */
-function createHandle(
-  port: number,
-  heartbeatFilePath: string,
-): WebServerHandle {
-  // 初始 touch
-  touchFile(heartbeatFilePath);
+function startTakeoverWatch(port: number, webDir: string, apiUrl: string): void {
+  if (takeoverTimer) return;
+  takeoverRetries = 0;
+  takeoverTimer = setInterval(async () => {
+    if (await probeExistingServer(port)) {
+      takeoverRetries = 0;
+      return;
+    }
+
+    takeoverRetries++;
+    if (takeoverRetries > TAKEOVER_MAX_RETRIES) {
+      logWarn("web-server: takeover abandoned after max retries", { port });
+      clearTakeoverTimer();
+      return;
+    }
 
-  // 每 30 秒 touch 心跳文件，保持子进程存活
-  const timer = setInterval(() => {
-    touchFile(heartbeatFilePath);
-  }, 30_000);
+    const jitter = TAKEOVER_JITTER_MIN_MS + Math.random() * TAKEOVER_JITTER_RANGE_MS;
+    await new Promise((r) => setTimeout(r, jitter));
+    if (await probeExistingServer(port)) {
+      takeoverRetries = 0;
+      return;
+    }
 
-  // 确保定时器不阻止进程退出
-  timer.unref();
+    const handle = await tryBind(port, webDir, apiUrl);
+    if (handle) {
+      activeServerHandle = handle;
+      logInfo("web-server: takeover successful", { port });
+      clearTakeoverTimer();
+    }
+  }, TAKEOVER_INTERVAL_MS);
+  takeoverTimer.unref();
+}
 
+function createHandle(port: number): WebServerHandle {
   return {
-    address() {
-      return { port, family: "IPv4", address: "127.0.0.1" };
+    address: () => ({ port, family: "IPv4", address: "127.0.0.1" }),
+    isOwner: () => activeServerHandle?.isOwner() ?? false,
+    stop: () => {
+      if (activeServerHandle?.isOwner()) {
+        clearTakeoverTimer();
+        const h = activeServerHandle;
+        activeServerHandle = null;
+        return h.stop();
+      }
+      clearTakeoverTimer();
+      activeServerHandle = null;
+      return Promise.resolve();
     },
   };
 }
 
-export function stopWebServer(_handle: WebServerHandle): Promise<void> {
-  // Intentionally do NOT touch heartbeat: parent exits → timer stops →
-  // heartbeat ages out → child detects mtime > 60s → self-terminate.
-  return Promise.resolve();
+export function stopWebServer(handle: WebServerHandle): Promise<void> {
+  return handle.stop();
 }

package/src/web-server-child.ts

@@ -1,267 +0,0 @@
-/**
- * web-server-child.ts — Cerebro Web Server Child Process
- *
- * 独立 fork 入口。实际 HTTP server 运行在此进程中。
- * 通过 IPC 从父进程接收配置，启动后通知父进程 ready。
- * 通过心跳文件 mtime 探测 plugin 进程存活状态。
- */
-import * as http from "node:http";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-
-// ── Lightweight file logger for child process ──────────────────────────
-// Cannot import logger.ts (no opencodeClient + circular dependency risk).
-// Writes to cerebro-web-child.log in the configured log directory.
-
-const CHILD_LOG_FILE = path.join(
-  process.env.OMEM_LOG_DIR || path.join(os.homedir(), ".config", "cerebro", "logs"),
-  "cerebro-web-child.log",
-);
-
-function childLog(level: string, message: string, fields?: Record<string, unknown>): void {
-  try {
-    const dir = path.dirname(CHILD_LOG_FILE);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    const now = new Date();
-    const ts = now.toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
-    const parts = [`${level.padEnd(5)} ${ts} service=cerebro-web-child`];
-    if (fields) {
-      for (const [k, v] of Object.entries(fields)) {
-        parts.push(`${k}=${typeof v === "string" ? v : JSON.stringify(v)}`);
-      }
-    }
-    parts.push(message);
-    fs.appendFileSync(CHILD_LOG_FILE, parts.join(" ") + "\n");
-  } catch { /* best effort */ }
-}
-
-// ── Types ────────────────────────────────────────────────────────────────
-
-interface ChildConfig {
-  port: number;
-  webDir: string;
-  apiUrl: string;
-}
-
-// ── MIME map ─────────────────────────────────────────────────────────────
-
-const MIME_TYPES: Record<string, string> = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "application/javascript; charset=utf-8",
-  ".mjs": "application/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".eot": "application/vnd.ms-fontobject",
-  ".webp": "image/webp",
-  ".webmanifest": "application/manifest+json",
-  ".map": "application/json",
-  ".txt": "text/plain; charset=utf-8",
-};
-
-function getMimeType(ext: string): string {
-  return MIME_TYPES[ext] || "application/octet-stream";
-}
-
-// ── Safe path resolver (prevent traversal) ───────────────────────────────
-
-function resolveSafe(baseDir: string, pathname: string): string | null {
-  const relative = pathname.startsWith("/") ? pathname.slice(1) : pathname;
-  const resolved = path.resolve(baseDir, relative || ".");
-  if (!resolved.startsWith(baseDir + path.sep) && resolved !== baseDir) {
-    return null;
-  }
-  return resolved;
-}
-
-// ── File serving ─────────────────────────────────────────────────────────
-
-function serveFile(
-  res: http.ServerResponse,
-  filePath: string,
-  apiUrl: string,
-): void {
-  const ext = path.extname(filePath).toLowerCase();
-  const contentType = getMimeType(ext);
-
-  fs.readFile(filePath, (err, data) => {
-    if (err) {
-      res.writeHead(500, { "Content-Type": "text/plain" });
-      res.end("Internal Server Error");
-      return;
-    }
-
-    let body: Buffer | string = data;
-
-    // Config injection: replace placeholder in index.html
-    if (ext === ".html" && data.includes("__OMEM_API_URL__")) {
-      body = data
-        .toString("utf-8")
-        .replace(
-          /window\.__OMEM_API_URL__\s*=\s*["']__OMEM_API_URL__["']/,
-          `window.__OMEM_API_URL__ = "${apiUrl}"`,
-        );
-    }
-
-    res.writeHead(200, {
-      "Content-Type": contentType,
-      "Cache-Control":
-        ext === ".html"
-          ? "no-cache, no-store, must-revalidate"
-          : "public, max-age=86400",
-    });
-    res.end(body);
-  });
-}
-
-// ── Server lifecycle ─────────────────────────────────────────────────────
-
-let server: http.Server | null = null;
-let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
-let pidFilePath = "";
-let heartbeatFilePath = "";
-
-function cleanup(): void {
-  if (heartbeatTimer) {
-    clearInterval(heartbeatTimer);
-    heartbeatTimer = null;
-  }
-  if (server) {
-    server.closeAllConnections?.();
-    const forceTimer = setTimeout(() => {
-      try { fs.unlinkSync(pidFilePath); } catch { /* ignore */ }
-      process.exit(0);
-    }, 3000);
-    server.close(() => {
-      clearTimeout(forceTimer);
-      try { fs.unlinkSync(pidFilePath); } catch { /* ignore */ }
-      process.exit(0);
-    });
-  } else {
-    try { fs.unlinkSync(pidFilePath); } catch { /* ignore */ }
-    process.exit(0);
-  }
-}
-
-function startServer(config: ChildConfig): void {
-  const { port, webDir, apiUrl } = config;
-
-  pidFilePath = path.join(os.tmpdir(), `cerebro-web-${port}.pid`);
-  heartbeatFilePath = path.join(os.tmpdir(), `cerebro-web-${port}.heartbeat`);
-
-  const indexPath = path.join(webDir, "index.html");
-
-  // 写 PID 文件（子进程自己的 PID）
-  try {
-    fs.writeFileSync(pidFilePath, String(process.pid));
-  } catch {
-    childLog("ERROR", "Failed to write PID file");
-  }
-
-  // 初始 touch 心跳文件
-  try {
-    fs.writeFileSync(heartbeatFilePath, "");
-  } catch {
-    childLog("ERROR", "Failed to create heartbeat file");
-  }
-
-  server = http.createServer(
-    (req: http.IncomingMessage, res: http.ServerResponse) => {
-      // ── /health 端点 ──
-      if (req.url === "/health" || req.url === "/health/") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: "ok", service: "cerebro", port }));
-        return;
-      }
-
-      // Only handle GET / HEAD
-      if (req.method !== "GET" && req.method !== "HEAD") {
-        res.writeHead(405, { "Content-Type": "text/plain" });
-        res.end("Method Not Allowed");
-        return;
-      }
-
-      // Parse URL, strip query string
-      const url = new URL(req.url || "/", `http://localhost:${port}`);
-      // new URL() already decodes percent-encoding; no double-decode
-      const pathname = url.pathname;
-
-      // Resolve safe file path
-      const safePath = resolveSafe(webDir, pathname);
-
-      if (!safePath) {
-        res.writeHead(403, { "Content-Type": "text/plain" });
-        res.end("Forbidden");
-        return;
-      }
-
-      // Try to serve the file directly
-      fs.stat(safePath, (statErr, stats) => {
-        if (!statErr && stats.isFile()) {
-          serveFile(res, safePath, apiUrl);
-          return;
-        }
-
-        // SPA fallback: serve index.html for non-file paths
-        fs.stat(indexPath, (idxErr, idxStats) => {
-          if (idxErr || !idxStats.isFile()) {
-            res.writeHead(404, { "Content-Type": "text/plain" });
-            res.end("Not Found");
-            return;
-          }
-          serveFile(res, indexPath, apiUrl);
-        });
-      });
-    },
-  );
-
-  server.on("error", (err: NodeJS.ErrnoException) => {
-    childLog("ERROR", "Server error", { error: err.message });
-    process.send?.({ type: "error", message: err.message });
-    cleanup();
-  });
-
-  server.listen(port, "127.0.0.1", () => {
-    childLog("INFO", "Server listening", { port });
-    process.send?.({ type: "ready", port });
-  });
-
-  // ── 心跳检测：每 30 秒检查心跳文件 mtime ──
-  heartbeatTimer = setInterval(() => {
-    try {
-      const stat = fs.statSync(heartbeatFilePath);
-      if (Date.now() - stat.mtimeMs > 60_000) {
-        childLog("INFO", "Heartbeat expired, shutting down");
-        cleanup();
-      }
-    } catch {
-      // 心跳文件不存在，可能被清理，继续等待不主动退出
-    }
-  }, 30_000);
-
-  // 确保定时器不阻止进程退出
-  if (heartbeatTimer) heartbeatTimer.unref();
-
-  // ── 信号处理 ──
-  process.on("SIGTERM", cleanup);
-  process.on("SIGINT", cleanup);
-}
-
-// ── IPC 监听（只处理第一条消息） ─────────────────────────────────────────
-
-let started = false;
-
-process.on("message", (config: ChildConfig) => {
-  if (started) return;
-  started = true;
-  startServer(config);
-});