lockstep-mcp 0.1.0

package/dist/tmux.js

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { getPlannerPrompt, getImplementerPrompt } from "./prompts.js";
+function runTmux(args, inherit = false) {
+    const result = spawnSync("tmux", args, { stdio: inherit ? "inherit" : "pipe" });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 0;
+}
+function ensureTmuxAvailable() {
+    try {
+        const status = runTmux(["-V"]);
+        if (status !== 0)
+            throw new Error("tmux not available");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`tmux not found or not available: ${message}`);
+    }
+}
+function sessionExists(session) {
+    const status = runTmux(["has-session", "-t", session]);
+    return status === 0;
+}
+function sendKeys(target, text) {
+    runTmux(["send-keys", "-t", target, "-l", text]);
+    runTmux(["send-keys", "-t", target, "C-m"]);
+}
+export async function launchTmux(options = {}) {
+    ensureTmuxAvailable();
+    const session = options.session ?? "lockstep";
+    const repo = path.resolve(options.repo ?? process.cwd());
+    const claudeCmd = options.claudeCmd ?? "claude";
+    const codexCmd = options.codexCmd ?? "codex";
+    const injectPrompts = options.injectPrompts !== false;
+    const layout = options.layout ?? "windows";
+    const split = options.split ?? "vertical";
+    const showDashboard = options.dashboard !== false;
+    const dashboardCmd = options.dashboardCmd ?? "lockstep-mcp dashboard --host 127.0.0.1 --port 8787";
+    const statusBar = options.statusBar !== false;
+    if (!sessionExists(session)) {
+        runTmux(["new-session", "-d", "-s", session, "-c", repo, "-n", "claude"]);
+        if (statusBar) {
+            runTmux(["set-option", "-t", session, "-g", "status", "on"]);
+            runTmux(["set-option", "-t", session, "-g", "status-style", "bg=colour237,fg=colour252"]);
+            runTmux(["set-option", "-t", session, "-g", "status-left", " lockstep "]);
+            runTmux(["set-option", "-t", session, "-g", "status-right", "Ctrl-b n/p | Ctrl-b w"]);
+            runTmux(["set-option", "-t", session, "-g", "window-status-format", " #I:#W "]);
+            runTmux(["set-option", "-t", session, "-g", "window-status-current-format", " #[bold]#I:#W "]);
+        }
+        sendKeys(`${session}:0.0`, claudeCmd);
+        if (layout === "panes") {
+            if (split === "vertical") {
+                runTmux(["split-window", "-h", "-t", `${session}:0`, "-c", repo]);
+            }
+            else {
+                runTmux(["split-window", "-v", "-t", `${session}:0`, "-c", repo]);
+            }
+            runTmux(["select-layout", "-t", `${session}:0`, "even-horizontal"]);
+            sendKeys(`${session}:0.1`, codexCmd);
+        }
+        else {
+            runTmux(["new-window", "-t", session, "-n", "codex", "-c", repo]);
+            sendKeys(`${session}:1.0`, codexCmd);
+        }
+        if (injectPrompts) {
+            await new Promise((resolve) => setTimeout(resolve, 1500));
+            sendKeys(`${session}:0.0`, getPlannerPrompt());
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            if (layout === "panes") {
+                sendKeys(`${session}:0.1`, getImplementerPrompt());
+            }
+            else {
+                sendKeys(`${session}:1.0`, getImplementerPrompt());
+            }
+        }
+        if (showDashboard) {
+            const targetIndex = layout === "panes" ? "1.0" : "2.0";
+            runTmux(["new-window", "-t", session, "-n", "dashboard", "-c", repo]);
+            sendKeys(`${session}:${targetIndex}`, dashboardCmd);
+        }
+        if (statusBar) {
+            runTmux(["display-message", "-t", session, "Lockstep: Ctrl-b n/p switch windows, Ctrl-b w list"]);
+        }
+    }
+    runTmux(["attach", "-t", session], true);
+}

package/dist/utils.js

@@ -0,0 +1,35 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export function expandHome(input) {
+    if (!input.startsWith("~"))
+        return input;
+    const home = process.env.HOME;
+    if (!home)
+        return input;
+    return path.join(home, input.slice(1));
+}
+export function normalizeRoots(roots) {
+    return roots
+        .map((root) => expandHome(root))
+        .map((root) => path.resolve(root));
+}
+export function isPathUnderRoot(targetPath, root) {
+    const rel = path.relative(root, targetPath);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+export function resolvePath(inputPath, mode, roots) {
+    const resolved = path.resolve(expandHome(inputPath));
+    if (mode === "open")
+        return resolved;
+    for (const root of roots) {
+        if (isPathUnderRoot(resolved, root))
+            return resolved;
+    }
+    throw new Error(`Path not allowed in strict mode: ${resolved}`);
+}
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/worktree.js

@@ -0,0 +1,356 @@
+/**
+ * Git worktree management for isolated implementer work
+ */
+import { exec as execCallback } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fs from "node:fs/promises";
+const exec = promisify(execCallback);
+const LOCKSTEP_WORKTREE_DIR = ".lockstep/worktrees";
+/**
+ * Check if a directory is a git repository
+ */
+export async function isGitRepo(repoPath) {
+    try {
+        await exec("git rev-parse --git-dir", { cwd: repoPath });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the git root directory
+ */
+export async function getGitRoot(repoPath) {
+    const { stdout } = await exec("git rev-parse --show-toplevel", { cwd: repoPath });
+    return stdout.trim();
+}
+/**
+ * Get the current branch name
+ */
+export async function getCurrentBranch(repoPath) {
+    const { stdout } = await exec("git rev-parse --abbrev-ref HEAD", { cwd: repoPath });
+    return stdout.trim();
+}
+/**
+ * Create a git worktree for an implementer
+ */
+export async function createWorktree(repoPath, implName) {
+    const gitRoot = await getGitRoot(repoPath);
+    const worktreeBase = path.join(gitRoot, LOCKSTEP_WORKTREE_DIR);
+    const worktreePath = path.join(worktreeBase, implName);
+    const branchName = `lockstep/${implName}`;
+    // Ensure the worktree directory exists
+    await fs.mkdir(worktreeBase, { recursive: true });
+    // Check if worktree already exists
+    try {
+        await fs.access(worktreePath);
+        // Worktree exists, clean it up first
+        await removeWorktree(worktreePath);
+    }
+    catch {
+        // Doesn't exist, that's fine
+    }
+    // Get current HEAD to branch from
+    const { stdout: currentHead } = await exec("git rev-parse HEAD", { cwd: gitRoot });
+    const headCommit = currentHead.trim();
+    // Delete branch if it exists (from previous run)
+    try {
+        await exec(`git branch -D "${branchName}"`, { cwd: gitRoot });
+    }
+    catch {
+        // Branch doesn't exist, that's fine
+    }
+    // Create the worktree with a new branch
+    await exec(`git worktree add -b "${branchName}" "${worktreePath}" "${headCommit}"`, { cwd: gitRoot });
+    return { worktreePath, branchName };
+}
+/**
+ * Remove a git worktree and its branch
+ */
+export async function removeWorktree(worktreePath) {
+    try {
+        // Get the branch name before removing
+        const { stdout: branchOutput } = await exec("git rev-parse --abbrev-ref HEAD", { cwd: worktreePath });
+        const branchName = branchOutput.trim();
+        // Get the main repo path
+        const { stdout: gitDirOutput } = await exec("git rev-parse --git-common-dir", { cwd: worktreePath });
+        const gitCommonDir = gitDirOutput.trim();
+        const mainRepoPath = path.dirname(gitCommonDir);
+        // Remove the worktree
+        await exec(`git worktree remove --force "${worktreePath}"`, { cwd: mainRepoPath });
+        // Delete the branch if it starts with lockstep/
+        if (branchName.startsWith("lockstep/")) {
+            try {
+                await exec(`git branch -D "${branchName}"`, { cwd: mainRepoPath });
+            }
+            catch {
+                // Branch might not exist or be the current branch
+            }
+        }
+    }
+    catch (error) {
+        // Fallback: just try to prune and remove directory
+        try {
+            const gitRoot = await getGitRoot(path.dirname(worktreePath));
+            await exec("git worktree prune", { cwd: gitRoot });
+            await fs.rm(worktreePath, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort cleanup
+        }
+    }
+}
+/**
+ * Get the status of a worktree (commits ahead/behind, uncommitted changes)
+ */
+export async function getWorktreeStatus(worktreePath) {
+    // Fetch latest from remote (silently)
+    try {
+        await exec("git fetch origin", { cwd: worktreePath, timeout: 10000 });
+    }
+    catch {
+        // Ignore fetch errors (might be offline)
+    }
+    // Get the main branch (usually main or master)
+    let mainBranch = "main";
+    try {
+        const { stdout } = await exec("git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo 'refs/remotes/origin/main'", { cwd: worktreePath });
+        mainBranch = stdout.trim().replace("refs/remotes/origin/", "");
+    }
+    catch {
+        // Default to main
+    }
+    // Count commits ahead/behind
+    let ahead = 0;
+    let behind = 0;
+    try {
+        const { stdout: aheadOutput } = await exec(`git rev-list --count origin/${mainBranch}..HEAD`, { cwd: worktreePath });
+        ahead = parseInt(aheadOutput.trim(), 10) || 0;
+        const { stdout: behindOutput } = await exec(`git rev-list --count HEAD..origin/${mainBranch}`, { cwd: worktreePath });
+        behind = parseInt(behindOutput.trim(), 10) || 0;
+    }
+    catch {
+        // Ignore errors (might be no remote)
+    }
+    // Get modified files
+    const { stdout: statusOutput } = await exec("git status --porcelain", { cwd: worktreePath });
+    const lines = statusOutput.trim().split("\n").filter(Boolean);
+    const modifiedFiles = [];
+    const untrackedFiles = [];
+    for (const line of lines) {
+        const status = line.substring(0, 2);
+        const file = line.substring(3);
+        if (status.includes("?")) {
+            untrackedFiles.push(file);
+        }
+        else {
+            modifiedFiles.push(file);
+        }
+    }
+    return {
+        ahead,
+        behind,
+        hasUncommittedChanges: modifiedFiles.length > 0 || untrackedFiles.length > 0,
+        modifiedFiles,
+        untrackedFiles,
+    };
+}
+/**
+ * Commit all changes in a worktree
+ */
+export async function commitWorktreeChanges(worktreePath, message, author) {
+    try {
+        // Stage all changes
+        await exec("git add -A", { cwd: worktreePath });
+        // Check if there's anything to commit
+        const { stdout: statusOutput } = await exec("git status --porcelain", { cwd: worktreePath });
+        if (!statusOutput.trim()) {
+            return { success: true }; // Nothing to commit
+        }
+        // Commit
+        const fullMessage = `${message}\n\nImplementer: ${author}`;
+        await exec(`git commit -m "${fullMessage.replace(/"/g, '\\"')}"`, { cwd: worktreePath });
+        // Get the commit hash
+        const { stdout: hashOutput } = await exec("git rev-parse HEAD", { cwd: worktreePath });
+        return { success: true, commitHash: hashOutput.trim() };
+    }
+    catch (error) {
+        const err = error;
+        return { success: false, error: err.message };
+    }
+}
+/**
+ * Attempt to merge a worktree's changes back to main
+ */
+export async function mergeWorktree(worktreePath, targetBranch) {
+    try {
+        // Get the git root
+        const { stdout: gitDirOutput } = await exec("git rev-parse --git-common-dir", { cwd: worktreePath });
+        const gitCommonDir = gitDirOutput.trim();
+        const mainRepoPath = path.dirname(gitCommonDir);
+        // Get the worktree branch
+        const { stdout: branchOutput } = await exec("git rev-parse --abbrev-ref HEAD", { cwd: worktreePath });
+        const worktreeBranch = branchOutput.trim();
+        // Determine target branch
+        if (!targetBranch) {
+            try {
+                const { stdout } = await exec("git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo 'refs/remotes/origin/main'", { cwd: mainRepoPath });
+                targetBranch = stdout.trim().replace("refs/remotes/origin/", "");
+            }
+            catch {
+                targetBranch = "main";
+            }
+        }
+        // Commit any uncommitted changes first
+        const status = await getWorktreeStatus(worktreePath);
+        if (status.hasUncommittedChanges) {
+            await commitWorktreeChanges(worktreePath, "WIP: Uncommitted changes before merge", "lockstep");
+        }
+        // Check if there's anything to merge
+        const { stdout: diffOutput } = await exec(`git diff ${targetBranch}..${worktreeBranch} --stat`, { cwd: mainRepoPath });
+        if (!diffOutput.trim()) {
+            return { success: true, merged: false }; // Nothing to merge
+        }
+        // Try to rebase onto target branch first (cleaner history)
+        try {
+            await exec(`git -C "${worktreePath}" rebase origin/${targetBranch}`, { cwd: mainRepoPath });
+        }
+        catch {
+            // Rebase failed, abort it
+            try {
+                await exec(`git -C "${worktreePath}" rebase --abort`, { cwd: mainRepoPath });
+            }
+            catch {
+                // Ignore
+            }
+        }
+        // Switch to target branch and merge
+        const currentBranch = await getCurrentBranch(mainRepoPath);
+        try {
+            await exec(`git checkout ${targetBranch}`, { cwd: mainRepoPath });
+            await exec(`git merge --no-ff ${worktreeBranch} -m "Merge ${worktreeBranch}"`, { cwd: mainRepoPath });
+            return { success: true, merged: true };
+        }
+        catch (error) {
+            // Merge conflict - get the conflicting files
+            const { stdout: conflictOutput } = await exec("git diff --name-only --diff-filter=U", { cwd: mainRepoPath });
+            const conflicts = conflictOutput.trim().split("\n").filter(Boolean);
+            // Abort the merge
+            await exec("git merge --abort", { cwd: mainRepoPath });
+            // Switch back to original branch
+            await exec(`git checkout ${currentBranch}`, { cwd: mainRepoPath });
+            return { success: false, merged: false, conflicts };
+        }
+    }
+    catch (error) {
+        const err = error;
+        return { success: false, merged: false, error: err.message };
+    }
+}
+/**
+ * List all lockstep worktrees
+ */
+export async function listWorktrees(repoPath) {
+    try {
+        const gitRoot = await getGitRoot(repoPath);
+        const { stdout } = await exec("git worktree list --porcelain", { cwd: gitRoot });
+        const worktrees = [];
+        const lines = stdout.trim().split("\n");
+        let current = {};
+        for (const line of lines) {
+            if (line.startsWith("worktree ")) {
+                current.path = line.substring(9);
+            }
+            else if (line.startsWith("HEAD ")) {
+                current.head = line.substring(5);
+            }
+            else if (line.startsWith("branch ")) {
+                current.branchName = line.substring(7).replace("refs/heads/", "");
+            }
+            else if (line === "") {
+                if (current.path && current.branchName?.startsWith("lockstep/")) {
+                    worktrees.push(current);
+                }
+                current = {};
+            }
+        }
+        // Don't forget the last one
+        if (current.path && current.branchName?.startsWith("lockstep/")) {
+            worktrees.push(current);
+        }
+        return worktrees;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Clean up orphaned worktrees (those without matching implementers)
+ */
+export async function cleanupOrphanedWorktrees(repoPath) {
+    const cleaned = [];
+    try {
+        const gitRoot = await getGitRoot(repoPath);
+        // Prune stale worktree references
+        await exec("git worktree prune", { cwd: gitRoot });
+        // Get remaining worktrees
+        const worktrees = await listWorktrees(repoPath);
+        // Check which directories still exist
+        for (const wt of worktrees) {
+            try {
+                await fs.access(wt.path);
+            }
+            catch {
+                // Directory doesn't exist, clean up the reference
+                try {
+                    await exec(`git worktree remove --force "${wt.path}"`, { cwd: gitRoot });
+                    cleaned.push(wt.path);
+                }
+                catch {
+                    // Ignore errors
+                }
+            }
+        }
+        // Also clean up the lockstep branches that don't have worktrees
+        const { stdout: branchOutput } = await exec("git branch --list 'lockstep/*'", { cwd: gitRoot });
+        const branches = branchOutput.trim().split("\n").filter(Boolean).map(b => b.trim().replace("* ", ""));
+        for (const branch of branches) {
+            const hasWorktree = worktrees.some(wt => wt.branchName === branch);
+            if (!hasWorktree) {
+                try {
+                    await exec(`git branch -D "${branch}"`, { cwd: gitRoot });
+                }
+                catch {
+                    // Ignore errors
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return cleaned;
+}
+/**
+ * Get diff between worktree and main branch
+ */
+export async function getWorktreeDiff(worktreePath) {
+    try {
+        // Get the main branch
+        let mainBranch = "main";
+        try {
+            const { stdout } = await exec("git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo 'refs/remotes/origin/main'", { cwd: worktreePath });
+            mainBranch = stdout.trim().replace("refs/remotes/origin/", "");
+        }
+        catch {
+            // Default to main
+        }
+        const { stdout } = await exec(`git diff origin/${mainBranch}...HEAD --stat`, { cwd: worktreePath });
+        return stdout;
+    }
+    catch {
+        return "";
+    }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "lockstep-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP coordination server for multi-agent workflows",
+  "type": "module",
+  "main": "dist/cli.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "lockstep-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "node --import tsx src/cli.ts server",
+    "start": "node dist/cli.js server",
+    "dashboard": "node dist/cli.js dashboard",
+    "prompts": "node dist/cli.js prompts",
+    "install:mcp": "node --import tsx src/cli.ts install",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "coordination",
+    "orchestration",
+    "automation",
+    "cli"
+  ],
+  "author": "Tim Moore",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tmmoore286/lockstep-mcp.git"
+  },
+  "homepage": "https://github.com/Tmmoore286/lockstep-mcp",
+  "bugs": {
+    "url": "https://github.com/Tmmoore286/lockstep-mcp/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "better-sqlite3": "^11.10.0",
+    "tsx": "^4.21.0",
+    "ws": "^8.18.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.9",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}