leduo-patrol 2.0.0 → 2.0.1

package/README.md

@@ -97,6 +97,7 @@
 - Node.js 22+
 - 已能正常运行 Claude Code
 - 服务器环境里已配置 `ANTHROPIC_API_KEY`
+- 若 `claude` 不在默认 `PATH` 中，请设置 `LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude`
 
 ## 启动
 
@@ -148,15 +149,17 @@ LEDUO_PATROL_BIND_MODE=server
 LEDUO_PATROL_APP_NAME=乐多汪汪队
 LEDUO_PATROL_WORKSPACE_PATH=/absolute/workspace/path
 LEDUO_PATROL_ALLOWED_ROOTS=/absolute/workspace/path,/another/allowed/root
+LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude
+LEDUO_PATROL_SHELL=/absolute/path/to/zsh
 ANTHROPIC_API_KEY=sk-...
 LEDUO_PATROL_ACCESS_KEY=your-fixed-key
-LEDUO_PATROL_AGENT_BIN=/absolute/path/to/claude-code-acp
 LEDUO_ENABLE_SHELL=true
 ```
 
 如果设置了 `LEDUO_PATROL_ALLOWED_ROOTS`，网页中只能连接这些根目录之下的路径；未设置时默认只允许启动命令所在目录。
 如果未设置 `LEDUO_PATROL_WORKSPACE_PATH`，默认工作目录为启动命令所在目录（`process.cwd()`），并在启动日志中提示如何通过环境变量修改。
 如果未设置 `LEDUO_PATROL_ALLOWED_ROOTS`，默认允许根目录同样为启动命令所在目录，并会在启动日志中提示可配置项。
+如果发布安装后的内嵌终端无法启动，可通过 `LEDUO_PATROL_SHELL` 显式指定 shell 路径；例如 macOS 上常见的 `/bin/zsh`。
 
 ## 状态持久化
 
@@ -187,7 +190,7 @@ LEDUO_ENABLE_SHELL=true
 
 ```bash
 LEDUO_PATROL_ACCESS_KEY=your-fixed-key
-LEDUO_PATROL_AGENT_BIN=/absolute/path/to/claude-code-acp
+LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude
 ```
 
 ## 已知限制

package/dist/server/__tests__/claude-cli-session.test.js

@@ -0,0 +1,24 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { claudeCliSessionTestables } from "../claude-cli-session.js";
+test("claudeCliSessionTestables.findExecutableOnPath resolves commands from PATH entries", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-claude-bin-"));
+    const binaryName = process.platform === "win32" ? "claude.cmd" : "claude";
+    const binaryPath = path.join(tempDir, binaryName);
+    writeFileSync(binaryPath, process.platform === "win32" ? "@echo off\r\n" : "#!/bin/sh\n");
+    const resolved = claudeCliSessionTestables.findExecutableOnPath("claude", tempDir);
+    assert.equal(resolved, binaryPath);
+});
+test("claudeCliSessionTestables.resolveClaudeBin accepts explicit executable paths", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-claude-explicit-"));
+    const binaryPath = path.join(tempDir, "claude");
+    writeFileSync(binaryPath, "#!/bin/sh\n");
+    const resolved = claudeCliSessionTestables.resolveClaudeBin(binaryPath, { PATH: "" });
+    assert.equal(resolved, binaryPath);
+});
+test("claudeCliSessionTestables.resolveClaudeBin throws actionable error when claude is missing", () => {
+    assert.throws(() => claudeCliSessionTestables.resolveClaudeBin(undefined, { PATH: "" }), /LEDUO_PATROL_CLAUDE_BIN/);
+});

package/dist/server/__tests__/server-helpers.test.js

@@ -1,7 +1,9 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
-import { formatError, resolveAllowedPath } from "../server-helpers.js";
+import os from "node:os";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { buildSpawnFailureMessage, ensureDirectoryExistsSync, formatError, resolveAllowedPath, } from "../server-helpers.js";
 test("server helpers formatError handles Error and primitives", () => {
     assert.equal(formatError(new Error("boom")), "boom");
     assert.equal(formatError("plain"), '"plain"');
@@ -16,3 +18,17 @@ test("server helpers resolveAllowedPath rejects outside roots", () => {
     const root = path.resolve("/tmp/repo");
     assert.throws(() => resolveAllowedPath("/etc", [root]), /outside allowed roots/);
 });
+test("server helpers ensureDirectoryExistsSync accepts existing directories", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-dir-"));
+    assert.equal(ensureDirectoryExistsSync(tempDir, "Workspace"), tempDir);
+});
+test("server helpers ensureDirectoryExistsSync rejects files and missing paths", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-file-"));
+    const filePath = path.join(tempDir, "file.txt");
+    writeFileSync(filePath, "hello");
+    assert.throws(() => ensureDirectoryExistsSync(filePath, "Workspace"), /is not a directory/);
+    assert.throws(() => ensureDirectoryExistsSync(path.join(tempDir, "missing"), "Workspace"), /does not exist/);
+});
+test("server helpers buildSpawnFailureMessage includes command cwd and hint", () => {
+    assert.equal(buildSpawnFailureMessage("shell", "/bin/zsh", "/repo", new Error("posix_spawnp failed"), "Try another shell."), 'Failed to start shell "/bin/zsh" in "/repo": posix_spawnp failed. Try another shell.');
+});

package/dist/server/__tests__/shell-session.test.js

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { shellSessionTestables } from "../shell-session.js";
+test("shellSessionTestables.resolveShellLaunch prefers configured shell over defaults", () => {
+    const resolved = shellSessionTestables.resolveShellLaunch({
+        LEDUO_PATROL_SHELL: "/custom/bin/zsh",
+        SHELL: "/bin/bash",
+    }, (candidate) => candidate === "/custom/bin/zsh" || candidate === "/bin/bash");
+    assert.deepEqual(resolved, {
+        command: "/custom/bin/zsh",
+        args: ["-l"],
+    });
+});
+test("shellSessionTestables.resolveShellLaunch falls back to /bin/sh when bash and zsh are unavailable", () => {
+    const resolved = shellSessionTestables.resolveShellLaunch({
+        SHELL: "/missing/shell",
+    }, (candidate) => candidate === "/bin/sh");
+    assert.deepEqual(resolved, {
+        command: "/bin/sh",
+        args: [],
+    });
+});
+test("shellSessionTestables.resolveShellLaunch accepts plain configured shell names as a last resort", () => {
+    const resolved = shellSessionTestables.resolveShellLaunch({
+        LEDUO_PATROL_SHELL: "fish",
+        SHELL: "",
+    }, () => false);
+    assert.deepEqual(resolved, {
+        command: "fish",
+        args: ["-l"],
+    });
+});
+test("shellSessionTestables.resolveShellLaunch throws actionable error when no shell is available", () => {
+    assert.throws(() => shellSessionTestables.resolveShellLaunch({ SHELL: "" }, () => false), /LEDUO_PATROL_SHELL/);
+});

package/dist/server/claude-cli-session.js

@@ -1,5 +1,8 @@
 import { spawn } from "node-pty";
 import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { buildSpawnFailureMessage, ensureDirectoryExistsSync } from "./server-helpers.js";
 /**
  * A PTY-backed session that runs the native Claude Code CLI.
  *
@@ -15,24 +18,30 @@ export class ClaudeCliSession extends EventEmitter {
     constructor(opts) {
         super();
         this.sessionId = opts.sessionId;
-        const bin = opts.claudeBin ?? "claude";
+        ensureDirectoryExistsSync(opts.workspacePath, "Session workspace");
+        const bin = resolveClaudeBin(opts.claudeBin);
         const args = opts.resume
             ? ["--resume", opts.sessionId]
             : ["--session-id", opts.sessionId];
         if (opts.allowSkipPermissions) {
             args.push("--allow-dangerously-skip-permissions");
         }
-        this.pty = spawn(bin, args, {
-            name: "xterm-256color",
-            cols: opts.cols ?? 80,
-            rows: opts.rows ?? 24,
-            cwd: opts.workspacePath,
-            env: {
-                ...process.env,
-                TERM: "xterm-256color",
-                COLORTERM: "truecolor",
-            },
-        });
+        try {
+            this.pty = spawn(bin, args, {
+                name: "xterm-256color",
+                cols: opts.cols ?? 80,
+                rows: opts.rows ?? 24,
+                cwd: opts.workspacePath,
+                env: {
+                    ...process.env,
+                    TERM: "xterm-256color",
+                    COLORTERM: "truecolor",
+                },
+            });
+        }
+        catch (error) {
+            throw new Error(buildSpawnFailureMessage("Claude CLI", bin, opts.workspacePath, error, "Check that the command is installed correctly, or override it with LEDUO_PATROL_CLAUDE_BIN."));
+        }
         this.pty.onData((data) => {
             this.emit("output", data);
         });
@@ -61,3 +70,38 @@ export class ClaudeCliSession extends EventEmitter {
         }
     }
 }
+function findExecutableOnPath(command, envPath = process.env.PATH) {
+    if (!envPath)
+        return null;
+    const extensions = process.platform === "win32"
+        ? (process.env.PATHEXT?.split(";").filter(Boolean) ?? [".exe", ".cmd", ".bat"])
+        : [""];
+    for (const entry of envPath.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(entry, `${command}${extension}`);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+function resolveClaudeBin(configuredBin, env = process.env) {
+    const candidate = configuredBin?.trim() || "claude";
+    const hasExplicitPath = candidate.includes("/") || candidate.includes("\\");
+    if (hasExplicitPath) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        throw new Error(`Claude CLI not found at "${candidate}". Set LEDUO_PATROL_CLAUDE_BIN to a valid Claude executable path.`);
+    }
+    const resolved = findExecutableOnPath(candidate, env.PATH);
+    if (resolved) {
+        return resolved;
+    }
+    throw new Error(`Claude CLI "${candidate}" was not found in PATH. Install Claude Code first, or set LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude.`);
+}
+export const claudeCliSessionTestables = {
+    findExecutableOnPath,
+    resolveClaudeBin,
+};

package/dist/server/index.js

@@ -27,7 +27,8 @@ const vscodeRemoteUri = process.env.LEDUO_PATROL_VSCODE_URI ??
     (sshHost ? `vscode://vscode-remote/ssh-remote+${encodeURIComponent(sshHost)}${sshPath}` : "");
 const requestedPort = Number(process.env.PORT ?? 3001);
 const devWebPort = Number(process.env.LEDUO_PATROL_WEB_PORT ?? 5173);
-const isDevServer = process.env.npm_lifecycle_event === "dev:server";
+const npmLifecycleEvent = process.env.npm_lifecycle_event ?? "";
+const isDevServer = npmLifecycleEvent === "dev:server" || npmLifecycleEvent === "dev:server:local";
 const bindMode = await resolveBindMode();
 const listenHost = bindMode === "local" ? "127.0.0.1" : "0.0.0.0";
 const launchHost = bindMode === "local" ? "127.0.0.1" : pickPreferredLanIp();

package/dist/server/server-helpers.js

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import path from "node:path";
 export function formatError(error) {
     if (error instanceof Error) {
@@ -21,3 +22,24 @@ export function resolveAllowedPath(requestedPath, allowedRoots) {
     }
     return resolvedPath;
 }
+export function ensureDirectoryExistsSync(requestedPath, label) {
+    try {
+        const stats = statSync(requestedPath);
+        if (!stats.isDirectory()) {
+            throw new Error(`${label} is not a directory: ${requestedPath}`);
+        }
+        return requestedPath;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("is not a directory")) {
+            throw error;
+        }
+        throw new Error(`${label} does not exist or is not accessible: ${requestedPath}`);
+    }
+}
+export function buildSpawnFailureMessage(commandLabel, command, cwd, error, hint) {
+    const quotedCommand = JSON.stringify(command);
+    const quotedCwd = JSON.stringify(cwd);
+    const message = `Failed to start ${commandLabel} ${quotedCommand} in ${quotedCwd}: ${formatError(error)}`;
+    return hint ? `${message}. ${hint}` : message;
+}

package/dist/server/session-manager.js

@@ -56,7 +56,13 @@ export class SessionManager {
     }
     async initialize() {
         const persistedState = await this.readPersistedState();
+        let skippedPersistedSessions = false;
         for (const persisted of persistedState.sessions) {
+            if (!(await this.isRestorableWorkspace(persisted.workspacePath))) {
+                skippedPersistedSessions = true;
+                console.warn(`[SessionManager] Skipping persisted session with unavailable workspace: ${persisted.workspacePath}`);
+                continue;
+            }
             const snapshot = {
                 clientSessionId: persisted.clientSessionId,
                 title: persisted.title,
@@ -75,6 +81,9 @@ export class SessionManager {
             this.sessionIdIndex.set(snapshot.sessionId, snapshot.clientSessionId);
             this.activityMonitor.watch(snapshot.sessionId, snapshot.workspacePath);
         }
+        if (skippedPersistedSessions) {
+            await this.writePersistedState().catch(() => undefined);
+        }
         for (const entry of this.sessions.values()) {
             this.startCliSession(entry, true).catch((error) => {
                 this.handleManagerError(entry.snapshot.clientSessionId, error);
@@ -279,6 +288,15 @@ export class SessionManager {
         await access(resolvedWorkspacePath);
         return resolvedWorkspacePath;
     }
+    async isRestorableWorkspace(workspacePath) {
+        try {
+            const workspaceStats = await stat(workspacePath);
+            return workspaceStats.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
     // ---------------------------------------------------------------------------
     // /clear detection → session ID discovery
     // ---------------------------------------------------------------------------

package/dist/server/shell-session.js

@@ -1,45 +1,80 @@
 import { spawn } from "node-pty";
 import { EventEmitter } from "node:events";
 import { existsSync } from "node:fs";
-// Resolve bash path; prefer the user's login shell if it is bash, then common locations
-function resolveBashPath() {
-    const loginShell = process.env.SHELL ?? "";
-    if (loginShell && /bash$/i.test(loginShell) && existsSync(loginShell)) {
-        return loginShell;
+import path from "node:path";
+import { buildSpawnFailureMessage, ensureDirectoryExistsSync } from "./server-helpers.js";
+function buildShellLoginArgs(command) {
+    const shellName = path.basename(command).toLowerCase();
+    if (["bash", "zsh", "ksh", "fish"].includes(shellName)) {
+        return ["-l"];
     }
-    for (const candidate of ["/bin/bash", "/usr/bin/bash", "/usr/local/bin/bash"]) {
-        if (existsSync(candidate)) {
-            return candidate;
+    return [];
+}
+function resolveShellLaunch(env = process.env, shellExists = existsSync) {
+    const configuredShell = env.LEDUO_PATROL_SHELL?.trim() ?? "";
+    const loginShell = env.SHELL?.trim() ?? "";
+    const absoluteCandidates = [
+        configuredShell,
+        loginShell,
+        "/bin/bash",
+        "/bin/zsh",
+        "/bin/sh",
+        "/usr/bin/bash",
+        "/usr/bin/zsh",
+        "/usr/local/bin/bash",
+        "/usr/local/bin/zsh",
+        "/opt/homebrew/bin/bash",
+        "/opt/homebrew/bin/zsh",
+    ].filter((candidate, index, all) => candidate && all.indexOf(candidate) === index);
+    for (const candidate of absoluteCandidates) {
+        if (shellExists(candidate)) {
+            return {
+                command: candidate,
+                args: buildShellLoginArgs(candidate),
+            };
         }
     }
-    // Fall back to plain "bash" and let the OS resolve it via PATH
-    return "bash";
+    if (configuredShell) {
+        return {
+            command: configuredShell,
+            args: buildShellLoginArgs(configuredShell),
+        };
+    }
+    throw new Error(`No supported shell was found. Set LEDUO_PATROL_SHELL to an absolute shell path if your system does not provide /bin/bash, /bin/zsh, or /bin/sh.`);
 }
 /**
  * An interactive shell session backed by a PTY.
  *
- * Spawns a login shell (`bash --login`) that inherits the full user
- * environment and loads ~/.bash_profile / ~/.bashrc so that tools like
- * pyenv, nvm, brew, cargo, aliases, etc. are all available.
+ * Spawns the best-available interactive shell for the host environment.
+ * We prefer a login shell when possible so that user toolchains such as
+ * pyenv, nvm, brew, cargo, aliases, etc. are available in published installs too.
  */
 export class ShellSession extends EventEmitter {
     pty;
     _alive = true;
     constructor(workspacePath, cols = 80, rows = 24) {
         super();
+        ensureDirectoryExistsSync(workspacePath, "Shell workspace");
+        const shellLaunch = resolveShellLaunch();
         const env = {
             ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] != null)),
             TERM: "xterm-256color",
             COLORTERM: "truecolor",
             PWD: workspacePath,
+            SHELL: shellLaunch.command,
         };
-        this.pty = spawn(resolveBashPath(), ["--login"], {
-            name: "xterm-256color",
-            cols,
-            rows,
-            cwd: workspacePath,
-            env,
-        });
+        try {
+            this.pty = spawn(shellLaunch.command, shellLaunch.args, {
+                name: "xterm-256color",
+                cols,
+                rows,
+                cwd: workspacePath,
+                env,
+            });
+        }
+        catch (error) {
+            throw new Error(buildSpawnFailureMessage("shell", shellLaunch.command, workspacePath, error, "Set LEDUO_PATROL_SHELL to a valid shell path if this environment uses a non-standard shell location."));
+        }
         this.pty.onData((data) => {
             this.emit("output", data);
         });
@@ -68,3 +103,7 @@ export class ShellSession extends EventEmitter {
         }
     }
 }
+export const shellSessionTestables = {
+    buildShellLoginArgs,
+    resolveShellLaunch,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leduo-patrol",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "乐多汪汪队（leduo-patrol）web console with embedded Claude Code CLI terminals.",
   "type": "module",
   "main": "dist/server/index.js",