xcode-build-queue 0.1.0

package/dist/enqueue.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enqueueAndWait = enqueueAndWait;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_js_1 = require("./config.js");
+const snapshot_js_1 = require("./snapshot.js");
+const utils_js_1 = require("./utils.js");
+/**
+ * Enqueue a job, wait for result, and return it.
+ */
+async function enqueueAndWait(opts) {
+    (0, utils_js_1.ensureDirs)();
+    const config = (0, config_js_1.loadConfig)();
+    // Ensure daemon is running
+    ensureDaemonRunning();
+    // Determine build strategy
+    const jobId = (0, utils_js_1.generateJobId)();
+    let branch = opts.branch;
+    let snapshotSha;
+    if (!branch) {
+        if ((0, snapshot_js_1.isInWorktree)()) {
+            snapshotSha = (0, snapshot_js_1.createSnapshot)();
+            utils_js_1.log.ok(`Snapshot: ${snapshotSha.slice(0, 8)}`);
+        }
+        else {
+            utils_js_1.log.error("Not in a worktree. Specify --branch or run from a worktree.");
+            process.exit(1);
+        }
+    }
+    // Create job
+    const job = {
+        id: jobId,
+        action: opts.action,
+        branch,
+        snapshot_sha: snapshotSha,
+        scheme: opts.scheme || config.default_scheme,
+        test_plan: opts.action === "test" ? (opts.testPlan || config.default_test_plan || undefined) : undefined,
+        destination: opts.destination || config.default_destination,
+        backend: opts.backend || config.backend,
+        submitted_at: new Date().toISOString(),
+        submitted_by: detectWorktreeName(),
+    };
+    // Write to queue
+    const jobFile = (0, node_path_1.join)(utils_js_1.BQ_QUEUE_DIR, `${job.id}.json`);
+    (0, node_fs_1.writeFileSync)(jobFile, JSON.stringify(job, null, 2) + "\n");
+    // Show queue position
+    const queueSize = (0, node_fs_1.readdirSync)(utils_js_1.BQ_QUEUE_DIR).filter(f => f.endsWith(".json")).length;
+    if (queueSize > 1) {
+        utils_js_1.log.status(`Queued (position: ${queueSize})`);
+    }
+    else {
+        utils_js_1.log.status("Queued (next up)");
+    }
+    // Wait for result
+    const timeout = opts.timeout || 1800; // 30 min
+    return waitForResult(job.id, timeout);
+}
+function ensureDaemonRunning() {
+    if ((0, node_fs_1.existsSync)(utils_js_1.BQ_PID_FILE)) {
+        const pid = parseInt((0, node_fs_1.readFileSync)(utils_js_1.BQ_PID_FILE, "utf-8").trim());
+        if ((0, utils_js_1.isProcessAlive)(pid))
+            return;
+    }
+    // Auto-start daemon in background
+    utils_js_1.log.info("Starting daemon...");
+    const { spawn } = require("node:child_process");
+    const daemonProcess = spawn(process.argv[0], // node
+    [process.argv[1], "daemon", "start"], {
+        detached: true,
+        stdio: "ignore",
+    });
+    daemonProcess.unref();
+    // Wait briefly for daemon to start
+    const start = Date.now();
+    while (Date.now() - start < 3000) {
+        if ((0, node_fs_1.existsSync)(utils_js_1.BQ_PID_FILE)) {
+            const pid = parseInt((0, node_fs_1.readFileSync)(utils_js_1.BQ_PID_FILE, "utf-8").trim());
+            if ((0, utils_js_1.isProcessAlive)(pid)) {
+                utils_js_1.log.ok("Daemon started");
+                return;
+            }
+        }
+        require("node:child_process").execSync("sleep 0.2");
+    }
+    utils_js_1.log.warn("Daemon may not have started — will proceed anyway");
+}
+async function waitForResult(jobId, timeoutSec) {
+    const resultFile = (0, node_path_1.join)(utils_js_1.BQ_RESULTS_DIR, `${jobId}.json`);
+    const startTime = Date.now();
+    let lastStatus = "";
+    while (true) {
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        if (elapsed > timeoutSec) {
+            utils_js_1.log.error(`Timed out after ${timeoutSec}s`);
+            return {
+                id: jobId,
+                status: "error",
+                duration_seconds: elapsed,
+                summary: `Timed out after ${timeoutSec}s`,
+                failures: [],
+                build_errors: ["Job timed out"],
+                warnings: [],
+                log_path: "",
+            };
+        }
+        if ((0, node_fs_1.existsSync)(resultFile)) {
+            const result = JSON.parse((0, node_fs_1.readFileSync)(resultFile, "utf-8"));
+            return result;
+        }
+        // Periodic status update (every 10s)
+        if (elapsed > 0 && elapsed % 10 === 0) {
+            const status = `Waiting... (${elapsed}s)`;
+            if (status !== lastStatus) {
+                utils_js_1.log.status(status);
+                lastStatus = status;
+            }
+        }
+        await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+}
+function detectWorktreeName() {
+    try {
+        const cwd = process.cwd();
+        const match = cwd.match(/worktrees?\/([^/]+)/);
+        if (match)
+            return match[1];
+        return cwd.split("/").pop() || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/executor.d.ts

@@ -0,0 +1,5 @@
+import { type Job, type JobResult } from "./types.js";
+/**
+ * Execute a single job: apply patch or checkout branch, build/test, return results.
+ */
+export declare function executeJob(job: Job): Promise<JobResult>;

package/dist/executor.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeJob = executeJob;
+const config_js_1 = require("./config.js");
+const snapshot_js_1 = require("./snapshot.js");
+const utils_js_1 = require("./utils.js");
+const mcp_js_1 = require("./backends/mcp.js");
+const xcodebuild_js_1 = require("./backends/xcodebuild.js");
+/**
+ * Execute a single job: apply patch or checkout branch, build/test, return results.
+ */
+async function executeJob(job) {
+    const config = (0, config_js_1.loadConfig)();
+    const repoPath = (0, utils_js_1.expandPath)(config.main_repo);
+    const workspace = config.workspace;
+    // 1. Stash any uncommitted changes in main repo
+    const stashed = stashIfDirty(repoPath);
+    try {
+        if (job.snapshot_sha) {
+            // Snapshot mode: detached HEAD checkout
+            (0, snapshot_js_1.applySnapshot)(repoPath, job.snapshot_sha);
+        }
+        else if (job.branch) {
+            // Branch mode: fetch and checkout
+            utils_js_1.log.info("Fetching latest changes...");
+            (0, utils_js_1.run)("git fetch --all --prune", { cwd: repoPath, quiet: true });
+            utils_js_1.log.info(`Checking out branch: ${job.branch}`);
+            checkoutBranch(repoPath, job.branch);
+        }
+        else {
+            throw new Error("Job has neither snapshot_sha nor branch");
+        }
+        // Restore file timestamps for incremental builds
+        if (config.git_restore_mtime) {
+            restoreMtime(repoPath);
+        }
+        // Run build/test via selected backend
+        const backend = job.backend || config.backend;
+        utils_js_1.log.info(`Backend: ${backend}`);
+        if (backend === "mcp") {
+            try {
+                return await (0, mcp_js_1.executeWithMCP)(job, repoPath, workspace);
+            }
+            catch (err) {
+                if (config.xcodebuild_fallback) {
+                    utils_js_1.log.warn(`MCP failed, falling back to xcodebuild: ${err}`);
+                    return await (0, xcodebuild_js_1.executeWithXcodebuild)(job, repoPath, workspace);
+                }
+                throw err;
+            }
+        }
+        else {
+            return await (0, xcodebuild_js_1.executeWithXcodebuild)(job, repoPath, workspace);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        utils_js_1.log.error(`Job failed: ${message}`);
+        return {
+            id: job.id,
+            status: "error",
+            duration_seconds: 0,
+            summary: message,
+            failures: [],
+            build_errors: [message],
+            warnings: [],
+            log_path: "",
+        };
+    }
+    finally {
+        // Return to default branch after snapshot checkout
+        if (job.snapshot_sha) {
+            (0, snapshot_js_1.cleanSnapshot)(repoPath);
+        }
+        // Restore stashed changes
+        if (stashed) {
+            try {
+                (0, utils_js_1.run)("git stash pop", { cwd: repoPath, quiet: true });
+            }
+            catch {
+                utils_js_1.log.warn("Could not restore stashed changes in main repo");
+            }
+        }
+    }
+}
+function stashIfDirty(repoPath) {
+    const status = (0, utils_js_1.run)("git status --porcelain", { cwd: repoPath, quiet: true });
+    if (status.length > 0) {
+        utils_js_1.log.warn("Main repo has uncommitted changes — stashing");
+        (0, utils_js_1.run)("git stash push -m 'xbq: auto-stash before build'", { cwd: repoPath, quiet: true });
+        return true;
+    }
+    return false;
+}
+function checkoutBranch(repoPath, branch) {
+    // Try local branch first
+    try {
+        (0, utils_js_1.run)(`git checkout ${branch}`, { cwd: repoPath, quiet: true });
+        return;
+    }
+    catch {
+        // Branch might not exist locally
+    }
+    // Try tracking remote branch
+    try {
+        (0, utils_js_1.run)(`git checkout -b ${branch} origin/${branch}`, { cwd: repoPath, quiet: true });
+        return;
+    }
+    catch {
+        // Already exists or other error
+    }
+    // Force update local branch to match remote
+    try {
+        (0, utils_js_1.run)(`git checkout ${branch}`, { cwd: repoPath, quiet: true });
+        (0, utils_js_1.run)(`git reset --hard origin/${branch}`, { cwd: repoPath, quiet: true });
+    }
+    catch (err) {
+        throw new Error(`Failed to checkout branch '${branch}': ${err}`);
+    }
+}
+/**
+ * Restore file modification times from git history.
+ * This helps Xcode's incremental build system avoid unnecessary recompilation.
+ */
+function restoreMtime(repoPath) {
+    try {
+        (0, utils_js_1.run)("which git-restore-mtime", { quiet: true });
+        utils_js_1.log.dim("Restoring file timestamps...");
+        (0, utils_js_1.run)("git-restore-mtime --skip-missing", { cwd: repoPath, quiet: true });
+    }
+    catch {
+        // git-restore-mtime not installed, skip silently
+    }
+}

package/dist/setup-claude.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Inject xbq instructions into CLAUDE.md at a given path.
+ * If CLAUDE.md exists, appends the snippet (or updates if already present).
+ * If CLAUDE.md doesn't exist, creates it.
+ */
+export declare function setupClaude(targetDir?: string): void;
+/**
+ * Remove xbq instructions from CLAUDE.md.
+ */
+export declare function removeClaude(targetDir?: string): void;

package/dist/setup-claude.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupClaude = setupClaude;
+exports.removeClaude = removeClaude;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const utils_js_1 = require("./utils.js");
+const MARKER_START = "<!-- xbq:start -->";
+const MARKER_END = "<!-- xbq:end -->";
+const SNIPPET = `${MARKER_START}
+## Build Queue (xbq)
+
+This project uses \`xbq\` (Xcode Build Queue) for all build and test operations. You are working in a **lightweight worktree** — do NOT build or run tests directly here.
+
+### Rules
+
+1. **NEVER run \`xcodebuild\` directly** in this worktree. Always use \`xbq\`.
+2. **NEVER run Xcode MCP build/test tools** directly. Route through \`xbq\`.
+
+### Workflow
+
+\`\`\`bash
+# 1. Build (automatically captures your changes via diff)
+xbq build
+
+# 2. Test
+xbq test
+
+# 3. Test with specific plan
+xbq test --test-plan All
+
+# 4. Build with specific destination
+xbq build --destination "platform=iOS Simulator,name=iPhone 16,OS=18.0"
+
+# 5. Check queue status
+xbq status
+\`\`\`
+
+### Important
+
+- Changes are captured automatically — no need to commit before building
+- \`xbq\` is a serial queue — your job may wait if another session is building
+- Results include build errors and test failures in structured output
+- For full logs: \`xbq logs <job-id>\`
+- Exit code is 0 on success, 1 on failure — use it to determine next steps
+${MARKER_END}`;
+/**
+ * Inject xbq instructions into CLAUDE.md at a given path.
+ * If CLAUDE.md exists, appends the snippet (or updates if already present).
+ * If CLAUDE.md doesn't exist, creates it.
+ */
+function setupClaude(targetDir) {
+    const dir = targetDir || process.cwd();
+    const claudeMd = (0, node_path_1.join)(dir, "CLAUDE.md");
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    if ((0, node_fs_1.existsSync)(claudeMd)) {
+        const content = (0, node_fs_1.readFileSync)(claudeMd, "utf-8");
+        if (content.includes(MARKER_START)) {
+            // Update existing snippet
+            const regex = new RegExp(`${escapeRegex(MARKER_START)}[\\s\\S]*?${escapeRegex(MARKER_END)}`, "g");
+            const updated = content.replace(regex, SNIPPET);
+            (0, node_fs_1.writeFileSync)(claudeMd, updated);
+            utils_js_1.log.ok(`Updated xbq section in ${claudeMd}`);
+        }
+        else {
+            // Append
+            (0, node_fs_1.appendFileSync)(claudeMd, "\n\n" + SNIPPET + "\n");
+            utils_js_1.log.ok(`Added xbq section to ${claudeMd}`);
+        }
+    }
+    else {
+        (0, node_fs_1.writeFileSync)(claudeMd, SNIPPET + "\n");
+        utils_js_1.log.ok(`Created ${claudeMd} with xbq instructions`);
+    }
+}
+/**
+ * Remove xbq instructions from CLAUDE.md.
+ */
+function removeClaude(targetDir) {
+    const dir = targetDir || process.cwd();
+    const claudeMd = (0, node_path_1.join)(dir, "CLAUDE.md");
+    if (!(0, node_fs_1.existsSync)(claudeMd)) {
+        utils_js_1.log.warn("No CLAUDE.md found");
+        return;
+    }
+    const content = (0, node_fs_1.readFileSync)(claudeMd, "utf-8");
+    if (!content.includes(MARKER_START)) {
+        utils_js_1.log.warn("No xbq section found in CLAUDE.md");
+        return;
+    }
+    const regex = new RegExp(`\\n*${escapeRegex(MARKER_START)}[\\s\\S]*?${escapeRegex(MARKER_END)}\\n*`, "g");
+    const updated = content.replace(regex, "\n");
+    (0, node_fs_1.writeFileSync)(claudeMd, updated.trim() + "\n");
+    utils_js_1.log.ok(`Removed xbq section from ${claudeMd}`);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Detect the default branch (master, main, develop) for a repo.
+ */
+export declare function getDefaultBranch(repoPath: string): string;
+/**
+ * Check if the current directory is inside a git worktree (not the main repo).
+ */
+export declare function isInWorktree(): boolean;
+/**
+ * Create a snapshot commit of the current worktree state (committed + uncommitted
+ * + untracked) without modifying any refs. Returns a SHA that the main repo can
+ * checkout via detached HEAD (shared object store across worktrees).
+ */
+export declare function createSnapshot(): string;
+/**
+ * Apply a snapshot by checking out the SHA as a detached HEAD in the main repo.
+ * Detached HEAD bypasses the worktree branch lock.
+ */
+export declare function applySnapshot(repoPath: string, sha: string): void;
+/**
+ * Clean up the main repo by returning to the default branch.
+ */
+export declare function cleanSnapshot(repoPath: string): void;

package/dist/snapshot.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultBranch = getDefaultBranch;
+exports.isInWorktree = isInWorktree;
+exports.createSnapshot = createSnapshot;
+exports.applySnapshot = applySnapshot;
+exports.cleanSnapshot = cleanSnapshot;
+const utils_js_1 = require("./utils.js");
+/**
+ * Detect the default branch (master, main, develop) for a repo.
+ */
+function getDefaultBranch(repoPath) {
+    try {
+        const ref = (0, utils_js_1.run)("git symbolic-ref refs/remotes/origin/HEAD", { cwd: repoPath, quiet: true });
+        return ref.replace("refs/remotes/origin/", "");
+    }
+    catch {
+        for (const branch of ["master", "main", "develop"]) {
+            try {
+                (0, utils_js_1.run)(`git rev-parse --verify origin/${branch}`, { cwd: repoPath, quiet: true });
+                return branch;
+            }
+            catch {
+                continue;
+            }
+        }
+        return "master";
+    }
+}
+/**
+ * Check if the current directory is inside a git worktree (not the main repo).
+ */
+function isInWorktree() {
+    try {
+        const commonDir = (0, utils_js_1.run)("git rev-parse --git-common-dir", { quiet: true }).replace(/\/$/, "");
+        const gitDir = (0, utils_js_1.run)("git rev-parse --git-dir", { quiet: true }).replace(/\/$/, "");
+        return commonDir !== gitDir;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create a snapshot commit of the current worktree state (committed + uncommitted
+ * + untracked) without modifying any refs. Returns a SHA that the main repo can
+ * checkout via detached HEAD (shared object store across worktrees).
+ */
+function createSnapshot() {
+    const cwd = process.cwd();
+    // Check if there are uncommitted changes (staged, unstaged, or untracked)
+    const status = (0, utils_js_1.run)("git status --porcelain", { cwd, quiet: true });
+    if (!status) {
+        // No uncommitted changes — use HEAD directly
+        const sha = (0, utils_js_1.run)("git rev-parse HEAD", { cwd, quiet: true });
+        utils_js_1.log.dim("No uncommitted changes — using HEAD");
+        return sha;
+    }
+    // Stage everything (including untracked files) to capture full state
+    (0, utils_js_1.run)("git add -A", { cwd, quiet: true });
+    try {
+        // Write the current index as a tree object
+        const tree = (0, utils_js_1.run)("git write-tree", { cwd, quiet: true });
+        // Create a commit object pointing to this tree (no ref update)
+        const head = (0, utils_js_1.run)("git rev-parse HEAD", { cwd, quiet: true });
+        const sha = (0, utils_js_1.run)(`git commit-tree ${tree} -p ${head} -m "xbq snapshot"`, { cwd, quiet: true });
+        utils_js_1.log.dim(`Snapshot: ${sha.slice(0, 8)}`);
+        return sha;
+    }
+    finally {
+        // Always restore the index to its original state
+        (0, utils_js_1.run)("git reset", { cwd, quiet: true });
+    }
+}
+/**
+ * Apply a snapshot by checking out the SHA as a detached HEAD in the main repo.
+ * Detached HEAD bypasses the worktree branch lock.
+ */
+function applySnapshot(repoPath, sha) {
+    utils_js_1.log.info(`Checking out snapshot ${sha.slice(0, 8)}...`);
+    try {
+        (0, utils_js_1.run)(`git checkout ${sha}`, { cwd: repoPath, quiet: true });
+    }
+    catch (err) {
+        throw new Error(`Failed to checkout snapshot ${sha.slice(0, 8)}: ${err}`);
+    }
+    utils_js_1.log.ok("Snapshot applied");
+}
+/**
+ * Clean up the main repo by returning to the default branch.
+ */
+function cleanSnapshot(repoPath) {
+    const defaultBranch = getDefaultBranch(repoPath);
+    try {
+        (0, utils_js_1.run)(`git checkout ${defaultBranch}`, { cwd: repoPath, quiet: true });
+    }
+    catch {
+        utils_js_1.log.warn(`Could not return to ${defaultBranch}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export interface BQConfig {
+    main_repo: string;
+    workspace: string;
+    default_scheme: string;
+    default_test_plan: string;
+    default_destination: string;
+    backend: "mcp" | "xcodebuild";
+    xcodebuild_fallback: boolean;
+    git_restore_mtime: boolean;
+}
+export interface Job {
+    id: string;
+    action: "build" | "test";
+    branch?: string;
+    snapshot_sha?: string;
+    scheme: string;
+    test_plan?: string;
+    destination?: string;
+    backend: "mcp" | "xcodebuild";
+    submitted_at: string;
+    submitted_by: string;
+}
+export interface JobResult {
+    id: string;
+    status: "passed" | "failed" | "error";
+    duration_seconds: number;
+    summary: string;
+    failures: string[];
+    build_errors: string[];
+    warnings: string[];
+    log_path: string;
+}
+export declare const DEFAULT_CONFIG: BQConfig;

package/dist/types.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.DEFAULT_CONFIG = {
+    main_repo: "",
+    workspace: "",
+    default_scheme: "",
+    default_test_plan: "",
+    default_destination: "platform=iOS Simulator,name=iPhone 16",
+    backend: "mcp",
+    xcodebuild_fallback: true,
+    git_restore_mtime: true,
+};

package/dist/utils.d.ts

@@ -0,0 +1,41 @@
+export declare const BQ_HOME: string;
+export declare const BQ_CONFIG_PATH: string;
+export declare const BQ_QUEUE_DIR: string;
+export declare const BQ_ACTIVE_DIR: string;
+export declare const BQ_RESULTS_DIR: string;
+export declare const BQ_LOGS_DIR: string;
+export declare const BQ_PID_FILE: string;
+export declare const BQ_LOCK_FILE: string;
+export declare const log: {
+    info: (msg: string) => void;
+    ok: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    status: (msg: string) => void;
+    dim: (msg: string) => void;
+};
+export declare function ensureDirs(): void;
+export declare function generateJobId(): string;
+export declare function expandPath(p: string): string;
+/**
+ * Run a command and return stdout. Throws on non-zero exit.
+ */
+export declare function run(cmd: string, opts?: {
+    cwd?: string;
+    quiet?: boolean;
+}): string;
+/**
+ * Spawn a long-running process and stream output to a log file + optional callback.
+ */
+export declare function spawnWithLog(cmd: string, args: string[], opts: {
+    cwd?: string;
+    logPath: string;
+    onLine?: (line: string) => void;
+}): Promise<{
+    exitCode: number;
+    output: string;
+}>;
+/**
+ * Check if a process with the given PID is alive.
+ */
+export declare function isProcessAlive(pid: number): boolean;