lockstep-mcp 0.1.0

package/dist/install.js

@@ -0,0 +1,252 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+function expandHome(input) {
+    if (!input.startsWith("~"))
+        return input;
+    const home = os.homedir();
+    return path.join(home, input.slice(1));
+}
+function getClaudeConfigPath() {
+    // Claude Code uses project-level .mcp.json or we create in home
+    const localConfig = path.resolve(process.cwd(), ".mcp.json");
+    if (fs.existsSync(localConfig))
+        return localConfig;
+    return localConfig; // Default to creating in current directory
+}
+function getCodexConfigPath() {
+    return path.join(os.homedir(), ".codex", "config.toml");
+}
+function resolveConfigPath(configPath) {
+    if (configPath)
+        return path.resolve(expandHome(configPath));
+    const localConfig = path.resolve(process.cwd(), ".mcp.json");
+    if (fs.existsSync(localConfig))
+        return localConfig;
+    return undefined;
+}
+function loadJsonConfig(configPath) {
+    if (!fs.existsSync(configPath)) {
+        return { mcpServers: {} };
+    }
+    const raw = fs.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.mcpServers || typeof parsed.mcpServers !== "object") {
+        parsed.mcpServers = {};
+    }
+    return parsed;
+}
+function resolveServerEntry() {
+    const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const distCli = path.join(repoRoot, "dist", "cli.js");
+    const srcCli = path.join(repoRoot, "src", "cli.ts");
+    if (fs.existsSync(distCli)) {
+        return { command: "node", args: [distCli, "server"], distCli };
+    }
+    return { command: "node", args: ["--import", "tsx", srcCli, "server"], distCli };
+}
+function getNodePath() {
+    // Try to find node in common locations
+    const candidates = [
+        "/opt/homebrew/bin/node",
+        "/usr/local/bin/node",
+        "/usr/bin/node",
+        process.execPath,
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return "node";
+}
+function buildServerArgs(options) {
+    const entry = resolveServerEntry();
+    const args = [...entry.args];
+    if (options.mode) {
+        args.push("--mode", options.mode);
+    }
+    if (options.roots) {
+        args.push("--roots", options.roots);
+    }
+    if (options.dataDir) {
+        args.push("--data-dir", options.dataDir);
+    }
+    if (options.logDir) {
+        args.push("--log-dir", options.logDir);
+    }
+    if (options.storage) {
+        args.push("--storage", options.storage);
+    }
+    if (options.dbPath) {
+        args.push("--db-path", options.dbPath);
+    }
+    if (options.commandMode) {
+        args.push("--command-mode", options.commandMode);
+    }
+    if (options.commandAllow) {
+        args.push("--command-allow", options.commandAllow);
+    }
+    return args;
+}
+// Install to Claude's .mcp.json
+function installToClaude(options) {
+    const configPath = options.configPath ? expandHome(options.configPath) : getClaudeConfigPath();
+    const config = loadJsonConfig(configPath);
+    const entryName = options.name ?? "lockstep";
+    const entry = resolveServerEntry();
+    const args = buildServerArgs(options);
+    config.mcpServers[entryName] = {
+        command: getNodePath(),
+        args: args.slice(1), // Remove 'node' from args since command is node
+    };
+    // Ensure directory exists
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    return { configPath, name: entryName };
+}
+// Install to Codex's config.toml
+function installToCodex(options) {
+    const configPath = getCodexConfigPath();
+    const entryName = options.name ?? "lockstep";
+    const entry = resolveServerEntry();
+    const args = buildServerArgs(options);
+    // Ensure directory exists
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Read existing config or create new
+    let existingContent = "";
+    if (fs.existsSync(configPath)) {
+        existingContent = fs.readFileSync(configPath, "utf8");
+    }
+    // Check if entry already exists
+    const sectionRegex = new RegExp(`\\[mcp_servers\\.${entryName}\\]`);
+    if (sectionRegex.test(existingContent)) {
+        // Update existing entry - remove old section first
+        const sectionStart = existingContent.search(sectionRegex);
+        const nextSectionMatch = existingContent.slice(sectionStart + 1).search(/\n\[/);
+        const sectionEnd = nextSectionMatch === -1
+            ? existingContent.length
+            : sectionStart + 1 + nextSectionMatch;
+        existingContent = existingContent.slice(0, sectionStart) + existingContent.slice(sectionEnd);
+    }
+    // Build TOML entry
+    const nodePath = getNodePath();
+    const argsWithoutNode = args.slice(1); // Remove 'node' since command handles it
+    const argsToml = argsWithoutNode.map(a => `"${a}"`).join(", ");
+    const tomlEntry = `
+[mcp_servers.${entryName}]
+command = "${nodePath}"
+args = [${argsToml}]
+env = { }
+`;
+    // Append to config
+    const newContent = existingContent.trim() + "\n" + tomlEntry;
+    fs.writeFileSync(configPath, newContent);
+    return { configPath, name: entryName };
+}
+// Uninstall from Claude's .mcp.json
+function uninstallFromClaude(name, configPath) {
+    const fullPath = configPath ? expandHome(configPath) : getClaudeConfigPath();
+    if (!fs.existsSync(fullPath))
+        return false;
+    const config = loadJsonConfig(fullPath);
+    if (!config.mcpServers[name])
+        return false;
+    delete config.mcpServers[name];
+    fs.writeFileSync(fullPath, JSON.stringify(config, null, 2));
+    return true;
+}
+// Uninstall from Codex's config.toml
+function uninstallFromCodex(name) {
+    const configPath = getCodexConfigPath();
+    if (!fs.existsSync(configPath))
+        return false;
+    let content = fs.readFileSync(configPath, "utf8");
+    const sectionRegex = new RegExp(`\\[mcp_servers\\.${name}\\]`);
+    if (!sectionRegex.test(content))
+        return false;
+    // Remove the section
+    const sectionStart = content.search(sectionRegex);
+    const nextSectionMatch = content.slice(sectionStart + 1).search(/\n\[/);
+    const sectionEnd = nextSectionMatch === -1
+        ? content.length
+        : sectionStart + 1 + nextSectionMatch;
+    content = content.slice(0, sectionStart) + content.slice(sectionEnd);
+    fs.writeFileSync(configPath, content.trim() + "\n");
+    return true;
+}
+export function installMcpEntry(options) {
+    const target = options.target ?? "config";
+    const results = [];
+    if (target === "config") {
+        // Legacy behavior: install to specified config path
+        const configPath = resolveConfigPath(options.configPath);
+        if (!configPath) {
+            throw new Error("Missing --config. Provide the MCP config path (or run from a repo with .mcp.json).");
+        }
+        const config = loadJsonConfig(configPath);
+        const entryName = options.name ?? "lockstep-mcp";
+        const entry = resolveServerEntry();
+        const args = buildServerArgs(options);
+        config.mcpServers[entryName] = {
+            command: entry.command,
+            args,
+        };
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+        return { configPath, name: entryName, serverPath: args.join(" ") };
+    }
+    if (target === "claude" || target === "all") {
+        const result = installToClaude(options);
+        results.push({ target: "claude", ...result });
+    }
+    if (target === "codex" || target === "all") {
+        const result = installToCodex(options);
+        results.push({ target: "codex", ...result });
+    }
+    return { results };
+}
+export function uninstallMcpEntry(options) {
+    const target = options.target ?? "all";
+    const name = options.name ?? "lockstep";
+    const results = [];
+    if (target === "claude" || target === "all") {
+        const removed = uninstallFromClaude(name, options.configPath);
+        results.push({ target: "claude", removed });
+    }
+    if (target === "codex" || target === "all") {
+        const removed = uninstallFromCodex(name);
+        results.push({ target: "codex", removed });
+    }
+    return { results };
+}
+export function getInstallStatus() {
+    const claudePath = getClaudeConfigPath();
+    const codexPath = getCodexConfigPath();
+    let claudeInstalled = false;
+    let codexInstalled = false;
+    if (fs.existsSync(claudePath)) {
+        try {
+            const config = loadJsonConfig(claudePath);
+            claudeInstalled = !!config.mcpServers["lockstep"] || !!config.mcpServers["lockstep-mcp"];
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (fs.existsSync(codexPath)) {
+        try {
+            const content = fs.readFileSync(codexPath, "utf8");
+            codexInstalled = /\[mcp_servers\.lockstep/.test(content);
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { claude: claudeInstalled, codex: codexInstalled, claudePath, codexPath };
+}

package/dist/macos.js

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { sleep } from "./utils.js";
+export async function launchMacos(options = {}) {
+    if (process.platform !== "darwin") {
+        throw new Error("macos launcher is only supported on macOS");
+    }
+    const repo = path.resolve(options.repo ?? process.cwd());
+    const claudeCmd = options.claudeCmd ?? "claude";
+    const codexCmd = options.codexCmd ?? "codex";
+    const dashboardHost = options.dashboardHost ?? "127.0.0.1";
+    const dashboardPort = options.dashboardPort ?? 8787;
+    const macosPath = path.resolve(fileURLToPath(import.meta.url));
+    const baseDir = path.dirname(macosPath);
+    const nodePath = process.execPath;
+    const cliPath = macosPath.endsWith(".ts")
+        ? path.join(baseDir, "cli.ts")
+        : path.join(baseDir, "cli.js");
+    const dashboardArgs = ["dashboard", "--host", dashboardHost, "--port", String(dashboardPort)];
+    const dashboardCmd = cliPath.endsWith(".ts")
+        ? `${nodePath} --import tsx ${cliPath} ${dashboardArgs.join(" ")}`
+        : `${nodePath} ${cliPath} ${dashboardArgs.join(" ")}`;
+    const commands = [
+        `cd "${repo}" && ${claudeCmd}`,
+        `cd "${repo}" && ${codexCmd}`,
+        dashboardCmd,
+    ];
+    for (const command of commands) {
+        const openResult = spawnSync("open", ["-na", "Terminal"]);
+        if (openResult.status !== 0) {
+            throw new Error("Failed to open Terminal window");
+        }
+        const escaped = command.replace(/\"/g, "\\\"");
+        const script = `tell application \"Terminal\" to do script \"${escaped}\"`;
+        let success = false;
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+            await sleep(500);
+            if (process.env.LOCKSTEP_DEBUG) {
+                process.stderr.write(`osascript: ${script}\n`);
+            }
+            const result = spawnSync("osascript", ["-e", script], { encoding: "utf8" });
+            if (result.status === 0) {
+                success = true;
+                break;
+            }
+            if (result.stderr) {
+                process.stderr.write(result.stderr);
+            }
+        }
+        if (!success) {
+            throw new Error("Failed to run command in Terminal window");
+        }
+    }
+}

package/dist/prompts.js

@@ -0,0 +1,173 @@
+export function getPlannerPrompt() {
+    return `You are the PLANNER for this lockstep coordination session.
+
+⛔ ABSOLUTE PROHIBITIONS - VIOLATING THESE IS A CRITICAL FAILURE:
+- NEVER use file write/edit/update tools - you are NOT allowed to modify files
+- NEVER run build commands (pnpm build, npm build, tsc, etc.)
+- NEVER run test commands (pnpm test, npm test, vitest, jest, etc.)
+- NEVER fix code errors yourself - CREATE A TASK for an implementer
+- NEVER create/modify source files (.ts, .tsx, .js, .jsx, .swift, etc.)
+- If you catch yourself about to edit a file - STOP and create a task instead
+
+YOUR ONLY ALLOWED ACTIONS:
+1. Call lockstep_mcp tools (coordination_init, task_create, task_list, etc.)
+2. Read files to understand the codebase (READ ONLY, never write)
+3. Communicate with the user
+4. Launch implementers with launch_implementer
+5. Review and approve/reject tasks submitted by implementers
+
+If you see a bug, build error, or code issue:
+→ DO NOT FIX IT YOURSELF
+→ CREATE A TASK with task_create and assign appropriate complexity
+→ LAUNCH AN IMPLEMENTER if none are active
+
+TASK COMPLEXITY - Set appropriately when creating tasks:
+- SIMPLE: 1-2 files, obvious fix, no architectural decisions
+- MEDIUM: 3-5 files, some ambiguity, needs verification
+- COMPLEX: 6+ files, architectural decisions, cross-system impact
+- CRITICAL: Database schema, security, affects other products (REQUIRES your approval)
+
+TASK ISOLATION - Choose based on task nature:
+- SHARED (default): Implementer works in main directory with file locks. Good for simple/medium tasks.
+- WORKTREE: Implementer gets isolated git worktree with own branch. Use for:
+  - Complex refactoring that touches many files
+  - Parallel independent features
+  - Changes that might conflict with other implementers
+  - When you want clean git history per feature
+
+When using worktree isolation:
+- Use worktree_status to check implementer's progress (commits, changes)
+- Use worktree_merge to merge their changes after approval
+- If merge has conflicts, use task_request_changes to have implementer resolve
+
+INITIALIZATION:
+1. Call coordination_init({ role: "planner" }) to check project state
+2. Follow the instructions in the response EXACTLY
+
+PHASE 1 (gather_info):
+If no project context exists:
+1. ASK: "What project or task are we working on today?"
+2. EXPLORE: Read README.md, package.json, CLAUDE.md to understand the codebase
+3. SUMMARIZE: Tell user what you found about the project
+4. ASK CLARIFYING QUESTIONS for anything missing:
+   - What is the desired end state/goal?
+   - Any specific requirements or constraints?
+   - What are the acceptance criteria?
+   - What tests should pass?
+   - What type of implementer - Claude or Codex?
+5. SAVE: Call project_context_set with combined info
+
+PHASE 2 (create_plan):
+- Create implementation plan based on user's answers
+- EXPLAIN the plan to the user (steps, reasoning, trade-offs)
+- ASK for feedback: "Any additional context or changes needed?"
+- ASK for permission: "Do I have your permission to proceed?"
+- ONLY AFTER user approves: call project_context_set with implementationPlan
+- Set status to "ready"
+
+PHASE 3 (create_tasks):
+- Create tasks using task_create with COMPLEXITY field (required!)
+- Use launch_implementer to spawn workers (type based on user's preference)
+- 1-2 implementers for simple projects, more for complex
+
+PHASE 4 (monitor and review):
+⚠️ FIRST: Check implementer_list - if NO active implementers, call launch_implementer IMMEDIATELY
+- Check task_list FREQUENTLY - look for tasks in "review" status
+- Check note_list for [REVIEW] notifications
+- Check discussion_inbox({ agent: "planner" }) for discussions
+- If tasks exist but no implementers are working, LAUNCH AN IMPLEMENTER
+
+REVIEWING TASKS (critical responsibility):
+When a task is in "review" status:
+1. Read the task's reviewNotes to see what the implementer did
+2. Consider: Does this fit the big picture? Will it work with other changes?
+3. If good: task_approve({ id: "task-id", feedback: "optional notes" })
+4. If needs work: task_request_changes({ id: "task-id", feedback: "what to fix" })
+
+COORDINATION RESPONSIBILITIES:
+- When implementers start COMPLEX/CRITICAL tasks, they should discuss with you first
+- Respond promptly to discussion_inbox items
+- Verify changes won't conflict with other implementers' work
+- Keep the big picture in mind - individual tasks must fit together
+
+DISCUSSIONS:
+When you need implementer input on architectural/implementation decisions:
+- discussion_start({ topic, message, author: "planner", waitingOn: "impl-1" })
+- Check discussion_inbox periodically for replies
+- discussion_resolve when a decision is reached
+
+Use project_status_set with "complete" when ALL work is done, "stopped" to halt`;
+}
+export function getImplementerPrompt() {
+    return `You are an IMPLEMENTER for this lockstep coordination session.
+
+INITIALIZATION:
+1. Call coordination_init({ role: "implementer" }) to get your name and instructions
+2. Follow the continuous work loop
+
+TASK COMPLEXITY PROTOCOL:
+When you claim a task, check its complexity field and follow the appropriate protocol:
+
+| Complexity | Before Starting | While Working | On Completion |
+|------------|-----------------|---------------|---------------|
+| SIMPLE     | Start immediately | Work independently | Mark done directly |
+| MEDIUM     | Brief review of approach | Work, note concerns | Submit for review |
+| COMPLEX    | Discuss approach with planner | Checkpoint mid-task | Submit for review, await approval |
+| CRITICAL   | MUST get planner approval first | Verify each step | Submit for review, WAIT for approval |
+
+CONTINUOUS WORK LOOP:
+1. Call task_list to see available tasks and check projectStatus
+2. Call discussion_inbox({ agent: "YOUR_NAME" }) to check for discussions/feedback
+3. If projectStatus is "stopped" or "complete" -> STOP working
+4. If discussions waiting on you -> respond with discussion_reply
+5. Check if any tasks in "review" status got feedback from planner
+6. If tasks available, call task_claim to take a "todo" task
+7. Read the complexity and follow the protocol above
+8. Call lock_acquire before editing any file
+9. Do the work
+10. Call lock_release when done with file
+11. Based on complexity:
+    - SIMPLE: task_update to mark "done"
+    - MEDIUM/COMPLEX/CRITICAL: task_submit_for_review with notes on what you did
+12. REPEAT from step 1
+
+WHEN TO DISCUSS WITH PLANNER:
+- ALWAYS for critical tasks before starting
+- When the task description is ambiguous
+- When you discover the scope is larger than expected
+- When your changes might affect other parts of the system
+- When you're unsure about architectural decisions
+
+HOW TO SUBMIT FOR REVIEW:
+task_submit_for_review({
+  id: "task-id",
+  owner: "your-name",
+  reviewNotes: "Summary: modified X files. Approach: used Y pattern. Notes: ..."
+})
+
+WORKTREE MODE:
+If you are told you're working in a worktree (isolated branch):
+- Your changes are on your own branch, not affecting others
+- You don't need file locks (lock_acquire/lock_release) - you have full isolation
+- Commit your changes frequently with clear messages
+- When done, submit_for_review - planner will use worktree_merge to merge your changes
+- If there are merge conflicts, planner will request changes for you to resolve
+
+IMPORTANT:
+- Keep working until all tasks are done or project is stopped
+- Do NOT wait for user input between tasks
+- For complex/critical tasks, coordination with planner is REQUIRED`;
+}
+export function getAutopilotPrompts() {
+    return `Lockstep MCP Coordination Prompts
+=====================================
+
+PLANNER PROMPT:
+${getPlannerPrompt()}
+
+=====================================
+
+IMPLEMENTER PROMPT:
+${getImplementerPrompt()}
+`;
+}