@datafrog-io/n2n-nexus 0.3.1 → 0.3.3

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

@@ -51,8 +51,8 @@ if (hasFlag("--version") || hasFlag("-v")) {
 }
 // --- 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,6 +65,18 @@ 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
  */
@@ -104,70 +116,74 @@ async function probeHost(port) {
  * 3. If not found, try to become Host
  * 4. If bind fails, wait and re-probe (give winner time to start)
  */
-async function isHostAutoElection(root, retryCount = 0) {
+async function isHostAutoElection(root) {
     const startPort = 5688;
     const endPort = 5800;
-    // Phase 1: Probe-First - Check if any Host already exists (Concurrent Batch Scan)
-    const BATCH_SIZE = 20;
-    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 })));
+    let retryCount = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        // Phase 1: Probe-First - Check if any Host already exists (Concurrent Batch Scan)
+        const BATCH_SIZE = 20;
+        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 })));
+            }
+            const results = await Promise.all(promises);
+            const found = results.find(r => r.isNexus);
+            if (found) {
+                return { isHost: false, port: found.port, rootStorage: found.rootStorage };
+            }
         }
-        const results = await Promise.all(promises);
-        const found = results.find(r => r.isNexus);
-        if (found) {
-            return { isHost: false, port: found.port, rootStorage: found.rootStorage };
-        }
-    }
-    // Phase 2: No Host found, attempt to become Host
-    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
-                    }));
-                    return;
-                }
-                res.writeHead(404);
-                res.end();
-            });
-            server.on("error", (err) => {
-                if (err.code === "EADDRINUSE") {
-                    resolve({ isHost: false });
-                }
-                else {
-                    resolve({ isHost: false });
-                }
-            });
-            server.listen(port, "127.0.0.1", () => {
-                resolve({ isHost: true, server });
+        // Phase 2: No Host found, attempt to become Host
+        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
+                        }));
+                        return;
+                    }
+                    res.writeHead(404);
+                    res.end();
+                });
+                server.on("error", (err) => {
+                    if (err.code === "EADDRINUSE") {
+                        resolve({ isHost: false });
+                    }
+                    else {
+                        resolve({ isHost: false });
+                    }
+                });
+                server.listen(port, "0.0.0.0", () => {
+                    resolve({ isHost: true, server });
+                });
             });
-        });
-        if (result.isHost) {
-            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);
-        if (probe.isNexus) {
-            return { isHost: false, port, rootStorage: probe.rootStorage };
+            if (result.isHost) {
+                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);
+            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 (occupied by non-Nexus service)
+        // 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}...`);
+        await new Promise(r => setTimeout(r, waitTime));
+        retryCount++;
     }
-    // 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}...`);
-    await new Promise(r => setTimeout(r, waitTime));
-    return isHostAutoElection(root, retryCount + 1);
 }
 /**
  * Automatic Project Name Detection
@@ -182,7 +198,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

@@ -231,7 +231,7 @@ class NexusServer {
                         const req = http.request({
                             hostname: "127.0.0.1",
                             port: CONFIG.port,
-                            path: `/mcp?sessionId=${sessionId}&id=${guestId}`,
+                            path: `/mcp?sessionId=${sessionId}&id=${encodeURIComponent(guestId)}`,
                             method: "POST",
                             headers: { "Content-Type": "application/json" }
                         });
@@ -243,7 +243,7 @@ class NexusServer {
                     catch { /* suppress */ }
                 };
                 process.stdin.on("data", stdioHandler);
-                http.get(`http://127.0.0.1:${CONFIG.port}/mcp?id=${guestId}`, (res) => {
+                http.get(`http://127.0.0.1:${CONFIG.port}/mcp?id=${encodeURIComponent(guestId)}`, (res) => {
                     retryCount = 0; // Reset on successful connection
                     let buffer = "";
                     res.on("data", (chunk) => {

package/docs/CHANGELOG_zh.md

@@ -2,6 +2,16 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [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.1",
+    "version": "0.3.3",
     "description": "Modular MCP Server for multi-AI assistant coordination",
     "main": "build/index.js",
     "type": "module",