worktree-bay 4.0.0 → 4.0.2

package/dist/commands/add.js

@@ -35,6 +35,8 @@ export async function addCommand(cfg, feature, service, branch, base) {
         }
         catch (e) {
             const m = String(e.message);
+            if (/not a valid branch name|cannot be used as a branch name/i.test(m)) // 分支名不合法（先于 base 判，二者都含 "not a valid"）
+                throw new Error(t(`分支名「${br}」不合法：git 分支名不能以 / 开头或结尾、不能含 // 或 ..。换一个，如 fix/log（去掉前导斜杠）。`, `invalid branch name "${br}": git branch names can't start/end with "/" or contain "//" or "..". Use e.g. fix/log (no leading slash).`));
             if (/invalid reference|unknown revision|ambiguous argument|not a valid|Not a valid object name/i.test(m))
                 throw new Error(t(`基分支「${resolvedBase}」无效（该仓可能没有 origin 或对应主分支）。给 add 显式传 base，例如：worktree-bay add ${feature} ${service} ${br} HEAD`, `invalid base ref "${resolvedBase}" (this repo may have no origin or main branch). Pass an explicit base to add, e.g.: worktree-bay add ${feature} ${service} ${br} HEAD`));
             throw e;

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

@@ -125,14 +125,28 @@ export async function ensureRuntime(ctx) {
     await ensureStarted(ctx);
 }
 // 停止运行体：杀 managed dev server + 跑 stop 钩子（docker compose stop）。不动 worktree。
+// 始终给每个服务输出一行状态——哪怕本就没在跑（否则只剩一个裸服务名，看不出结果）。
+// 用端口实判：docker 容器停了端口即释放、dev server 同理，比「有没有 managed 记录」更准，
+// 据此给出诚实状态（本就空闲 / 外部未托管 / 未在运行），不让一个绿勾掩盖「其实没东西在跑」。
 export async function stopRuntime(ctx) {
     const { cfg, sp, dir, service, vars } = ctx;
+    const port = Number(vars.port);
+    const wasUp = await portInUse(port);
     const stopped = stopManaged(cfg.workspaceRoot, dir);
     if (stopped)
         log(`  ${cc.green('✓')} ` + t(`已停止 dev server（pid ${stopped.pid}）`, `stopped dev server (pid ${stopped.pid})`));
     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 (!wasUp)
+            log(`  ${cc.dim('•')} ` + t(`（端口 ${port} 此前空闲，${service} 实际并未在对外服务）`, `(port ${port} was idle; ${service} wasn't actually serving)`));
+    }
+    if (!stopped && !sp.stop) {
+        if (wasUp)
+            log(`  ${cc.yellow('•')} ` + t(`端口 ${port} 仍被占用（外部启动、未托管），请手动停止`, `port ${port} in use (external, unmanaged); stop manually`));
+        else
+            log(`  ${cc.dim('•')} ` + t('未在运行', 'not running'));
     }
 }
 export function execArgv(ctx, cmd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "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,8 @@ 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` 的 `running`、`stop` 的「是否真在跑」一律按约定端口是否被监听判（覆盖 docker / 托管 dev server / 外部手起三类），不依赖 pid 账本（dir 形态会漂移、docker 无账本记录）。`stop` 对每个服务都给状态：已停 / 端口空闲（docker 钩子仍幂等跑一遍）/ 外部未托管需手动停。
 - **并发安全**：`claim/add/up/rm/down/gc` 全程持工作区原子锁。
 - **前端自接后端**：前端有 `upstream` 且同槽该上游服务的 worktree 已建，则 `{upstreamBase}` = 本槽上游端口；否则用 `fallback`。所以**联调时先 `up`/`add` 后端，再起前端**。
 - **合并感知回收**：`gc` 先 `git fetch`，用 `merge-base --is-ancestor` 判断是否并入主分支；**只在「已合并 + 工作区干净 + 无未推」时才自动删**，判不准一律保守不删、只标记。
@@ -171,7 +172,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` 取本指南全文。
 
 ## 常见坑