worktree-bay 1.0.3 → 1.2.0

package/README.md

@@ -27,12 +27,8 @@ npm i -g worktree-bay
 ## 快速上手
 
 ```bash
-# 占一个槽位
-worktree-bay claim drill-fix          # → 槽 1，端口块 6010
-
-# 把服务挂进这个功能的槽（开 worktree + 跑该服务的步骤）
-worktree-bay add drill-fix api    feature/drill-fix      # api 起在 6011
-worktree-bay add drill-fix lms    feature/drill-ui       # 前端自动接 6011
+# 一条命令起整个功能：自动占槽 + 在 api/lms 上开 worktree（分支默认 = 功能名）
+worktree-bay up drill-fix api lms
 
 # 看占用
 worktree-bay ls
@@ -40,11 +36,15 @@ worktree-bay ls
 # 在服务运行体里跑命令（透传）
 worktree-bay run drill-fix api test
 
-# 收尾
-worktree-bay rm drill-fix          # 整槽拆除（默认查脏/未推保护，-f 强删）
-worktree-bay gc                    # 合并感知回收（默认 dry-run，--apply 实际执行）
+# 拆除整个功能（默认查脏/未推保护，-f 强删）
+worktree-bay down drill-fix
+
+# 回收已合并的（默认 dry-run，--apply 实际执行）
+worktree-bay gc
 ```
 
+> 需要更细的控制：`claim <feature>` 单独占槽、`add <feature> <service> [branch]` 单加一个服务（branch 可自定义，省略则用功能名）、`rm <feature> [service]` 拆单个服务。
+
 ## 配置
 
 在工作区根放一份 `worktree-bay.config.json`，集中声明所有服务。工具运行时自下而上查找它（或用环境变量 `WORKTREE_BAY_CONFIG` 指定）。
@@ -106,10 +106,30 @@ worktree-bay gc                    # 合并感知回收（默认 dry-run，--app
 
 ## Shell 补全
 
+一条命令装好（自动探测 shell、幂等写入对应 rc；fish 直接写补全目录）：
+
 ```bash
-worktree-bay completion bash >> ~/.bashrc      # 或 zsh / fish
+worktree-bay completion install
+```
+
+执行 `source ~/.bashrc`（或重开终端）即可 tab 补全子命令、功能名、服务名。也可手动：`worktree-bay completion bash`（打印脚本，自行接入）。
+
+## MCP（让 AI 直接用）
+
+内置一个 MCP 服务，让 AI（Claude Code 等）通过 MCP 调用 worktree-bay 完成并行开发，并内置工作流指导（告诉 AI 何时用 up/ls/run/down/gc）。
+
+启动：`worktree-bay mcp`（stdio）。在 Claude Code 里注册：
+
+```json
+{
+  "mcpServers": {
+    "worktree-bay": { "command": "worktree-bay", "args": ["mcp"] }
+  }
+}
 ```
 
+> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（或设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_up / ls / add / run / down / gc`。
+
 ## 许可证
 
 [MIT](./LICENSE)

package/dist/cli.js

@@ -4,11 +4,12 @@ import { Command } from 'commander';
 import { loadConfig } from './config.js';
 import { claimCommand } from './commands/claim.js';
 import { lsCommand } from './commands/ls.js';
-import { addCommand } from './commands/add.js';
+import { addCommand, upCommand } from './commands/add.js';
 import { runCommand, shCommand } from './commands/passthrough.js';
 import { rmCommand } from './commands/rm.js';
 import { gcCommand } from './commands/gc.js';
-import { complete, completionCommand } from './commands/completion.js';
+import { complete, completionCommand, installCompletion } from './commands/completion.js';
+import { startMcp } from './mcp.js';
 import { die } from './util/log.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
@@ -28,7 +29,14 @@ catch (e) {
 } });
 program.command('ls').description('列出所有槽位与占用状态')
     .action(() => sync(lsCommand));
-program.command('add <feature> <service> <branch> [base]').description('在某服务为功能开 worktree 并挂入其槽位')
+program.command('up <feature> <services...>').description('一条命令为功能起多个服务（自动 claim + 各服务默认分支 = 功能名）')
+    .action(async (f, services) => { try {
+    await upCommand(loadConfig(process.cwd()), f, services);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('add <feature> <service> [branch] [base]').description('为功能在某服务开 worktree（branch 默认 = 功能名）')
     .action(async (f, s, b, base) => { try {
     await addCommand(loadConfig(process.cwd()), f, s, b, base);
 }
@@ -39,6 +47,13 @@ program.command('run <feature> <service> <name> [args...]').description('在服
     .action((f, s, n, args) => sync((c) => runCommand(c, f, s, n, args ?? [])));
 program.command('sh <feature> <service>').description('进入服务运行体的 shell')
     .action((f, s) => sync((c) => shCommand(c, f, s)));
+program.command('down <feature>').description('拆除整个功能的所有服务 worktree（= rm <feature>）').option('-f, --force', '跳过脏/未推检查强制删除')
+    .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('拆除某服务或整槽的 worktree（默认查脏/未推保护）').option('-f, --force', '跳过脏/未推检查强制删除')
     .action(async (f, s, o) => { try {
     await rmCommand(loadConfig(process.cwd()), f, s, !!o.force);
@@ -53,9 +68,19 @@ program.command('gc').description('合并感知回收（默认 dry-run）').opti
 catch (e) {
     die(e.message);
 } });
-program.command('completion <shell>').description('打印 shell 补全脚本（bash|zsh|fish）')
-    .action((sh) => { try {
-    completionCommand(sh);
+program.command('completion <target> [shell]').description('install 一键装进 shell；或 bash|zsh|fish 打印补全脚本')
+    .action((target, shell) => { try {
+    if (target === 'install')
+        installCompletion(shell);
+    else
+        completionCommand(target);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('mcp').description('启动 MCP 服务（stdio），供 AI 通过 MCP 调用 worktree-bay 完成并行开发')
+    .action(async () => { try {
+    await startMcp();
 }
 catch (e) {
     die(e.message);

package/dist/commands/add.js

@@ -14,12 +14,18 @@ export function resolveAdd(cfg, feature, service, branch) {
     return { service, slot, slug, dir: path.join(repoPath(cfg, service), '.worktrees', slug), repo: repoPath(cfg, service) };
 }
 export async function addCommand(cfg, feature, service, branch, base) {
+    const br = branch || feature; // 默认分支 = 功能名
     await withLock(cfg.workspaceRoot, async () => {
-        const p = resolveAdd(cfg, feature, service, branch);
+        const p = resolveAdd(cfg, feature, service, br);
         const sp = cfg.services[service];
         const ctxBase = { cfg, service, sp, slot: p.slot, slug: p.slug, dir: p.dir, repo: p.repo };
         const ctx = { ...ctxBase, vars: buildVars(cfg, ctxBase) };
-        await bringUp(ctx, base ?? `origin/${mainBranch(p.repo)}`, branch);
-        log(`✓ ${service} 挂入 "${feature}"（槽 ${p.slot}，端口 ${ctx.vars.port}）`);
+        await bringUp(ctx, base ?? `origin/${mainBranch(p.repo)}`, br);
+        log(`✓ ${service} 挂入 "${feature}"（槽 ${p.slot}，端口 ${ctx.vars.port}，分支 ${br}）`);
     });
 }
+// up: 一条命令为功能批量起多个服务（claim 自动 + 各服务默认分支）
+export async function upCommand(cfg, feature, services, base) {
+    for (const service of services)
+        await addCommand(cfg, feature, service, undefined, base);
+}

package/dist/commands/completion.js

@@ -1,25 +1,55 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { readLabels } from '../slots.js';
 import { log } from '../util/log.js';
-const SUBCMDS = ['claim', 'add', 'ls', 'gc', 'rm', 'run', 'sh', 'completion'];
+const SUBCMDS = ['claim', 'up', 'add', 'ls', 'gc', 'down', 'rm', 'run', 'sh', 'completion', 'mcp'];
+// words = 命令名 + 光标前已输入完的词（不含当前正在补的词）
 export function complete(cfg, words) {
-    const args = words.slice(1);
-    if (args.length === 0)
+    const prev = words.slice(1);
+    if (prev.length === 0)
         return SUBCMDS;
-    const sub = args[0];
-    const pos = args.length;
-    if (['add', 'rm', 'run', 'sh'].includes(sub) && pos === 1)
+    const sub = prev[0];
+    const pos = prev.length;
+    const featureSubs = ['up', 'add', 'rm', 'down', 'run', 'sh'];
+    if (featureSubs.includes(sub) && pos === 1)
         return Object.values(readLabels(cfg));
     if (['add', 'run', 'sh'].includes(sub) && pos === 2)
         return Object.keys(cfg.services);
+    if (sub === 'up' && pos >= 2)
+        return Object.keys(cfg.services); // up 接变长服务列表
     return [];
 }
 export function completionScript(shell) {
+    // 脚本只传"光标前已完成的词"，不含当前正在补的词，与 complete() 的模型一致
     if (shell === 'bash')
-        return `_worktree_bay(){ COMPREPLY=( $(worktree-bay __complete -- "\${COMP_WORDS[@]}") ); }\ncomplete -F _worktree_bay worktree-bay`;
+        return `_worktree_bay(){ COMPREPLY=( $(worktree-bay __complete -- "\${COMP_WORDS[@]:0:\$COMP_CWORD}") ); }\ncomplete -F _worktree_bay worktree-bay`;
     if (shell === 'zsh')
-        return `#compdef worktree-bay\n_worktree_bay(){ compadd -- $(worktree-bay __complete -- "\${words[@]}") }\ncompdef _worktree_bay worktree-bay`;
+        return `#compdef worktree-bay\n_worktree_bay(){ compadd -- $(worktree-bay __complete -- "\${(@)words[1,CURRENT-1]}") }\ncompdef _worktree_bay worktree-bay`;
     if (shell === 'fish')
-        return `complete -c worktree-bay -a '(worktree-bay __complete -- (commandline -opc))'`;
+        return `complete -c worktree-bay -f -a '(worktree-bay __complete -- (commandline -opc))'`;
     throw new Error('unsupported shell: ' + shell);
 }
 export function completionCommand(shell) { log(completionScript(shell)); }
+// 一键把补全装进当前 shell（幂等）。fish 直接写补全目录（零配置生效）；bash/zsh 往 rc 加一行 eval。
+export function installCompletion(shell) {
+    const sh = shell || path.basename(process.env.SHELL || 'bash');
+    if (sh === 'fish') {
+        const dir = path.join(os.homedir(), '.config', 'fish', 'completions');
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, 'worktree-bay.fish');
+        fs.writeFileSync(file, completionScript('fish') + '\n');
+        log(`✓ fish 补全已写入 ${file}（新开 fish 即生效）`);
+        return;
+    }
+    const isZsh = sh === 'zsh';
+    const rc = path.join(os.homedir(), isZsh ? '.zshrc' : '.bashrc');
+    const line = `eval "$(worktree-bay completion ${isZsh ? 'zsh' : 'bash'})"`;
+    const cur = fs.existsSync(rc) ? fs.readFileSync(rc, 'utf8') : '';
+    if (cur.includes(line)) {
+        log(`✓ 补全已在 ${rc}，无需重复安装`);
+        return;
+    }
+    fs.appendFileSync(rc, `\n# worktree-bay completion\n${line}\n`);
+    log(`✓ 补全已加入 ${rc}，执行 'source ${rc}' 或重开终端即生效`);
+}

package/dist/mcp.js

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.js');
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+// 工具实现：直接调底层 worktree-bay CLI 并捕获输出返回，复用全部逻辑
+function runCli(args) {
+    const r = spawnSync(process.execPath, [CLI, ...args], { encoding: 'utf8' });
+    const text = [r.stdout, r.stderr].filter(Boolean).join('\n').trim() || '(无输出)';
+    return { content: [{ type: 'text', text }] };
+}
+export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开发编排器。当你需要在一个多服务工作区里并行开发多个功能、又不想让它们的端口/依赖/数据互相干扰时，用本服务的工具来完成开发工作。
+
+核心模型：一个功能占一个「槽位」→ 得到一个端口块；该功能用到哪些服务，就在哪些服务上各开一个 git worktree 挂进这个槽，端口自动错开，前端自动连到同槽的后端。
+
+推荐工作流：
+1. 起新功能：调用 worktree_bay_up，传功能名 + 要改的服务列表（如 ["api","lms"]）。它会自动占槽、为每个服务开 worktree、拷依赖、注入端口并起服务。
+2. 查看在跑的功能：worktree_bay_ls。
+3. 在某功能的某服务里跑测试/命令：worktree_bay_run（name 用配置里定义的，如 "test"）。
+4. 收尾：分支合并后，先 worktree_bay_gc 看可回收项，再 worktree_bay_down 拆掉该功能。
+
+要点：
+- 同一个功能从头到尾用同一个功能名（它同时是默认分支名）贯穿 up/run/down。
+- 只起这个功能「实际要改」的服务，不要全起。
+- 拿不准当前状态时先调 worktree_bay_ls。
+- worktree_bay_gc 默认只读（dry-run 列出建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，安全保守、不会误删未完成的工作。`;
+export function createServer() {
+    const server = new McpServer({ name: 'worktree-bay', version: VERSION }, { instructions: INSTRUCTIONS });
+    server.tool('worktree_bay_ls', '列出所有功能槽位与占用（每槽：功能名、端口块、已起服务及端口、是否已并入主分支）', {}, async () => runCli(['ls']));
+    server.tool('worktree_bay_up', '为一个功能一次性起多个服务（自动占槽 + 各服务开 worktree，分支默认 = 功能名，前端自动接同槽后端）。并行开发新功能首选。', {
+        feature: z.string().describe('功能名（同时作为默认分支名）'),
+        services: z.array(z.string()).describe('要起的服务名列表，如 ["api","lms"]'),
+    }, async ({ feature, services }) => runCli(['up', feature, ...services]));
+    server.tool('worktree_bay_add', '为功能在单个服务上开 worktree（branch 省略则用功能名）', {
+        feature: z.string(), service: z.string(), branch: z.string().optional(),
+    }, async ({ feature, service, branch }) => runCli(['add', feature, service, ...(branch ? [branch] : [])]));
+    server.tool('worktree_bay_run', '在某功能某服务的运行体里跑预设命令（如 test），可透传额外参数', {
+        feature: z.string(), service: z.string(),
+        name: z.string().describe('配置里 run.<name> 的名字，如 test'),
+        args: z.array(z.string()).optional(),
+    }, async ({ feature, service, name, args }) => runCli(['run', feature, service, name, ...(args ?? [])]));
+    server.tool('worktree_bay_down', '拆除整个功能的所有服务 worktree（默认查脏/未推保护，force=true 强删）', {
+        feature: z.string(), force: z.boolean().optional(),
+    }, async ({ feature, force }) => runCli(['down', feature, ...(force ? ['-f'] : [])]));
+    server.tool('worktree_bay_gc', '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能', {
+        apply: z.boolean().optional(),
+    }, async ({ apply }) => runCli(['gc', ...(apply ? ['--apply'] : [])]));
+    return server;
+}
+export async function startMcp() {
+    await createServer().connect(new StdioServerTransport());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Config-driven git worktree slot + port orchestrator for parallel multi-service development",
   "keywords": [
     "git",
@@ -43,7 +43,9 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^12.1.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",