worktree-compose 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,132 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { buildContext, filterWorktrees } from "../context.js";
+import { allocateWorktreePorts } from "../ports/allocate.js";
+import { composeProjectName } from "../utils/sanitize.js";
+import { exec, execSafe } from "../utils/exec.js";
+import { syncWorktreeFiles } from "../sync/files.js";
+import { copyBaseEnv, injectPortOverrides } from "../sync/env.js";
+import { getRepoRoot } from "../compose/detect.js";
+import { getWorktreeByIndex, getWorktreeBranch } from "../git/worktree.js";
+import { getChangedFiles, getLocalDirtyFiles, findConflicts, promoteFiles, } from "../git/promote.js";
+function startWorktrees(indices) {
+    const ctx = buildContext();
+    if (ctx.worktrees.length === 0)
+        return "No worktrees found.";
+    const targets = filterWorktrees(ctx.worktrees, indices);
+    const results = [];
+    for (const wt of targets) {
+        const idx = ctx.worktrees.indexOf(wt) + 1;
+        const project = composeProjectName(ctx.repoName, idx, wt.branch);
+        const allocations = allocateWorktreePorts(ctx.portMappings, idx);
+        syncWorktreeFiles(ctx.repoRoot, wt.path, ctx.composeFile, ctx.config.sync);
+        copyBaseEnv(ctx.repoRoot, wt.path);
+        injectPortOverrides(`${wt.path}/.env`, allocations, ctx.config.envOverrides);
+        exec(`docker compose -p "${project}" up -d --build`, { cwd: wt.path });
+        const ports = allocations.map((a) => `${a.envVar}=${a.port}`).join(", ");
+        results.push(`Worktree ${idx} (${wt.branch}): started [${ports}]`);
+    }
+    return results.join("\n");
+}
+function stopWorktrees(indices) {
+    const ctx = buildContext();
+    if (ctx.worktrees.length === 0)
+        return "No worktrees found.";
+    const targets = filterWorktrees(ctx.worktrees, indices);
+    const results = [];
+    for (const wt of targets) {
+        const idx = ctx.worktrees.indexOf(wt) + 1;
+        const project = composeProjectName(ctx.repoName, idx, wt.branch);
+        try {
+            exec(`docker compose -p "${project}" down`, { cwd: wt.path });
+            results.push(`Worktree ${idx} (${wt.branch}): stopped`);
+        }
+        catch {
+            results.push(`Worktree ${idx} (${wt.branch}): already stopped`);
+        }
+    }
+    return results.join("\n");
+}
+function listWorktrees() {
+    const ctx = buildContext();
+    return ctx.worktrees.map((wt, i) => {
+        const idx = i + 1;
+        const project = composeProjectName(ctx.repoName, idx, wt.branch);
+        const allocations = allocateWorktreePorts(ctx.portMappings, idx);
+        const up = execSafe(`docker compose -p "${project}" ps --format json`, {
+            cwd: wt.path,
+        }) !== null;
+        return {
+            index: idx,
+            branch: wt.branch,
+            path: wt.path,
+            project,
+            status: up ? "up" : "down",
+            ports: Object.fromEntries(allocations.map((a) => [a.envVar, a.port])),
+        };
+    });
+}
+function promoteWorktree(index) {
+    const repoRoot = getRepoRoot();
+    const wt = getWorktreeByIndex(repoRoot, index);
+    if (!wt)
+        return `Worktree index ${index} not found.`;
+    const currentBranch = getWorktreeBranch(repoRoot);
+    const files = getChangedFiles(repoRoot, wt.path, currentBranch, wt.branch);
+    if (files.length === 0)
+        return "No changes to promote.";
+    const dirtyFiles = getLocalDirtyFiles(repoRoot);
+    const conflicts = findConflicts(files, dirtyFiles);
+    if (conflicts.length > 0) {
+        return `Abort: ${conflicts.length} file(s) have uncommitted changes: ${conflicts.join(", ")}`;
+    }
+    promoteFiles(repoRoot, wt.path, files);
+    return `Promoted ${files.length} file(s) from worktree ${index} (${wt.branch}) into ${currentBranch}:\n${files.join("\n")}`;
+}
+export async function startMcpServer() {
+    const server = new McpServer({
+        name: "worktree-compose",
+        version: "0.1.0",
+    });
+    server.tool("wtc_start", "Start Docker Compose stacks for worktrees. Syncs files, injects isolated ports, runs docker compose up.", { indices: z.array(z.number()).optional().describe("Worktree indices to start. Omit for all.") }, async ({ indices }) => ({
+        content: [{ type: "text", text: startWorktrees(indices ?? []) }],
+    }));
+    server.tool("wtc_stop", "Stop Docker Compose stacks for worktrees.", { indices: z.array(z.number()).optional().describe("Worktree indices to stop. Omit for all.") }, async ({ indices }) => ({
+        content: [{ type: "text", text: stopWorktrees(indices ?? []) }],
+    }));
+    server.tool("wtc_restart", "Restart Docker Compose stacks for worktrees. Use after DB migrations, Dockerfile changes, or config updates.", { indices: z.array(z.number()).optional().describe("Worktree indices to restart. Omit for all.") }, async ({ indices }) => {
+        stopWorktrees(indices ?? []);
+        const result = startWorktrees(indices ?? []);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("wtc_list", "List all worktrees with branch, status, ports, and URLs.", {}, async () => ({
+        content: [
+            { type: "text", text: JSON.stringify(listWorktrees(), null, 2) },
+        ],
+    }));
+    server.tool("wtc_promote", "Copy changed files from a worktree into the current branch as uncommitted changes.", { index: z.number().describe("Worktree index to promote.") }, async ({ index }) => ({
+        content: [{ type: "text", text: promoteWorktree(index) }],
+    }));
+    server.tool("wtc_clean", "Stop all worktree containers, remove all worktrees, prune everything.", {}, async () => {
+        const { cleanCommand } = await import("../commands/clean.js");
+        try {
+            cleanCommand();
+            return {
+                content: [{ type: "text", text: "Cleanup complete." }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Cleanup failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/ports/allocate.d.ts

@@ -0,0 +1,3 @@
+import type { PortMapping, PortAllocation } from "./types.js";
+export declare function allocatePort(defaultPort: number, worktreeIndex: number): number;
+export declare function allocateWorktreePorts(mappings: PortMapping[], worktreeIndex: number): PortAllocation[];

package/dist/ports/allocate.js

@@ -0,0 +1,29 @@
+const BASE_OFFSET = 20000;
+export function allocatePort(defaultPort, worktreeIndex) {
+    let port = BASE_OFFSET + defaultPort + worktreeIndex;
+    if (port > 65535) {
+        port = defaultPort + 100 * worktreeIndex;
+    }
+    if (port > 65535 || port < 1024) {
+        throw new Error(`Cannot allocate port for default ${defaultPort} at worktree index ${worktreeIndex}. ` +
+            `Computed port ${port} is out of valid range (1024-65535).`);
+    }
+    return port;
+}
+export function allocateWorktreePorts(mappings, worktreeIndex) {
+    const overridable = mappings.filter((m) => m.envVar !== null);
+    const allocations = overridable.map((m) => ({
+        serviceName: m.serviceName,
+        envVar: m.envVar,
+        port: allocatePort(m.defaultPort, worktreeIndex),
+        containerPort: m.containerPort,
+    }));
+    const seen = new Set();
+    for (const a of allocations) {
+        if (seen.has(a.port)) {
+            throw new Error(`Port collision: ${a.port} is assigned to multiple services in worktree ${worktreeIndex}.`);
+        }
+        seen.add(a.port);
+    }
+    return allocations;
+}

package/dist/ports/extract.d.ts

@@ -0,0 +1,4 @@
+import type { ComposeService } from "../compose/types.js";
+import type { PortMapping } from "./types.js";
+export declare function extractPortMappings(services: ComposeService[]): PortMapping[];
+export declare function suggestEnvVar(serviceName: string): string;

package/dist/ports/extract.js

@@ -0,0 +1,92 @@
+const ENV_VAR_PATTERN = /^\$\{([A-Z_][A-Z0-9_]*):-(\d+)\}$/;
+function stripProtocol(port) {
+    return port.replace(/\/(tcp|udp|sctp)$/i, "");
+}
+function splitPortString(raw) {
+    const cleaned = stripProtocol(raw);
+    const segments = [];
+    let current = "";
+    let depth = 0;
+    for (const ch of cleaned) {
+        if (ch === "$" || (depth > 0 && ch !== "}")) {
+            current += ch;
+            if (ch === "{")
+                depth++;
+            continue;
+        }
+        if (ch === "{" && current.endsWith("$")) {
+            current += ch;
+            depth++;
+            continue;
+        }
+        if (ch === "}") {
+            current += ch;
+            depth--;
+            continue;
+        }
+        if (ch === ":" && depth === 0) {
+            segments.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    segments.push(current);
+    if (segments.length === 1)
+        return null;
+    if (segments.length === 2)
+        return { host: segments[0], container: segments[1] };
+    if (segments.length === 3)
+        return { host: segments[1], container: segments[2] };
+    return null;
+}
+function resolveEnvVar(segment) {
+    const match = segment.match(ENV_VAR_PATTERN);
+    if (!match)
+        return null;
+    return { envVar: match[1], defaultPort: parseInt(match[2], 10) };
+}
+function resolvePort(segment) {
+    const n = parseInt(segment, 10);
+    return isNaN(n) ? null : n;
+}
+export function extractPortMappings(services) {
+    const mappings = [];
+    for (const svc of services) {
+        for (const raw of svc.ports) {
+            const split = splitPortString(raw);
+            if (!split)
+                continue;
+            const envResult = resolveEnvVar(split.host);
+            const containerEnv = resolveEnvVar(split.container);
+            const containerPort = containerEnv?.defaultPort ?? resolvePort(split.container);
+            if (containerPort === null)
+                continue;
+            if (envResult) {
+                mappings.push({
+                    serviceName: svc.name,
+                    envVar: envResult.envVar,
+                    defaultPort: envResult.defaultPort,
+                    containerPort,
+                    raw,
+                });
+            }
+            else {
+                const hostPort = resolvePort(split.host);
+                if (hostPort !== null) {
+                    mappings.push({
+                        serviceName: svc.name,
+                        envVar: null,
+                        defaultPort: hostPort,
+                        containerPort,
+                        raw,
+                    });
+                }
+            }
+        }
+    }
+    return mappings;
+}
+export function suggestEnvVar(serviceName) {
+    return `${serviceName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_PORT`;
+}

package/dist/ports/types.d.ts

@@ -0,0 +1,13 @@
+export interface PortMapping {
+    serviceName: string;
+    envVar: string | null;
+    defaultPort: number;
+    containerPort: number;
+    raw: string;
+}
+export interface PortAllocation {
+    serviceName: string;
+    envVar: string;
+    port: number;
+    containerPort: number;
+}

package/dist/ports/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sync/env.d.ts

@@ -0,0 +1,5 @@
+import type { PortAllocation } from "../ports/types.js";
+export declare function stripOverrideBlock(content: string): string;
+export declare function buildOverrideBlock(allocations: PortAllocation[], envOverrides?: Record<string, string>): string;
+export declare function injectPortOverrides(envPath: string, allocations: PortAllocation[], envOverrides?: Record<string, string>): void;
+export declare function copyBaseEnv(repoRoot: string, wtPath: string): void;

package/dist/sync/env.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+const BLOCK_START = "# --- wtc port overrides ---";
+const BLOCK_END = "# --- end wtc ---";
+export function stripOverrideBlock(content) {
+    const startIdx = content.indexOf(BLOCK_START);
+    if (startIdx === -1)
+        return content;
+    const endIdx = content.indexOf(BLOCK_END, startIdx);
+    if (endIdx === -1)
+        return content;
+    const before = content.slice(0, startIdx).trimEnd();
+    const after = content.slice(endIdx + BLOCK_END.length).trimStart();
+    return [before, after].filter(Boolean).join("\n") + "\n";
+}
+export function buildOverrideBlock(allocations, envOverrides) {
+    const lines = [BLOCK_START];
+    const portValues = new Map();
+    for (const a of allocations) {
+        lines.push(`${a.envVar}=${a.port}`);
+        portValues.set(a.envVar, a.port);
+    }
+    if (envOverrides) {
+        for (const [key, template] of Object.entries(envOverrides)) {
+            let value = template;
+            for (const [envVar, port] of portValues) {
+                value = value.replace(`\${${envVar}}`, String(port));
+            }
+            lines.push(`${key}=${value}`);
+        }
+    }
+    lines.push(BLOCK_END);
+    return lines.join("\n");
+}
+export function injectPortOverrides(envPath, allocations, envOverrides) {
+    let content = "";
+    if (fs.existsSync(envPath)) {
+        content = fs.readFileSync(envPath, "utf-8");
+    }
+    content = stripOverrideBlock(content);
+    const block = buildOverrideBlock(allocations, envOverrides);
+    const result = content.trimEnd() + "\n\n" + block + "\n";
+    fs.writeFileSync(envPath, result, "utf-8");
+}
+export function copyBaseEnv(repoRoot, wtPath) {
+    const envSrc = path.join(repoRoot, ".env");
+    const envExampleSrc = path.join(repoRoot, ".env.example");
+    const envDst = path.join(wtPath, ".env");
+    if (fs.existsSync(envSrc)) {
+        fs.copyFileSync(envSrc, envDst);
+    }
+    else if (fs.existsSync(envExampleSrc)) {
+        fs.copyFileSync(envExampleSrc, envDst);
+    }
+    else {
+        fs.writeFileSync(envDst, "", "utf-8");
+    }
+}

package/dist/sync/files.d.ts

@@ -0,0 +1,2 @@
+import type { ComposeFile } from "../compose/types.js";
+export declare function syncWorktreeFiles(repoRoot: string, wtPath: string, composeFile: ComposeFile, extraSync?: string[]): void;

package/dist/sync/files.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+function copyFile(src, dst) {
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    if (fs.existsSync(src)) {
+        fs.copyFileSync(src, dst);
+    }
+}
+function copyDir(src, dst) {
+    if (!fs.existsSync(src))
+        return;
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const dstPath = path.join(dst, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, dstPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, dstPath);
+        }
+    }
+}
+function getDockerfiles(composeFile, repoRoot) {
+    const files = [];
+    for (const svc of composeFile.services) {
+        if (!svc.build)
+            continue;
+        const context = svc.build.context ?? ".";
+        const dockerfile = svc.build.dockerfile ?? "Dockerfile";
+        const resolvedDir = path.resolve(path.dirname(composeFile.composePath), context);
+        const fullPath = path.join(resolvedDir, dockerfile);
+        const rel = path.relative(repoRoot, fullPath);
+        files.push(rel);
+    }
+    return [...new Set(files)];
+}
+export function syncWorktreeFiles(repoRoot, wtPath, composeFile, extraSync) {
+    const composeRel = path.relative(repoRoot, composeFile.composePath);
+    copyFile(path.join(repoRoot, composeRel), path.join(wtPath, composeRel));
+    for (const df of getDockerfiles(composeFile, repoRoot)) {
+        copyFile(path.join(repoRoot, df), path.join(wtPath, df));
+    }
+    if (extraSync) {
+        for (const p of extraSync) {
+            const src = path.join(repoRoot, p);
+            const dst = path.join(wtPath, p);
+            if (fs.existsSync(src)) {
+                const stat = fs.statSync(src);
+                if (stat.isDirectory()) {
+                    copyDir(src, dst);
+                }
+                else {
+                    copyFile(src, dst);
+                }
+            }
+        }
+    }
+}

package/dist/utils/exec.d.ts

@@ -0,0 +1,4 @@
+import { type ExecSyncOptions } from "node:child_process";
+export declare function exec(cmd: string, opts?: ExecSyncOptions): string;
+export declare function execLive(cmd: string, opts?: ExecSyncOptions): void;
+export declare function execSafe(cmd: string, opts?: ExecSyncOptions): string | null;

package/dist/utils/exec.js

@@ -0,0 +1,23 @@
+import { execSync } from "node:child_process";
+export function exec(cmd, opts) {
+    const result = execSync(cmd, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        ...opts,
+    });
+    return result.trim();
+}
+export function execLive(cmd, opts) {
+    execSync(cmd, {
+        stdio: "inherit",
+        ...opts,
+    });
+}
+export function execSafe(cmd, opts) {
+    try {
+        return exec(cmd, opts);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/log.d.ts

@@ -0,0 +1,5 @@
+export declare function info(msg: string): void;
+export declare function success(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function error(msg: string): void;
+export declare function header(msg: string): void;

package/dist/utils/log.js

@@ -0,0 +1,16 @@
+import chalk from "chalk";
+export function info(msg) {
+    console.log(chalk.blue("ℹ"), msg);
+}
+export function success(msg) {
+    console.log(chalk.green("✔"), msg);
+}
+export function warn(msg) {
+    console.log(chalk.yellow("⚠"), msg);
+}
+export function error(msg) {
+    console.error(chalk.red("✖"), msg);
+}
+export function header(msg) {
+    console.log(chalk.bold.cyan(`\n=== ${msg} ===`));
+}

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitize(input: string): string;
+export declare function composeProjectName(repoName: string, index: number, branch: string): string;

package/dist/utils/sanitize.js

@@ -0,0 +1,11 @@
+export function sanitize(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-/, "")
+        .replace(/-$/, "");
+}
+export function composeProjectName(repoName, index, branch) {
+    return sanitize(`${repoName}-wt-${index}-${branch}`);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "worktree-compose",
+  "version": "0.1.0",
+  "description": "Zero-config Docker Compose isolation for git worktrees",
+  "type": "module",
+  "bin": {
+    "worktree-compose": "./dist/cli.js",
+    "wtc": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "git",
+    "worktree",
+    "docker",
+    "compose",
+    "isolation",
+    "parallel",
+    "development",
+    "mcp"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.0",
+    "yaml": "^2.8.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.15.21",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.4",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}