worktree-bay 4.0.1 → 4.0.3

package/dist/commands/ls.js

@@ -1,19 +1,20 @@
 import { scanOccupancy, readLabels } from '../slots.js';
 import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
-import { recordedFor, pidOnPort } from '../proc.js';
+import { pidOnPort } from '../proc.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
-// 该服务的约定端口是否有进程在监听（按端口判，不受 shell/pnpm 让记录 pid 漂移的影响）
-function running(cfg, dir, port) { return !!recordedFor(cfg.workspaceRoot, dir) && !!pidOnPort(port); }
+// 「在跑」= 该服务约定端口上有进程监听，覆盖三类：docker(setup) / managed dev server(start) / 外部手起。
+// 只按端口判：不依赖进程账本 dir 精确匹配（dir 相对/绝对形态会漂移），docker 服务也无 managed 记录。
+function running(port) { return !!pidOnPort(port); }
 export function renderSlots(cfg) {
     const occ = scanOccupancy(cfg);
     const labels = readLabels(cfg);
     const slots = new Set([...occ.keys(), ...Object.keys(labels).map(Number)]);
     const lines = [];
     for (const n of [...slots].sort((a, b) => a - b)) {
-        const svc = (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); return `${o.service}@${p}${running(cfg, o.dir, p) ? c.green(' ▸run') : ''}`; });
-        lines.push(`${c.dim('slot ' + n)}  ${c.bold(c.cyan(labels[String(n)] ?? t('(未命名)', '(unnamed)')))}  [${svc.join(', ') || c.dim(t('无 worktree', 'no worktree'))}]`);
+        const svc = (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); const dot = running(p) ? c.green('●') : c.dim('●'); return `${dot}${o.service}@${p}`; });
+        lines.push(`${c.bold(c.cyan(String(n)))}${c.dim(':')} ${c.bold(labels[String(n)] ?? t('(未命名)', '(unnamed)'))}  [${svc.join(', ') || c.dim(t('无 worktree', 'no worktree'))}]`);
     }
     return lines.join('\n') || t('(无槽位在用)', '(no slots in use)');
 }
@@ -23,7 +24,7 @@ export function slotsData(cfg) {
     const slots = new Set([...occ.keys(), ...Object.keys(labels).map(Number)]);
     return [...slots].sort((a, b) => a - b).map((n) => ({
         slot: n, feature: labels[String(n)] ?? null,
-        services: (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); return { service: o.service, port: p, dir: o.dir, running: running(cfg, o.dir, p) }; }),
+        services: (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); return { service: o.service, port: p, dir: o.dir, running: running(p) }; }),
     }));
 }
 export function lsCommand(cfg, json = false) { log(json ? JSON.stringify(slotsData(cfg), null, 2) : renderSlots(cfg)); }

package/dist/config.js

@@ -4,16 +4,19 @@ import { t } from './i18n.js';
 function refs(tpl) { return [...tpl.matchAll(/\{(\w+)\}/g)].map((m) => m[1]); }
 export function parseConfig(configPath) {
     const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    for (const k of ['workspaceRoot', 'maxSlots'])
-        if (raw[k] === undefined)
-            throw new Error(t(`config: 缺少必填字段 ${k}`, `config: ${k} required`));
+    if (raw.maxSlots === undefined)
+        throw new Error(t('config: 缺少必填字段 maxSlots', 'config: maxSlots required'));
+    const configDir = path.dirname(configPath);
+    // workspaceRoot 非必选，默认当前目录（= config 所在目录）；相对路径相对 config 目录解析，
+    // 已是绝对路径时 path.resolve 原样返回（向后兼容，且不再受进程 cwd 影响）
+    const workspaceRoot = path.resolve(configDir, raw.workspaceRoot ?? '.');
     const maxSlots = raw.maxSlots;
     const services = raw.services ?? {};
     // 端口段：每个服务 [port, port+maxSlots]（port=主 dev/槽0，槽 1..maxSlots 落在段内）
     for (const [name, sp] of Object.entries(services)) {
         if (typeof sp.port !== 'number' || sp.port < 1)
             throw new Error(t(`config: ${name}.port 必须是正整数`, `config: ${name}.port must be a positive number`)); // V2
-        const repoDir = path.join(raw.workspaceRoot, sp.repo ?? name);
+        const repoDir = path.join(workspaceRoot, sp.repo ?? name);
         if (!fs.existsSync(repoDir))
             throw new Error(t(`config: ${name}.repo 目录不存在: ${repoDir}（检查 workspaceRoot 与 repo 名，或先 git clone）`, `config: ${name}.repo dir missing: ${repoDir} (check workspaceRoot and the repo name, or clone it first)`)); // V5
     }
@@ -32,7 +35,7 @@ export function parseConfig(configPath) {
             for (const ref of refs(v))
                 if (!known.has(ref) && !(sp.vars && ref in sp.vars))
                     throw new Error(t(`config: 未知模板变量 {${ref}}（只能引用内置变量或本服务 vars 里已声明的）`, `config: unknown template var {${ref}} (only built-in vars or this service's declared vars are allowed)`));
-    return { workspaceRoot: raw.workspaceRoot, maxSlots, services, configDir: path.dirname(configPath) };
+    return { workspaceRoot, maxSlots, services, configDir };
 }
 export function loadConfig(startDir) {
     if (process.env.WORKTREE_BAY_CONFIG)

package/dist/engine.js

@@ -8,7 +8,7 @@ import { runShellLive, run, spliceArgv, isTTY } from './util/exec.js';
 import { warn, log } from './util/log.js';
 import { withProgress } from './util/progress.js';
 import { color as cc } from './util/color.js';
-import { startDetached, recordedFor, pidAlive, setPid, pidOnPort, readLogTail, stopManaged } from './proc.js';
+import { startDetached, recordedFor, pidAlive, setPid, pidOnPort, readLogTail, stopManaged, stopUnrecordedOnPort } from './proc.js';
 import { t } from './i18n.js';
 export function mergeEnvText(text, kv) {
     const lines = text.split('\n');
@@ -82,7 +82,7 @@ export async function ensureStarted(ctx) {
         log(cc.dim(t(`  • ${service} dev server 已在跑（pid ${rec.pid}，端口 ${port}）`, `  • ${service} dev server already running (pid ${rec.pid}, port ${port})`)));
         return;
     }
-    if (await portInUse(port)) {
+    if (pidOnPort(port)) {
         log(cc.dim(t(`  • 端口 ${port} 已在监听，视为 ${service} dev server 在跑，跳过启动`, `  • port ${port} already listening; treating ${service} dev server as up, skip`)));
         return;
     }
@@ -115,24 +115,53 @@ async function waitForListen(port, ms) {
     }
 }
 // 「运行体」= docker 容器(infra) + node dev server。up 重入 / start / restart 共用，统一边界。
-// 恢复运行体：有 stop 钩子的 infra 服务重跑 setup（docker compose up -d 幂等恢复）+ 起 managed dev server。
+// 恢复运行体：有 stop 钩子的 infra 服务在端口没监听时才重跑 setup（docker compose up -d）+ 起 managed dev server。
+// 「是否在跑」一律按端口实判，与 ls 同源（pidOnPort/netstat，而非 connect 探测——docker 发布端口两者会不一致，
+// 导致 ls 显示在跑、start 却误判没跑去「恢复」）。端口已在监听就视为在跑、跳过，不再无脑重跑 setup。
 export async function ensureRuntime(ctx) {
     const { sp, dir, service, vars } = ctx;
     if (sp.stop && sp.setup) {
-        const cmd = renderTemplate(sp.setup, vars);
-        await runShellLive(cmd, { cwd: dir }, t(`恢复 ${service}：${cmd}`, `resume ${service}: ${cmd}`));
+        const port = Number(vars.port);
+        if (pidOnPort(port))
+            log(cc.dim(t(`  • ${service} 已在跑（端口 ${port} 在监听），跳过恢复`, `  • ${service} already up (port ${port} listening), skip resume`)));
+        else {
+            const cmd = renderTemplate(sp.setup, vars);
+            await runShellLive(cmd, { cwd: dir }, t(`恢复 ${service}：${cmd}`, `resume ${service}: ${cmd}`));
+        }
     }
     await ensureStarted(ctx);
 }
 // 停止运行体：杀 managed dev server + 跑 stop 钩子（docker compose stop）。不动 worktree。
+// 始终给每个服务输出一行状态。「是否在跑」用 pidOnPort（与 ls 同源），不用 connect 探测。
+// 严格判定：只停「本目录 + 本端口 + 本进程」——dev server 凭账本（dir 已规范化匹配）认本进程，
+// 不去按端口盲杀（端口可能被无关进程占）；没有账本记录就如实报告、不动它。
 export async function stopRuntime(ctx) {
     const { cfg, sp, dir, service, vars } = ctx;
+    const port = Number(vars.port);
+    const onPort = pidOnPort(port); // 停之前先记下端口真相（stopManaged 可能把它杀掉）
     const stopped = stopManaged(cfg.workspaceRoot, dir);
     if (stopped)
-        log(`  ${cc.green('✓')} ` + t(`已停止 dev server（pid ${stopped.pid}）`, `stopped dev server (pid ${stopped.pid})`));
+        log(`  ${cc.green('✓')} ` + t(`已停止 dev server（pid ${stopped.pid}，端口 ${stopped.port}）`, `stopped dev server (pid ${stopped.pid}, port ${stopped.port})`));
     if (sp.stop) {
+        // stop 钩子始终跑（docker compose stop 幂等，且能收掉 app 端口没监听、但 mysql/redis 等边车还在的情况）。
         const cmd = renderTemplate(sp.stop, vars);
         await runShellLive(cmd, { cwd: dir }, t(`停 ${service}：${cmd}`, `stop ${service}: ${cmd}`));
+        if (!onPort)
+            log(`  ${cc.dim('•')} ` + t(`（端口 ${port} 此前空闲，${service} 实际并未在对外服务）`, `(port ${port} was idle; ${service} wasn't actually serving)`));
+    }
+    if (!stopped && !sp.stop) {
+        if (!onPort) {
+            log(`  ${cc.dim('•')} ` + t('未在运行', 'not running'));
+            return;
+        }
+        // 无账本记录：校验后才杀（cwd==本目录 或 命令行含本端口），确证不了就不动
+        const r = stopUnrecordedOnPort(cfg.workspaceRoot, dir, port);
+        if (r.confirmed)
+            log(`  ${cc.green('✓')} ` + t(`已停止（端口 ${port} 上 pid ${r.pid}，经${r.how === 'cwd' ? '工作目录' : '命令行'}确认属本 worktree）`, `stopped (pid ${r.pid} on port ${port}, confirmed as this worktree by ${r.how})`));
+        else if (r.reason === 'cwd-mismatch')
+            log(`  ${cc.yellow('•')} ` + t(`端口 ${port} 被 pid ${r.pid} 占用，但其工作目录非本 worktree（${r.cwd}），未停`, `port ${port} held by pid ${r.pid}, but its cwd isn't this worktree (${r.cwd}); left running`));
+        else
+            log(`  ${cc.yellow('•')} ` + t(`端口 ${port} 被 pid ${r.pid} 占用，无账本记录且无法确认是本服务本进程，未自动停止`, `port ${port} held by pid ${r.pid}, no record and can't confirm it's this service; left running`));
     }
 }
 export function execArgv(ctx, cmd) {

package/dist/proc.js

@@ -17,8 +17,12 @@ export function pidAlive(pid) { if (!pid || pid < 1)
 catch {
     return false;
 } }
-export function recordedFor(ws, dir) { return readProcs(ws).find((r) => r.dir === dir); }
-export function setPid(ws, dir, pid) { const recs = readProcs(ws); const r = recs.find((x) => x.dir === dir); if (r) {
+// 账本 dir 可能存成相对/绝对、斜杠或大小写不一（写入与查时来源不同）。统一相对 ws 解析成绝对、
+// Windows 下再大小写折叠后比较，保证「同一个 worktree 目录」一定能匹配上（严格判定的「本目录」凭据）。
+function normDir(ws, p) { const r = path.resolve(ws, p); return process.platform === 'win32' ? r.toLowerCase() : r; }
+function sameDir(ws, a, b) { return normDir(ws, a) === normDir(ws, b); }
+export function recordedFor(ws, dir) { return readProcs(ws).find((r) => sameDir(ws, r.dir, dir)); }
+export function setPid(ws, dir, pid) { const recs = readProcs(ws); const r = recs.find((x) => sameDir(ws, x.dir, dir)); if (r) {
     r.pid = pid;
     writeProcs(ws, recs);
 } }
@@ -55,6 +59,70 @@ export function pidOnPort(port) {
     }
     return undefined;
 }
+// 取进程工作目录(cwd)。Linux/macOS 原生可取（最强的「本目录」证据）；
+// Windows 普通命令拿不到他进程 cwd（存在 PEB、需 ReadProcessMemory），返回 undefined，由调用方降级到命令行核对。
+export function processCwd(pid) {
+    if (!pid || pid < 1)
+        return undefined;
+    try {
+        if (process.platform === 'linux')
+            return fs.readlinkSync(`/proc/${pid}/cwd`);
+        if (process.platform === 'darwin') {
+            const r = spawnSync('lsof', ['-a', '-d', 'cwd', '-p', String(pid), '-Fn'], { encoding: 'utf8' });
+            if (r.status === 0) {
+                const m = /^n(.+)$/m.exec(r.stdout || '');
+                if (m)
+                    return m[1].trim();
+            }
+        }
+    }
+    catch { /* 取不到就降级 */ }
+    return undefined;
+}
+// 取进程命令行（cwd 取不到时的跨平台兜底，尤其 Windows）。
+export function processCmdline(pid) {
+    if (!pid || pid < 1)
+        return undefined;
+    try {
+        if (process.platform === 'win32') {
+            const r = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`], { encoding: 'utf8' });
+            if (r.status === 0)
+                return (r.stdout || '').trim() || undefined;
+        }
+        else {
+            const r = spawnSync('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8' });
+            if (r.status === 0)
+                return (r.stdout || '').trim() || undefined;
+        }
+    }
+    catch { /* 取不到就放弃确证 */ }
+    return undefined;
+}
+// 无账本记录时的严格兜底：端口上的进程，仅当能确证属于本 worktree 才杀（先校验后杀，绝不凭端口盲杀）。
+// 证据：① cwd == 本 worktree 目录（Linux/macOS，最强，证明「本目录」）；
+//      ② cwd 取不到（Windows）→ 命令行含 `--port <本端口>`（本端口按槽唯一分配，等价确证本服务本进程）。
+// 杀用 killTree（含进程树）；都无法确证则不动、返回 confirmed:false 供上层如实报告。
+export function stopUnrecordedOnPort(ws, dir, port) {
+    const pid = pidOnPort(port);
+    if (!pid)
+        return { confirmed: false, reason: 'idle' };
+    const cwd = processCwd(pid);
+    if (cwd !== undefined) {
+        if (sameDir(ws, cwd, dir)) {
+            if (pidAlive(pid))
+                killTree(pid);
+            return { pid, confirmed: true, how: 'cwd', cwd };
+        }
+        return { pid, confirmed: false, cwd, reason: 'cwd-mismatch' };
+    }
+    const cmd = processCmdline(pid);
+    if (cmd && (cmd.includes(`--port ${port}`) || cmd.includes(`--port=${port}`))) {
+        if (pidAlive(pid))
+            killTree(pid);
+        return { pid, confirmed: true, how: 'cmdline', cmd };
+    }
+    return { pid, confirmed: false, cmd, reason: 'unverified' };
+}
 export function startDetached(ws, dir, service, slug, port, cmd) {
     const logDir = path.join(ws, '.worktree-bay', 'logs');
     fs.mkdirSync(logDir, { recursive: true });
@@ -69,8 +137,9 @@ export function startDetached(ws, dir, service, slug, port, cmd) {
     const child = spawn(cmd, { cwd: dir, shell: true, detached, stdio: ['ignore', fd, fd], windowsHide: true });
     const pid = child.pid ?? -1;
     child.unref();
-    const rec = { dir, service, port, pid, cmd, log, startedAt: Date.now() };
-    writeProcs(ws, [...readProcs(ws).filter((r) => r.dir !== dir), rec]);
+    // 一律存绝对 dir，避免相对/绝对混存导致后续按目录匹配漂移
+    const rec = { dir: path.resolve(ws, dir), service, port, pid, cmd, log, startedAt: Date.now() };
+    writeProcs(ws, [...readProcs(ws).filter((r) => !sameDir(ws, r.dir, dir)), rec]);
     return rec;
 }
 function killTree(pid) {
@@ -92,7 +161,7 @@ function killTree(pid) {
 // 同时按「记录 pid」和「当前端口占用 pid」双杀——shell/pnpm 中间层会让记录 pid 漂移，按端口兜底最稳。
 export function stopManaged(ws, dir) {
     const recs = readProcs(ws);
-    const rec = recs.find((r) => r.dir === dir);
+    const rec = recs.find((r) => sameDir(ws, r.dir, dir));
     if (!rec)
         return undefined;
     const targets = new Set();
@@ -104,6 +173,6 @@ export function stopManaged(ws, dir) {
     for (const pid of targets)
         if (pidAlive(pid))
             killTree(pid);
-    writeProcs(ws, recs.filter((r) => r.dir !== dir));
+    writeProcs(ws, recs.filter((r) => !sameDir(ws, r.dir, dir)));
     return rec;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Per-feature git worktree + port slots for parallel multi-service development: auto deps, env wiring, frontend-to-backend, merge-aware reclaim, plus an MCP server for AI agents.",
   "keywords": [
     "git",

package/skill.md

@@ -66,7 +66,7 @@ worktree-bay gc                        # 回收已合并的
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| `workspaceRoot` | string | 工作区根绝对路径，各服务仓在其下 |
+| `workspaceRoot` | string | **非必选**，工作区根，各服务仓在其下；**默认 = config 文件所在目录**（即省略时等同 `"."`）。可填相对路径（相对 config 目录解析，不受进程 cwd 影响）或绝对路径 |
 | `maxSlots` | number | 最大并行功能数（每个服务预留 `maxSlots` 个端口），如 `9` |
 | `services` | object | 服务名 → 服务定义（见下） |
 
@@ -85,7 +85,7 @@ worktree-bay gc                        # 回收已合并的
 | `upstream` | | object | 声明依赖的上游服务：`{ "service": "api", "fallback": "http://localhost:6001" }`，产出 `{upstreamBase}` 变量 |
 | `setup` | | string | 挂入后执行的 shell 命令（创建/装好运行体，如 `docker compose up -d`、`pnpm install`）。`up` 时跑 |
 | `teardown` | | string | 拆除时执行的 shell 命令（销毁运行体，如 `docker compose down -v`）。`down`/`rm`/`gc` 时跑 |
-| `start` | | string | 长进程 dev server（如 `pnpm dev`）。`up` 时**自动后台启动**（detach + 日志落 `.worktree-bay/logs/`），按端口追踪 pid；由 `start`/`stop`/`restart` 控制，`ls` 标 `▸run` |
+| `start` | | string | 长进程 dev server（如 `pnpm dev`）。`up` 时**自动后台启动**（detach + 日志落 `.worktree-bay/logs/`），按端口追踪 pid；由 `start`/`stop`/`restart` 控制，`ls` 行首 `●` 标在跑（绿）/未跑（灰） |
 | `stop` | | string | 停止该服务 infra 运行体的 shell（如 `docker compose stop`）。供 `stop`/`restart` 用——让 docker 容器能「停而不毁」；`start` 时对配了它的服务重跑 `setup` 幂等恢复 |
 | `exec` | | string[] | 透传命令模板（argv 数组），`{cmd...}` 是 argv splice 占位，防 shell 注入。如 `["docker","exec","-i","{project}-app-1","{cmd...}"]` |
 | `run` | | object | 命名命令：`{ "test": ["composer","run","test"] }`，供 `worktree-bay run <feature> <service> test` 调用 |
@@ -162,7 +162,9 @@ worktree-bay gc                        # 回收已合并的
 ## 工作原理要点
 
 - **占用真相 = 文件系统**：扫各服务 `.worktrees/s<N>-*`；`.worktree-bay-slots.json` 只是「功能名→槽号」标签账本（预约）。
-- **dev server 托管**：`start` 进程后台 detach 启动、日志落 `.worktree-bay/logs/`、按端口追踪真实 pid；`ls` 标 `▸run`；`stop`/`down` 按端口可靠停。
+- **dev server 托管**：`start` 进程后台 detach 启动、日志落 `.worktree-bay/logs/`、按端口追踪真实 pid；`ls` 行首 `●` 标在跑（绿）/未跑（灰）；`stop`/`down` 按端口可靠停。
+- **运行状态判断 = 端口**：`ls`/`start`/`stop` 判「在不在跑」全用 `pidOnPort`（netstat/lsof，与 ls 同源），不用 connect 探测（docker 发布端口两者会不一致）、也不只看 pid 账本（dir 形态会漂移、docker 无账本记录）。`start` 端口已在监听就跳过、不再误报「恢复」。
+- **stop 严格停「本目录+本端口+本进程」**：① 优先用启动账本（dir 已规范化匹配：相对/绝对/大小写都认）；② 账本缺失时**校验后才杀**——Linux/macOS 比对进程 `cwd` 是否为本 worktree，Windows 取不到 cwd 则核对命令行含 `--port <本端口>`（端口按槽唯一，等价确证）；都确证不了就**不动它**并如实报告（绝不凭端口盲杀）。每个服务都有状态行：已停 / 端口空闲 / 无法确认未停。
 - **并发安全**：`claim/add/up/rm/down/gc` 全程持工作区原子锁。
 - **前端自接后端**：前端有 `upstream` 且同槽该上游服务的 worktree 已建，则 `{upstreamBase}` = 本槽上游端口；否则用 `fallback`。所以**联调时先 `up`/`add` 后端，再起前端**。
 - **合并感知回收**：`gc` 先 `git fetch`，用 `merge-base --is-ancestor` 判断是否并入主分支；**只在「已合并 + 工作区干净 + 无未推」时才自动删**，判不准一律保守不删、只标记。
@@ -171,7 +173,7 @@ worktree-bay gc                        # 回收已合并的
 
 ## 给 AI（MCP）
 
-`worktree-bay mcp` 暴露工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / gc / init / skill`。`doctor` 列出全部服务（AI 借此得知服务名）；`ls` 以 JSON 返回（含各 worktree 绝对路径、`▸run`）；`path` 给某功能某服务的 worktree 目录；`start/stop/restart` 控制运行体（docker+node）；`down` 省略 services 拆整功能、给 services 只拆这些。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
+`worktree-bay mcp` 暴露工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / gc / init / skill`。`doctor` 列出全部服务（AI 借此得知服务名）；`ls` 以 JSON 返回 `[{slot, feature(可 null), services:[{service, port, dir, running}]}]`（含各 worktree 绝对路径、布尔 `running`）；`path` 给某功能某服务的 worktree 目录；`start/stop/restart` 控制运行体（docker+node）；`down` 省略 services 拆整功能、给 services 只拆这些。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
 
 ## 常见坑