xcode-build-queue 0.1.0

package/README.md

@@ -0,0 +1,266 @@
+# xbq — Xcode Build Queue
+
+Serial build queue for Xcode projects with git worktrees.
+
+## Problem
+
+Running multiple Claude Code sessions on the same Xcode project requires separate repos, each needing its own SPM resolution and DerivedData (~8GB+ per copy). This tool eliminates that duplication by routing all builds through a single "main" repo.
+
+## How It Works
+
+```
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│ Claude Code  │  │ Claude Code  │  │ Claude Code  │
+│ (worktree A) │  │ (worktree B) │  │ (worktree C) │
+└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
+       │ snapshot          │ snapshot          │ snapshot
+       └──────────────────┼──────────────────┘
+                          ▼
+               ┌────────────────────┐
+               │  xbq (serial queue) │
+               │                    │
+               │ checkout snapshot  │
+               │ (detached HEAD)    │
+               │ build/test via     │
+               │ Xcode MCP or       │
+               │ xcodebuild         │
+               └────────┬───────────┘
+                        ▼
+                  ┌───────────┐
+                  │ Main Repo  │  ← single DerivedData
+                  │ (warm)     │  ← SPM already resolved
+                  └───────────┘
+```
+
+- Claude Code sessions edit code in lightweight git worktrees (code only, no builds)
+- When they need to build/test, they run `xbq build` or `xbq test`
+- `xbq` creates a snapshot commit of all changes and checks it out via detached HEAD in the main repo
+- Jobs run serially to prevent DerivedData corruption
+- Results are returned to the requesting session
+- Each worktree gets a `CLAUDE.md` that tells Claude Code to use `xbq`
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g xbq
+```
+
+### From GitHub
+
+```bash
+npm install -g github:a-ulkhan/xbq
+```
+
+### From source
+
+```bash
+git clone https://github.com/a-ulkhan/xbq.git
+cd xbq
+make install
+```
+
+## Setup
+
+```bash
+# Configure (point to your main Xcode repo)
+xbq init ~/path/to/your/project
+
+# Start the daemon
+xbq daemon start
+```
+
+### Optional: `git-restore-mtime`
+
+For best incremental build performance after branch switches:
+
+```bash
+pip3 install git-restore-mtime
+```
+
+## Quick Start
+
+### Start a new parallel session
+
+```bash
+# Create a worktree + launch Claude Code (all-in-one)
+xbq session my-feature
+
+# Or create worktree only (e.g. to open in a new terminal)
+xbq worktree new my-feature
+
+# Auto-named session (timestamp-based)
+xbq session
+```
+
+`xbq session` / `xbq worktree new`:
+1. Creates a git worktree branching from the default branch
+2. Auto-injects `xbq` instructions into the worktree's `CLAUDE.md`
+3. Optionally launches Claude Code in the worktree
+
+### Build and test from a worktree
+
+```bash
+# Build (changes are captured automatically via diff — no commit needed)
+xbq build
+
+# Run tests
+xbq test
+
+# With specific destination
+xbq build --destination "platform=iOS Simulator,name=iPhone 16,OS=26.2"
+
+# Specific scheme/test plan
+xbq test --scheme MyScheme --test-plan All
+
+# Force xcodebuild backend
+xbq build --backend xcodebuild
+
+# Legacy branch mode (for pushed branches)
+xbq build --branch feature/my-branch
+```
+
+## Worktree Management
+
+```bash
+# List all worktrees
+xbq worktree list
+
+# Clean up merged and stale worktrees (>7 days, no uncommitted changes)
+xbq worktree clean
+
+# Force remove all non-main worktrees
+xbq worktree clean --force
+
+# Custom age threshold
+xbq worktree clean --days 3
+```
+
+### Cleanup rules
+
+| Condition | Action |
+|-----------|--------|
+| Branch merged into default branch | Removed automatically |
+| Stale (>7d) with no uncommitted changes | Removed automatically |
+| Active with uncommitted work | Kept (unless `--force`) |
+
+Tip: add to crontab for automatic cleanup:
+```bash
+0 9 * * * xbq worktree clean
+```
+
+## Claude Code Integration
+
+Every worktree created by `xbq` gets a `CLAUDE.md` that instructs Claude Code to:
+
+- **NEVER** run `xcodebuild` directly in the worktree
+- **NEVER** use Xcode MCP build/test tools directly
+- **ALWAYS** use `xbq build` / `xbq test` (changes are captured automatically)
+
+This is automatic — no manual setup needed per session.
+
+To manually manage the Claude integration:
+
+```bash
+# Inject xbq instructions into an existing project's CLAUDE.md
+xbq setup-claude /path/to/worktree
+
+# Remove xbq instructions
+xbq setup-claude --remove /path/to/worktree
+```
+
+The injection is idempotent (safe to run multiple times) and uses HTML markers to update in place.
+
+## Queue Management
+
+```bash
+# Check daemon and queue status
+xbq status
+
+# View recent job results
+xbq logs
+
+# View a specific job's full log
+xbq logs 20260323-101530-abc123
+
+# Clean old results and logs (default: 7 days)
+xbq clean
+```
+
+## Daemon
+
+```bash
+xbq daemon start      # Start in background
+xbq daemon stop       # Stop
+xbq daemon status     # Check status + queue info
+xbq daemon start -f   # Foreground (for debugging)
+```
+
+The daemon auto-starts when you enqueue a job if it's not already running.
+
+## Backends
+
+### Xcode MCP (default)
+
+Uses Xcode 26.3+'s native MCP server (`xcrun mcpbridge`). Requires Xcode to be running with the project open. Provides richer diagnostics.
+
+### xcodebuild (fallback)
+
+Standard CLI build tool. Works headless, no Xcode GUI needed. Auto-selected when mcpbridge is unavailable.
+
+If MCP fails, `xbq` automatically falls back to xcodebuild (configurable).
+
+## Configuration
+
+Stored at `~/.bq/config.json`:
+
+```json
+{
+  "main_repo": "~/path/to/your/project",
+  "workspace": "MyApp.xcworkspace",
+  "default_scheme": "MyApp",
+  "default_test_plan": "",
+  "default_destination": "platform=iOS Simulator,name=iPhone 16",
+  "backend": "mcp",
+  "xcodebuild_fallback": true,
+  "git_restore_mtime": true
+}
+```
+
+Workspace and scheme are auto-detected during `xbq init`.
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `xbq init [path]` | First-time setup — set main repo path |
+| `xbq session [name]` | Create worktree + start Claude Code |
+| `xbq worktree new [name]` | Create a new worktree |
+| `xbq worktree list` | List all worktrees |
+| `xbq worktree clean` | Remove merged/stale worktrees |
+| `xbq build` | Enqueue a build job |
+| `xbq test` | Enqueue a test job |
+| `xbq status` | Show daemon + queue status |
+| `xbq logs [job-id]` | View build logs / recent results |
+| `xbq daemon start\|stop\|status` | Manage the queue daemon |
+| `xbq setup-claude [dir]` | Inject/update xbq instructions in CLAUDE.md |
+| `xbq clean` | Clean old results and logs |
+
+### Common flags
+
+| Flag | Commands | Description |
+|------|----------|-------------|
+| `-b, --branch <branch>` | build, test | Branch to build (optional in worktree) |
+| `-s, --scheme <scheme>` | build, test | Xcode scheme override |
+| `-d, --destination <dest>` | build, test | Simulator destination |
+| `-t, --test-plan <plan>` | test | Test plan name |
+| `--backend <backend>` | build, test | Force mcp or xcodebuild |
+| `--timeout <seconds>` | build, test | Job timeout (default: 1800) |
+
+## Requirements
+
+- Node.js >= 18
+- Xcode 26.3+ (for MCP backend) or any Xcode (for xcodebuild backend)
+- git
+- Optional: `git-restore-mtime` (`pip3 install git-restore-mtime`)

package/dist/backends/mcp.d.ts

@@ -0,0 +1,5 @@
+import { type Job, type JobResult } from "../types.js";
+/**
+ * Execute a build/test job using Xcode MCP.
+ */
+export declare function executeWithMCP(job: Job, repoPath: string, workspace: string): Promise<JobResult>;

package/dist/backends/mcp.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWithMCP = executeWithMCP;
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const utils_js_1 = require("../utils.js");
+/**
+ * Minimal MCP client that talks to Xcode's mcpbridge via JSON-RPC over stdio.
+ */
+class MCPClient {
+    process = null;
+    requestId = 0;
+    pending = new Map();
+    buffer = "";
+    async connect() {
+        return new Promise((resolve, reject) => {
+            try {
+                this.process = (0, node_child_process_1.spawn)("xcrun", ["mcpbridge"], {
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+            }
+            catch (err) {
+                reject(new Error(`Failed to spawn mcpbridge: ${err}`));
+                return;
+            }
+            this.process.stdout?.on("data", (data) => {
+                this.buffer += data.toString();
+                this.processBuffer();
+            });
+            this.process.stderr?.on("data", (data) => {
+                const msg = data.toString().trim();
+                if (msg)
+                    utils_js_1.log.dim(`mcpbridge: ${msg}`);
+            });
+            this.process.on("error", (err) => {
+                reject(new Error(`mcpbridge error: ${err.message}`));
+            });
+            this.process.on("close", (code) => {
+                for (const [, { reject: r }] of this.pending) {
+                    r(new Error(`mcpbridge exited with code ${code}`));
+                }
+                this.pending.clear();
+            });
+            // Initialize MCP session
+            this.sendRequest("initialize", {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "xbq", version: "0.1.0" },
+            }).then(() => {
+                this.sendNotification("notifications/initialized", {});
+                resolve();
+            }).catch(reject);
+        });
+    }
+    processBuffer() {
+        // MCP uses Content-Length framed messages
+        while (true) {
+            const headerEnd = this.buffer.indexOf("\r\n\r\n");
+            if (headerEnd === -1)
+                break;
+            const header = this.buffer.slice(0, headerEnd);
+            const match = header.match(/Content-Length:\s*(\d+)/i);
+            if (!match) {
+                this.buffer = this.buffer.slice(headerEnd + 4);
+                continue;
+            }
+            const contentLength = parseInt(match[1]);
+            const bodyStart = headerEnd + 4;
+            if (this.buffer.length < bodyStart + contentLength)
+                break;
+            const body = this.buffer.slice(bodyStart, bodyStart + contentLength);
+            this.buffer = this.buffer.slice(bodyStart + contentLength);
+            try {
+                const msg = JSON.parse(body);
+                if (msg.id !== undefined && this.pending.has(msg.id)) {
+                    const { resolve, reject } = this.pending.get(msg.id);
+                    this.pending.delete(msg.id);
+                    if (msg.error) {
+                        reject(new Error(`MCP error: ${msg.error.message || JSON.stringify(msg.error)}`));
+                    }
+                    else {
+                        resolve(msg.result);
+                    }
+                }
+            }
+            catch {
+                // Skip malformed messages
+            }
+        }
+    }
+    sendRaw(msg) {
+        const body = JSON.stringify(msg);
+        const frame = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+        this.process?.stdin?.write(frame);
+    }
+    sendRequest(method, params) {
+        const id = ++this.requestId;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`MCP request timed out: ${method}`));
+            }, 300_000); // 5 min timeout for builds
+            this.pending.set(id, {
+                resolve: (v) => { clearTimeout(timeout); resolve(v); },
+                reject: (e) => { clearTimeout(timeout); reject(e); },
+            });
+            this.sendRaw({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    sendNotification(method, params) {
+        this.sendRaw({ jsonrpc: "2.0", method, params });
+    }
+    async callTool(name, args) {
+        return this.sendRequest("tools/call", { name, arguments: args });
+    }
+    disconnect() {
+        this.process?.kill();
+        this.process = null;
+    }
+}
+/**
+ * Execute a build/test job using Xcode MCP.
+ */
+async function executeWithMCP(job, repoPath, workspace) {
+    const logPath = (0, node_path_1.join)(utils_js_1.BQ_LOGS_DIR, `${job.id}.log`);
+    const logStream = (0, node_fs_1.createWriteStream)(logPath, { flags: "a" });
+    const startTime = Date.now();
+    const appendLog = (msg) => {
+        logStream.write(msg + "\n");
+    };
+    const client = new MCPClient();
+    try {
+        utils_js_1.log.info("Connecting to Xcode MCP...");
+        await client.connect();
+        utils_js_1.log.ok("Connected to Xcode MCP");
+        let result;
+        if (job.action === "build") {
+            utils_js_1.log.info(`Building scheme: ${job.scheme}`);
+            appendLog(`[bq] Building scheme: ${job.scheme}`);
+            result = await client.callTool("build", {
+                scheme: job.scheme,
+                workspace: (0, node_path_1.join)(repoPath, workspace),
+                ...(job.destination ? { destination: job.destination } : {}),
+            });
+        }
+        else {
+            utils_js_1.log.info(`Testing scheme: ${job.scheme}, plan: ${job.test_plan || "default"}`);
+            appendLog(`[bq] Testing scheme: ${job.scheme}`);
+            result = await client.callTool("run_tests", {
+                scheme: job.scheme,
+                workspace: (0, node_path_1.join)(repoPath, workspace),
+                ...(job.test_plan ? { testPlan: job.test_plan } : {}),
+                ...(job.destination ? { destination: job.destination } : {}),
+            });
+        }
+        const duration = Math.round((Date.now() - startTime) / 1000);
+        appendLog(`[bq] Completed in ${duration}s`);
+        appendLog(JSON.stringify(result, null, 2));
+        // Parse MCP response
+        return parseMCPResult(job.id, result, duration, logPath);
+    }
+    catch (err) {
+        const duration = Math.round((Date.now() - startTime) / 1000);
+        const message = err instanceof Error ? err.message : String(err);
+        appendLog(`[bq] Error: ${message}`);
+        return {
+            id: job.id,
+            status: "error",
+            duration_seconds: duration,
+            summary: `MCP error: ${message}`,
+            failures: [],
+            build_errors: [message],
+            warnings: [],
+            log_path: logPath,
+        };
+    }
+    finally {
+        client.disconnect();
+        logStream.end();
+    }
+}
+function parseMCPResult(jobId, raw, duration, logPath) {
+    // MCP tool results come as { content: [{ type: "text", text: "..." }] }
+    const r = raw;
+    const text = r?.content?.map((c) => c.text).join("\n") || JSON.stringify(raw);
+    const failures = [];
+    const buildErrors = [];
+    const warnings = [];
+    for (const line of text.split("\n")) {
+        if (line.match(/error:/i))
+            buildErrors.push(line.trim());
+        else if (line.match(/Test Case .* failed/))
+            failures.push(line.trim());
+        else if (line.match(/warning:/i) && warnings.length < 20)
+            warnings.push(line.trim());
+    }
+    const hasError = buildErrors.length > 0 || failures.length > 0;
+    const testMatch = text.match(/Executed (\d+) tests?, with (\d+) failures?/);
+    let summary = "";
+    if (testMatch) {
+        const [, total, failed] = testMatch;
+        summary = `${parseInt(total) - parseInt(failed)}/${total} tests passed`;
+    }
+    else if (text.includes("BUILD SUCCEEDED") || text.includes("TEST SUCCEEDED")) {
+        summary = "Succeeded";
+    }
+    else if (hasError) {
+        summary = `${buildErrors.length} errors, ${failures.length} test failures`;
+    }
+    else {
+        summary = "Completed (check logs for details)";
+    }
+    return {
+        id: jobId,
+        status: hasError ? "failed" : "passed",
+        duration_seconds: duration,
+        summary,
+        failures,
+        build_errors: buildErrors,
+        warnings,
+        log_path: logPath,
+    };
+}

package/dist/backends/xcodebuild.d.ts

@@ -0,0 +1,5 @@
+import { type Job, type JobResult } from "../types.js";
+/**
+ * Execute a build/test job using xcodebuild.
+ */
+export declare function executeWithXcodebuild(job: Job, repoPath: string, workspace: string): Promise<JobResult>;

package/dist/backends/xcodebuild.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWithXcodebuild = executeWithXcodebuild;
+const node_path_1 = require("node:path");
+const utils_js_1 = require("../utils.js");
+/**
+ * Execute a build/test job using xcodebuild.
+ */
+async function executeWithXcodebuild(job, repoPath, workspace) {
+    const logPath = (0, node_path_1.join)(utils_js_1.BQ_LOGS_DIR, `${job.id}.log`);
+    const workspacePath = (0, node_path_1.join)(repoPath, workspace);
+    const startTime = Date.now();
+    const destination = job.destination || "platform=iOS Simulator,name=iPhone 16";
+    const args = [];
+    if (job.action === "test") {
+        args.push("test", "-workspace", workspacePath, "-scheme", job.scheme, "-destination", destination, "-resultBundlePath", (0, node_path_1.join)(utils_js_1.BQ_LOGS_DIR, `${job.id}.xcresult`));
+        if (job.test_plan) {
+            args.push("-testPlan", job.test_plan);
+        }
+    }
+    else {
+        args.push("build", "-workspace", workspacePath, "-scheme", job.scheme, "-destination", destination);
+    }
+    utils_js_1.log.info(`Running: xcodebuild ${args.slice(0, 3).join(" ")} ...`);
+    const failures = [];
+    const buildErrors = [];
+    const warnings = [];
+    const { exitCode, output } = await (0, utils_js_1.spawnWithLog)("xcodebuild", args, {
+        cwd: repoPath,
+        logPath,
+        onLine: (line) => {
+            if (line.includes("** BUILD FAILED **")) {
+                buildErrors.push("Build failed");
+            }
+            else if (line.includes("** TEST FAILED **")) {
+                // Will parse individual failures below
+            }
+            else if (line.includes("** BUILD SUCCEEDED **")) {
+                utils_js_1.log.ok("Build succeeded");
+            }
+            else if (line.includes("** TEST SUCCEEDED **")) {
+                utils_js_1.log.ok("Tests succeeded");
+            }
+            else if (line.match(/error:/i)) {
+                buildErrors.push(line.trim());
+            }
+            else if (line.match(/Test Case .* failed/)) {
+                failures.push(line.trim());
+            }
+            else if (line.match(/warning:/i) && warnings.length < 20) {
+                warnings.push(line.trim());
+            }
+        },
+    });
+    const duration = Math.round((Date.now() - startTime) / 1000);
+    // Parse test count from output
+    let summary = "";
+    const testSummary = output.match(/Executed (\d+) tests?, with (\d+) failures?/);
+    if (testSummary) {
+        const [, total, failed] = testSummary;
+        const passed = parseInt(total) - parseInt(failed);
+        summary = `${passed}/${total} tests passed`;
+        if (parseInt(failed) > 0) {
+            summary += ` (${failed} failed)`;
+        }
+    }
+    else if (exitCode === 0) {
+        summary = job.action === "test" ? "All tests passed" : "Build succeeded";
+    }
+    else {
+        summary = job.action === "test" ? "Tests failed" : "Build failed";
+    }
+    return {
+        id: job.id,
+        status: exitCode === 0 ? "passed" : "failed",
+        duration_seconds: duration,
+        summary,
+        failures,
+        build_errors: buildErrors,
+        warnings,
+        log_path: logPath,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};