worktree-bay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hughcube
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+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 { 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 { die } from './util/log.js';
+const program = new Command();
+program.name('worktree-bay').description('worktree 槽位+端口编排器').version('0.1.0');
+const sync = (fn) => { try {
+    fn(loadConfig(process.cwd()));
+}
+catch (e) {
+    die(e.message);
+} };
+program.command('claim <feature>').action(async (f) => { try {
+    await claimCommand(loadConfig(process.cwd()), f);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('ls').action(() => sync(lsCommand));
+program.command('add <feature> <service> <branch> [base]').action(async (f, s, b, base) => { try {
+    await addCommand(loadConfig(process.cwd()), f, s, b, base);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('run <feature> <service> <name> [args...]').action((f, s, n, args) => sync((c) => runCommand(c, f, s, n, args ?? [])));
+program.command('sh <feature> <service>').action((f, s) => sync((c) => shCommand(c, f, s)));
+program.command('rm <feature> [service]').option('-f, --force').action(async (f, s, o) => { try {
+    await rmCommand(loadConfig(process.cwd()), f, s, !!o.force);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('gc').option('--apply').action(async (o) => { try {
+    await gcCommand(loadConfig(process.cwd()), !!o.apply);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('completion <shell>').action((sh) => { try {
+    completionCommand(sh);
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('__complete', { hidden: true }).allowUnknownOption().action(() => {
+    const words = process.argv.slice(process.argv.indexOf('--') + 1);
+    try {
+        console.log(complete(loadConfig(process.cwd()), words).join('\n'));
+    }
+    catch { /* 静默 */ }
+});
+program.parseAsync(process.argv);

package/dist/commands/add.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { repoPath } from '../config.js';
+import { withLock } from '../lock.js';
+import { claim } from '../slots.js';
+import { slugify, worktreeDirName } from '../naming.js';
+import { buildVars, bringUp } from '../engine.js';
+import { log } from '../util/log.js';
+export function resolveAdd(cfg, feature, service, branch) {
+    if (!cfg.services[service])
+        throw new Error('unknown service: ' + service);
+    const slot = claim(cfg, feature);
+    const slug = worktreeDirName(slot, slugify(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) {
+    await withLock(cfg.workspaceRoot, async () => {
+        const p = resolveAdd(cfg, feature, service, branch);
+        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/HEAD', branch);
+        log(`✓ ${service} 挂入 "${feature}"（槽 ${p.slot}，端口 ${ctx.vars.port}）`);
+    });
+}

package/dist/commands/claim.js

@@ -0,0 +1,11 @@
+import { withLock } from '../lock.js';
+import { claim } from '../slots.js';
+import { blockBase } 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}）`);
+    for (const [n, sp] of Object.entries(cfg.services))
+        log(`  ${n.padEnd(8)} ${base + sp.offset}`);
+}

package/dist/commands/completion.js

@@ -0,0 +1,25 @@
+import { readLabels } from '../slots.js';
+import { log } from '../util/log.js';
+const SUBCMDS = ['claim', 'add', 'ls', 'gc', 'rm', 'run', 'sh', 'completion'];
+export function complete(cfg, words) {
+    const args = words.slice(1);
+    if (args.length === 0)
+        return SUBCMDS;
+    const sub = args[0];
+    const pos = args.length;
+    if (['add', 'rm', 'run', 'sh'].includes(sub) && pos === 1)
+        return Object.values(readLabels(cfg));
+    if (['add', 'run', 'sh'].includes(sub) && pos === 2)
+        return Object.keys(cfg.services);
+    return [];
+}
+export function completionScript(shell) {
+    if (shell === 'bash')
+        return `_worktree_bay(){ COMPREPLY=( $(worktree-bay __complete -- "\${COMP_WORDS[@]}") ); }\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`;
+    if (shell === 'fish')
+        return `complete -c worktree-bay -a '(worktree-bay __complete -- (commandline -opc))'`;
+    throw new Error('unsupported shell: ' + shell);
+}
+export function completionCommand(shell) { log(completionScript(shell)); }

package/dist/commands/gc.js

@@ -0,0 +1,46 @@
+import { repoPath, renderTemplate } from '../config.js';
+import { withLock } from '../lock.js';
+import { scanOccupancy, pruneEmptyLabels, removeLabel } from '../slots.js';
+import { buildVars } from '../engine.js';
+import { currentBranch, isDirty, hasUnpushed, isMergedToMain, remoteBranchGone, removeWorktree } from '../git.js';
+import { runShell } from '../util/exec.js';
+import { log, warn } from '../util/log.js';
+export function classifyForGc(s) {
+    if (s.merged && !s.dirty && !s.unpushed)
+        return 'auto-remove';
+    if (s.merged)
+        return 'flag';
+    return 'keep';
+}
+export async function gcCommand(cfg, apply) {
+    await withLock(cfg.workspaceRoot, async () => {
+        for (const [slot, occupants] of scanOccupancy(cfg))
+            for (const o of occupants) {
+                const repo = repoPath(cfg, o.service);
+                const branch = currentBranch(o.dir);
+                const v = classifyForGc({ merged: isMergedToMain(repo, branch), dirty: isDirty(o.dir), unpushed: hasUnpushed(repo, branch) });
+                if (v === 'auto-remove') {
+                    log(`[gc] ${o.service} (slot ${slot}) 已合并且干净 → 移除`);
+                    if (apply) {
+                        const sp = cfg.services[o.service];
+                        if (sp.teardown) {
+                            const vars = buildVars(cfg, { cfg, service: o.service, sp, slot, slug: o.slug, dir: o.dir, repo });
+                            runShell(renderTemplate(sp.teardown, vars), { cwd: repo });
+                        }
+                        removeWorktree(repo, o.dir, false);
+                    }
+                }
+                else if (v === 'flag')
+                    warn(`[gc] ${o.service} (slot ${slot}) 已合并但脏/未推 → 跳过，确认后手动删`);
+                else if (remoteBranchGone(repo, branch))
+                    warn(`[gc] ${o.service} (slot ${slot}) 远端分支已删（疑似 squash）→ 确认后 bay rm`);
+            }
+        for (const { slot, feature } of pruneEmptyLabels(cfg)) {
+            log(`[gc] 槽 ${slot}（${feature}）空预约（无 worktree）`);
+            if (apply)
+                removeLabel(cfg, slot);
+        }
+        if (!apply)
+            log('（dry-run；加 --apply 执行 auto-remove 与空预约清理）');
+    });
+}

package/dist/commands/ls.js

@@ -0,0 +1,16 @@
+import { scanOccupancy, readLabels } from '../slots.js';
+import { blockBase } from '../ports.js';
+import { log } from '../util/log.js';
+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 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)'}  api=${base + 1}  [${svc.join(', ') || 'no worktree'}]`);
+    }
+    return lines.join('\n') || '(no slots in use)';
+}
+export function lsCommand(cfg) { log(renderSlots(cfg)); }

package/dist/commands/passthrough.js

@@ -0,0 +1,26 @@
+import { repoPath } from '../config.js';
+import { scanOccupancy, slotOfFeature } from '../slots.js';
+import { buildVars, execArgv, run } from '../engine.js';
+function ctxOf(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}`);
+    const sp = cfg.services[service];
+    return { sp, vars: buildVars(cfg, { cfg, service, sp, slot, slug: occ.slug, dir: occ.dir, repo: repoPath(cfg, service) }) };
+}
+export function runCommand(cfg, feature, service, name, args) {
+    const ctx = ctxOf(cfg, feature, service);
+    const named = ctx.sp.run?.[name];
+    if (!named)
+        throw new Error(`run.${name} 未定义于 ${service}`);
+    const argv = execArgv(ctx, [...named, ...args]);
+    process.exit(run(argv[0], argv.slice(1)).code);
+}
+export function shCommand(cfg, feature, service) {
+    const ctx = ctxOf(cfg, feature, service);
+    const argv = execArgv(ctx, ['sh']);
+    process.exit(run(argv[0], argv.slice(1)).code);
+}

package/dist/commands/rm.js

@@ -0,0 +1,36 @@
+import { repoPath, renderTemplate } from '../config.js';
+import { withLock } from '../lock.js';
+import { scanOccupancy, slotOfFeature, removeLabel } from '../slots.js';
+import { buildVars } from '../engine.js';
+import { isDirty, hasUnpushed, currentBranch, removeWorktree } from '../git.js';
+import { runShell } from '../util/exec.js';
+import { log, warn } from '../util/log.js';
+export function resolveRm(cfg, feature, service) {
+    const slot = slotOfFeature(cfg, feature);
+    if (slot === undefined)
+        throw new Error('unknown feature: ' + feature);
+    const all = scanOccupancy(cfg).get(slot) ?? [];
+    return service ? all.filter((o) => o.service === service) : all;
+}
+export async function rmCommand(cfg, feature, service, force) {
+    await withLock(cfg.workspaceRoot, async () => {
+        for (const o of resolveRm(cfg, feature, service)) {
+            const repo = repoPath(cfg, o.service);
+            const branch = currentBranch(o.dir);
+            if (!force && (isDirty(o.dir) || hasUnpushed(repo, branch))) {
+                warn(`跳过 ${o.service}：有未提交/未推改动（-f 强删）`);
+                continue;
+            }
+            const sp = cfg.services[o.service];
+            if (sp.teardown) {
+                const vars = buildVars(cfg, { cfg, service: o.service, sp, slot: o.slot, slug: o.slug, dir: o.dir, repo });
+                runShell(renderTemplate(sp.teardown, vars), { cwd: repo });
+            }
+            removeWorktree(repo, o.dir, force);
+            log(`✓ 移除 ${o.service}`);
+        }
+        const slot = slotOfFeature(cfg, feature);
+        if (!service && (scanOccupancy(cfg).get(slot) ?? []).length === 0)
+            removeLabel(cfg, slot);
+    });
+}

package/dist/config.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+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'])
+        if (raw[k] === undefined)
+            throw new Error(`config: ${k} required`);
+    const services = raw.services ?? {};
+    const offsets = new Set();
+    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);
+        const repoDir = path.join(raw.workspaceRoot, sp.repo ?? name);
+        if (!fs.existsSync(repoDir))
+            throw new Error(`config: ${name}.repo dir missing: ${repoDir}`); // V5
+    }
+    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
+    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) };
+}
+export function loadConfig(startDir) {
+    if (process.env.WORKTREE_BAY_CONFIG)
+        return parseConfig(process.env.WORKTREE_BAY_CONFIG);
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const p = path.join(dir, 'worktree-bay.config.json');
+        if (fs.existsSync(p))
+            return parseConfig(p);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error('worktree-bay.config.json not found');
+        dir = parent;
+    }
+}
+export function repoPath(cfg, service) {
+    const sp = cfg.services[service];
+    if (!sp)
+        throw new Error('unknown service: ' + service);
+    return path.join(cfg.workspaceRoot, sp.repo ?? service);
+}
+export function renderTemplate(tpl, vars) {
+    return tpl.replace(/\{(\w+)\}/g, (_, k) => (vars[k] !== undefined ? String(vars[k]) : `{${k}}`));
+}

package/dist/engine.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderTemplate } from './config.js';
+import { blockBase, portOf, isPortFree } from './ports.js';
+import { scanOccupancy } from './slots.js';
+import { addWorktree } from './git.js';
+import { runShell, run, spliceArgv, isTTY } from './util/exec.js';
+import { warn, log } from './util/log.js';
+export function mergeEnvText(text, kv) {
+    const lines = text.split('\n');
+    const seen = new Set();
+    const out = lines.map((line) => { const m = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(line); if (m && kv[m[1]] !== undefined) {
+        seen.add(m[1]);
+        return `${m[1]}=${kv[m[1]]}`;
+    } return line; });
+    for (const [k, v] of Object.entries(kv))
+        if (!seen.has(k)) {
+            if (out.length && out[out.length - 1] === '')
+                out.splice(out.length - 1, 0, `${k}=${v}`);
+            else
+                out.push(`${k}=${v}`);
+        }
+    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;
+}
+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 };
+    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 ?? {}))
+        base[k] = renderTemplate(v, base);
+    return base;
+}
+export async function bringUp(ctx, base, branch) {
+    const { sp, dir, repo, vars } = ctx;
+    if (!(await isPortFree(Number(vars.port))))
+        throw new Error(`port ${vars.port} 被占用（Codex#11）`);
+    addWorktree(repo, dir, branch, base);
+    for (const rel of sp.copy ?? []) {
+        // dereference: vendor/node_modules 含符号链接，Windows 下原样复制符号链接会失败，跟随并拷目标内容
+        fs.cpSync(path.join(repo, rel), path.join(dir, rel), { recursive: true, dereference: true });
+        for (const lock of ['composer.lock', 'pnpm-lock.yaml', 'package-lock.json']) {
+            const a = path.join(repo, lock), b = path.join(dir, lock);
+            if (fs.existsSync(a) && fs.existsSync(b) && fs.readFileSync(a, 'utf8') !== fs.readFileSync(b, 'utf8'))
+                warn(`⚠ ${lock} 与主 checkout 不一致，拷来依赖可能版本错位，建议改跑安装（Codex#18）`);
+        }
+    }
+    for (const [file, kv] of Object.entries(sp.env ?? {})) {
+        const fp = path.join(dir, file);
+        const cur = fs.existsSync(fp) ? fs.readFileSync(fp, 'utf8') : '';
+        const rendered = {};
+        for (const [k, v] of Object.entries(kv))
+            rendered[k] = renderTemplate(v, vars);
+        fs.writeFileSync(fp, mergeEnvText(cur, rendered));
+    }
+    if (sp.setup) {
+        const r = runShell(renderTemplate(sp.setup, vars), { cwd: dir });
+        if (r.code !== 0)
+            throw new Error('setup 失败');
+    }
+    if (sp.start)
+        log(`  启动: (cd ${dir} && ${renderTemplate(sp.start, vars)})`);
+}
+export function execArgv(ctx, cmd) {
+    const tpl = (ctx.sp.exec ?? ['sh', '-c', '{cmd...}']).map((el) => el === '{cmd...}' ? el : renderTemplate(el, ctx.vars));
+    const spliced = spliceArgv(tpl, cmd);
+    if (isTTY() && cmd[0] === 'sh' && spliced.includes('exec'))
+        spliced.splice(spliced.indexOf('exec') + 1, 0, '-it');
+    return spliced;
+}
+export { run };

package/dist/git.js

@@ -0,0 +1,30 @@
+import { spawnSync } from 'node:child_process';
+function git(repo, ...a) { return spawnSync('git', ['-C', repo, ...a], { encoding: 'utf8' }); }
+function ok(repo, ...a) { const r = git(repo, ...a); if (r.status !== 0)
+    throw new Error(`git ${a.join(' ')}: ${r.stderr || r.stdout}`); return r.stdout; }
+export function addWorktree(repo, dir, branch, base) { ok(repo, 'worktree', 'add', '-b', branch, dir, base); }
+export function removeWorktree(repo, dir, force) { const a = ['worktree', 'remove', dir]; if (force)
+    a.push('--force'); const r = git(repo, ...a); if (r.status !== 0)
+    throw new Error('worktree remove: ' + (r.stderr || r.stdout)); git(repo, 'worktree', 'prune'); }
+export function isDirty(dir) { return ok(dir, 'status', '--porcelain').trim().length > 0; }
+export function currentBranch(dir) { return ok(dir, 'rev-parse', '--abbrev-ref', 'HEAD').trim(); }
+export function mainBranch(repo) {
+    const r = git(repo, 'symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD');
+    if (r.status === 0 && r.stdout.trim())
+        return r.stdout.trim().replace(/^origin\//, '');
+    for (const b of ['master', 'main'])
+        if (git(repo, 'rev-parse', '--verify', `origin/${b}`).status === 0)
+            return b;
+    return 'master';
+}
+export function isMergedToMain(repo, branch) { git(repo, 'fetch', '-q', 'origin'); return git(repo, 'merge-base', '--is-ancestor', branch, `origin/${mainBranch(repo)}`).status === 0; }
+export function remoteBranchGone(repo, branch) { return git(repo, 'rev-parse', '--verify', `origin/${branch}`).status !== 0; }
+export function hasUnpushed(repo, branch) {
+    const main = mainBranch(repo);
+    const r = git(repo, 'log', '--oneline', `origin/${main}..${branch}`);
+    if (r.status !== 0)
+        return true;
+    if (!r.stdout.trim())
+        return false;
+    return remoteBranchGone(repo, branch) ? true : git(repo, 'log', '--oneline', `origin/${branch}..${branch}`).stdout.trim().length > 0;
+}

package/dist/lock.js

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export async function withLock(ws, fn) {
+    const lockDir = path.join(ws, '.worktree-bay', 'lock');
+    fs.mkdirSync(path.join(ws, '.worktree-bay'), { recursive: true });
+    const start = Date.now();
+    for (;;) {
+        try {
+            fs.mkdirSync(lockDir);
+            break;
+        }
+        catch {
+            if (Date.now() - start > 30000)
+                throw new Error('worktree-bay: lock timeout (另一个 worktree-bay 在运行?)');
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        fs.rmdirSync(lockDir);
+    }
+}

package/dist/naming.js

@@ -0,0 +1,8 @@
+export function slugify(branch) {
+    return branch.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 40).replace(/-+$/g, '');
+}
+export function worktreeDirName(slot, slug) { return `s${slot}-${slug}`; }
+export function parseWorktreeDir(name) {
+    const m = /^s(\d+)-(.+)$/.exec(name);
+    return m ? { slot: Number(m[1]), slug: m[2] } : null;
+}

package/dist/ports.js

@@ -0,0 +1,11 @@
+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; }
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once('error', () => resolve(false));
+        srv.once('listening', () => srv.close(() => resolve(true)));
+        srv.listen(port, '127.0.0.1');
+    });
+}

package/dist/slots.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { repoPath } from './config.js';
+import { parseWorktreeDir } from './naming.js';
+export function scanOccupancy(cfg) {
+    const map = new Map();
+    for (const service of Object.keys(cfg.services)) {
+        const root = path.join(repoPath(cfg, service), '.worktrees');
+        if (!fs.existsSync(root))
+            continue;
+        for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+            if (!e.isDirectory())
+                continue;
+            const p = parseWorktreeDir(e.name);
+            if (!p)
+                continue;
+            const list = map.get(p.slot) ?? [];
+            list.push({ service, slot: p.slot, slug: e.name, dir: path.join(root, e.name) });
+            map.set(p.slot, list);
+        }
+    }
+    return map;
+}
+function labelPath(cfg) { return path.join(cfg.workspaceRoot, '.worktree-bay-slots.json'); }
+export function readLabels(cfg) { const p = labelPath(cfg); return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {}; }
+function save(cfg, l) { fs.writeFileSync(labelPath(cfg), JSON.stringify(l, null, 2) + '\n'); }
+export function writeLabel(cfg, slot, f) { const l = readLabels(cfg); l[String(slot)] = f; save(cfg, l); }
+export function removeLabel(cfg, slot) { const l = readLabels(cfg); delete l[String(slot)]; save(cfg, l); }
+export function slotOfFeature(cfg, f) { for (const [k, v] of Object.entries(readLabels(cfg)))
+    if (v === f)
+        return Number(k); return undefined; }
+export function freeSlot(cfg) {
+    const occ = scanOccupancy(cfg);
+    const l = readLabels(cfg);
+    for (let n = 1; n <= cfg.maxSlots; n++)
+        if (!occ.has(n) && l[String(n)] === undefined)
+            return n;
+    throw new Error(`no free slot (1..${cfg.maxSlots} all taken)`);
+}
+export function claim(cfg, f) { const e = slotOfFeature(cfg, f); if (e !== undefined)
+    return e; const n = freeSlot(cfg); writeLabel(cfg, n, f); return n; }
+export function pruneEmptyLabels(cfg) {
+    const occ = scanOccupancy(cfg);
+    const removed = [];
+    for (const [k, v] of Object.entries(readLabels(cfg)))
+        if (!occ.has(Number(k)))
+            removed.push({ slot: Number(k), feature: v });
+    return removed;
+}

package/dist/util/exec.js

@@ -0,0 +1,10 @@
+import { spawnSync } from 'node:child_process';
+export function run(cmd, args, opts = {}) { const r = spawnSync(cmd, args, { cwd: opts.cwd, stdio: 'inherit', shell: false }); return { code: r.status ?? 1 }; }
+export function runShell(line, opts = {}) { const r = spawnSync(line, { cwd: opts.cwd, stdio: 'inherit', shell: true }); return { code: r.status ?? 1 }; }
+export function spliceArgv(template, cmd) { const out = []; for (const el of template) {
+    if (el === '{cmd...}')
+        out.push(...cmd);
+    else
+        out.push(el);
+} return out; }
+export function isTTY() { return Boolean(process.stdout.isTTY && process.stdin.isTTY); }

package/dist/util/log.js

@@ -0,0 +1,3 @@
+export const log = (...a) => console.log(...a);
+export const warn = (...a) => console.warn(...a);
+export const die = (m) => { console.error('worktree-bay: ' + m); process.exit(1); };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "worktree-bay",
+  "version": "0.1.0",
+  "description": "Config-driven git worktree slot + port orchestrator for parallel multi-service development",
+  "keywords": [
+    "git",
+    "worktree",
+    "monorepo",
+    "cli",
+    "ports",
+    "orchestration",
+    "parallel",
+    "dev"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "hughcube",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hughcube/worktree-bay.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hughcube/worktree-bay/issues"
+  },
+  "homepage": "https://github.com/hughcube/worktree-bay#readme",
+  "bin": {
+    "worktree-bay": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}