worktree-bay 1.5.0 → 2.0.0

package/README.md

@@ -11,7 +11,7 @@
 
 在 monorepo / 多仓工作区里并行开发多个功能时，git worktree 能隔离代码，但隔离不了运行时——端口会撞、依赖要重装、前端连不上你本地起在偏移端口的后端。`worktree-bay` 在 worktree 之上补一层「**功能 = 槽位**」的编排：
 
-- **端口不撞**：每个功能占一个槽 `N`，得到端口块 `6000 + N*10`，块内各服务按固定偏移取端口。
+- **端口不撞**：每个服务有自己的端口段，功能占槽 `N` → 各服务用 `自己的基址 + N`，与主 dev（槽 0）和其它槽天然错开。
 - **免重装**：依赖从主 checkout 拷贝（或按服务自定义安装命令），不必每个 worktree 从头装。
 - **前端自接后端**：前端按「同槽上游服务」自动把 api base 指向本槽后端端口。
 - **不泄漏**：槽位占用从文件系统派生；`gc` 合并感知回收（已并入主分支且干净才删，保守不误删）。
@@ -52,12 +52,10 @@ worktree-bay gc
 ```jsonc
 {
   "workspaceRoot": "/path/to/workspace",
-  "portBase": 6000,
-  "slotSpan": 10,
   "maxSlots": 9,
   "services": {
     "api": {
-      "offset": 1,
+      "port": 6001,                                                // 端口段基址（= 主 dev/槽0），槽 N 用 6001+N
       "vars": { "project": "myapi-{slug}" },
       "copy": [".env", "vendor"],                                  // 从主 checkout 递归拷文件/目录
       "env": { ".env": { "APP_PORT": "{port}" } },                 // 合并键值进 dotenv（保留其它键）
@@ -67,7 +65,7 @@ worktree-bay gc
       "run": { "test": ["composer", "run", "test"] }               // 命名命令
     },
     "lms": {
-      "offset": 2,
+      "port": 6011,                                                // 与 api 段不重叠（间距 > maxSlots）
       "upstream": { "service": "api", "fallback": "http://localhost:6001" }, // → {upstreamBase}
       "env": { ".env.dev.local": { "VITE_API_BASE_URL": "{upstreamBase}" } },
       "setup": "pnpm install",
@@ -81,7 +79,7 @@ worktree-bay gc
 
 | 原语 | 说明 |
 |---|---|
-| `offset`（必填） | 本服务端口 = `块基址 + offset`，各服务互不相同、`1 ≤ offset < slotSpan` |
+| `port`（必填） | 本服务端口段基址（= 主 dev/槽0）；槽 N 端口 = `port + N`；各服务的段 `[port, port+maxSlots]` 互不重叠 |
 | `repo` | 仓库目录名（相对 workspaceRoot），默认 = 服务名 |
 | `vars` | 自定义模板变量 |
 | `copy` | 从主 checkout 递归拷贝的文件/目录（含依赖目录） |
@@ -94,11 +92,11 @@ worktree-bay gc
 
 ### 模板变量
 
-`{slot}` `{blockBase}` `{port}` `{slug}` `{worktree}` `{repo}` `{upstreamBase}` `{cmd...}`，以及 `vars` 里自定义的。
+`{slot}` `{port}` `{slug}` `{worktree}` `{repo}` `{upstreamBase}` `{cmd...}`，以及 `vars` 里自定义的。
 
 ## 工作原理
 
-- **槽位 = 端口块**：功能占槽 `N`（1..`maxSlots`）→ 端口块 `portBase + N*slotSpan`；块内服务按 `offset` 取端口。
+- **按服务分段**：每个服务有自己的端口段（基址 `port` = 主 dev/槽0），功能占槽 `N`（1..`maxSlots`）→ 该服务用 `port + N`。服务数量无上限，各段不重叠即可。
 - **占用从文件系统派生**：槽是否被占，看各服务 `<repo>/.worktrees/s<N>-*` 目录是否存在；`.worktree-bay-slots.json` 只是「功能名 → 槽号」的标签账本（预约）。删了 worktree，槽自动空出。
 - **并发安全**：`claim/add/rm/gc` 全程持工作区原子锁。
 - **前端自接**：前端有 `upstream` 时，若同槽已起该上游服务的 worktree，就把 api base 指向本槽端口；否则用 `fallback`。

package/dist/commands/claim.js

@@ -1,11 +1,10 @@
 import { withLock } from '../lock.js';
 import { claim } from '../slots.js';
-import { blockBase } from '../ports.js';
+import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
 export async function claimCommand(cfg, feature) {
     const slot = await withLock(cfg.workspaceRoot, async () => claim(cfg, feature));
-    const base = blockBase(cfg.portBase, cfg.slotSpan, slot);
-    log(`功能 "${feature}" → 槽 ${slot}（块 ${base}）`);
+    log(`功能 "${feature}" → 槽 ${slot}`);
     for (const [n, sp] of Object.entries(cfg.services))
-        log(`  ${n.padEnd(8)} ${base + sp.offset}`);
+        log(`  ${n.padEnd(8)} ${portOf(sp.port, slot)}`);
 }

package/dist/commands/doctor.js

@@ -12,7 +12,7 @@ export function doctor(cfg) {
         ok('git 可用');
     else
         bad('git 不可用（worktree 依赖 git）');
-    ok(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口块 ${cfg.portBase}+N*${cfg.slotSpan}）`);
+    ok(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口 = 服务基址 + 槽号）`);
     for (const name of Object.keys(cfg.services)) {
         const repo = repoPath(cfg, name);
         if (!fs.existsSync(repo))

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { log, warn } from '../util/log.js';
-// 引导生成一份 worktree-bay.config.json：扫描 cwd 子目录里的 git 仓预填为服务
+// 引导生成一份 worktree-bay.config.json：扫描 cwd 子目录里的 git 仓预填为服务（按服务分配端口段）
 export function initCommand(cwd) {
     const target = path.join(cwd, 'worktree-bay.config.json');
     if (fs.existsSync(target)) {
@@ -18,19 +18,19 @@ export function initCommand(cwd) {
     let services;
     if (repos.length) {
         services = {};
-        repos.slice(0, 9).forEach((r, i) => { services[r] = { offset: i + 1, setup: 'echo TODO: 起本服务的命令', run: { test: ['echo', 'TODO'] } }; });
+        repos.forEach((r, i) => { services[r] = { port: 6001 + i * 10, setup: 'echo TODO: 起本服务的命令', run: { test: ['echo', 'TODO'] } }; });
     }
     else {
         services = {
-            api: { offset: 1, copy: ['.env'], env: { '.env': { APP_PORT: '{port}' } }, setup: 'echo TODO: 起后端', run: { test: ['echo', 'TODO'] } },
-            web: { offset: 2, upstream: { service: 'api', fallback: 'http://localhost:6001' }, env: { '.env.local': { VITE_API_BASE_URL: '{upstreamBase}' } }, setup: 'pnpm install', start: 'pnpm dev --port {port}' },
+            api: { port: 6001, copy: ['.env'], env: { '.env': { APP_PORT: '{port}' } }, setup: 'echo TODO: 起后端', run: { test: ['echo', 'TODO'] } },
+            web: { port: 6011, upstream: { service: 'api', fallback: 'http://localhost:6001' }, env: { '.env.local': { VITE_API_BASE_URL: '{upstreamBase}' } }, setup: 'pnpm install', start: 'pnpm dev --port {port}' },
         };
     }
-    const config = { workspaceRoot: cwd, portBase: 6000, slotSpan: 10, maxSlots: 9, services };
+    const config = { workspaceRoot: cwd, maxSlots: 9, services };
     fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
     log(`✓ 已生成 ${target}`);
     if (repos.length)
-        log(`  识别到服务: ${repos.join(', ')}（按目录预填，offset 自增）`);
+        log(`  识别到服务: ${repos.join(', ')}（每个分配一段端口，基址间隔 10）`);
     else
         log(`  未识别到子 git 仓，已写入 api/web 示例模板`);
     log(`  下一步：补全各服务的 setup/env/upstream/exec/run。完整配置说明：worktree-bay skill`);

package/dist/commands/ls.js

@@ -1,5 +1,5 @@
 import { scanOccupancy, readLabels } from '../slots.js';
-import { blockBase } from '../ports.js';
+import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
 export function renderSlots(cfg) {
     const occ = scanOccupancy(cfg);
@@ -7,9 +7,8 @@ export function renderSlots(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 base = blockBase(cfg.portBase, cfg.slotSpan, n);
-        const svc = (occ.get(n) ?? []).map((o) => `${o.service}@${base + cfg.services[o.service].offset}`);
-        lines.push(`slot ${n}  ${labels[String(n)] ?? '(unnamed)'}  block=${base}  [${svc.join(', ') || 'no worktree'}]`);
+        const svc = (occ.get(n) ?? []).map((o) => `${o.service}@${portOf(cfg.services[o.service].port, n)}`);
+        lines.push(`slot ${n}  ${labels[String(n)] ?? '(unnamed)'}  [${svc.join(', ') || 'no worktree'}]`);
     }
     return lines.join('\n') || '(no slots in use)';
 }
@@ -17,9 +16,9 @@ export function slotsData(cfg) {
     const occ = scanOccupancy(cfg);
     const labels = readLabels(cfg);
     const slots = new Set([...occ.keys(), ...Object.keys(labels).map(Number)]);
-    return [...slots].sort((a, b) => a - b).map((n) => {
-        const base = blockBase(cfg.portBase, cfg.slotSpan, n);
-        return { slot: n, feature: labels[String(n)] ?? null, block: base, services: (occ.get(n) ?? []).map((o) => ({ service: o.service, port: base + cfg.services[o.service].offset, dir: o.dir })) };
-    });
+    return [...slots].sort((a, b) => a - b).map((n) => ({
+        slot: n, feature: labels[String(n)] ?? null,
+        services: (occ.get(n) ?? []).map((o) => ({ service: o.service, port: portOf(cfg.services[o.service].port, n), dir: o.dir })),
+    }));
 }
 export function lsCommand(cfg, json = false) { log(json ? JSON.stringify(slotsData(cfg), null, 2) : renderSlots(cfg)); }

package/dist/config.js

@@ -3,33 +3,35 @@ import path from 'node:path';
 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', 'portBase', 'slotSpan', 'maxSlots'])
+    for (const k of ['workspaceRoot', 'maxSlots'])
         if (raw[k] === undefined)
             throw new Error(`config: ${k} required`);
+    const maxSlots = raw.maxSlots;
     const services = raw.services ?? {};
-    const offsets = new Set();
+    // 端口段：每个服务 [port, port+maxSlots]（port=主 dev/槽0，槽 1..maxSlots 落在段内）
     for (const [name, sp] of Object.entries(services)) {
-        if (typeof sp.offset !== 'number')
-            throw new Error(`config: ${name}.offset required`);
-        if (sp.offset < 1 || sp.offset >= raw.slotSpan)
-            throw new Error(`config: ${name}.offset must be 1..${raw.slotSpan - 1}`); // V2
-        if (offsets.has(sp.offset))
-            throw new Error(`config: duplicate offset ${sp.offset} (${name})`); // V1
-        offsets.add(sp.offset);
+        if (typeof sp.port !== 'number' || sp.port < 1)
+            throw new Error(`config: ${name}.port must be a positive number`); // V2
         const repoDir = path.join(raw.workspaceRoot, sp.repo ?? name);
         if (!fs.existsSync(repoDir))
             throw new Error(`config: ${name}.repo dir missing: ${repoDir}`); // V5
     }
+    const entries = Object.entries(services);
+    for (let i = 0; i < entries.length; i++)
+        for (let j = i + 1; j < entries.length; j++) { // V1: 段不重叠
+            if (Math.abs(entries[i][1].port - entries[j][1].port) <= maxSlots)
+                throw new Error(`config: 服务 ${entries[i][0]} 与 ${entries[j][0]} 端口段重叠（间距需 > maxSlots=${maxSlots}）`);
+        }
     for (const [name, sp] of Object.entries(services))
         if (sp.upstream && !services[sp.upstream.service])
             throw new Error(`config: ${name}.upstream.service '${sp.upstream.service}' not found`); // V3
-    const known = new Set(['slot', 'blockBase', 'port', 'slug', 'worktree', 'repo', 'upstreamBase', 'cmd']); // V4
+    const known = new Set(['slot', 'port', 'slug', 'worktree', 'repo', 'upstreamBase', 'cmd']); // V4
     for (const sp of Object.values(services))
         for (const v of Object.values(sp.vars ?? {}))
             for (const ref of refs(v))
                 if (!known.has(ref) && !(sp.vars && ref in sp.vars))
                     throw new Error(`config: unknown template var {${ref}}`);
-    return { workspaceRoot: raw.workspaceRoot, portBase: raw.portBase, slotSpan: raw.slotSpan, maxSlots: raw.maxSlots, services, configDir: path.dirname(configPath) };
+    return { workspaceRoot: raw.workspaceRoot, maxSlots, services, configDir: path.dirname(configPath) };
 }
 export function loadConfig(startDir) {
     if (process.env.WORKTREE_BAY_CONFIG)

package/dist/engine.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { renderTemplate } from './config.js';
-import { blockBase, portOf, isPortFree } from './ports.js';
+import { portOf, isPortFree } from './ports.js';
 import { scanOccupancy } from './slots.js';
 import { addWorktree } from './git.js';
 import { runShell, run, spliceArgv, isTTY } from './util/exec.js';
@@ -23,13 +23,13 @@ export function mergeEnvText(text, kv) {
     return out.join('\n');
 }
 export function resolveUpstreamBase(cfg, slot, up, materialized) {
-    return materialized ? `http://localhost:${portOf(cfg.portBase, cfg.slotSpan, slot, cfg.services[up.service].offset)}` : up.fallback;
+    return materialized ? `http://localhost:${portOf(cfg.services[up.service].port, slot)}` : up.fallback;
 }
 function upstreamMaterialized(cfg, slot, service) {
     return (scanOccupancy(cfg).get(slot) ?? []).some((o) => o.service === service);
 }
 export function buildVars(cfg, ctx) {
-    const base = { slot: ctx.slot, blockBase: blockBase(cfg.portBase, cfg.slotSpan, ctx.slot), port: portOf(cfg.portBase, cfg.slotSpan, ctx.slot, ctx.sp.offset), slug: ctx.slug, worktree: ctx.dir, repo: ctx.repo };
+    const base = { slot: ctx.slot, port: portOf(ctx.sp.port, ctx.slot), slug: ctx.slug, worktree: ctx.dir, repo: ctx.repo };
     if (ctx.sp.upstream)
         base.upstreamBase = resolveUpstreamBase(cfg, ctx.slot, ctx.sp.upstream, upstreamMaterialized(cfg, ctx.slot, ctx.sp.upstream.service));
     for (const [k, v] of Object.entries(ctx.sp.vars ?? {}))

package/dist/ports.js

@@ -1,6 +1,6 @@
 import net from 'node:net';
-export function blockBase(portBase, slotSpan, slot) { return portBase + slot * slotSpan; }
-export function portOf(portBase, slotSpan, slot, offset) { return blockBase(portBase, slotSpan, slot) + offset; }
+// 按服务分段：某服务在某槽的端口 = 服务基址(主 dev/槽0) + 槽号
+export function portOf(servicePort, slot) { return servicePort + slot; }
 export function isPortFree(port) {
     return new Promise((resolve) => {
         const srv = net.createServer();

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "worktree-bay",
-  "version": "1.5.0",
-  "description": "Config-driven git worktree slot + port orchestrator for parallel multi-service development",
+  "version": "2.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",
+    "git-worktree",
     "worktree",
     "monorepo",
     "cli",
     "ports",
     "orchestration",
     "parallel",
-    "dev"
+    "parallel-development",
+    "developer-tools",
+    "dev-environment",
+    "mcp"
   ],
   "type": "module",
   "license": "MIT",

package/skill.md

@@ -63,19 +63,17 @@ worktree-bay gc                        # 回收已合并的
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `workspaceRoot` | string | 工作区根绝对路径，各服务仓在其下 |
-| `portBase` | number | 端口基址，如 `6000` |
-| `slotSpan` | number | 每个槽位的端口跨度（块大小），如 `10` |
-| `maxSlots` | number | 最大并行功能数，如 `9` |
+| `maxSlots` | number | 最大并行功能数（每个服务预留 `maxSlots` 个端口），如 `9` |
 | `services` | object | 服务名 → 服务定义（见下） |
 
-**端口计算**：`块基址 = portBase + 槽位N * slotSpan`；`某服务端口 = 块基址 + 该服务 offset`。
-例：portBase=6000, slotSpan=10，槽 1 的块基址 = 6010，offset=1 的服务端口 = 6011。
+**端口模型（按服务分段）**：每个服务有自己的端口段，基址 `port` 就是它的主 dev 端口（= 槽 0）；某服务在某槽 N 的端口 = `service.port + N`（槽 1..maxSlots）。
+例：`api.port=6001` → 槽 1 用 6002、槽 2 用 6003…；`lms.port=6011` → 槽 1 用 6012…。**服务数量无上限**，只要各服务端口段（`[port, port+maxSlots]`）互不重叠即可。
 
 ### 服务定义原语
 
 | 原语 | 必填 | 类型 | 说明 |
 |---|---|---|---|
-| `offset` | ✅ | number | 本服务在块内的偏移；`1 ≤ offset < slotSpan`，各服务互不相同 |
+| `port` | ✅ | number | 本服务端口段基址（= 主 dev/槽0 端口）；各服务的段 `[port, port+maxSlots]` 互不重叠 |
 | `repo` | | string | 仓库目录名（相对 workspaceRoot），**默认 = 服务名** |
 | `vars` | | object | 自定义模板变量，值里可引用基础变量，如 `{ "project": "myapi-{slug}" }` |
 | `copy` | | string[] | 挂入时从主 checkout **递归拷贝**到 worktree 的文件/目录（含依赖目录，如 `vendor`）。含符号链接也安全（会跟随拷目标内容） |
@@ -94,8 +92,7 @@ worktree-bay gc                        # 回收已合并的
 | 变量 | 含义 |
 |---|---|
 | `{slot}` | 槽位号 |
-| `{blockBase}` | 块基址 `portBase + slot*slotSpan` |
-| `{port}` | 本服务端口 `blockBase + offset` |
+| `{port}` | 本服务端口 `service.port + slot` |
 | `{slug}` | worktree 目录名 `s<slot>-<分支归一化>` |
 | `{worktree}` | worktree 绝对路径 |
 | `{repo}` | 服务仓绝对路径 |
@@ -105,8 +102,8 @@ worktree-bay gc                        # 回收已合并的
 
 ### 加载时强制校验
 
-1. 各服务 `offset` 互不相同；
-2. `1 ≤ offset < slotSpan`；
+1. 各服务端口段 `[port, port+maxSlots]` 互不重叠（任意两服务 `|portA - portB| > maxSlots`）；
+2. `port` 必填且为正数；
 3. `upstream.service` 必须存在于 `services`；
 4. 所有模板里引用的 `{var}` 可解析（基础变量或本服务 vars 已声明）；
 5. `repo` 指向的目录存在。
@@ -117,12 +114,10 @@ worktree-bay gc                        # 回收已合并的
 ```jsonc
 {
   "workspaceRoot": "/path/to/workspace",
-  "portBase": 6000,
-  "slotSpan": 10,
   "maxSlots": 9,
   "services": {
     "api": {
-      "offset": 1,
+      "port": 6001,
       "vars": { "project": "myapi-{slug}" },
       "copy": [".env", "vendor"],
       "env": { ".env": { "APP_PORT": "{port}", "CACHE_PREFIX": "dev:{slug}:" } },
@@ -132,7 +127,7 @@ worktree-bay gc                        # 回收已合并的
       "run": { "test": ["composer", "run", "test"], "migrate": ["php", "artisan", "migrate"] }
     },
     "web": {
-      "offset": 2,
+      "port": 6011,
       "upstream": { "service": "api", "fallback": "http://localhost:6001" },
       "env": { ".env.local": { "VITE_API_BASE_URL": "{upstreamBase}" } },
       "setup": "pnpm install",