@ai-hero/sandcastle 0.2.4 → 0.4.0

package/dist/syncOut.js

@@ -0,0 +1,271 @@
+/**
+ * Sync-out: extract changes from an isolated sandbox back to the host.
+ *
+ * Two-phase approach:
+ * 1. Save phase: eagerly save all artifacts (patches, diff, untracked files)
+ *    to `.sandcastle/patches/<timestamp>/` before attempting to apply.
+ * 2. Apply phase: apply from the saved directory.
+ *    - On success: clean up the patch directory.
+ *    - On failure: preserve the patch directory and print recovery commands.
+ *
+ * Three-prong extraction within each phase:
+ * 1. Committed changes: `git format-patch` + `git am --3way`
+ * 2. Uncommitted changes (staged + unstaged): `git diff HEAD` + `git apply`
+ * 3. Untracked files: `git ls-files --others` + `copyOut` each file
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { Effect } from "effect";
+import { buildRecoveryMessage } from "./RecoveryMessage.js";
+import { SyncError } from "./errors.js";
+/**
+ * Execute a command on the host side, returning stdout.
+ * Fails with SyncError on non-zero exit.
+ */
+const execHost = (command, cwd) => Effect.tryPromise({
+    try: async () => {
+        const { exec } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execAsync = promisify(exec);
+        const { stdout } = await execAsync(command, {
+            cwd,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return stdout;
+    },
+    catch: (e) => new SyncError({
+        message: `Host command failed: ${command}\n${e instanceof Error ? e.message : String(e)}`,
+    }),
+});
+/**
+ * Execute a command in the sandbox, failing with SyncError if it exits non-zero.
+ */
+const execOk = (handle, command, options) => Effect.tryPromise({
+    try: () => handle.exec(command, options),
+    catch: (e) => new SyncError({
+        message: `Sandbox exec failed: ${command}\n${e instanceof Error ? e.message : String(e)}`,
+    }),
+}).pipe(Effect.flatMap((result) => result.exitCode !== 0
+    ? Effect.fail(new SyncError({
+        message: `Sandbox command failed (exit ${result.exitCode}): ${command}\n${result.stderr}`,
+    }))
+    : Effect.succeed(result)));
+/**
+ * Execute a command in the sandbox, returning the result without failing on non-zero exit.
+ */
+const execSandbox = (handle, command, options) => Effect.tryPromise({
+    try: () => handle.exec(command, options),
+    catch: (e) => new SyncError({
+        message: `Sandbox exec failed: ${command}\n${e instanceof Error ? e.message : String(e)}`,
+    }),
+});
+/**
+ * Check if a patch file is empty or header-only.
+ * Merge commits produce patches with headers but no diff content.
+ * A patch is considered empty if it has no lines starting with "diff --git".
+ */
+const isEmptyPatch = (patchPath) => Effect.tryPromise({
+    try: async () => {
+        const info = await stat(patchPath);
+        if (info.size === 0)
+            return true;
+        const content = await readFile(patchPath, "utf-8");
+        return !content.includes("diff --git");
+    },
+    catch: (e) => new SyncError({
+        message: `Failed to check patch ${patchPath}: ${e instanceof Error ? e.message : String(e)}`,
+    }),
+});
+/**
+ * Generate a YYYYMMDD-HHMMSS timestamp directory name.
+ * Appends a counter suffix (-1, -2, ...) if the directory already exists.
+ */
+const createPatchDir = (hostRepoDir) => Effect.tryPromise({
+    try: async () => {
+        const now = new Date();
+        const pad = (n) => String(n).padStart(2, "0");
+        const base = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+        const patchesRoot = join(hostRepoDir, ".sandcastle", "patches");
+        await mkdir(patchesRoot, { recursive: true });
+        let dirName = base;
+        let counter = 0;
+        while (existsSync(join(patchesRoot, dirName))) {
+            counter++;
+            dirName = `${base}-${counter}`;
+        }
+        const patchDir = join(patchesRoot, dirName);
+        await mkdir(patchDir, { recursive: true });
+        return patchDir;
+    },
+    catch: (e) => new SyncError({
+        message: `Failed to create patch directory: ${e instanceof Error ? e.message : String(e)}`,
+    }),
+});
+/**
+ * Sync changes from an isolated sandbox back to the host repo.
+ *
+ * Two-phase extraction with artifact persistence:
+ * 1. Save all artifacts to `.sandcastle/patches/<timestamp>/`
+ * 2. Apply from saved directory; on failure, preserve artifacts and print recovery
+ */
+export const syncOut = (hostRepoDir, handle) => Effect.gen(function* () {
+    const workspacePath = handle.workspacePath;
+    const hostHead = (yield* execHost("git rev-parse HEAD", hostRepoDir)).trim();
+    const sandboxHead = (yield* execOk(handle, "git rev-parse HEAD", {
+        cwd: workspacePath,
+    })).stdout.trim();
+    const hasCommits = hostHead !== sandboxHead;
+    // Check for uncommitted changes
+    const diffResult = yield* execSandbox(handle, "git diff HEAD", {
+        cwd: workspacePath,
+    });
+    const hasDiff = diffResult.exitCode === 0 && diffResult.stdout.trim().length > 0;
+    // Check for untracked files
+    const lsFilesResult = yield* execSandbox(handle, "git ls-files --others --exclude-standard", { cwd: workspacePath });
+    const hasUntracked = lsFilesResult.exitCode === 0 && lsFilesResult.stdout.trim().length > 0;
+    const untrackedFiles = hasUntracked
+        ? lsFilesResult.stdout
+            .trim()
+            .split("\n")
+            .filter((f) => f.length > 0)
+        : [];
+    // Nothing to sync
+    if (!hasCommits && !hasDiff && !hasUntracked) {
+        return;
+    }
+    // --- Phase 1: Save all artifacts ---
+    const patchDir = yield* createPatchDir(hostRepoDir);
+    const relativePatchDir = join(".sandcastle", "patches", basename(patchDir));
+    const nonEmptyPatches = [];
+    // Save committed patches
+    if (hasCommits) {
+        const mkTempResult = yield* execOk(handle, "mktemp -d -t sandcastle-patches-XXXXXX");
+        const sandboxPatchDir = mkTempResult.stdout.trim();
+        try {
+            yield* execOk(handle, `git format-patch "${hostHead}..HEAD" -o "${sandboxPatchDir}"`, { cwd: workspacePath });
+            const lsResult = yield* execOk(handle, `ls -1 "${sandboxPatchDir}"`);
+            const patchNames = lsResult.stdout
+                .trim()
+                .split("\n")
+                .filter((name) => name.length > 0);
+            for (const patchName of patchNames) {
+                const sandboxPatchPath = `${sandboxPatchDir}/${patchName}`;
+                const hostPatchPath = join(patchDir, patchName);
+                yield* Effect.tryPromise({
+                    try: () => handle.copyOut(sandboxPatchPath, hostPatchPath),
+                    catch: (e) => new SyncError({
+                        message: `Failed to copy patch ${patchName}: ${e instanceof Error ? e.message : String(e)}`,
+                    }),
+                });
+                if (!(yield* isEmptyPatch(hostPatchPath))) {
+                    nonEmptyPatches.push(hostPatchPath);
+                }
+            }
+        }
+        finally {
+            yield* execSandbox(handle, `rm -rf "${sandboxPatchDir}"`);
+        }
+    }
+    // Save uncommitted diff
+    if (hasDiff) {
+        const diffPath = join(patchDir, "changes.patch");
+        yield* Effect.tryPromise({
+            try: () => writeFile(diffPath, diffResult.stdout),
+            catch: (e) => new SyncError({
+                message: `Failed to write diff patch: ${e instanceof Error ? e.message : String(e)}`,
+            }),
+        });
+    }
+    // Save untracked files
+    if (hasUntracked) {
+        const untrackedDir = join(patchDir, "untracked");
+        for (const relPath of untrackedFiles) {
+            const sandboxFilePath = `${workspacePath}/${relPath}`;
+            const hostFilePath = join(untrackedDir, relPath);
+            yield* Effect.tryPromise({
+                try: async () => {
+                    await mkdir(dirname(hostFilePath), { recursive: true });
+                    await handle.copyOut(sandboxFilePath, hostFilePath);
+                },
+                catch: (e) => new SyncError({
+                    message: `Failed to save untracked file ${relPath}: ${e instanceof Error ? e.message : String(e)}`,
+                }),
+            });
+        }
+    }
+    // --- Phase 2: Apply from saved directory ---
+    let failedStep;
+    // Apply committed patches
+    if (nonEmptyPatches.length > 0) {
+        const abortResult = yield* Effect.either(execHost("git am --abort", hostRepoDir));
+        void abortResult; // ignore abort failures
+        const patchArgs = nonEmptyPatches.map((p) => `"${p}"`).join(" ");
+        const applyResult = yield* Effect.either(execHost(`git am --3way ${patchArgs}`, hostRepoDir));
+        if (applyResult._tag === "Left") {
+            failedStep = "commits";
+        }
+    }
+    // Apply uncommitted diff
+    if (!failedStep && hasDiff) {
+        const diffPath = join(patchDir, "changes.patch");
+        const applyResult = yield* Effect.either(execHost(`git apply "${diffPath}"`, hostRepoDir));
+        if (applyResult._tag === "Left") {
+            failedStep = "diff";
+        }
+    }
+    // Copy untracked files
+    if (!failedStep && hasUntracked) {
+        const copyResult = yield* Effect.either(Effect.tryPromise({
+            try: async () => {
+                const untrackedDir = join(patchDir, "untracked");
+                for (const relPath of untrackedFiles) {
+                    const srcPath = join(untrackedDir, relPath);
+                    const destPath = join(hostRepoDir, relPath);
+                    await mkdir(dirname(destPath), { recursive: true });
+                    const content = await readFile(srcPath);
+                    await writeFile(destPath, content);
+                }
+            },
+            catch: (e) => new SyncError({
+                message: `Failed to copy untracked files: ${e instanceof Error ? e.message : String(e)}`,
+            }),
+        }));
+        if (copyResult._tag === "Left") {
+            failedStep = "untracked";
+        }
+    }
+    // --- Cleanup or preserve ---
+    if (failedStep) {
+        const msg = buildRecoveryMessage({
+            patchDir: relativePatchDir,
+            failedStep,
+            hasCommits: nonEmptyPatches.length > 0,
+            hasDiff,
+            hasUntracked,
+        });
+        console.error(`\n${msg}`);
+    }
+    else {
+        yield* Effect.tryPromise({
+            try: async () => {
+                await rm(patchDir, { recursive: true, force: true });
+                const patchesRoot = join(hostRepoDir, ".sandcastle", "patches");
+                try {
+                    const remaining = await readdir(patchesRoot);
+                    if (remaining.length === 0) {
+                        await rm(join(hostRepoDir, ".sandcastle"), {
+                            recursive: true,
+                            force: true,
+                        });
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            },
+            catch: () => new SyncError({ message: "Failed to clean up patch directory" }),
+        });
+    }
+});
+//# sourceMappingURL=syncOut.js.map

package/dist/syncOut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncOut.js","sourceRoot":"","sources":["../src/syncOut.ts"],"names":[],"mappings":"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"}

package/dist/templates/blank/.env.example

@@ -1,4 +1,5 @@
 # Anthropic API key
+# If you want to use your Claude subscription instead of an API key, see https://github.com/mattpocock/sandcastle/issues/191
 ANTHROPIC_API_KEY=
 # GitHub personal access token
 GH_TOKEN=

package/dist/templates/blank/main.mts

@@ -1,4 +1,5 @@
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // Blank template: customize this to build your own orchestration.
 // Run this with: npx tsx .sandcastle/main.mts
@@ -6,5 +7,6 @@ import { run, claudeCode } from "@ai-hero/sandcastle";
 
 await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: "./.sandcastle/prompt.md",
 });

package/dist/templates/parallel-planner/.env.example

@@ -1,4 +1,5 @@
 # Anthropic API key
+# If you want to use your Claude subscription instead of an API key, see https://github.com/mattpocock/sandcastle/issues/191
 ANTHROPIC_API_KEY=
 # GitHub personal access token
 GH_TOKEN=

package/dist/templates/parallel-planner/main.mts

@@ -17,6 +17,7 @@
 //   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
 
 import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -56,6 +57,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   const plan = await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "planner",
     // One iteration is enough: the planner just needs to read and reason,
     // not write code.
@@ -105,6 +107,8 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
       sandcastle.run({
         hooks,
         copyToSandbox,
+        // Each agent starts on its own branch via the provider's branchStrategy.
+        sandbox: docker({ branchStrategy: { type: "branch", branch: issue.branch } }),
         name: "implementer",
         // Give each agent plenty of room to implement and iterate on tests.
         maxIterations: 100,
@@ -119,8 +123,6 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
           ISSUE_TITLE: issue.title,
           BRANCH: issue.branch,
         },
-        // Each agent starts on its own branch.
-        worktree: { mode: "branch", branch: issue.branch },
       }),
     ),
   );
@@ -179,6 +181,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "merger",
     maxIterations: 10,
     // Sonnet is sufficient for merge conflict resolution.

package/dist/templates/sequential-reviewer/.env.example

@@ -1,4 +1,5 @@
 # Anthropic API key
+# If you want to use your Claude subscription instead of an API key, see https://github.com/mattpocock/sandcastle/issues/191
 ANTHROPIC_API_KEY=
 # GitHub personal access token
 GH_TOKEN=

package/dist/templates/sequential-reviewer/main.mts

@@ -17,6 +17,7 @@
 //   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
 
 import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -57,6 +58,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   const implement = await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "implementer",
     maxIterations: 100,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),
@@ -84,6 +86,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker({ branchStrategy: { type: "branch", branch } }),
     name: "reviewer",
     maxIterations: 10,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),
@@ -93,7 +96,6 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
     promptArgs: {
       BRANCH: branch,
     },
-    worktree: { mode: "branch", branch },
   });
 
   console.log("\nReview complete.");

package/dist/templates/simple-loop/.env.example

@@ -1,4 +1,5 @@
 # Anthropic API key
+# If you want to use your Claude subscription instead of an API key, see https://github.com/mattpocock/sandcastle/issues/191
 ANTHROPIC_API_KEY=
 # GitHub personal access token
 GH_TOKEN=

package/dist/templates/simple-loop/main.mts

@@ -1,4 +1,5 @@
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // Simple loop: an agent that picks open GitHub issues one by one and closes them.
 // Run this with: npx tsx .sandcastle/main.mts
@@ -8,6 +9,9 @@ await run({
   // A name for this run, shown as a prefix in log output.
   name: "worker",
 
+  // Sandbox provider — Docker is the default runtime.
+  sandbox: docker(),
+
   // The agent provider. Pass a model string to claudeCode() — sonnet balances
   // capability and speed for most tasks. Switch to claude-opus-4-6 for harder
   // problems, or claude-haiku-4-5-20251001 for speed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-hero/sandcastle",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "CLI for orchestrating AI agents in isolated sandbox environments",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./sandboxes/docker": {
+      "import": "./dist/sandboxes/docker.js",
+      "types": "./dist/sandboxes/docker.d.ts"
     }
   },
   "bin": {