@ai-hero/sandcastle 0.0.1

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { run } from "./run.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":""}

package/dist/main.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { cli } from "./cli.js";
+import { ClackDisplay } from "./Display.js";
+import { withFriendlyErrors } from "./ErrorHandler.js";
+import { setupTerminalCleanup } from "./terminalCleanup.js";
+// Restore terminal state on any exit.
+// @clack/prompts' spinner/taskLog set stdin to raw mode and hide the cursor.
+// If the process exits via a signal handler that calls process.exit() directly
+// (e.g. the Ctrl-C handler in SandboxFactory), clack's own cleanup is
+// bypassed, leaving the terminal broken. This exit hook fixes that.
+setupTerminalCleanup();
+const mainLayer = Layer.merge(NodeContext.layer, ClackDisplay.layer);
+cli(process.argv).pipe(withFriendlyErrors, Effect.provide(mainLayer), NodeRuntime.runMain);
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,sCAAsC;AACtC,6EAA6E;AAC7E,+EAA+E;AAC/E,sEAAsE;AACtE,oEAAoE;AACpE,oBAAoB,EAAE,CAAC;AAEvB,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;AAErE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CACpB,kBAAkB,EAClB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EACzB,WAAW,CAAC,OAAO,CACpB,CAAC"}

package/dist/run.d.ts

@@ -0,0 +1,91 @@
+import { type Severity } from "./Display.js";
+import { type PromptArgs } from "./PromptArgumentSubstitution.js";
+/** Default maximum number of iterations for a run. */
+export declare const DEFAULT_MAX_ITERATIONS = 1;
+/** Replace characters that are invalid or problematic in file paths with dashes. */
+export declare const sanitizeBranchForFilename: (branch: string) => string;
+export interface FileDisplayStartupOptions {
+    readonly logPath: string;
+    readonly agentName?: string;
+    readonly branch?: string;
+}
+/**
+ * Print the startup message to the terminal when using file-based logging.
+ * Uses styleText for lightweight bold/dim styling — does not use Clack.
+ */
+export declare const printFileDisplayStartup: (options: FileDisplayStartupOptions) => void;
+/**
+ * Derive the default Docker image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for Docker image tag rules.
+ */
+export declare const defaultImageName: (repoDir: string) => string;
+/**
+ * Build the log filename for a run.
+ * When a targetBranch is provided (temp branch mode), prefixes the filename
+ * with the sanitized target branch name so developers can identify which
+ * branch the run was targeting: `<targetBranch>-<resolvedBranch>.log`
+ * When no targetBranch, uses just the resolved branch: `<resolvedBranch>.log`
+ */
+export declare const buildLogFilename: (resolvedBranch: string, targetBranch?: string | undefined) => string;
+/**
+ * Build the completion status message for a run, used in both terminal mode
+ * and log-to-file mode to record the final outcome.
+ */
+export declare const buildCompletionMessage: (wasCompletionSignalDetected: boolean, iterationsRun: number) => {
+    readonly message: string;
+    readonly severity: Severity;
+};
+export type LoggingOption = {
+    readonly type: "file";
+    readonly path: string;
+} | {
+    readonly type: "stdout";
+};
+export interface RunOptions {
+    /** Inline prompt string (mutually exclusive with promptFile) */
+    readonly prompt?: string;
+    /** Path to a prompt file (mutually exclusive with prompt) */
+    readonly promptFile?: string;
+    /** Maximum iterations to run (default: 1) */
+    readonly maxIterations?: number;
+    /** Hooks to run during sandbox lifecycle */
+    readonly hooks?: {
+        readonly onSandboxReady?: ReadonlyArray<{
+            command: string;
+        }>;
+    };
+    /** Target branch name for sandbox work */
+    readonly branch?: string;
+    /** Model to use for the agent (default: claude-opus-4-6) */
+    readonly model?: string;
+    /** Agent provider name (default: claude-code) */
+    readonly agent?: string;
+    /** Docker image name to use for the sandbox (default: sandcastle:<repo-dir-name>) */
+    readonly imageName?: string;
+    /** Key-value map for {{KEY}} placeholder substitution in prompts */
+    readonly promptArgs?: PromptArgs;
+    /** Logging mode (default: { type: 'file' } with auto-generated path under .sandcastle/logs/) */
+    readonly logging?: LoggingOption;
+    /** Custom completion signal string (default: "<promise>COMPLETE</promise>") */
+    readonly completionSignal?: string;
+    /** Timeout in seconds. If the run exceeds this, it fails. Default: 1200 (20 minutes) */
+    readonly timeoutSeconds?: number;
+    /** Optional name for the run, shown as a prefix in log output */
+    readonly name?: string;
+    /** Paths relative to the host repo root to copy into the worktree before container start. */
+    readonly copyToSandbox?: string[];
+}
+export interface RunResult {
+    readonly iterationsRun: number;
+    readonly wasCompletionSignalDetected: boolean;
+    readonly stdout: string;
+    readonly commits: {
+        sha: string;
+    }[];
+    readonly branch: string;
+    /** Path to the log file, if logging was drained to a file. */
+    readonly logFilePath?: string;
+}
+export declare const run: (options: RunOptions) => Promise<RunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,QAAQ,EACd,MAAM,cAAc,CAAC;AAUtB,OAAO,EACL,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AAEzC,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,4BACA,CAAC;AAEvC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,8CASnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAI5B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,uEAS5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;CAclC,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9D,CAAC;IACF,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,wFAAwF;IACxF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,GAAG,6CA0If,CAAC"}

package/dist/run.js

@@ -0,0 +1,155 @@
+import { NodeContext, NodeFileSystem } from "@effect/platform-node";
+import path, { join } from "node:path";
+import { styleText } from "node:util";
+import { Effect, Layer } from "effect";
+import { getAgentProvider } from "./AgentProvider.js";
+import { ClackDisplay, Display, FileDisplay, } from "./Display.js";
+import { orchestrate } from "./Orchestrator.js";
+import { resolvePrompt } from "./PromptResolver.js";
+import { WorktreeDockerSandboxFactory, WorktreeSandboxConfig, SANDBOX_WORKSPACE_DIR, } from "./SandboxFactory.js";
+import { resolveEnv } from "./EnvResolver.js";
+import { generateTempBranchName, getCurrentBranch } from "./WorktreeManager.js";
+import { substitutePromptArgs, } from "./PromptArgumentSubstitution.js";
+/** Default maximum number of iterations for a run. */
+export const DEFAULT_MAX_ITERATIONS = 1;
+/** Replace characters that are invalid or problematic in file paths with dashes. */
+export const sanitizeBranchForFilename = (branch) => branch.replace(/[/\\:*?"<>|]/g, "-");
+/**
+ * Print the startup message to the terminal when using file-based logging.
+ * Uses styleText for lightweight bold/dim styling — does not use Clack.
+ */
+export const printFileDisplayStartup = (options) => {
+    const name = options.agentName ?? "Agent";
+    const label = styleText("bold", `[${name}]`);
+    const branchPart = options.branch ? ` on branch ${options.branch}` : "";
+    const relativeLogPath = path.relative(process.cwd(), options.logPath);
+    console.log(`${label} Started${branchPart}`);
+    console.log(styleText("dim", `  tail -f ${relativeLogPath}`));
+};
+/**
+ * Derive the default Docker image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for Docker image tag rules.
+ */
+export const defaultImageName = (repoDir) => {
+    const dirName = repoDir.replace(/\/+$/, "").split("/").pop() ?? "local";
+    const sanitized = dirName.toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    return `sandcastle:${sanitized}`;
+};
+/**
+ * Build the log filename for a run.
+ * When a targetBranch is provided (temp branch mode), prefixes the filename
+ * with the sanitized target branch name so developers can identify which
+ * branch the run was targeting: `<targetBranch>-<resolvedBranch>.log`
+ * When no targetBranch, uses just the resolved branch: `<resolvedBranch>.log`
+ */
+export const buildLogFilename = (resolvedBranch, targetBranch) => {
+    const sanitized = sanitizeBranchForFilename(resolvedBranch);
+    if (targetBranch) {
+        return `${sanitizeBranchForFilename(targetBranch)}-${sanitized}.log`;
+    }
+    return `${sanitized}.log`;
+};
+/**
+ * Build the completion status message for a run, used in both terminal mode
+ * and log-to-file mode to record the final outcome.
+ */
+export const buildCompletionMessage = (wasCompletionSignalDetected, iterationsRun) => {
+    if (wasCompletionSignalDetected) {
+        return {
+            message: `Run complete: agent finished after ${iterationsRun} iteration(s).`,
+            severity: "success",
+        };
+    }
+    return {
+        message: `Run complete: reached ${iterationsRun} iteration(s) without completion signal.`,
+        severity: "warn",
+    };
+};
+export const run = async (options) => {
+    const { prompt, promptFile, maxIterations = DEFAULT_MAX_ITERATIONS, hooks, branch, model, agent, } = options;
+    const hostRepoDir = process.cwd();
+    // Resolve prompt
+    const rawPrompt = await Effect.runPromise(resolvePrompt({ prompt, promptFile }).pipe(Effect.provide(NodeContext.layer)));
+    // Resolve model: explicit option > default
+    const resolvedModel = model;
+    // Resolve agent provider: explicit option > default
+    const agentName = agent ?? "claude-code";
+    const provider = getAgentProvider(agentName);
+    // Resolve image name: explicit option > default
+    const resolvedImageName = options.imageName ?? defaultImageName(hostRepoDir);
+    // Resolve env vars
+    const env = await Effect.runPromise(resolveEnv(hostRepoDir).pipe(Effect.provide(NodeContext.layer)));
+    // When no branch is provided, generate a temporary branch name.
+    // This names the log file after the temp branch and also directs
+    // the sandbox to work on that branch (instead of the current host branch).
+    const resolvedBranch = branch ?? generateTempBranchName(agentName);
+    // When using a temp branch, prefix the log filename with the target branch
+    // (the host's current branch) so developers can tell which branch was targeted.
+    const targetBranch = branch === undefined
+        ? await Effect.runPromise(getCurrentBranch(hostRepoDir))
+        : undefined;
+    // Resolve logging option
+    const resolvedLogging = options.logging ?? {
+        type: "file",
+        path: join(hostRepoDir, ".sandcastle", "logs", buildLogFilename(resolvedBranch, targetBranch)),
+    };
+    const displayLayer = resolvedLogging.type === "file"
+        ? (() => {
+            printFileDisplayStartup({
+                logPath: resolvedLogging.path,
+                agentName: options.name,
+                branch: resolvedBranch,
+            });
+            return Layer.provide(FileDisplay.layer(resolvedLogging.path), NodeFileSystem.layer);
+        })()
+        : ClackDisplay.layer;
+    const factoryLayer = Layer.provide(WorktreeDockerSandboxFactory.layer, Layer.mergeAll(Layer.succeed(WorktreeSandboxConfig, {
+        imageName: resolvedImageName,
+        env,
+        hostRepoDir,
+        // Pass explicit branch only — when undefined, WorktreeManager creates a temp branch
+        // and SandboxLifecycle cherry-picks commits onto the host's current branch
+        branch,
+        copyToSandbox: options.copyToSandbox,
+        agentName,
+    }), NodeFileSystem.layer, displayLayer));
+    const runLayer = Layer.merge(factoryLayer, displayLayer);
+    const result = await Effect.runPromise(Effect.gen(function* () {
+        const d = yield* Display;
+        yield* d.intro(options.name ?? "sandcastle");
+        const rows = {
+            Agent: agentName,
+            Image: resolvedImageName,
+            "Max iterations": String(maxIterations),
+        };
+        rows["Branch"] = resolvedBranch;
+        if (resolvedModel)
+            rows["Model"] = resolvedModel;
+        yield* d.summary("Sandcastle Run", rows);
+        // Substitute prompt arguments ({{KEY}} placeholders) before orchestration
+        const resolvedPrompt = options.promptArgs
+            ? yield* substitutePromptArgs(rawPrompt, options.promptArgs)
+            : rawPrompt;
+        const orchestrateResult = yield* orchestrate({
+            hostRepoDir,
+            sandboxRepoDir: SANDBOX_WORKSPACE_DIR,
+            iterations: maxIterations,
+            hooks,
+            prompt: resolvedPrompt,
+            branch,
+            model: resolvedModel,
+            completionSignal: options.completionSignal,
+            timeoutSeconds: options.timeoutSeconds,
+            name: options.name,
+        });
+        const completion = buildCompletionMessage(orchestrateResult.wasCompletionSignalDetected, orchestrateResult.iterationsRun);
+        yield* d.status(completion.message, completion.severity);
+        return orchestrateResult;
+    }).pipe(Effect.provide(runLayer)));
+    return {
+        ...result,
+        logFilePath: resolvedLogging.type === "file" ? resolvedLogging.path : undefined,
+    };
+};
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,YAAY,EACZ,OAAO,EACP,WAAW,GAEZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAEL,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AAEzC,sDAAsD;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,oFAAoF;AACpF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,MAAc,EAAU,EAAE,CAClE,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;AAQvC;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,OAAkC,EAC5B,EAAE;IACR,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;IAC1C,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,WAAW,UAAU,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,eAAe,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAU,EAAE;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC;IACxE,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;IACtE,OAAO,cAAc,SAAS,EAAE,CAAC;AACnC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,cAAsB,EACtB,YAAqB,EACb,EAAE;IACV,MAAM,SAAS,GAAG,yBAAyB,CAAC,cAAc,CAAC,CAAC;IAC5D,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,GAAG,yBAAyB,CAAC,YAAY,CAAC,IAAI,SAAS,MAAM,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,SAAS,MAAM,CAAC;AAC5B,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,2BAAoC,EACpC,aAAqB,EACsC,EAAE;IAC7D,IAAI,2BAA2B,EAAE,CAAC;QAChC,OAAO;YACL,OAAO,EAAE,sCAAsC,aAAa,gBAAgB;YAC5E,QAAQ,EAAE,SAAS;SACpB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE,yBAAyB,aAAa,0CAA0C;QACzF,QAAQ,EAAE,MAAM;KACjB,CAAC;AACJ,CAAC,CAAC;AAiDF,MAAM,CAAC,MAAM,GAAG,GAAG,KAAK,EAAE,OAAmB,EAAsB,EAAE;IACnE,MAAM,EACJ,MAAM,EACN,UAAU,EACV,aAAa,GAAG,sBAAsB,EACtC,KAAK,EACL,MAAM,EACN,KAAK,EACL,KAAK,GACN,GAAG,OAAO,CAAC;IAEZ,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAElC,iBAAiB;IACjB,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,UAAU,CACvC,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,IAAI,CACxC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAClC,CACF,CAAC;IAEF,2CAA2C;IAC3C,MAAM,aAAa,GAAG,KAAK,CAAC;IAE5B,oDAAoD;IACpD,MAAM,SAAS,GAAG,KAAK,IAAI,aAAa,CAAC;IACzC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAE7C,gDAAgD;IAChD,MAAM,iBAAiB,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAE7E,mBAAmB;IACnB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,UAAU,CACjC,UAAU,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAChE,CAAC;IAEF,gEAAgE;IAChE,iEAAiE;IACjE,2EAA2E;IAC3E,MAAM,cAAc,GAAG,MAAM,IAAI,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEnE,2EAA2E;IAC3E,gFAAgF;IAChF,MAAM,YAAY,GAChB,MAAM,KAAK,SAAS;QAClB,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;QACxD,CAAC,CAAC,SAAS,CAAC;IAEhB,yBAAyB;IACzB,MAAM,eAAe,GAAkB,OAAO,CAAC,OAAO,IAAI;QACxD,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,IAAI,CACR,WAAW,EACX,aAAa,EACb,MAAM,EACN,gBAAgB,CAAC,cAAc,EAAE,YAAY,CAAC,CAC/C;KACF,CAAC;IACF,MAAM,YAAY,GAChB,eAAe,CAAC,IAAI,KAAK,MAAM;QAC7B,CAAC,CAAC,CAAC,GAAG,EAAE;YACJ,uBAAuB,CAAC;gBACtB,OAAO,EAAE,eAAe,CAAC,IAAI;gBAC7B,SAAS,EAAE,OAAO,CAAC,IAAI;gBACvB,MAAM,EAAE,cAAc;aACvB,CAAC,CAAC;YACH,OAAO,KAAK,CAAC,OAAO,CAClB,WAAW,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,EACvC,cAAc,CAAC,KAAK,CACrB,CAAC;QACJ,CAAC,CAAC,EAAE;QACN,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC;IAEzB,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAChC,4BAA4B,CAAC,KAAK,EAClC,KAAK,CAAC,QAAQ,CACZ,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE;QACnC,SAAS,EAAE,iBAAiB;QAC5B,GAAG;QACH,WAAW;QACX,oFAAoF;QACpF,2EAA2E;QAC3E,MAAM;QACN,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,SAAS;KACV,CAAC,EACF,cAAc,CAAC,KAAK,EACpB,YAAY,CACb,CACF,CAAC;IAEF,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CACpC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC;QACzB,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC,CAAC;QAC7C,MAAM,IAAI,GAA2B;YACnC,KAAK,EAAE,SAAS;YAChB,KAAK,EAAE,iBAAiB;YACxB,gBAAgB,EAAE,MAAM,CAAC,aAAa,CAAC;SACxC,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC;QAChC,IAAI,aAAa;YAAE,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC;QACjD,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QAEzC,0EAA0E;QAC1E,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU;YACvC,CAAC,CAAC,KAAK,CAAC,CAAC,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC;YAC5D,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,iBAAiB,GAAG,KAAK,CAAC,CAAC,WAAW,CAAC;YAC3C,WAAW;YACX,cAAc,EAAE,qBAAqB;YACrC,UAAU,EAAE,aAAa;YACzB,KAAK;YACL,MAAM,EAAE,cAAc;YACtB,MAAM;YACN,KAAK,EAAE,aAAa;YACpB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;YAC1C,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,sBAAsB,CACvC,iBAAiB,CAAC,2BAA2B,EAC7C,iBAAiB,CAAC,aAAa,CAChC,CAAC;QACF,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;QAEzD,OAAO,iBAAiB,CAAC;IAC3B,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAClC,CAAC;IAEF,OAAO;QACL,GAAG,MAAM;QACT,WAAW,EACT,eAAe,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;KACrE,CAAC;AACJ,CAAC,CAAC"}

package/dist/templates/blank/main.ts

@@ -0,0 +1,9 @@
+import { run } from "@ai-hero/sandcastle";
+
+// Blank template: customize this to build your own orchestration.
+// Run this with: npx tsx .sandcastle/main.ts
+// Or add to package.json scripts: "sandcastle": "npx tsx .sandcastle/main.ts"
+
+await run({
+  promptFile: "./.sandcastle/prompt.md",
+});

package/dist/templates/blank/prompt.md

@@ -0,0 +1,12 @@
+# Context
+
+<!-- Use !`command` to pull in dynamic context. Commands run inside the sandbox. -->
+<!-- Example: !`git log --oneline -10` or !`gh issue list --json number,title` -->
+
+# Task
+
+<!-- Describe what the agent should do. -->
+
+# Done
+
+<!-- When the task is complete, output <promise>COMPLETE</promise> to signal early termination. -->

package/dist/templates/blank/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "blank",
+  "description": "Bare scaffold — write your own prompt and orchestration"
+}

package/dist/templates/parallel-planner/implement-prompt.md

@@ -0,0 +1,62 @@
+# TASK
+
+Fix issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}
+
+Pull in the issue using `gh issue view`. If it has a parent PRD, pull that in too.
+
+Only work on the issue specified.
+
+Work on branch {{BRANCH}}. Make commits, run tests, and close the issue when done.
+
+# CONTEXT
+
+Here are the last 10 commits:
+
+<recent-commits>
+
+!`git log -n 10 --format="%H%n%ad%n%B---" --date=short`
+
+</recent-commits>
+
+# EXPLORATION
+
+Explore the repo and fill your context window with relevant information that will allow you to complete the task.
+
+Pay extra attention to test files that touch the relevant parts of the code.
+
+# EXECUTION
+
+If applicable, use RGR to complete the task.
+
+1. RED: write one test
+2. GREEN: write the implementation to pass that test
+3. REPEAT until done
+4. REFACTOR the code
+
+# FEEDBACK LOOPS
+
+Before committing, run `npm run typecheck` and `npm run test` to ensure the tests pass.
+
+# COMMIT
+
+Make a git commit. The commit message must:
+
+1. Start with `RALPH:` prefix
+2. Include task completed + PRD reference
+3. Key decisions made
+4. Files changed
+5. Blockers or notes for next iteration
+
+Keep it concise.
+
+# THE ISSUE
+
+If the task is not complete, leave a comment on the GitHub issue with what was done.
+
+Do not close the issue - this will be done later.
+
+Once complete, output <promise>COMPLETE</promise>.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.

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

@@ -0,0 +1,200 @@
+// Parallel Planner — three-phase orchestration loop
+//
+// This template drives a multi-phase workflow:
+//   Phase 1 (Plan):    An opus agent analyzes open issues, builds a dependency
+//                      graph, and outputs a <plan> JSON listing unblocked issues
+//                      with their target branch names.
+//   Phase 2 (Execute): N sonnet agents run in parallel via Promise.allSettled,
+//                      each working a single issue on its own branch.
+//   Phase 3 (Merge):   A sonnet agent merges all branches that produced commits.
+//
+// The outer loop repeats up to MAX_ITERATIONS times so that newly unblocked
+// issues are picked up after each round of merges.
+//
+// Usage:
+//   npx tsx .sandcastle/main.ts
+// Or add to package.json:
+//   "scripts": { "sandcastle": "npx tsx .sandcastle/main.ts" }
+
+import * as sandcastle from "@ai-hero/sandcastle";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+// Maximum number of plan→execute→merge cycles before stopping.
+// Raise this if your backlog is large; lower it for a quick smoke-test 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 = {
+  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 copyToSandbox = ["node_modules"];
+
+// ---------------------------------------------------------------------------
+// Main loop
+// ---------------------------------------------------------------------------
+
+for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
+  console.log(`\n=== Iteration ${iteration}/${MAX_ITERATIONS} ===\n`);
+
+  // -------------------------------------------------------------------------
+  // Phase 1: Plan
+  //
+  // The planning agent (opus, for deeper reasoning) reads the open issue list,
+  // builds a dependency graph, and selects the issues that can be worked in
+  // parallel right now (i.e., no blocking dependencies on other open issues).
+  //
+  // It outputs a <plan> JSON block — we parse that to drive Phase 2.
+  // -------------------------------------------------------------------------
+  const plan = await sandcastle.run({
+    hooks,
+    copyToSandbox,
+    name: "planner",
+    // One iteration is enough: the planner just needs to read and reason,
+    // not write code.
+    maxIterations: 1,
+    // Opus for planning: dependency analysis benefits from deeper reasoning.
+    model: "claude-opus-4-6",
+    promptFile: "./.sandcastle/plan-prompt.md",
+  });
+
+  // Extract the <plan>…</plan> block from the agent's stdout.
+  const planMatch = plan.stdout.match(/<plan>([\s\S]*?)<\/plan>/);
+  if (!planMatch) {
+    throw new Error(
+      "Planning agent did not produce a <plan> tag.\n\n" + plan.stdout,
+    );
+  }
+
+  // The plan JSON contains an array of issues, each with number, title, branch.
+  const { issues } = JSON.parse(planMatch[1]!) as {
+    issues: { number: number; title: string; branch: string }[];
+  };
+
+  if (issues.length === 0) {
+    // No unblocked work — either everything is done or everything is blocked.
+    console.log("No unblocked issues to work on. Exiting.");
+    break;
+  }
+
+  console.log(
+    `Planning complete. ${issues.length} issue(s) to work in parallel:`,
+  );
+  for (const issue of issues) {
+    console.log(`  #${issue.number}: ${issue.title} → ${issue.branch}`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Phase 2: Execute
+  //
+  // Spawn one sonnet agent per issue, all running concurrently.
+  // Each agent works on its own branch so there are no conflicts during
+  // execution — merging happens in Phase 3.
+  //
+  // Promise.allSettled means one failing agent doesn't cancel the others.
+  // -------------------------------------------------------------------------
+  const settled = await Promise.allSettled(
+    issues.map((issue) =>
+      sandcastle.run({
+        hooks,
+        copyToSandbox,
+        name: "implementer",
+        // Give each agent plenty of room to implement and iterate on tests.
+        maxIterations: 100,
+        // Sonnet for execution: fast and capable enough for typical issue work.
+        model: "claude-sonnet-4-6",
+        promptFile: "./.sandcastle/implement-prompt.md",
+        // Prompt arguments substitute {{ISSUE_NUMBER}}, {{ISSUE_TITLE}},
+        // and {{BRANCH}} placeholders in implement-prompt.md before the
+        // agent sees the prompt.
+        promptArgs: {
+          ISSUE_NUMBER: String(issue.number),
+          ISSUE_TITLE: issue.title,
+          BRANCH: issue.branch,
+        },
+        // Each agent starts on its own branch.
+        branch: issue.branch,
+      }),
+    ),
+  );
+
+  // Log any agents that threw (network error, sandbox crash, etc.).
+  for (const [i, outcome] of settled.entries()) {
+    if (outcome.status === "rejected") {
+      console.error(
+        `  ✗ #${issues[i]!.number} (${issues[i]!.branch}) failed: ${outcome.reason}`,
+      );
+    }
+  }
+
+  // Only pass branches that actually produced commits to the merge phase.
+  // An agent that ran successfully but made no commits has nothing to merge.
+  const completedIssues = settled
+    .map((outcome, i) => ({ outcome, issue: issues[i]! }))
+    .filter(
+      (
+        entry,
+      ): entry is {
+        outcome: PromiseFulfilledResult<
+          Awaited<ReturnType<typeof sandcastle.run>>
+        >;
+        issue: (typeof issues)[number];
+      } =>
+        entry.outcome.status === "fulfilled" &&
+        entry.outcome.value.commits.length > 0,
+    )
+    .map((entry) => entry.issue);
+
+  const completedBranches = completedIssues.map((i) => i.branch);
+
+  console.log(
+    `\nExecution complete. ${completedBranches.length} branch(es) with commits:`,
+  );
+  for (const branch of completedBranches) {
+    console.log(`  ${branch}`);
+  }
+
+  if (completedBranches.length === 0) {
+    // All agents ran but none made commits — nothing to merge this cycle.
+    console.log("No commits produced. Nothing to merge.");
+    continue;
+  }
+
+  // -------------------------------------------------------------------------
+  // Phase 3: Merge
+  //
+  // One sonnet agent merges all completed branches into the current branch,
+  // resolving any conflicts and running tests to confirm everything still works.
+  //
+  // The {{BRANCHES}} and {{ISSUES}} prompt arguments are lists that the agent
+  // uses to know which branches to merge and which issues to close.
+  // -------------------------------------------------------------------------
+  await sandcastle.run({
+    hooks,
+    copyToSandbox,
+    name: "merger",
+    maxIterations: 10,
+    // Sonnet is sufficient for merge conflict resolution.
+    model: "claude-sonnet-4-6",
+    promptFile: "./.sandcastle/merge-prompt.md",
+    promptArgs: {
+      // A markdown list of branch names, one per line.
+      BRANCHES: completedBranches.map((b) => `- ${b}`).join("\n"),
+      // A markdown list of issue numbers and titles, one per line.
+      ISSUES: completedIssues
+        .map((i) => `- #${i.number}: ${i.title}`)
+        .join("\n"),
+    },
+  });
+
+  console.log("\nBranches merged.");
+}
+
+console.log("\nAll done.");

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

@@ -0,0 +1,22 @@
+# 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 `npx vitest run` 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. Here are all the issues:
+
+{{ISSUES}}
+
+Once you've merged everything you can, output <promise>COMPLETE</promise>.

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

@@ -0,0 +1,33 @@
+# ISSUES
+
+Here are the open issues in the repo:
+
+<issues-json>
+
+!`gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`
+
+</issues-json>
+
+# 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 format `sandcastle/issue-{number}-{slug}`.
+
+# OUTPUT
+
+Output your plan as a JSON object wrapped in `<plan>` tags:
+
+<plan>
+{"issues": [{"number": 42, "title": "Fix auth bug", "branch": "sandcastle/issue-42-fix-auth-bug"}]}
+</plan>
+
+Include only unblocked issues. If every issue is blocked, include the single highest-priority candidate (the one with the fewest or weakest dependencies).

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

@@ -0,0 +1,4 @@
+{
+  "name": "parallel-planner",
+  "description": "Plans parallelizable issues, executes on separate branches, merges"
+}