worktree-bay 2.5.0 → 4.0.0

package/README.md

@@ -47,7 +47,7 @@ worktree-bay gc
 
 > 运行体随起随停（不动 worktree/代码）：`worktree-bay stop drill-fix` 停掉（docker 容器 + dev server 一起）、`start` 起回来、`restart` 重启。
 >
-> 更细的控制：`claim <feature>` 单独占槽、`add <feature> <service> [branch]` 单加一个服务（branch 可自定义，省略则用功能名）、`rm <feature> [service]` 拆单个服务。
+> 更细的控制：`claim <feature>` 单独占槽、`add <feature> <service> [branch]` 单加一个服务（branch 可自定义，省略则用功能名）、`down <feature> <service>` 只拆某个服务（省略服务则拆整功能）。
 
 ## 配置
 

package/dist/cli.js

@@ -73,8 +73,10 @@ catch (e) {
     die(e.message);
 } });
 program.command('add <feature> <service> [branch] [base]').description(t('为功能在某服务开 worktree（branch 默认 = 功能名）', 'open a worktree for a feature on one service (branch defaults to feature name)'))
-    .action(async (f, s, b, base) => { try {
-    await addCommand(loadConfig(process.cwd()), f, s, b, base);
+    .option('--branch <branch>', t('要创建的分支名（默认 = 功能名）', 'branch to create (default = feature name)'))
+    .option('--base <base>', t('分支基点（默认 = origin/<主分支>）', 'base ref for the branch (default = origin/<main>)'))
+    .action(async (f, s, b, base, o) => { try {
+    await addCommand(loadConfig(process.cwd()), f, s, o.branch ?? b, o.base ?? base);
 }
 catch (e) {
     die(e.message);
@@ -83,37 +85,30 @@ program.command('run <feature> <service> <name> [args...]').description(t('在
     .action((f, s, n, args) => sync((c) => runCommand(c, f, s, n, args ?? [])));
 program.command('sh <feature> <service>').description(t('进入服务运行体的 shell', 'open a shell inside the service runtime'))
     .action((f, s) => sync((c) => shCommand(c, f, s)));
-program.command('start <feature> [service]').description(t('启动该功能的 dev server（worktree 已在，只起 start 进程，不动 worktree）', 'start the feature\'s dev server(s) (worktree already exists; runs the start process only)'))
+program.command('start <feature> [services...]').description(t('启动功能的运行体（docker 容器 + dev server）；省略 service = 全部，可列多个。不动 worktree', 'start the feature\'s runtime (docker + dev server); omit services = all, or list several. Leaves the worktree untouched'))
     .action(async (f, s) => { try {
-    await startCommand(loadConfig(process.cwd()), f, s);
+    await startCommand(loadConfig(process.cwd()), f, s ?? []);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('stop <feature> [service]').description(t('停止该功能的 dev server（保留 worktree）', 'stop the feature\'s dev server(s) (keeps the worktree)'))
+program.command('stop <feature> [services...]').description(t('停止功能的运行体（停 docker + 杀 dev server）；省略 = 全部，可列多个。保留 worktree', 'stop the feature\'s runtime (stop docker + kill dev server); omit = all, or list several. Keeps the worktree'))
     .action(async (f, s) => { try {
-    await stopCommand(loadConfig(process.cwd()), f, s);
+    await stopCommand(loadConfig(process.cwd()), f, s ?? []);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('restart <feature> [service]').description(t('重启该功能的 dev server（停掉再起）', 'restart the feature\'s dev server(s) (stop then start)'))
+program.command('restart <feature> [services...]').description(t('重启功能的运行体（停掉再起）；省略 = 全部，可列多个', 'restart the feature\'s runtime (stop then start); omit = all, or list several'))
     .action(async (f, s) => { try {
-    await restartCommand(loadConfig(process.cwd()), f, s);
+    await restartCommand(loadConfig(process.cwd()), f, s ?? []);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('down <feature>').description(t('拆除整个功能的所有服务 worktree（= rm <feature>）', 'tear down all of a feature\'s service worktrees (= rm <feature>)')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
-    .action(async (f, o) => { try {
-    await rmCommand(loadConfig(process.cwd()), f, undefined, !!o.force);
-}
-catch (e) {
-    die(e.message);
-} });
-program.command('rm <feature> [service]').description(t('拆除某服务或整槽的 worktree（默认查脏/未推保护）', 'remove one service\'s or the whole slot\'s worktree (dirty/unpushed protected by default)')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
+program.command('down <feature> [services...]').description(t('拆除功能的 worktree（停运行体 + teardown + 删 worktree）；省略 services = 整功能，可列多个只拆这些。默认查脏/未推保护', 'tear down a feature\'s worktree(s) (stop runtime + teardown + remove worktree); omit services = whole feature, or list several. Dirty/unpushed protected by default')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
     .action(async (f, s, o) => { try {
-    await rmCommand(loadConfig(process.cwd()), f, s, !!o.force);
+    await rmCommand(loadConfig(process.cwd()), f, s ?? [], !!o.force);
 }
 catch (e) {
     die(e.message);

package/dist/commands/completion.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { readLabels } from '../slots.js';
 import { log } from '../util/log.js';
 import { t } from '../i18n.js';
-const SUBCMDS = ['init', 'doctor', 'claim', 'up', 'add', 'ls', 'path', 'gc', 'down', 'rm', 'run', 'sh', 'start', 'stop', 'restart', 'completion', 'mcp', 'skill', 'version', 'help'];
+const SUBCMDS = ['init', 'doctor', 'claim', 'up', 'add', 'ls', 'path', 'gc', 'down', 'run', 'sh', 'start', 'stop', 'restart', 'completion', 'mcp', 'skill', 'version', 'help'];
 // words = 命令名 + 光标前已输入完的词（不含当前正在补的词）
 export function complete(cfg, words) {
     const prev = words.slice(1);
@@ -14,15 +14,15 @@ export function complete(cfg, words) {
         return []; // 无配置（不在工作区内）：子命令已补全，feature/service 无从读取
     const sub = prev[0];
     const pos = prev.length;
-    const featureSubs = ['up', 'add', 'rm', 'down', 'run', 'sh', 'path', 'start', 'stop', 'restart'];
+    const featureSubs = ['up', 'add', 'down', 'run', 'sh', 'path', 'start', 'stop', 'restart'];
     if (featureSubs.includes(sub) && pos === 1)
         return Object.values(readLabels(cfg));
-    if (['add', 'run', 'sh', 'path', 'start', 'stop', 'restart'].includes(sub) && pos === 2)
-        return Object.keys(cfg.services);
+    if (['add', 'run', 'sh', 'path'].includes(sub) && pos === 2)
+        return Object.keys(cfg.services); // 单服务
     if (sub === 'run' && pos === 3)
         return Object.keys(cfg.services[prev[2]]?.run ?? {}); // run <feature> <service> <name>：补该服务的 run 命令名
-    if (sub === 'up' && pos >= 2)
-        return Object.keys(cfg.services); // up 接变长服务列表
+    if (['up', 'start', 'stop', 'restart', 'down'].includes(sub) && pos >= 2)
+        return Object.keys(cfg.services); // 变长服务列表
     return [];
 }
 export function completionScript(shell) {

package/dist/commands/lifecycle.js

@@ -7,12 +7,18 @@ import { log } from '../util/log.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
 // dev server + infra 生命周期：stop/start/restart 同时管 node（managed 进程）与 docker（stop 钩子 + setup 恢复），不动 worktree。
-function occupantsOf(cfg, feature, service) {
+// services 为空 = 整功能；否则只这些服务
+function occupantsOf(cfg, feature, services = []) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
         throw new Error(t(`功能「${feature}」未占槽。先 \`worktree-bay up ${feature} <服务...>\` 起它。`, `feature "${feature}" hasn't claimed a slot. Run \`worktree-bay up ${feature} <services...>\` first.`));
     const all = scanOccupancy(cfg).get(slot) ?? [];
-    return service ? all.filter((o) => o.service === service) : all;
+    if (!services.length)
+        return all;
+    for (const s of services)
+        if (!all.some((o) => o.service === s))
+            throw new Error(t(`服务「${s}」不在功能「${feature}」里。用 \`worktree-bay ls\` 看已起的服务。`, `service "${s}" is not in feature "${feature}". See \`worktree-bay ls\`.`));
+    return all.filter((o) => services.includes(o.service));
 }
 function ctxOf(cfg, o) {
     const base = { cfg, service: o.service, sp: cfg.services[o.service], slot: o.slot, slug: o.slug, dir: o.dir, repo: repoPath(cfg, o.service) };
@@ -20,10 +26,10 @@ function ctxOf(cfg, o) {
 }
 // 该服务是否有「可停起的运行体」：managed dev server(start) 或可停的 infra(stop 钩子)
 const hasRuntime = (cfg, service) => { const sp = cfg.services[service]; return !!(sp.start || sp.stop); };
-export async function stopCommand(cfg, feature, service) {
+export async function stopCommand(cfg, feature, services = []) {
     await withLock(cfg.workspaceRoot, async () => {
         let any = false;
-        for (const o of occupantsOf(cfg, feature, service)) {
+        for (const o of occupantsOf(cfg, feature, services)) {
             if (!hasRuntime(cfg, o.service))
                 continue;
             any = true;
@@ -34,10 +40,10 @@ export async function stopCommand(cfg, feature, service) {
             log(t('没有可停止的运行体（相关服务未配置 start/stop）', 'nothing to stop (no start/stop configured for those services)'));
     });
 }
-export async function startCommand(cfg, feature, service) {
+export async function startCommand(cfg, feature, services = []) {
     await withLock(cfg.workspaceRoot, async () => {
         let any = false;
-        for (const o of occupantsOf(cfg, feature, service)) {
+        for (const o of occupantsOf(cfg, feature, services)) {
             if (!hasRuntime(cfg, o.service))
                 continue;
             any = true;
@@ -48,9 +54,9 @@ export async function startCommand(cfg, feature, service) {
             log(t('没有可启动的运行体（相关服务未配置 start/stop）', 'nothing to start (no start/stop configured for those services)'));
     });
 }
-export async function restartCommand(cfg, feature, service) {
+export async function restartCommand(cfg, feature, services = []) {
     await withLock(cfg.workspaceRoot, async () => {
-        for (const o of occupantsOf(cfg, feature, service)) {
+        for (const o of occupantsOf(cfg, feature, services)) {
             if (!hasRuntime(cfg, o.service))
                 continue;
             const ctx = ctxOf(cfg, o);

package/dist/commands/rm.js

@@ -9,17 +9,24 @@ import { stopManaged } from '../proc.js';
 import { log, warn } from '../util/log.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
-export function resolveRm(cfg, feature, service) {
+// services 为空 = 整功能；否则只这些服务（顺带校验服务名确实在该功能里）
+export function resolveRm(cfg, feature, services = []) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
         throw new Error(t(`功能「${feature}」未占槽，无需拆除。用 \`worktree-bay ls\` 看在用的功能。`, `feature "${feature}" has no slot — nothing to tear down. See \`worktree-bay ls\`.`));
     const all = scanOccupancy(cfg).get(slot) ?? [];
-    return service ? all.filter((o) => o.service === service) : all;
+    if (!services.length)
+        return all;
+    for (const s of services)
+        if (!all.some((o) => o.service === s))
+            throw new Error(t(`服务「${s}」不在功能「${feature}」里。用 \`worktree-bay ls\` 看已起的服务。`, `service "${s}" is not in feature "${feature}". See \`worktree-bay ls\`.`));
+    return all.filter((o) => services.includes(o.service));
 }
-export async function rmCommand(cfg, feature, service, force) {
+export async function rmCommand(cfg, feature, services, force) {
     await withLock(cfg.workspaceRoot, async () => {
         let removed = 0;
-        const occs = resolveRm(cfg, feature, service);
+        const wholeFeature = services.length === 0;
+        const occs = resolveRm(cfg, feature, services);
         for (const o of occs) {
             const repo = repoPath(cfg, o.service);
             const branch = currentBranch(o.dir);
@@ -41,7 +48,7 @@ export async function rmCommand(cfg, feature, service, force) {
             removed++;
         }
         const slot = slotOfFeature(cfg, feature);
-        if (!service && (scanOccupancy(cfg).get(slot) ?? []).length === 0) {
+        if (wholeFeature && (scanOccupancy(cfg).get(slot) ?? []).length === 0) {
             removeLabel(cfg, slot);
             if (removed === 0)
                 log(`${c.green('✓')} ` + t(`释放空槽预约 "${feature}"（槽 ${slot}）`, `released empty slot reservation "${feature}" (slot ${slot})`));

package/dist/mcp.js

@@ -52,18 +52,18 @@ export const TOOLS = [
     { name: 'worktree_bay_run', description: '在某功能某服务的运行体里跑预设命令（如 test），可透传额外参数',
         inputSchema: { type: 'object', properties: { feature: str, service: str, name: str, args: { type: 'array', items: str } }, required: ['feature', 'service', 'name'] },
         toArgs: (a) => ['run', String(a.feature), String(a.service), String(a.name), ...(a.args ?? [])] },
-    { name: 'worktree_bay_start', description: '启动功能的运行体（docker 容器 + node dev server 一起），不动 worktree。service 省略=该功能所有服务。',
-        inputSchema: { type: 'object', properties: { feature: str, service: str }, required: ['feature'] },
-        toArgs: (a) => ['start', String(a.feature), ...(a.service ? [String(a.service)] : [])] },
-    { name: 'worktree_bay_stop', description: '停止功能的运行体（停 docker 容器 + 杀 node dev server），保留 worktree。service 省略=该功能所有服务。',
-        inputSchema: { type: 'object', properties: { feature: str, service: str }, required: ['feature'] },
-        toArgs: (a) => ['stop', String(a.feature), ...(a.service ? [String(a.service)] : [])] },
-    { name: 'worktree_bay_restart', description: '重启功能的运行体（停掉再起，docker + node 一起）。改了配置或端口卡住时用。service 省略=该功能所有服务。',
-        inputSchema: { type: 'object', properties: { feature: str, service: str }, required: ['feature'] },
-        toArgs: (a) => ['restart', String(a.feature), ...(a.service ? [String(a.service)] : [])] },
-    { name: 'worktree_bay_down', description: '拆除功能的 worktree：省略 service 拆整个功能的所有服务，传 service 只拆该服务（默认查脏/未推保护，force=true 强删）',
-        inputSchema: { type: 'object', properties: { feature: str, service: str, force: { type: 'boolean' } }, required: ['feature'] },
-        toArgs: (a) => ['rm', String(a.feature), ...(a.service ? [String(a.service)] : []), ...(a.force ? ['-f'] : [])] },
+    { name: 'worktree_bay_start', description: '启动功能的运行体（docker 容器 + node dev server 一起），不动 worktree。services 省略=该功能所有服务，也可列多个。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature'] },
+        toArgs: (a) => ['start', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_stop', description: '停止功能的运行体（停 docker 容器 + 杀 node dev server），保留 worktree。services 省略=全部，也可列多个。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature'] },
+        toArgs: (a) => ['stop', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_restart', description: '重启功能的运行体（停掉再起，docker + node 一起）。改了配置或端口卡住时用。services 省略=全部，也可列多个。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature'] },
+        toArgs: (a) => ['restart', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_down', description: '拆除 worktree：省略 services 拆整个功能（所有服务），给 services 只拆这些服务（默认查脏/未推保护，force=true 强删）',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str }, force: { type: 'boolean' } }, required: ['feature'] },
+        toArgs: (a) => ['down', String(a.feature), ...(a.services ?? []), ...(a.force ? ['-f'] : [])] },
     { name: 'worktree_bay_gc', description: '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能',
         inputSchema: { type: 'object', properties: { apply: { type: 'boolean' } } },
         toArgs: (a) => ['gc', ...(a.apply ? ['--apply'] : [])] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "2.5.0",
+  "version": "4.0.0",
   "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

@@ -35,11 +35,10 @@ worktree-bay completion install   # 一键装 shell 补全（可选）
 | `worktree-bay path <feature> <service>` | 打印某服务 worktree 的绝对路径（可 `cd $(worktree-bay path f api)`） |
 | `worktree-bay run <feature> <service> <name> [args...]` | 在某服务运行体里跑配置的 `run.<name>`（如 test），透传 args |
 | `worktree-bay sh <feature> <service>` | 进入某服务运行体的 shell |
-| `worktree-bay start <feature> [service]` | 启动功能的运行体（docker 容器 + node dev server 一起），不动 worktree |
-| `worktree-bay stop <feature> [service]` | 停止功能的运行体（停 docker + 杀 node dev server），保留 worktree |
-| `worktree-bay restart <feature> [service]` | 重启运行体（停掉再起；改了配置/端口卡住时用） |
-| `worktree-bay down <feature> [-f]` | 拆除整个功能的所有服务 worktree（= `rm <feature>`） |
-| `worktree-bay rm <feature> [service] [-f]` | 拆除某服务或整槽。默认查脏/未推保护，`-f` 强删 |
+| `worktree-bay start <feature> [services...]` | 启动功能的运行体（docker 容器 + node dev server 一起）；**省略 = 全部**，也可列多个。不动 worktree |
+| `worktree-bay stop <feature> [services...]` | 停止功能的运行体（停 docker + 杀 node dev server）；省略 = 全部，可列多个。保留 worktree |
+| `worktree-bay restart <feature> [services...]` | 重启运行体（停掉再起）；省略 = 全部，可列多个 |
+| `worktree-bay down <feature> [services...]` | 拆除 worktree（停运行体 + teardown + 删 worktree）；**省略 services = 整功能**，也可列多个只拆这些。默认查脏/未推保护，`-f` 强删 |
 | `worktree-bay gc [--apply]` | 合并感知回收：默认 dry-run 只列建议，`--apply` 才删「已合并且干净」的 |
 | `worktree-bay completion <install\|bash\|zsh\|fish>` | `install` 一键装进 shell；或打印补全脚本 |
 | `worktree-bay mcp` | 启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 |
@@ -157,8 +156,8 @@ worktree-bay gc                        # 回收已合并的
 | ③ 在运行体里执行 | 跑命令 / 开 shell | — | `run` / `sh` | — |
 
 - `up`：建 worktree+infra（首次）并起运行体；**重入 = 恢复运行体**（docker 挂了重跑 `up` 能拉回来，等价 `start`）。
-- `start`/`stop`/`restart`：只管②运行体，省略 service = 整功能、带 service = 单个；不碰 worktree 与代码。
-- `down`(=`rm <feature>`) ↔ `up`（功能级）；`rm <feature> <service>` ↔ `add`（单服务级）。
+- 整套 runtime/teardown 命令统一为「一个动词 + `[services...]`（省略=全部）」：`start` / `stop` / `restart` / `down`。
+- `up`（创建，服务必填）↔ `down`（拆除，服务可省=整功能）。`add` 是「单服务 + 自定义分支/基点」的精细创建，其反操作 = `down <feature> <service>`。
 
 ## 工作原理要点
 
@@ -172,7 +171,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` 省略 service 拆整功能、带 service 只拆该服务。要写或修改 `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 返回（含各 worktree 绝对路径、`▸run`）；`path` 给某功能某服务的 worktree 目录；`start/stop/restart` 控制运行体（docker+node）；`down` 省略 services 拆整功能、给 services 只拆这些。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
 
 ## 常见坑