napbox 0.0.0-stage → 0.1.0

package/dist/agent/cache.d.ts

@@ -0,0 +1 @@
+export declare function sweepCachedVersions(): Promise<void>;

package/dist/agent/cache.js

@@ -0,0 +1,17 @@
+// 插件把每个版本的包装进缓存目录（scripts/server-launcher.mjs）。一周没启动过的版本删掉，别的版本要用时重新安装。
+import { readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { cacheDirectory, packageVersion } from "./locations.js";
+const KEEP_MS = 7 * 24 * 60 * 60 * 1000;
+export async function sweepCachedVersions() {
+    const versions = path.join(cacheDirectory(), "versions");
+    const names = await readdir(versions).catch(() => []);
+    for (const name of names) {
+        if (name === packageVersion)
+            continue;
+        const directory = path.join(versions, name);
+        const used = await stat(path.join(directory, "last-used")).catch(() => stat(directory));
+        if (Date.now() - used.mtimeMs > KEEP_MS)
+            await rm(directory, { recursive: true, force: true });
+    }
+}

package/dist/agent/hooks.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentInfo } from "../protocol.ts";
+export interface HookInput {
+    hook_event_name?: string;
+    cwd?: string;
+    tool_name?: string;
+    tool_input?: {
+        command?: unknown;
+    };
+}
+export declare function runHook(input: HookInput): Promise<Record<string, unknown> | undefined>;
+export declare function describeEnvironment(info: EnvironmentInfo): string;

package/dist/agent/hooks.js

@@ -0,0 +1,139 @@
+// Claude Code 插件的钩子（DESIGN.md 第 4 节、第 12 节第 3 条）：
+// - 会话开始和每次压缩上下文之后，当前 worktree 有环境就把端口告诉 agent；
+// - 已接入的项目里运行 docker compose up/start/run 时拦下；自己起数据库这类服务、或者 docker run 时提醒。
+import { execFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { NapboxClient, NapboxError } from "../client.js";
+import { composeSubcommand, isDockerRun, simpleCommands, startsOwnService } from "./shell-command.js";
+const BLOCKED_COMPOSE = new Set(["up", "start", "run"]);
+const RUN_INSTEAD = "要像 docker compose run 那样单独跑一次某个服务（测试、检查），用 run 工具（命令行是 npx napbox run <服务> [-- 命令]）：临时起一个环境，在前台跑它，跑完销毁，返回它的退出码和输出。";
+const TEMP_INSTEAD = "测试要一套用完就扔的（比如空的数据库），给 up 工具传 temp 起一个临时环境（命令行是 npx napbox up --temp <名字>），用完调 down 传同一个名字。";
+/** 大多数 Bash 命令到这里就结束，不用查 git 和 napboxd */
+const MIGHT_MATTER = /docker|postgres|pg_ctl|mysql|mongod|redis-server|minio|brew/;
+export async function runHook(input) {
+    const cwd = input.cwd || process.cwd();
+    if (input.hook_event_name === "SessionStart") {
+        const note = await sessionNote(cwd);
+        return note
+            ? { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: note } }
+            : undefined;
+    }
+    if (input.hook_event_name === "PreToolUse" && input.tool_name === "Bash") {
+        const command = input.tool_input?.command;
+        return typeof command === "string" ? await checkCommand(command, cwd) : undefined;
+    }
+    return undefined;
+}
+async function sessionNote(cwd) {
+    let info;
+    try {
+        info = await new NapboxClient().environment({ cwd });
+    }
+    catch (error) {
+        if (error instanceof NapboxError && error.code === "daemon_unavailable") {
+            return (await isOnboarded(cwd))
+                ? "这个项目用 napbox 管理服务，但 napbox 的后台程序没有运行。需要服务时调用 napbox 的 setup 工具。"
+                : undefined;
+        }
+        // 这里没有环境（environment_not_found、not_in_repository 等）：什么都不说
+        if (error instanceof NapboxError)
+            return undefined;
+        throw error;
+    }
+    return describeEnvironment(info);
+}
+export function describeEnvironment(info) {
+    const lines = [`这个 worktree 的 napbox 环境是 ${info.name}（${info.state}）。服务和端口：`];
+    for (const port of info.ports) {
+        lines.push(`- ${port.service}:${port.containerPort} → 127.0.0.1:${port.hostPort}（变量 ${port.variable}）`);
+    }
+    if (info.state !== "running")
+        lines.push("休眠时一连接就会自动唤醒，不用手动启动。");
+    if (info.lastError)
+        lines.push(`最近出错：${info.lastError}`);
+    if (info.unsetVariables.length) {
+        lines.push(`compose 里用到但没有值的变量：${info.unsetVariables.join("、")}`);
+    }
+    lines.push("用 napbox 的工具（up、env、logs、exec、reset）管理这些服务，不要运行 docker compose up。");
+    return lines.join("\n");
+}
+async function checkCommand(command, cwd) {
+    if (!MIGHT_MATTER.test(command))
+        return undefined;
+    const commands = simpleCommands(command);
+    for (const { argv, cds } of commands) {
+        const subcommand = composeSubcommand(argv);
+        if (subcommand === undefined || !BLOCKED_COMPOSE.has(subcommand))
+            continue;
+        if (!(await isOnboarded(resolveCds(cwd, cds))))
+            continue;
+        return {
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: `这个项目的服务由 napbox 管理，不能运行 docker compose ${subcommand}。改用 napbox 的 up 工具（命令行是 npx napbox up），它用同一份 compose 起服务，并返回分配好的端口和变量。服务里执行命令用 exec 工具。${subcommand === "run" ? RUN_INSTEAD : ""}如果用户明确要用 Docker，请用户自己在终端运行。`,
+            },
+        };
+    }
+    for (const { argv, cds } of commands) {
+        const reminder = ownServiceReminder(argv);
+        if (reminder === undefined || !(await isOnboarded(resolveCds(cwd, cds))))
+            continue;
+        return { hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: reminder } };
+    }
+    return undefined;
+}
+/** 不拦、只提醒的命令：在宿主机上自己起数据库这类服务，或者 docker run 直接起一个容器 */
+function ownServiceReminder(argv) {
+    const service = startsOwnService(argv);
+    if (service !== undefined) {
+        return `提醒：这个项目的服务由 napbox 管理。如果 ${service} 是 compose 里已有的服务，用 napbox 的 up 工具和它分配的端口，不要自己再起一份。${TEMP_INSTEAD}`;
+    }
+    if (isDockerRun(argv)) {
+        return `提醒：这个项目的服务由 napbox 管理。如果 docker run 要起的是 compose 里已有的服务，用 napbox 的工具，不要自己再起一份。${TEMP_INSTEAD}只跑一次拿结果的，用 run 工具（命令行是 npx napbox run <服务> [-- 命令]）。`;
+    }
+    return undefined;
+}
+function resolveCds(cwd, cds) {
+    return cds.reduce((directory, target) => path.resolve(directory, target), cwd);
+}
+/** 已接入：worktree 根目录有 .napbox.yaml，或者这个仓库的某个 worktree 有环境记录（DESIGN.md 第 12 节第 3 条） */
+async function isOnboarded(directory) {
+    const root = await git(directory, ["rev-parse", "--show-toplevel"]);
+    if (!root)
+        return false;
+    if (existsSync(path.join(root.trim(), ".napbox.yaml")))
+        return true;
+    let worktrees;
+    try {
+        const { environments } = await new NapboxClient().status();
+        worktrees = new Set(environments.filter((e) => !e.owner).map((e) => canonical(e.worktree)));
+    }
+    catch (error) {
+        if (error instanceof NapboxError && error.code === "daemon_unavailable")
+            return false;
+        throw error;
+    }
+    const listed = (await git(directory, ["worktree", "list", "--porcelain"])) ?? "";
+    return listed
+        .split("\n")
+        .filter((line) => line.startsWith("worktree "))
+        .some((line) => worktrees.has(canonical(line.slice("worktree ".length))));
+}
+/** 路径可能写成 /var 或 /private/var，比较前统一。已经不存在的路径原样比较 */
+function canonical(file) {
+    try {
+        return realpathSync(file);
+    }
+    catch {
+        return file;
+    }
+}
+function git(directory, args) {
+    return new Promise((resolve) => {
+        execFile("git", ["-C", directory, ...args], (error, stdout) => {
+            resolve(error ? undefined : stdout);
+        });
+    });
+}

package/dist/agent/locations.d.ts

@@ -0,0 +1,6 @@
+export declare const packageRoot: string;
+export declare const packageVersion: string;
+/** 编译好的 napbox、napboxd、napbox-guard。发布的包在 native/ 下；仓库里没有，要用 NAPBOX_BIN 指向编译产物 */
+export declare const nativeDirectory: () => string;
+/** 插件把固定版本的包装在这里。可以随时删，下次用到时重新安装；napboxd 不放这里（DESIGN.md 第 4 节） */
+export declare const cacheDirectory: () => string;

package/dist/agent/locations.js

@@ -0,0 +1,11 @@
+// 包自己的位置和版本。发布后是 dist/agent/ 下的 .js，仓库里是 src/agent/ 下的 .ts，往上两层都是包的根目录。
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+export const packageVersion = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+/** 编译好的 napbox、napboxd、napbox-guard。发布的包在 native/ 下；仓库里没有，要用 NAPBOX_BIN 指向编译产物 */
+export const nativeDirectory = () => process.env.NAPBOX_BIN || path.join(packageRoot, "native");
+/** 插件把固定版本的包装在这里。可以随时删，下次用到时重新安装；napboxd 不放这里（DESIGN.md 第 4 节） */
+export const cacheDirectory = () => path.join(homedir(), "Library/Caches/napbox");

package/dist/agent/mcp.d.ts

@@ -0,0 +1 @@
+export declare function serveMcp(): Promise<void>;

package/dist/agent/mcp.js

@@ -0,0 +1,132 @@
+// 标准输入输出上的 MCP 服务（JSON-RPC，一行一条）。只提供工具，协议部分照 layermap 手写，不加 SDK 依赖。
+import { createInterface } from "node:readline";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { NapboxClient } from "../client.js";
+import { packageVersion } from "./locations.js";
+import { callTool, listTools } from "./tools.js";
+const ROOTS_WAIT_MS = 5_000;
+const INSTRUCTIONS = "napbox 用项目的 compose 文件给每个 worktree 起一套隔离的开发服务（数据库、对象存储、后端），不用 Docker，端口不冲突，同一个环境的端口固定不变，闲置自动休眠，连接时自动唤醒。需要这些服务时用 up 工具，不要运行 docker compose up。测试要一套用完就扔的服务时给 up 传 temp，要单独跑一次某个服务时用 run 工具，不要运行 docker run。前端、小程序要连后端时，由项目的启动脚本从 up 或 env 取地址交给它们，不要把端口写进代码。新项目要用这些服务时也照这样：写 compose.yaml（ports 只写容器端口）用 up 起，项目的脚本和 README 里不要用 docker，写法见 napbox 技能。";
+export function serveMcp() {
+    const send = (message) => process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+    const client = new NapboxClient();
+    const calls = new Map();
+    const replies = new Map();
+    // 环境按 worktree 识别，所以要知道会话在哪工作。客户端不一定在那里启动服务：Claude Code 桌面版
+    // 在主 checkout 启动，会话却在别的 worktree。客户端能列出 roots 时以第一个 root 为准。
+    let sessionDirectory = process.cwd();
+    let listsRoots = false;
+    let rooted = Promise.resolve();
+    let requests = 0;
+    const readRoots = () => {
+        const id = `napbox-roots-${++requests}`;
+        const reply = new Promise((resolve) => replies.set(id, resolve));
+        send({ id, method: "roots/list" });
+        rooted = Promise.race([reply, delay(ROOTS_WAIT_MS, undefined, { ref: false })]).then((message) => {
+            replies.delete(id);
+            const roots = message?.result?.roots;
+            const root = Array.isArray(roots)
+                ? roots.find((item) => typeof item?.uri === "string" && item.uri.startsWith("file:"))
+                : undefined;
+            if (root && id === `napbox-roots-${requests}`)
+                sessionDirectory = fileURLToPath(root.uri);
+        });
+    };
+    const call = async (id, params) => {
+        const controller = new AbortController();
+        calls.set(id, controller);
+        try {
+            const { value, isError } = await callTool(String(params.name), params.arguments, {
+                client,
+                sessionDirectory: async () => {
+                    await rooted;
+                    return sessionDirectory;
+                },
+                signal: controller.signal,
+            });
+            send({
+                id,
+                result: { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError },
+            });
+        }
+        catch (error) {
+            // 取消的请求不用回应（MCP 规定）
+            if (controller.signal.aborted)
+                return;
+            send({
+                id,
+                result: {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: { code: "internal_error", message: String(error) } }),
+                        },
+                    ],
+                    isError: true,
+                },
+            });
+        }
+        finally {
+            calls.delete(id);
+        }
+    };
+    const handle = (message) => {
+        const { id, method, params = {} } = message;
+        if (method === undefined) {
+            if (id !== undefined && id !== null)
+                replies.get(id)?.(message);
+            return;
+        }
+        if (id === undefined || id === null) {
+            if (listsRoots && (method === "notifications/initialized" || method === "notifications/roots/list_changed")) {
+                readRoots();
+            }
+            if (method === "notifications/cancelled") {
+                calls.get(params.requestId)?.abort();
+            }
+            return;
+        }
+        switch (method) {
+            case "initialize":
+                listsRoots = Boolean(params.capabilities?.roots);
+                return send({
+                    id,
+                    result: {
+                        protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : "2025-06-18",
+                        capabilities: { tools: { listChanged: false } },
+                        serverInfo: { name: "napbox", title: "napbox", version: packageVersion },
+                        instructions: INSTRUCTIONS,
+                    },
+                });
+            case "ping":
+                return send({ id, result: {} });
+            case "tools/list":
+                return send({ id, result: { tools: listTools() } });
+            case "tools/call":
+                return void call(id, params);
+            default:
+                return send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+        }
+    };
+    return new Promise((resolve) => {
+        const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+        lines.on("line", (line) => {
+            if (!line.trim())
+                return;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                return send({ id: null, error: { code: -32700, message: "Parse error" } });
+            }
+            handle(message);
+        });
+        // 会话结束：结束还在跑的 exec，进程退出时连接随之断开
+        lines.on("close", () => {
+            for (const controller of calls.values())
+                controller.abort();
+            resolve();
+        });
+    });
+}

package/dist/agent/setup.d.ts

@@ -0,0 +1,20 @@
+export interface SetupResult {
+    version: string;
+    /** started：新启动；restarted：换了版本；unchanged：已经是这个版本；kept：有环境在运行，没换 */
+    daemon: "started" | "restarted" | "unchanged" | "kept";
+    daemonVersion: string;
+    pid: number;
+    message?: string;
+    runningEnvironments?: string[];
+}
+export interface SetupOptions {
+    restart: boolean;
+    log: (line: string) => void;
+}
+export declare function setup({ restart, log }: SetupOptions): Promise<SetupResult>;
+export type SetupAgent = "claude" | "codex";
+export declare function registerMcp(agent: SetupAgent): Promise<{
+    agent: SetupAgent;
+    server: string;
+    command: string[];
+}>;

package/dist/agent/setup.js

@@ -0,0 +1,255 @@
+// napbox setup（DESIGN.md 第 4 节）：把后台程序放到固定位置，准备内核和 vminit，注册成登录项并启动。
+// 不放在 npm 或 npx 的目录里运行：那些目录会变、会被清理，登录项要一直找得到程序。
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { chmod, cp, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { NapboxClient, NapboxError, supportDirectory } from "../client.js";
+import { cacheDirectory, nativeDirectory, packageRoot, packageVersion } from "./locations.js";
+const execFile = promisify(execFileCallback);
+const BASE_LABEL = "io.github.coffeecoproject.napbox";
+const MINIMUM_MACOS = 26;
+/** napboxd 收到 SIGTERM 后要停掉所有环境，launchd 默认只等 20 秒 */
+const EXIT_TIMEOUT_SECONDS = 120;
+const START_TIMEOUT_MS = 20_000;
+const failed = (message) => new NapboxError("setup_failed", message);
+/** 设了 NAPBOX_SUPPORT_DIR（测试用的独立目录）时用另一个名字，不和正式的登录项冲突 */
+function launchLabel() {
+    const custom = process.env.NAPBOX_SUPPORT_DIR;
+    if (!custom)
+        return BASE_LABEL;
+    return `${BASE_LABEL}.${createHash("sha256").update(custom).digest("hex").slice(0, 8)}`;
+}
+const launchDomain = () => `gui/${process.getuid?.()}`;
+async function launchctl(...args) {
+    return execFile("launchctl", args);
+}
+async function isRegistered() {
+    try {
+        await launchctl("print", `${launchDomain()}/${launchLabel()}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkPlatform() {
+    if (process.platform !== "darwin" || process.arch !== "arm64") {
+        throw failed(`napbox 只支持 Apple 芯片的 Mac，这里是 ${process.platform} ${process.arch}`);
+    }
+    const { stdout } = await execFile("sw_vers", ["-productVersion"]);
+    if (Number.parseInt(stdout, 10) < MINIMUM_MACOS) {
+        throw failed(`napbox 要 macOS ${MINIMUM_MACOS} 或更新的版本，这里是 ${stdout.trim()}`);
+    }
+}
+async function runningDaemon(client) {
+    try {
+        return await client.status();
+    }
+    catch (error) {
+        if (error instanceof NapboxError && error.code === "daemon_unavailable")
+            return undefined;
+        throw error;
+    }
+}
+const fileHash = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
+export async function setup({ restart, log }) {
+    await checkPlatform();
+    const source = nativeDirectory();
+    const sourceDaemon = path.join(source, "napboxd");
+    if (!existsSync(sourceDaemon))
+        throw failed(`没有 ${sourceDaemon}：包不完整`);
+    const client = new NapboxClient();
+    const current = await runningDaemon(client);
+    const registered = await isRegistered();
+    if (current && !registered) {
+        throw failed(`有一份不是登录项的 napboxd 在运行（pid ${current.pid}），先停掉它再运行 setup`);
+    }
+    const installDirectory = path.join(supportDirectory(), "daemon", packageVersion);
+    const installedDaemon = path.join(installDirectory, "napboxd");
+    const sameProgram = existsSync(installedDaemon) && fileHash(installedDaemon) === fileHash(sourceDaemon);
+    const upToDate = current?.version === packageVersion && sameProgram;
+    if (current && !upToDate && !restart) {
+        const running = current.environments.filter((e) => e.state === "running").map((e) => e.name);
+        if (running.length) {
+            return {
+                version: packageVersion,
+                daemon: "kept",
+                daemonVersion: current.version,
+                pid: current.pid,
+                runningEnvironments: running,
+                message: `有 ${running.length} 个环境在运行，后台程序还是 ${current.version}，没有换。换版本会停掉这些环境、断开连接；要现在换就加 restart。`,
+            };
+        }
+    }
+    if (!sameProgram)
+        await install(source, installDirectory);
+    await prepare(installedDaemon, log);
+    if (current && upToDate) {
+        return { version: packageVersion, daemon: "unchanged", daemonVersion: current.version, pid: current.pid };
+    }
+    await writeLaunchAgent(installedDaemon);
+    if (registered)
+        await stopRegistered(client);
+    await bootstrap();
+    const started = await waitForDaemon(client);
+    if (started.version !== packageVersion) {
+        throw failed(`启动后 napboxd 的版本是 ${started.version}，包的版本是 ${packageVersion}，这个包打得不对`);
+    }
+    await removeOldVersions(path.dirname(installDirectory));
+    return {
+        version: packageVersion,
+        daemon: current ? "restarted" : "started",
+        daemonVersion: started.version,
+        pid: started.pid,
+    };
+}
+/** 先放进临时目录再改名：不会留下一半 */
+async function install(source, destination) {
+    const parent = path.dirname(destination);
+    await mkdir(parent, { recursive: true });
+    const staging = await mkdtemp(path.join(parent, ".install-"));
+    try {
+        for (const name of ["napboxd", "napbox-guard"]) {
+            await cp(path.join(source, name), path.join(staging, name));
+            await chmod(path.join(staging, name), 0o755);
+        }
+        await rm(destination, { recursive: true, force: true });
+        await rename(staging, destination);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+async function prepare(daemon, log) {
+    try {
+        const { stdout } = await execFile(daemon, ["prepare"], { maxBuffer: 1 << 20 });
+        for (const line of stdout.split("\n"))
+            if (line)
+                log(line);
+    }
+    catch (error) {
+        const { stderr, message } = error;
+        throw failed(`准备内核和 vminit 失败：${stderr?.trim() || message}`);
+    }
+}
+const xml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+function launchAgent(daemon) {
+    const log = xml(path.join(supportDirectory(), "napboxd.log"));
+    const custom = process.env.NAPBOX_SUPPORT_DIR;
+    const environment = custom
+        ? `  <key>EnvironmentVariables</key>
+  <dict>
+    <key>NAPBOX_SUPPORT_DIR</key>
+    <string>${xml(custom)}</string>
+  </dict>
+`
+        : "";
+    // ProcessType：不写时 launchd 会限速，虚拟机跟着慢（DESIGN.md 第 2 节）。Interactive 和普通 app 一样不限。
+    // KeepAlive：崩溃了拉起来；正常退出（退出码 0）不拉，比如 launchctl bootout。
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${launchLabel()}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(daemon)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>ExitTimeOut</key>
+  <integer>${EXIT_TIMEOUT_SECONDS}</integer>
+  <key>StandardOutPath</key>
+  <string>${log}</string>
+  <key>StandardErrorPath</key>
+  <string>${log}</string>
+${environment}</dict>
+</plist>
+`;
+}
+const launchAgentPath = () => path.join(homedir(), "Library/LaunchAgents", `${launchLabel()}.plist`);
+async function writeLaunchAgent(daemon) {
+    const file = launchAgentPath();
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(`${file}.tmp`, launchAgent(daemon));
+    await rename(`${file}.tmp`, file);
+}
+/** 停掉正在运行的。bootout 发 SIGTERM，napboxd 停完环境才退出 */
+async function stopRegistered(client) {
+    await launchctl("bootout", `${launchDomain()}/${launchLabel()}`).catch(() => { });
+    const deadline = Date.now() + (EXIT_TIMEOUT_SECONDS + 10) * 1000;
+    while ((await isRegistered()) || (await runningDaemon(client))) {
+        if (Date.now() > deadline)
+            throw failed("旧的 napboxd 一直没有退出");
+        await sleep(200);
+    }
+}
+/** launchd 刚清理完同名服务时可能短暂报错，等一下再试 */
+async function bootstrap() {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await launchctl("bootstrap", launchDomain(), launchAgentPath());
+            return;
+        }
+        catch (error) {
+            if (attempt >= 10) {
+                throw failed(`注册登录项失败：${error.stderr?.trim() || String(error)}`);
+            }
+            await sleep(500);
+        }
+    }
+}
+async function waitForDaemon(client) {
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    for (;;) {
+        const status = await runningDaemon(client);
+        if (status)
+            return status;
+        if (Date.now() > deadline) {
+            throw failed(`napboxd 没有启动，看 ${path.join(supportDirectory(), "napboxd.log")}`);
+        }
+        await sleep(200);
+    }
+}
+async function removeOldVersions(directory) {
+    for (const name of await readdir(directory)) {
+        if (name !== packageVersion)
+            await rm(path.join(directory, name), { recursive: true, force: true });
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** agent 启动 MCP 服务用的命令。发布的包：缓存目录里的启动脚本，不依赖 npx 的目录；仓库里：直接运行自己 */
+async function mcpCommand() {
+    const published = path.join(packageRoot, "dist/server-launcher.mjs");
+    if (!existsSync(published))
+        return [process.execPath, path.resolve(process.argv[1]), "mcp"];
+    const launcher = path.join(cacheDirectory(), "server.mjs");
+    await mkdir(cacheDirectory(), { recursive: true });
+    await cp(published, launcher);
+    return ["node", launcher];
+}
+export async function registerMcp(agent) {
+    const scope = agent === "claude" ? ["--scope", "user"] : [];
+    const command = await mcpCommand();
+    await execFile(agent, ["mcp", "remove", "napbox", ...scope]).catch(() => { });
+    try {
+        await execFile(agent, ["mcp", "add", ...scope, "napbox", "--", ...command]);
+    }
+    catch (error) {
+        const { stderr, message } = error;
+        throw failed(`加不进 ${agent}：${stderr?.trim() || message}`);
+    }
+    return { agent, server: "napbox", command };
+}

package/dist/agent/shell-command.d.ts

@@ -0,0 +1,13 @@
+export interface SimpleCommand {
+    argv: string[];
+    /** 这条命令之前出现过的 cd 的目标（只认字面路径），按顺序；相对路径相对于前一个 */
+    cds: string[];
+}
+/** 拆成简单命令。sh -c '...' 里的内容也拆开看 */
+export declare function simpleCommands(command: string, depth?: number): SimpleCommand[];
+/** docker compose 的子命令，不是 docker compose 时是 undefined */
+export declare function composeSubcommand(argv: string[]): string | undefined;
+/** 是不是 docker run（或者同一件事的另一种写法 docker container run）：不靠 compose 直接起一个容器 */
+export declare function isDockerRun(argv: string[]): boolean;
+/** 自己在宿主机上起数据库这类服务的命令，返回一句话描述；不是时返回 undefined */
+export declare function startsOwnService(argv: string[]): string | undefined;