@datafrog-io/n2n-nexus 0.3.2 → 0.3.4

package/README.md

@@ -115,15 +115,25 @@ Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP se
 
 > **Zero-Config**: No `--id` or `--host` needed. Just run and collaborate!
 
-**Optional**: Use `--root` to specify a custom storage path:
-```json
-"args": ["-y", "@datafrog-io/n2n-nexus", "--root", "/path/to/storage"]
+"args": ["-y", "@datafrog-io/n2n-nexus"]
 ```
 
+### 💾 Data Persistence (Zero-Config)
+
+Nexus now automatically stores data in your system's standard **User Data Directory** (XDG Base Directory). This ensures your meeting history and projects persist across IDE restarts, `npx` cache clears, and updates.
+
+- **Linux / WSL**: `~/.local/share/n2n-nexus`
+- **Windows**: `%APPDATA%\n2n-nexus`
+- **macOS**: `~/Library/Application Support/n2n-nexus`
+
+> **Note for WSL Users**: To maximize I/O performance, WSL instances store data in the Linux file system (`~/.local/share`), while Windows instances use `%APPDATA%`. Data is **isolated** between environments to prevent database corruption and performance degradation.
+
 ### CLI Arguments
 | Argument | Description | Default |
 |----------|-------------|---------|
-| `--root` | Local storage path for all Nexus data | `./storage` |
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--root` | Override storage path (advanced use only) | System User Data Dir |
 
 > **Note:** Host identity and Instance ID are determined automatically based on the project folder name and startup order.
 

package/build/config.js

@@ -15,7 +15,7 @@ const getArg = (k) => {
 const hasFlag = (k) => args.includes(k) || args.includes(k.charAt(1) === "-" ? k : k.substring(0, 2));
 // --- CLI Commands Handlers ---
 if (hasFlag("--help") || hasFlag("-h")) {
-    console.log(`
+    console.error(`
 n2ns Nexus 🚀 - Local Digital Asset Hub (MCP Server) v${pkg.version}
 
 USAGE:
@@ -46,13 +46,13 @@ ENVIRONMENT VARIABLES:
     process.exit(0);
 }
 if (hasFlag("--version") || hasFlag("-v")) {
-    console.log(pkg.version);
+    console.error(pkg.version);
     process.exit(0);
 }
 // --- Path Normalization Logic ---
 function normalizeRootPath(inputPath) {
-    // 1. Priority: CLI --root > ENV NEXUS_ROOT > Default ./storage
-    let root = inputPath || process.env.NEXUS_ROOT || path.join(__dirname, "../storage");
+    // 1. Priority: CLI --root > ENV NEXUS_ROOT > System Default (XDG/AppData)
+    let root = inputPath || process.env.NEXUS_ROOT || getDefaultDataDir();
     // 2. Resolve ~ to home directory
     if (root.startsWith("~")) {
         root = path.join(os.homedir(), root.slice(1));
@@ -65,18 +65,48 @@ function normalizeRootPath(inputPath) {
     }
     return path.resolve(root);
 }
+function getDefaultDataDir() {
+    const home = os.homedir();
+    const appName = "n2n-nexus";
+    switch (process.platform) {
+        case "win32":
+            return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), appName);
+        case "darwin":
+            return path.join(home, "Library", "Application Support", appName);
+        default: // linux, wsl, etc.
+            return path.join(process.env.XDG_DATA_HOME || path.join(home, ".local", "share"), appName);
+    }
+}
 /**
  * Probe a port to see if it's a Nexus Host
  */
-async function probeHost(port) {
+/**
+ * Probe a port to see if it's a Nexus Host using the Custom Handshake Protocol
+ */
+async function probeHost(port, myId) {
     return new Promise((resolve) => {
-        const req = http.get(`http://127.0.0.1:${port}/hello`, { timeout: 500 }, (res) => {
+        const postData = JSON.stringify({
+            clientVersion: pkg.version,
+            instanceId: myId
+        });
+        const req = http.request({
+            hostname: "127.0.0.1",
+            port: port,
+            path: "/nexus/handshake",
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(postData)
+            },
+            timeout: 500
+        }, (res) => {
             let data = "";
             res.on("data", (chunk) => data += chunk);
             res.on("end", () => {
                 try {
                     const info = JSON.parse(data);
                     if (info.service === "n2n-nexus" && info.role === "host") {
+                        // console.error(`[Nexus Handshake] Connected to Host v${info.serverVersion} (Protocol ${info.protocol})`);
                         resolve({ isNexus: true, rootStorage: info.rootStorage });
                     }
                     else {
@@ -93,6 +123,8 @@ async function probeHost(port) {
             req.destroy();
             resolve({ isNexus: false });
         });
+        req.write(postData);
+        req.end();
     });
 }
 /**
@@ -112,11 +144,12 @@ async function isHostAutoElection(root) {
     while (true) {
         // Phase 1: Probe-First - Check if any Host already exists (Concurrent Batch Scan)
         const BATCH_SIZE = 20;
+        const myId = getArg("--id") || `candidate-${Math.random().toString(36).substring(2, 6)}`;
         for (let batchStart = startPort; batchStart <= endPort; batchStart += BATCH_SIZE) {
             const batchEnd = Math.min(batchStart + BATCH_SIZE - 1, endPort);
             const promises = [];
             for (let port = batchStart; port <= batchEnd; port++) {
-                promises.push(probeHost(port).then(res => ({ port, ...res })));
+                promises.push(probeHost(port, myId).then(res => ({ port, ...res })));
             }
             const results = await Promise.all(promises);
             const found = results.find(r => r.isNexus);
@@ -128,28 +161,35 @@ async function isHostAutoElection(root) {
         for (let port = startPort; port <= endPort; port++) {
             const result = await new Promise((resolve) => {
                 const server = http.createServer((req, res) => {
-                    if (req.url === "/hello") {
-                        res.writeHead(200, { "Content-Type": "application/json" });
-                        res.end(JSON.stringify({
-                            service: "n2n-nexus",
-                            role: "host",
-                            version: pkg.version,
-                            rootStorage: root
-                        }));
+                    // HANDSHAKE ENDPOINT
+                    if (req.method === "POST" && req.url === "/nexus/handshake") {
+                        let body = "";
+                        req.on("data", chunk => body += chunk);
+                        req.on("end", () => {
+                            try {
+                                const _clientInfo = JSON.parse(body);
+                                // console.error(`[Nexus Handshake] Client connected: ${_clientInfo.instanceId} (v${_clientInfo.clientVersion})`);
+                            }
+                            catch { /* ignore malformed */ }
+                            res.writeHead(200, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({
+                                service: "n2n-nexus",
+                                protocol: "v1", // Nexus Handshake Protocol v1
+                                role: "host",
+                                serverVersion: pkg.version,
+                                rootStorage: root,
+                                status: "ready"
+                            }));
+                        });
                         return;
                     }
                     res.writeHead(404);
                     res.end();
                 });
-                server.on("error", (err) => {
-                    if (err.code === "EADDRINUSE") {
-                        resolve({ isHost: false });
-                    }
-                    else {
-                        resolve({ isHost: false });
-                    }
+                server.on("error", (_err) => {
+                    resolve({ isHost: false });
                 });
-                server.listen(port, "127.0.0.1", () => {
+                server.listen(port, "0.0.0.0", () => {
                     resolve({ isHost: true, server });
                 });
             });
@@ -157,18 +197,16 @@ async function isHostAutoElection(root) {
                 return { isHost: true, port, server: result.server };
             }
             // Phase 3: Bind failed - another Guest won. Wait then join winner.
-            await new Promise(r => setTimeout(r, 10000)); // Give winner 10s to start /hello
-            const probe = await probeHost(port);
+            await new Promise(r => setTimeout(r, 2000)); // Short wait for winner to stabilize
+            const probe = await probeHost(port, myId);
             if (probe.isNexus) {
                 return { isHost: false, port, rootStorage: probe.rootStorage };
             }
-            // If still not Nexus, try next port (occupied by non-Nexus service)
+            // If still not Nexus, try next port
         }
         // Fallback: All ports occupied - progressive backoff retry
-        // First 5 attempts: 1 minute interval, then 2 minute interval
-        const waitTime = retryCount < 5 ? 60000 : 120000;
-        const intervalStr = retryCount < 5 ? "1 minute" : "2 minutes";
-        console.error(`[Nexus] All ports ${startPort}-${endPort} occupied. Retry #${retryCount + 1} in ${intervalStr}...`);
+        const waitTime = retryCount < 5 ? 5000 : 30000;
+        console.error(`[Nexus] All ports ${startPort}-${endPort} occupied. Retry #${retryCount + 1} in ${waitTime / 1000}s...`);
         await new Promise(r => setTimeout(r, waitTime));
         retryCount++;
     }
@@ -186,7 +224,10 @@ function getAutoProjectName() {
         }
     }
     catch { /* ignore */ }
-    return path.basename(process.cwd()) || "Assistant";
+    const base = path.basename(process.cwd()) || "Assistant";
+    // Append random suffix to prevent collisions when multiple IDEs open empty/same folders
+    const suffix = Math.random().toString(36).substring(2, 6);
+    return `${base}-${suffix}`;
 }
 const rootPath = normalizeRootPath(getArg("--root"));
 const election = await isHostAutoElection(rootPath);

package/build/index.js

@@ -141,6 +141,16 @@ class NexusServer {
             catch { /* ignore */ }
             process.exit(0);
         };
+        // Global Error Handlers to prevent process exit on background errors
+        process.on("uncaughtException", (err) => {
+            console.error("[Nexus CRITICAL] Uncaught Exception:", err);
+            // Attempt to log to disk if possible, but keep process alive if safe
+            // For a Hub, staying alive is often preferred over crashing
+        });
+        process.on("unhandledRejection", (reason, promise) => {
+            console.error("[Nexus WARNING] Unhandled Rejection at:", promise, "reason:", reason);
+            // Do not exit. Background tasks (like file sync) often trigger this.
+        });
         process.on("SIGINT", () => shutdown("SIGINT"));
         process.on("SIGTERM", () => shutdown("SIGTERM"));
         if (CONFIG.isHost && hostServer) {
@@ -262,7 +272,7 @@ class NexusServer {
                                 try {
                                     process.stdout.write(dataLine.substring(6) + "\n");
                                 }
-                                catch { }
+                                catch { /* ignore stdout errors */ }
                             }
                         }
                     });

package/build/storage/index.js

@@ -13,7 +13,10 @@ export class StorageManager {
     static get projectsRoot() { return path.join(CONFIG.rootStorage, "projects"); }
     static get registryFile() { return path.join(CONFIG.rootStorage, "registry.json"); }
     static get archivesDir() { return path.join(CONFIG.rootStorage, "archives"); }
+    static initialized = false;
     static async init() {
+        if (this.initialized)
+            return;
         await fs.mkdir(CONFIG.rootStorage, { recursive: true });
         await fs.mkdir(this.globalDir, { recursive: true });
         await fs.mkdir(this.projectsRoot, { recursive: true });
@@ -32,6 +35,10 @@ export class StorageManager {
         catch {
             // SQLite may not be available or database not ready - will be initialized on first use
         }
+        this.initialized = true;
+    }
+    static resetInit() {
+        this.initialized = false;
     }
     /**
      * Proactively reads and validates JSON.

package/build/storage/tasks.js

@@ -11,10 +11,13 @@ function generateTaskId() {
     const random = Math.random().toString(36).substring(2, 6);
     return `task_${timestamp}_${random}`;
 }
+let initialized = false;
 /**
  * Initialize the tasks table (run migrations)
  */
 export function initTasksTable() {
+    if (initialized)
+        return;
     const db = getDatabase();
     const TASKS_SCHEMA = `
     CREATE TABLE IF NOT EXISTS tasks (
@@ -50,6 +53,10 @@ export function initTasksTable() {
         // Trigger may already exist in older SQLite versions without IF NOT EXISTS support
     }
     console.error("[Nexus] Tasks table initialized");
+    initialized = true;
+}
+export function resetTasksInit() {
+    initialized = false;
 }
 /**
  * Create a new task

package/docs/CHANGELOG_zh.md

@@ -2,6 +2,24 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [0.3.4] - 2026-01-10
+### 协议与稳定性
+- **新握手协议**: 引入 `POST /nexus/handshake` 替代旧版 `/hello`。支持严格的客户端/服务端版本校验和稳健的 Host 探测。
+- **全局错误安全网**: 增加了 `uncaughtException` 和 `unhandledRejection` 处理器，防止后台任务错误导致进程退出，确保 Hub 的高可用性。
+- **修复 (EOF 错误)**: 解决了由于 SQLite 非幂等初始化导致的“连接关闭：EOF”崩溃问题。
+- **修复 (僵尸 Host)**: 改进了 Guest 的 Host检测逻辑，消除了死循环重试。
+- **测试覆盖**: 新增 `guest_connection.test.ts` 验证 Guest-Host SSE 集成。
+
+## [0.3.3] - 2026-01-10
+### 🔄 零配置持久化 (Zero-Config Persistence)
+- **支持 XDG Base Directory**: 将存储位置从不稳定的 `node_modules` 迁移至系统标准的 User Data 路径：
+  - **Linux/WSL**: `~/.local/share/n2n-nexus`
+  - **Windows**: `%APPDATA%\n2n-nexus`
+  - **macOS**: `~/Library/Application Support/n2n-nexus`
+- **数据持久化**: 数据现在可以从 `npx` 缓存清理、项目删除和重新安装中幸存。
+- **监听地址**: 默认监听地址更改为 `0.0.0.0` 以支持 WSL 镜像模式网络。
+- **身份安全**: 默认的 "Assistant" ID 现在会自动追加随机后缀（例如 `Assistant-x9a2`），以防止多个空 IDE 连接时发生冲突。
+
 ## [v0.3.0] - 2026-01-08
 
 ### 🌐 全局 Hub 架构 (零配置多 IDE 协作)

package/docs/README_zh.md

@@ -115,15 +115,25 @@
 
 > **零配置**: 无需 `--id` 或 `--host`。直接运行即可协作！
 
-**可选**: 使用 `--root` 指定自定义存储路径：
-```json
-"args": ["-y", "@datafrog-io/n2n-nexus", "--root", "/path/to/storage"]
+"args": ["-y", "@datafrog-io/n2n-nexus"]
 ```
 
+### 💾 数据持久化 (零配置)
+
+Nexus 现在自动将数据存储在系统标准的 **用户数据目录** (XDG Base Directory) 中。这确保了会议历史和项目数据在 IDE 重启、`npx` 缓存清理和更新后依然存在。
+
+- **Linux / WSL**: `~/.local/share/n2n-nexus`
+- **Windows**: `%APPDATA%\n2n-nexus`
+- **macOS**: `~/Library/Application Support/n2n-nexus`
+
+> **WSL 用户注意**: 为了获得最佳 I/O 性能，WSL 实例将数据存储在 Linux 文件系统中 (`~/.local/share`)，而 Windows 实例使用 `%APPDATA%`。数据在两个环境之间是 **隔离** 的，以防止数据库损坏和性能下降。
+
 ### 命令行参数
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
-| `--root` | 本地数据存储路径 | `./storage` |
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--root` | 覆盖存储路径 (仅限高级用途) | 系统用户数据目录 |
 
 > **注意：** 实例 ID（默认为当前项目文件夹名称）和 Host 身份将根据启动顺序自动生成。
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datafrog-io/n2n-nexus",
-    "version": "0.3.2",
+    "version": "0.3.4",
     "description": "Modular MCP Server for multi-AI assistant coordination",
     "main": "build/index.js",
     "type": "module",