@rockclaver/sandcastle 0.7.0

package/dist/templates/parallel-planner-with-review/merge-prompt.md

@@ -0,0 +1,26 @@
+# TASK
+
+Merge the following branches into the current branch:
+
+{{BRANCHES}}
+
+For each branch:
+
+1. Run `git merge <branch> --no-edit`
+2. If there are merge conflicts, resolve them intelligently by reading both sides and choosing the correct resolution
+3. After resolving conflicts, run `npm run typecheck` and `npm run test` to verify everything works
+4. If tests fail, fix the issues before proceeding to the next branch
+
+After all branches are merged, make a single commit summarizing the merge.
+
+# CLOSE ISSUES
+
+For each branch that was merged, close its issue using the following command:
+
+`{{CLOSE_TASK_COMMAND}}`
+
+Here are all the issues:
+
+{{ISSUES}}
+
+Once you've merged everything you can, output <promise>COMPLETE</promise>.

package/dist/templates/parallel-planner-with-review/plan-prompt.md

@@ -0,0 +1,37 @@
+# ISSUES
+
+Here are the open issues in the repo:
+
+<issues-json>
+
+!`{{LIST_TASKS_COMMAND}}`
+
+</issues-json>
+
+The list above has already been filtered to issues ready for work.
+
+# TASK
+
+Analyze the open issues and build a dependency graph. For each issue, determine whether it **blocks** or **is blocked by** any other open issue.
+
+An issue B is **blocked by** issue A if:
+
+- B requires code or infrastructure that A introduces
+- B and A modify overlapping files or modules, making concurrent work likely to produce merge conflicts
+- B's requirements depend on a decision or API shape that A will establish
+
+An issue is **unblocked** if it has zero blocking dependencies on other open issues.
+
+For each unblocked issue, assign a branch name using the exact format `sandcastle/issue-{id}` (no slug or other suffix). This must be deterministic so that re-planning the same issue always produces the same branch name and accumulated progress is preserved.
+
+# OUTPUT
+
+Output your plan as a JSON object wrapped in `<plan>` tags:
+
+<plan>
+{"issues": [{"id": "42", "title": "Fix auth bug", "branch": "sandcastle/issue-42"}]}
+</plan>
+
+Include only unblocked issues. If every issue is blocked, include the single highest-priority candidate (the one with the fewest or weakest dependencies).
+
+Always emit the `<plan>` tags, even when there is nothing to do. If there are no issues to work on at all, output `<plan>{"issues": []}</plan>` so the run can exit cleanly.

package/dist/templates/parallel-planner-with-review/review-prompt.md

@@ -0,0 +1,55 @@
+# TASK
+
+Review the code changes on branch `{{BRANCH}}` and improve code clarity, consistency, and maintainability while preserving exact functionality.
+
+# CONTEXT
+
+## Branch diff
+
+!`git diff {{TARGET_BRANCH}}...{{BRANCH}}`
+
+## Commits on this branch
+
+!`git log {{TARGET_BRANCH}}..{{BRANCH}} --oneline`
+
+# REVIEW PROCESS
+
+1. **Understand the change**: Read the diff and commits above to understand the intent.
+
+2. **Analyze for improvements**: Look for opportunities to:
+   - Reduce unnecessary complexity and nesting
+   - Eliminate redundant code and abstractions
+   - Improve readability through clear variable and function names
+   - Consolidate related logic
+   - Remove unnecessary comments that describe obvious code
+   - Avoid nested ternary operators - prefer switch statements or if/else chains
+   - Choose clarity over brevity - explicit code is often better than overly compact code
+
+3. **Check correctness**:
+   - Does the implementation match the intent? Are edge cases handled?
+   - Are new/changed behaviours covered by tests?
+   - Are there unsafe casts, `any` types, or unchecked assumptions?
+   - Does the change introduce injection vulnerabilities, credential leaks, or other security issues?
+
+4. **Maintain balance**: Avoid over-simplification that could:
+   - Reduce code clarity or maintainability
+   - Create overly clever solutions that are hard to understand
+   - Combine too many concerns into single functions or components
+   - Remove helpful abstractions that improve code organization
+   - Make the code harder to debug or extend
+
+5. **Apply project standards**: Follow the coding standards defined in @.sandcastle/CODING_STANDARDS.md
+
+6. **Preserve functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+# EXECUTION
+
+If you find improvements to make:
+
+1. Make the changes directly on this branch
+2. Run tests and type checking to ensure nothing is broken
+3. Commit describing the refinements
+
+If the code is already clean and well-structured, do nothing.
+
+Once complete, output <promise>COMPLETE</promise>.

package/dist/templates/parallel-planner-with-review/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "parallel-planner-with-review",
+  "description": "Plans parallelizable issues, executes with per-branch review, merges"
+}

package/dist/templates/sequential-reviewer/CODING_STANDARDS.md

@@ -0,0 +1,27 @@
+# Coding Standards
+
+<!-- Customize this file with your project's coding standards.
+     The reviewer agent loads it during code review via @.sandcastle/CODING_STANDARDS.md
+     so these standards are enforced during review without costing tokens during implementation. -->
+
+## Style
+
+<!-- Example:
+- Use camelCase for variables and functions
+- Use PascalCase for classes and types
+- Prefer named exports over default exports
+-->
+
+## Testing
+
+<!-- Example:
+- Every public function must have at least one test
+- Use descriptive test names that explain the expected behavior
+-->
+
+## Architecture
+
+<!-- Example:
+- Keep modules focused on a single responsibility
+- Prefer composition over inheritance
+-->

package/dist/templates/sequential-reviewer/implement-prompt.md

@@ -0,0 +1,53 @@
+# Context
+
+## Open issues
+
+!`{{LIST_TASKS_COMMAND}}`
+
+The list above has already been filtered to issues ready for work and is the sole source of truth for what work exists. Do not run your own unfiltered query to find more issues — if the list is empty, there is nothing to do.
+
+## Recent RALPH commits (last 10)
+
+!`git log --oneline --grep="RALPH" -10`
+
+# Task
+
+You are RALPH — an autonomous coding agent working through issues one at a time.
+
+## Priority order
+
+Work on issues in this order:
+
+1. **Bug fixes** — broken behaviour affecting users
+2. **Tracer bullets** — thin end-to-end slices that prove an approach works
+3. **Polish** — improving existing functionality (error messages, UX, docs)
+4. **Refactors** — internal cleanups with no user-visible change
+
+Pick the highest-priority open issue that is not blocked by another open issue.
+
+## Workflow
+
+1. **Explore** — read the issue carefully. Pull in the parent PRD if referenced. Read the relevant source files and tests before writing any code.
+2. **Plan** — decide what to change and why. Keep the change as small as possible.
+3. **Execute** — use RGR (Red → Green → Repeat → Refactor): write a failing test first, then write the implementation to pass it.
+4. **Verify** — run `npm run typecheck` and `npm run test` before committing. Fix any failures before proceeding.
+5. **Commit** — make a single git commit. The message MUST:
+   - Start with `RALPH:` prefix
+   - Include the task completed and any PRD reference
+   - List key decisions made
+   - List files changed
+   - Note any blockers for the next iteration
+6. **Close** — close the issue with `{{CLOSE_TASK_COMMAND}}` explaining what was done.
+
+## Rules
+
+- Work on **one issue per iteration**. Do not attempt multiple issues in a single iteration.
+- Do not close an issue until you have committed the fix and verified tests pass.
+- Do not leave commented-out code or TODO comments in committed code.
+- If you are blocked (missing context, failing tests you cannot fix, external dependency), leave a comment on the issue and move on — do not close it.
+
+# Done
+
+When all actionable issues are complete (or you are blocked on all remaining ones), or the open-issues block at the top of this prompt is empty, output the completion signal:
+
+<promise>COMPLETE</promise>

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

@@ -0,0 +1,119 @@
+// Sequential Reviewer — implement-then-review loop
+//
+// This template drives a two-phase workflow per issue:
+//   Phase 1 (Implement): A sonnet agent picks an open issue, works on it
+//                        on a dedicated branch, commits the changes, and signals
+//                        completion.
+//   Phase 2 (Review):    A second sonnet agent reviews the branch diff and either
+//                        approves it or makes corrections directly on the branch.
+//
+// Both phases share a single sandbox created via createSandbox(), so the
+// implementer and reviewer work on the same explicit branch.
+//
+// The outer loop repeats up to MAX_ITERATIONS times, processing one issue per
+// iteration and stopping early once the backlog is exhausted (an implement
+// phase that produces no commits). This is a middle-complexity option between
+// the simple-loop (no review gate) and the parallel-planner (concurrent
+// execution with a planning phase).
+//
+// Usage:
+//   npx tsx .sandcastle/main.mts
+// Or add to package.json:
+//   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
+
+import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+// Maximum number of implement→review cycles to run before stopping.
+// Each cycle works on one issue. Raise this to process more issues per run.
+const MAX_ITERATIONS = 10;
+
+// Hooks run inside the sandbox before the agent starts each iteration.
+// npm install ensures the sandbox always has fresh dependencies.
+const hooks = {
+  sandbox: { onSandboxReady: [{ command: "npm install" }] },
+};
+
+// Copy node_modules from the host into the worktree before each sandbox
+// starts. Avoids a full npm install from scratch; the hook above handles
+// platform-specific binaries and any packages added since the last copy.
+const copyToWorktree = ["node_modules"];
+
+// ---------------------------------------------------------------------------
+// Main loop
+// ---------------------------------------------------------------------------
+
+for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
+  console.log(`\n=== Iteration ${iteration}/${MAX_ITERATIONS} ===\n`);
+
+  // Generate a unique branch name for this iteration.
+  const branch = `sandcastle/sequential-reviewer/${Date.now()}`;
+
+  // Create a single sandbox that both the implementer and reviewer share.
+  // This gives both agents a real, named branch that persists across phases.
+  const sandbox = await sandcastle.createSandbox({
+    branch,
+    sandbox: docker(),
+    hooks,
+    copyToWorktree,
+  });
+
+  try {
+    // -----------------------------------------------------------------------
+    // Phase 1: Implement
+    //
+    // A sonnet agent picks the next open issue, writes the
+    // implementation (using RGR: Red → Green → Repeat → Refactor), and
+    // commits the result.
+    //
+    // The agent signals completion via <promise>COMPLETE</promise> when done.
+    // -----------------------------------------------------------------------
+    // One iteration so each outer pass implements a single issue on its own
+    // branch, then hands it to the reviewer. A higher value lets the agent
+    // drain the whole backlog onto this one branch in a single pass, which
+    // defeats the per-issue review.
+    const implement = await sandbox.run({
+      name: "implementer",
+      maxIterations: 1,
+      agent: sandcastle.agent({ default: "claude-code" }),
+      promptFile: "./.sandcastle/implement-prompt.md",
+    });
+
+    if (!implement.commits.length) {
+      // No commits means the backlog is empty or every remaining issue is
+      // blocked — there is nothing left to implement or review, so stop.
+      console.log("Implementation agent made no commits. Stopping.");
+      break;
+    }
+
+    console.log(`\nImplementation complete on branch: ${branch}`);
+    console.log(`Commits: ${implement.commits.length}`);
+
+    // -----------------------------------------------------------------------
+    // Phase 2: Review
+    //
+    // A second sonnet agent reviews the diff of the branch produced by
+    // Phase 1. It uses the {{BRANCH}} prompt argument to inspect the right
+    // branch, and either approves or makes corrections directly on the branch.
+    // -----------------------------------------------------------------------
+    await sandbox.run({
+      name: "reviewer",
+      maxIterations: 1,
+      agent: sandcastle.agent({ default: "claude-code" }),
+      promptFile: "./.sandcastle/review-prompt.md",
+      promptArgs: {
+        BRANCH: branch,
+      },
+    });
+
+    console.log("\nReview complete.");
+  } finally {
+    await sandbox.close();
+  }
+}
+
+console.log("\nAll done.");

package/dist/templates/sequential-reviewer/review-prompt.md

@@ -0,0 +1,55 @@
+# TASK
+
+Review the code changes on branch `{{BRANCH}}` and improve code clarity, consistency, and maintainability while preserving exact functionality.
+
+# CONTEXT
+
+## Branch diff
+
+!`git diff {{TARGET_BRANCH}}...{{BRANCH}}`
+
+## Commits on this branch
+
+!`git log {{TARGET_BRANCH}}..{{BRANCH}} --oneline`
+
+# REVIEW PROCESS
+
+1. **Understand the change**: Read the diff and commits above to understand the intent.
+
+2. **Analyze for improvements**: Look for opportunities to:
+   - Reduce unnecessary complexity and nesting
+   - Eliminate redundant code and abstractions
+   - Improve readability through clear variable and function names
+   - Consolidate related logic
+   - Remove unnecessary comments that describe obvious code
+   - Avoid nested ternary operators - prefer switch statements or if/else chains
+   - Choose clarity over brevity - explicit code is often better than overly compact code
+
+3. **Check correctness**:
+   - Does the implementation match the intent? Are edge cases handled?
+   - Are new/changed behaviours covered by tests?
+   - Are there unsafe casts, `any` types, or unchecked assumptions?
+   - Does the change introduce injection vulnerabilities, credential leaks, or other security issues?
+
+4. **Maintain balance**: Avoid over-simplification that could:
+   - Reduce code clarity or maintainability
+   - Create overly clever solutions that are hard to understand
+   - Combine too many concerns into single functions or components
+   - Remove helpful abstractions that improve code organization
+   - Make the code harder to debug or extend
+
+5. **Apply project standards**: Follow the coding standards defined in @.sandcastle/CODING_STANDARDS.md
+
+6. **Preserve functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+# EXECUTION
+
+If you find improvements to make:
+
+1. Make the changes directly on this branch
+2. Run tests and type checking to ensure nothing is broken
+3. Commit describing the refinements
+
+If the code is already clean and well-structured, do nothing.
+
+Once complete, output <promise>COMPLETE</promise>.

package/dist/templates/sequential-reviewer/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "sequential-reviewer",
+  "description": "Implements issues one by one, with a code review step after each"
+}

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

@@ -0,0 +1,49 @@
+import { run, agent } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+
+// Simple loop: an agent that picks open issues one by one and closes them.
+// Run this with: npx tsx .sandcastle/main.mts
+// Or add to package.json scripts: "sandcastle": "npx tsx .sandcastle/main.mts"
+
+await run({
+  // A name for this run, shown as a prefix in log output.
+  name: "worker",
+
+  // Sandbox provider — runs the agent inside an isolated container.
+  sandbox: docker(),
+
+  // The agent provider is resolved at runtime by agent(): the AGENT env var
+  // (or this baked default) picks the provider, AGENT_MODEL picks the model.
+  agent: agent({ default: "claude-code" }),
+
+  // Path to the prompt file. Shell expressions inside are evaluated inside the
+  // sandbox at the start of each iteration, so the agent always sees fresh data.
+  promptFile: "./.sandcastle/prompt.md",
+
+  // Maximum number of iterations (agent invocations) to run in a session.
+  // Each iteration works on a single issue. Increase this to process more issues
+  // per run, or set it to 1 for a single-shot mode.
+  maxIterations: 3,
+
+  // Branch strategy — merge-to-head creates a temporary branch for the agent
+  // to work on, then merges the result back to HEAD when the run completes.
+  // This is required when using copyToWorktree, since head mode bind-mounts
+  // the host directory directly (no worktree to copy into).
+  branchStrategy: { type: "merge-to-head" },
+
+  // Copy node_modules from the host into the worktree before the sandbox
+  // starts. This avoids a full npm install from scratch on every iteration.
+  // The onSandboxReady hook still runs npm install as a safety net to handle
+  // platform-specific binaries and any packages added since the last copy.
+  copyToWorktree: ["node_modules"],
+
+  // Lifecycle hooks — commands grouped by where they run (host or sandbox).
+  hooks: {
+    sandbox: {
+      // onSandboxReady runs once after the sandbox is initialised and the repo is
+      // synced in, before the agent starts. Use it to install dependencies or run
+      // any other setup steps your project needs.
+      onSandboxReady: [{ command: "npm install" }],
+    },
+  },
+});

package/dist/templates/simple-loop/prompt.md

@@ -0,0 +1,53 @@
+# Context
+
+## Open issues
+
+!`{{LIST_TASKS_COMMAND}}`
+
+The list above has already been filtered to issues ready for work and is the sole source of truth for what work exists. Do not run your own unfiltered query to find more issues — if the list is empty, there is nothing to do.
+
+## Recent RALPH commits (last 10)
+
+!`git log --oneline --grep="RALPH" -10`
+
+# Task
+
+You are RALPH — an autonomous coding agent working through issues one at a time.
+
+## Priority order
+
+Work on issues in this order:
+
+1. **Bug fixes** — broken behaviour affecting users
+2. **Tracer bullets** — thin end-to-end slices that prove an approach works
+3. **Polish** — improving existing functionality (error messages, UX, docs)
+4. **Refactors** — internal cleanups with no user-visible change
+
+Pick the highest-priority open issue that is not blocked by another open issue.
+
+## Workflow
+
+1. **Explore** — read the issue carefully. Pull in the parent PRD if referenced. Read the relevant source files and tests before writing any code.
+2. **Plan** — decide what to change and why. Keep the change as small as possible.
+3. **Execute** — use RGR (Red → Green → Repeat → Refactor): write a failing test first, then write the implementation to pass it.
+4. **Verify** — run `npm run typecheck` and `npm run test` before committing. Fix any failures before proceeding.
+5. **Commit** — make a single git commit. The message MUST:
+   - Start with `RALPH:` prefix
+   - Include the task completed and any PRD reference
+   - List key decisions made
+   - List files changed
+   - Note any blockers for the next iteration
+6. **Close** — close the issue with `{{CLOSE_TASK_COMMAND}}` explaining what was done.
+
+## Rules
+
+- Work on **one issue per iteration**. Do not attempt multiple issues in a single iteration.
+- Do not close an issue until you have committed the fix and verified tests pass.
+- Do not leave commented-out code or TODO comments in committed code.
+- If you are blocked (missing context, failing tests you cannot fix, external dependency), leave a comment on the issue and move on — do not close it.
+
+# Done
+
+When all actionable issues are complete (or you are blocked on all remaining ones), or the open-issues block at the top of this prompt is empty, output the completion signal:
+
+<promise>COMPLETE</promise>

package/dist/templates/simple-loop/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "simple-loop",
+  "description": "Picks issues one by one and closes them"
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@rockclaver/sandcastle",
+  "version": "0.7.0",
+  "description": "CLI for orchestrating AI agents in isolated sandbox environments",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sandboxes/docker": {
+      "import": "./dist/sandboxes/docker.js",
+      "types": "./dist/sandboxes/docker.d.ts"
+    },
+    "./sandboxes/vercel": {
+      "import": "./dist/sandboxes/vercel.js",
+      "types": "./dist/sandboxes/vercel.d.ts"
+    },
+    "./sandboxes/podman": {
+      "import": "./dist/sandboxes/podman.js",
+      "types": "./dist/sandboxes/podman.d.ts"
+    },
+    "./sandboxes/daytona": {
+      "import": "./dist/sandboxes/daytona.js",
+      "types": "./dist/sandboxes/daytona.d.ts"
+    },
+    "./sandboxes/no-sandbox": {
+      "import": "./dist/sandboxes/no-sandbox.js",
+      "types": "./dist/sandboxes/no-sandbox.d.ts"
+    }
+  },
+  "bin": {
+    "sandcastle": "dist/main.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "rm -rf dist/templates && cp -r src/templates dist/templates && node scripts/check-public-types-effect-free.mjs",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsgo --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "release": "changeset publish",
+    "sandcastle": "npm run build && tsx .sandcastle/run.ts",
+    "test-podman": "npm run build && tsx --env-file=.sandcastle/.env .sandcastle/test-podman.ts",
+    "test-vercel": "npm run build && tsx --env-file=.sandcastle/.env .sandcastle/test-vercel.ts",
+    "test-interactive": "npm run build && tsx --env-file=.sandcastle/.env .sandcastle/test-interactive.ts"
+  },
+  "keywords": [
+    "cli",
+    "sandbox",
+    "docker",
+    "ai",
+    "agent"
+  ],
+  "packageManager": "npm@10.9.2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattpocock/sandcastle"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@daytona/sdk": "^0.164.0",
+    "@effect/cli": "^0.74.0",
+    "@effect/platform": "^0.95.0",
+    "@effect/platform-node": "^0.105.0",
+    "@effect/printer": "^0.48.0",
+    "@effect/printer-ansi": "^0.48.0",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260317.1",
+    "effect": "^3.20.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.1",
+    "prettier": "^3.5.3",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.0",
+    "zod": "^4.4.3"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@daytona/sdk": "^0.164.0",
+    "@vercel/sandbox": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/sandbox": {
+      "optional": true
+    },
+    "@daytona/sdk": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist"
+  ]
+}