worktree-bay 1.4.0 → 1.5.0

package/dist/cli.js

@@ -5,22 +5,41 @@ import { loadConfig } from './config.js';
 import { claimCommand } from './commands/claim.js';
 import { lsCommand } from './commands/ls.js';
 import { addCommand, upCommand } from './commands/add.js';
-import { runCommand, shCommand } from './commands/passthrough.js';
+import { runCommand, shCommand, pathCommand } from './commands/passthrough.js';
 import { rmCommand } from './commands/rm.js';
 import { gcCommand } from './commands/gc.js';
+import { doctorCommand } from './commands/doctor.js';
 import { complete, completionCommand, installCompletion } from './commands/completion.js';
 import { startMcp } from './mcp.js';
 import { readSkill } from './skill.js';
+import { initCommand } from './commands/init.js';
 import { die, log } from './util/log.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
-program.name('worktree-bay').description('worktree 槽位+端口编排器').version(pkg.version);
+program.name('worktree-bay').description('worktree 槽位 + 端口编排器：多服务并行开发利器').version(pkg.version);
+program.addHelpText('after', `
+示例:
+  worktree-bay init                      在当前工作区生成配置（扫描子 git 仓预填服务）
+  worktree-bay up drill-fix api lms      一条命令为功能起 api+lms（分支默认 = 功能名）
+  worktree-bay ls                        看所有功能/端口占用
+  worktree-bay run drill-fix api test    在 api 跑 run.test
+  worktree-bay down drill-fix            拆除整个功能
+  worktree-bay gc                        回收已合并的功能（默认 dry-run）
+
+更多: worktree-bay skill（完整使用与配置指南） · worktree-bay help <命令>（单命令帮助）`);
 const sync = (fn) => { try {
     fn(loadConfig(process.cwd()));
 }
 catch (e) {
     die(e.message);
 } };
+program.command('init').description('在当前工作区生成 worktree-bay.config.json（扫描子 git 仓预填服务）')
+    .action(() => { try {
+    initCommand(process.cwd());
+}
+catch (e) {
+    die(e.message);
+} });
 program.command('claim <feature>').description('为功能占一个槽位（端口块）')
     .action(async (f) => { try {
     await claimCommand(loadConfig(process.cwd()), f);
@@ -28,8 +47,12 @@ program.command('claim <feature>').description('为功能占一个槽位（端
 catch (e) {
     die(e.message);
 } });
-program.command('ls').description('列出所有槽位与占用状态')
-    .action(() => sync(lsCommand));
+program.command('ls').description('列出所有槽位与占用状态').option('--json', '以 JSON 输出（含 worktree 路径，便于脚本/AI 消费）')
+    .action((o) => sync((c) => lsCommand(c, !!o.json)));
+program.command('path <feature> <service>').description('打印某功能某服务的 worktree 绝对路径（可 cd $(...)）')
+    .action((f, s) => sync((c) => pathCommand(c, f, s)));
+program.command('doctor').description('体检：git/配置/各服务仓是否就绪')
+    .action(() => sync(doctorCommand));
 program.command('up <feature> <services...>').description('一条命令为功能起多个服务（自动 claim + 各服务默认分支 = 功能名）')
     .action(async (f, services) => { try {
     await upCommand(loadConfig(process.cwd()), f, services);
@@ -93,6 +116,7 @@ program.command('skill').description('打印 worktree-bay 使用与配置完全
 catch (e) {
     die(e.message);
 } });
+program.command('version').description('显示版本号').action(() => log(pkg.version));
 program.command('__complete', { hidden: true }).allowUnknownOption().action(() => {
     const words = process.argv.slice(process.argv.indexOf('--') + 1);
     try {

package/dist/commands/completion.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { readLabels } from '../slots.js';
 import { log } from '../util/log.js';
-const SUBCMDS = ['claim', 'up', 'add', 'ls', 'gc', 'down', 'rm', 'run', 'sh', 'completion', 'mcp', 'skill'];
+const SUBCMDS = ['init', 'doctor', 'claim', 'up', 'add', 'ls', 'path', 'gc', 'down', 'rm', 'run', 'sh', 'completion', 'mcp', 'skill', 'version', 'help'];
 // words = 命令名 + 光标前已输入完的词（不含当前正在补的词）
 export function complete(cfg, words) {
     const prev = words.slice(1);

package/dist/commands/doctor.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { repoPath } from '../config.js';
+import { log, warn } from '../util/log.js';
+// 体检：git 是否可用、配置是否有效、各服务仓是否存在且是 git 仓。返回问题数。
+export function doctor(cfg) {
+    let problems = 0;
+    const ok = (m) => log(`✓ ${m}`);
+    const bad = (m) => { warn(`✗ ${m}`); problems++; };
+    if (spawnSync('git', ['--version'], { encoding: 'utf8' }).status === 0)
+        ok('git 可用');
+    else
+        bad('git 不可用（worktree 依赖 git）');
+    ok(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口块 ${cfg.portBase}+N*${cfg.slotSpan}）`);
+    for (const name of Object.keys(cfg.services)) {
+        const repo = repoPath(cfg, name);
+        if (!fs.existsSync(repo))
+            bad(`服务 ${name} 仓目录不存在: ${repo}`);
+        else if (!fs.existsSync(path.join(repo, '.git')))
+            bad(`服务 ${name} 不是 git 仓: ${repo}`);
+        else
+            ok(`服务 ${name} → ${repo}`);
+    }
+    log(problems === 0 ? '\n✓ 一切正常' : `\n✗ 发现 ${problems} 个问题`);
+    return problems;
+}
+export function doctorCommand(cfg) { if (doctor(cfg) > 0)
+    process.exit(1); }

package/dist/commands/init.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { log, warn } from '../util/log.js';
+// 引导生成一份 worktree-bay.config.json：扫描 cwd 子目录里的 git 仓预填为服务
+export function initCommand(cwd) {
+    const target = path.join(cwd, 'worktree-bay.config.json');
+    if (fs.existsSync(target)) {
+        warn(`已存在 ${target}，未覆盖`);
+        return;
+    }
+    const repos = [];
+    for (const e of fs.readdirSync(cwd, { withFileTypes: true })) {
+        if (!e.isDirectory() || e.name.startsWith('.'))
+            continue;
+        if (fs.existsSync(path.join(cwd, e.name, '.git')))
+            repos.push(e.name);
+    }
+    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'] } }; });
+    }
+    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}' },
+        };
+    }
+    const config = { workspaceRoot: cwd, portBase: 6000, slotSpan: 10, maxSlots: 9, services };
+    fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
+    log(`✓ 已生成 ${target}`);
+    if (repos.length)
+        log(`  识别到服务: ${repos.join(', ')}（按目录预填，offset 自增）`);
+    else
+        log(`  未识别到子 git 仓，已写入 api/web 示例模板`);
+    log(`  下一步：补全各服务的 setup/env/upstream/exec/run。完整配置说明：worktree-bay skill`);
+}

package/dist/commands/ls.js

@@ -13,4 +13,13 @@ export function renderSlots(cfg) {
     }
     return lines.join('\n') || '(no slots in use)';
 }
-export function lsCommand(cfg) { log(renderSlots(cfg)); }
+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 })) };
+    });
+}
+export function lsCommand(cfg, json = false) { log(json ? JSON.stringify(slotsData(cfg), null, 2) : renderSlots(cfg)); }

package/dist/commands/passthrough.js

@@ -1,15 +1,23 @@
 import { repoPath } from '../config.js';
 import { scanOccupancy, slotOfFeature } from '../slots.js';
 import { buildVars, execArgv, run } from '../engine.js';
-function ctxOf(cfg, feature, service) {
+import { log } from '../util/log.js';
+function occupantOf(cfg, feature, service) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
         throw new Error('unknown feature: ' + feature);
     const occ = (scanOccupancy(cfg).get(slot) ?? []).find((o) => o.service === service);
     if (!occ)
         throw new Error(`${service} not in ${feature}`);
+    return occ;
+}
+function ctxOf(cfg, feature, service) {
+    const occ = occupantOf(cfg, feature, service);
     const sp = cfg.services[service];
-    return { sp, vars: buildVars(cfg, { cfg, service, sp, slot, slug: occ.slug, dir: occ.dir, repo: repoPath(cfg, service) }) };
+    return { sp, vars: buildVars(cfg, { cfg, service, sp, slot: occ.slot, slug: occ.slug, dir: occ.dir, repo: repoPath(cfg, service) }) };
+}
+export function pathCommand(cfg, feature, service) {
+    log(occupantOf(cfg, feature, service).dir);
 }
 export function runCommand(cfg, feature, service, name, args) {
     const ctx = ctxOf(cfg, feature, service);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Config-driven git worktree slot + port orchestrator for parallel multi-service development",
   "keywords": [
     "git",

package/skill.md

@@ -24,10 +24,13 @@ worktree-bay completion install   # 一键装 shell 补全（可选）
 
 | 命令 | 作用 |
 |---|---|
+| `worktree-bay init` | 在当前工作区生成 `worktree-bay.config.json`（扫描子 git 仓预填服务） |
+| `worktree-bay doctor` | 体检：git 是否可用、配置是否有效、各服务仓是否就绪 |
 | `worktree-bay up <feature> <service...>` | **最常用**：一条命令为功能起多个服务（自动占槽 + 各服务开 worktree，分支默认 = 功能名） |
 | `worktree-bay claim <feature>` | 只占一个槽、打印端口块（不开 worktree） |
 | `worktree-bay add <feature> <service> [branch] [base]` | 为功能在单个服务开 worktree。`branch` 省略 = 功能名；`base` 省略 = `origin/<主分支>` |
-| `worktree-bay ls` | 列出所有槽位：功能名、端口块、已起服务及端口、是否已并入主分支 |
+| `worktree-bay ls [--json]` | 列出所有槽位：功能名、端口块、已起服务及端口、是否已并入主分支；`--json` 输出结构化数据（含 worktree 路径） |
+| `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 down <feature> [-f]` | 拆除整个功能的所有服务 worktree（= `rm <feature>`） |
@@ -36,6 +39,8 @@ worktree-bay completion install   # 一键装 shell 补全（可选）
 | `worktree-bay completion <install\|bash\|zsh\|fish>` | `install` 一键装进 shell；或打印补全脚本 |
 | `worktree-bay mcp` | 启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 |
 | `worktree-bay skill` | 打印本指南 |
+| `worktree-bay version` / `--version` | 显示版本号 |
+| `worktree-bay help [命令]` | 帮助；`help <命令>` 看单命令用法 |
 
 典型流程：