@ai-hero/sandcastle 0.0.1

package/README.md

@@ -0,0 +1,284 @@
+# Sandcastle
+
+A TypeScript CLI for orchestrating AI coding agents in isolated Docker containers. Sandcastle handles the hard parts — building worktrees, invoking the agent, and merging commits back — so you can run AFK agents with a single `run()`.
+
+## Prerequisites
+
+- [Docker Desktop](https://www.docker.com/)
+- [Git](https://git-scm.com/)
+
+## Installation
+
+```bash
+pnpm add @ai-hero/sandcastle
+```
+
+## Quick start
+
+```bash
+# 1. Initialize — scaffolds .sandcastle/ config directory and builds the Docker image
+cd /path/to/your/repo
+npx sandcastle init
+
+# 2. Set up environment variables in .sandcastle/.env
+cp .sandcastle/.env.example .sandcastle/.env
+# Edit .sandcastle/.env and fill in your values
+```
+
+```typescript
+// 3. Run the agent via the JS API
+import { run } from "@ai-hero/sandcastle";
+
+await run({
+  promptFile: ".sandcastle/prompt.md",
+});
+```
+
+```bash
+npx tsx main.ts
+```
+
+## CLI commands
+
+### `sandcastle init`
+
+Scaffolds the `.sandcastle/` config directory and builds the Docker image. This is the first command you run in a new repo.
+
+| Option         | Required | Default            | Description                                |
+| -------------- | -------- | ------------------ | ------------------------------------------ |
+| `--image-name` | No       | `sandcastle:local` | Docker image name                          |
+| `--agent`      | No       | `claude-code`      | Agent provider to use (e.g. `claude-code`) |
+
+Creates the following files:
+
+```
+.sandcastle/
+├── Dockerfile      # Sandbox environment (customize as needed)
+├── prompt.md       # Agent instructions
+├── .env.example    # Token placeholders
+└── .gitignore      # Ignores .env, patches/, logs/
+```
+
+Errors if `.sandcastle/` already exists to prevent overwriting customizations.
+
+### `sandcastle build-image`
+
+Rebuilds the Docker image from an existing `.sandcastle/` directory. Use this after modifying the Dockerfile.
+
+| Option         | Required | Default            | Description                                                                       |
+| -------------- | -------- | ------------------ | --------------------------------------------------------------------------------- |
+| `--image-name` | No       | `sandcastle:local` | Docker image name                                                                 |
+| `--dockerfile` | No       | —                  | Path to a custom Dockerfile (build context will be the current working directory) |
+
+### `sandcastle interactive`
+
+Opens an interactive Claude Code session inside the sandbox. Syncs your repo in, launches Claude with TTY passthrough, and syncs changes back when you exit.
+
+| Option         | Required | Default            | Description                |
+| -------------- | -------- | ------------------ | -------------------------- |
+| `--image-name` | No       | `sandcastle:local` | Docker image name          |
+| `--model`      | No       | `claude-opus-4-6`  | Model to use for the agent |
+| `--agent`      | No       | `claude-code`      | Agent provider to use      |
+
+### `sandcastle remove-image`
+
+Removes the Docker image.
+
+| Option         | Required | Default            | Description       |
+| -------------- | -------- | ------------------ | ----------------- |
+| `--image-name` | No       | `sandcastle:local` | Docker image name |
+
+## Prompts
+
+Sandcastle uses a flexible prompt system. You write the prompt, and the engine executes it — no opinions about workflow, task management, or context sources are imposed.
+
+### Prompt resolution
+
+The prompt is resolved from one of three sources (in order of precedence):
+
+1. `prompt: "inline string"` — pass an inline prompt directly via `RunOptions`
+2. `promptFile: "./path/to/prompt.md"` — point to a specific file via `RunOptions`
+3. `.sandcastle/prompt.md` — default location (created by `sandcastle init`)
+
+`prompt` and `promptFile` are mutually exclusive — providing both is an error.
+
+### Dynamic context with `` !`command` ``
+
+Use `` !`command` `` expressions in your prompt to pull in dynamic context. Each expression is replaced with the command's stdout before the prompt is sent to the agent.
+
+Commands run **inside the sandbox** after sync-in and `onSandboxReady` hooks, so they see the same repo state the agent sees (including installed dependencies).
+
+```markdown
+# Open issues
+
+!`gh issue list --state open --json number,title,body,comments,labels --limit 20`
+
+# Recent commits
+
+!`git log --oneline -10`
+```
+
+If any command exits with a non-zero code, the run fails immediately with an error.
+
+### Prompt arguments with `{{KEY}}`
+
+Use `{{KEY}}` placeholders in your prompt to inject values from the `promptArgs` option. This is useful for reusing the same prompt file across multiple runs with different parameters.
+
+```typescript
+import { run } from "@ai-hero/sandcastle";
+
+await run({
+  promptFile: "./my-prompt.md",
+  promptArgs: { ISSUE_NUMBER: 42, PRIORITY: "high" },
+});
+```
+
+In the prompt file:
+
+```markdown
+Work on issue #{{ISSUE_NUMBER}} (priority: {{PRIORITY}}).
+```
+
+Prompt argument substitution runs on the host before shell expression expansion, so `{{KEY}}` placeholders inside `` !`command` `` expressions are replaced first:
+
+```markdown
+!`gh issue view {{ISSUE_NUMBER}} --json body -q .body`
+```
+
+A `{{KEY}}` placeholder with no matching prompt argument is an error. Unused prompt arguments produce a warning.
+
+### Early termination with `<promise>COMPLETE</promise>`
+
+When the agent outputs `<promise>COMPLETE</promise>`, the orchestrator stops the iteration loop early. This is a convention you document in your prompt for the agent to follow — the engine never injects it.
+
+This is useful for task-based workflows where the agent should stop once it has finished, rather than running all remaining iterations.
+
+### Templates
+
+`sandcastle init` prompts you to choose a template, which scaffolds a ready-to-use prompt and `main.ts` suited to a specific workflow. Four templates are available:
+
+| Template              | Description                                                             |
+| --------------------- | ----------------------------------------------------------------------- |
+| `blank`               | Bare scaffold — write your own prompt and orchestration                 |
+| `simple-loop`         | Picks GitHub issues one by one and closes them                          |
+| `sequential-reviewer` | Implements issues one by one, with a code review step after each        |
+| `parallel-planner`    | Plans parallelizable issues, executes on separate branches, then merges |
+
+Select a template during `sandcastle init` when prompted, or re-run init in a fresh repo to try a different one.
+
+## Node API
+
+Sandcastle exports a programmatic `run()` function for use in Node.js scripts, CI pipelines, or custom tooling.
+
+```typescript
+import { run } from "@ai-hero/sandcastle";
+
+const result = await run({
+  promptFile: "./my-prompt.md",
+  maxIterations: 3,
+  branch: "agent/fix-123",
+});
+
+console.log(result.iterationsRun); // number of iterations executed
+console.log(result.wasCompletionSignalDetected); // true if agent emitted <promise>COMPLETE</promise>
+console.log(result.commits); // array of { sha } for commits created
+console.log(result.branch); // target branch name
+```
+
+### `RunOptions`
+
+| Option             | Type       | Default                       | Description                                                    |
+| ------------------ | ---------- | ----------------------------- | -------------------------------------------------------------- |
+| `prompt`           | string     | —                             | Inline prompt (mutually exclusive with `promptFile`)           |
+| `promptFile`       | string     | `.sandcastle/prompt.md`       | Path to prompt file (mutually exclusive with `prompt`)         |
+| `maxIterations`    | number     | `5`                           | Maximum iterations to run                                      |
+| `hooks`            | object     | —                             | Lifecycle hooks (`onSandboxReady`)                             |
+| `branch`           | string     | —                             | Target branch for sandbox work                                 |
+| `model`            | string     | `claude-opus-4-6`             | Model to use for the agent                                     |
+| `agent`            | string     | `claude-code`                 | Agent provider name                                            |
+| `imageName`        | string     | `sandcastle:local`            | Docker image name for the sandbox                              |
+| `promptArgs`       | PromptArgs | —                             | Key-value map for `{{KEY}}` placeholder substitution           |
+| `logging`          | object     | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`               |
+| `completionSignal` | string     | `<promise>COMPLETE</promise>` | Custom string the agent emits to stop the iteration loop early |
+| `timeoutSeconds`   | number     | `900`                         | Timeout for the entire run in seconds                          |
+
+### `RunResult`
+
+| Field                         | Type        | Description                                        |
+| ----------------------------- | ----------- | -------------------------------------------------- |
+| `iterationsRun`               | number      | Number of iterations that were executed            |
+| `wasCompletionSignalDetected` | boolean     | Whether the agent signaled completion              |
+| `stdout`                      | string      | Agent output                                       |
+| `commits`                     | `{ sha }[]` | Commits created during the run                     |
+| `branch`                      | string      | Target branch name                                 |
+| `logFilePath`                 | string?     | Path to the log file (only when logging to a file) |
+
+Environment variables are resolved automatically from `.sandcastle/.env` and `process.env` — no need to pass them to the API. The required variables depend on the **agent provider** (see `sandcastle init` output for details).
+
+## Configuration
+
+### Config directory (`.sandcastle/`)
+
+All per-repo sandbox configuration lives in `.sandcastle/`. Run `sandcastle init` to create it.
+
+### Custom Dockerfile
+
+The `.sandcastle/Dockerfile` controls the sandbox environment. The default template installs:
+
+- **Node.js 22** (base image)
+- **git**, **curl**, **jq** (system dependencies)
+- **GitHub CLI** (`gh`)
+- **Claude Code CLI**
+- A non-root `agent` user (required — Claude runs as this user)
+
+When customizing the Dockerfile, ensure you keep:
+
+- A non-root user (the default `agent` user) for Claude to run as
+- `git` (required for sync-in/sync-out)
+- `gh` (required for issue fetching)
+- Claude Code CLI installed and on PATH
+
+Add your project-specific dependencies (e.g., language runtimes, build tools) to the Dockerfile as needed.
+
+### Hooks
+
+Hooks are arrays of `{ "command": "..." }` objects executed sequentially inside the sandbox. If any command exits with a non-zero code, execution stops immediately with an error.
+
+| Hook             | When it runs            | Working directory      |
+| ---------------- | ----------------------- | ---------------------- |
+| `onSandboxReady` | After sync-in completes | Sandbox repo directory |
+
+**`onSandboxReady`** runs after the repo is synced in. Use it for dependency installation or build steps (e.g., `npm install`).
+
+Pass hooks programmatically via `run()`:
+
+```ts
+await run({
+  hooks: {
+    onSandboxReady: [{ command: "npm install" }],
+  },
+  // ...
+});
+```
+
+## How it works
+
+Sandcastle uses git primitives for reliable repo synchronization:
+
+- **Sync-in**: Creates a `git bundle` on your host capturing all refs (including unpushed commits), copies it into the sandbox, and unpacks it. The sandbox always matches your host's committed state.
+- **Sync-out**: Runs `git format-patch` inside the sandbox to extract new commits, copies the patches to your host, and applies them with `git am --3way`. Uncommitted changes (staged, unstaged, and untracked files) are also captured.
+
+This approach avoids GitHub round-trips and produces clean, replayable commit history.
+
+## Development
+
+```bash
+npm install
+npm run build    # Build with tsgo
+npm test         # Run tests with vitest
+npm run typecheck # Type-check
+```
+
+## License
+
+MIT

package/dist/AgentProvider.d.ts

@@ -0,0 +1,8 @@
+export interface AgentProvider {
+    readonly name: string;
+    readonly envManifest: Record<string, string>;
+    readonly dockerfileTemplate: string;
+}
+export declare const claudeCodeProvider: AgentProvider;
+export declare const getAgentProvider: (name: string) => AgentProvider;
+//# sourceMappingURL=AgentProvider.d.ts.map

package/dist/AgentProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentProvider.d.ts","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AA2CD,eAAO,MAAM,kBAAkB,EAAE,aAShC,CAAC;AAMF,eAAO,MAAM,gBAAgB,iCAQ5B,CAAC"}

package/dist/AgentProvider.js

@@ -0,0 +1,60 @@
+import { SANDBOX_WORKSPACE_DIR } from "./SandboxFactory.js";
+const CLAUDE_CODE_DOCKERFILE = `FROM node:22-bookworm
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \\
+  git \\
+  curl \\
+  jq \\
+  && rm -rf /var/lib/apt/lists/*
+
+# Enable corepack (pnpm, yarn)
+RUN corepack enable
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \\
+  | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \\
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \\
+  | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \\
+  && apt-get update && apt-get install -y gh \\
+  && rm -rf /var/lib/apt/lists/*
+
+# Create a non-root user for Claude to run as
+RUN useradd -m -s /bin/bash agent
+USER agent
+
+# Install Claude Code CLI
+RUN curl -fsSL https://claude.ai/install.sh | bash
+
+# Add Claude to PATH
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+# Create repos directory
+RUN mkdir -p /home/agent/repos
+
+WORKDIR /home/agent
+
+# In worktree sandbox mode, Sandcastle bind-mounts the git worktree at ${SANDBOX_WORKSPACE_DIR}
+# and overrides the working directory to ${SANDBOX_WORKSPACE_DIR} at container start.
+# Structure your Dockerfile so that ${SANDBOX_WORKSPACE_DIR} can serve as the project root.
+ENTRYPOINT ["sleep", "infinity"]
+`;
+export const claudeCodeProvider = {
+    name: "claude-code",
+    envManifest: {
+        ANTHROPIC_API_KEY: "Anthropic API key",
+        GH_TOKEN: "GitHub personal access token",
+    },
+    dockerfileTemplate: CLAUDE_CODE_DOCKERFILE,
+};
+const AGENT_REGISTRY = {
+    "claude-code": claudeCodeProvider,
+};
+export const getAgentProvider = (name) => {
+    const provider = AGENT_REGISTRY[name];
+    if (!provider) {
+        throw new Error(`Unknown agent provider: "${name}". Available providers: ${Object.keys(AGENT_REGISTRY).join(", ")}`);
+    }
+    return provider;
+};
+//# sourceMappingURL=AgentProvider.js.map

package/dist/AgentProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentProvider.js","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAQ5D,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yEAmC0C,qBAAqB;2CACnD,qBAAqB;sCAC1B,qBAAqB;;CAE1D,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAkB;IAC/C,IAAI,EAAE,aAAa;IAEnB,WAAW,EAAE;QACX,iBAAiB,EAAE,mBAAmB;QACtC,QAAQ,EAAE,8BAA8B;KACzC;IAED,kBAAkB,EAAE,sBAAsB;CAC3C,CAAC;AAEF,MAAM,cAAc,GAAkC;IACpD,aAAa,EAAE,kBAAkB;CAClC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAiB,EAAE;IAC9D,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,4BAA4B,IAAI,2BAA2B,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpG,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC"}

package/dist/Config.d.ts

@@ -0,0 +1,35 @@
+import { FileSystem } from "@effect/platform";
+import { Effect, Schema } from "effect";
+declare const HookDefinition: Schema.Struct<{
+    command: typeof Schema.String;
+}>;
+declare const SandcastleConfigSchema: Schema.Struct<{
+    hooks: Schema.optional<Schema.Struct<{
+        onSandboxReady: Schema.optional<Schema.Array$<Schema.Struct<{
+            command: typeof Schema.String;
+        }>>>;
+    }>>;
+    defaultMaxIterations: Schema.optional<typeof Schema.Number>;
+    model: Schema.optional<typeof Schema.String>;
+    agent: Schema.optional<typeof Schema.String>;
+    imageName: Schema.optional<typeof Schema.String>;
+}>;
+export type HookDefinition = typeof HookDefinition.Type;
+export type SandcastleConfig = typeof SandcastleConfigSchema.Type;
+export declare class ConfigError extends Error {
+    readonly _tag = "ConfigError";
+    constructor(message: string);
+}
+export declare const readConfig: (repoDir: string) => Effect.Effect<{
+    readonly hooks?: {
+        readonly onSandboxReady?: readonly {
+            readonly command: string;
+        }[] | undefined;
+    } | undefined;
+    readonly defaultMaxIterations?: number | undefined;
+    readonly model?: string | undefined;
+    readonly agent?: string | undefined;
+    readonly imageName?: string | undefined;
+}, ConfigError, FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=Config.d.ts.map

package/dist/Config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../src/Config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGxC,QAAA,MAAM,cAAc;;EAEuB,CAAC;AAE5C,QAAA,MAAM,sBAAsB;;;;;;;;;;EAUiB,CAAC;AAE9C,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AACxD,MAAM,MAAM,gBAAgB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAC;AAElE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAUD,eAAO,MAAM,UAAU;;;;;;;;;;sCAoCnB,CAAC"}

package/dist/Config.js

@@ -0,0 +1,56 @@
+import { FileSystem } from "@effect/platform";
+import { Effect, Schema } from "effect";
+import { join } from "node:path";
+const HookDefinition = Schema.Struct({
+    command: Schema.String,
+}).annotations({ title: "HookDefinition" });
+const SandcastleConfigSchema = Schema.Struct({
+    hooks: Schema.optional(Schema.Struct({
+        onSandboxReady: Schema.optional(Schema.Array(HookDefinition)),
+    })),
+    defaultMaxIterations: Schema.optional(Schema.Number),
+    model: Schema.optional(Schema.String),
+    agent: Schema.optional(Schema.String),
+    imageName: Schema.optional(Schema.String),
+}).annotations({ title: "SandcastleConfig" });
+export class ConfigError extends Error {
+    _tag = "ConfigError";
+    constructor(message) {
+        super(message);
+    }
+}
+const RENAMED_KEYS = {
+    defaultIterations: "defaultMaxIterations",
+};
+const decodeConfig = Schema.decodeUnknownEither(SandcastleConfigSchema, {
+    onExcessProperty: "error",
+});
+export const readConfig = (repoDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const content = yield* fs
+        .readFileString(join(repoDir, ".sandcastle", "config.json"))
+        .pipe(Effect.catchAll(() => Effect.succeed(null)));
+    if (content === null)
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(content);
+    }
+    catch {
+        return yield* Effect.fail(new ConfigError("Invalid JSON in config.json"));
+    }
+    // Check for renamed keys and produce clear errors
+    if (typeof raw === "object" && raw !== null) {
+        for (const [oldKey, newKey] of Object.entries(RENAMED_KEYS)) {
+            if (oldKey in raw) {
+                return yield* Effect.fail(new ConfigError(`"${oldKey}" has been renamed to "${newKey}" in config.json. Please update your config.`));
+            }
+        }
+    }
+    const result = decodeConfig(raw);
+    if (result._tag === "Left") {
+        return yield* Effect.fail(new ConfigError(result.left.message));
+    }
+    return result.right;
+});
+//# sourceMappingURL=Config.js.map

package/dist/Config.js.map

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

package/dist/CopyToSandbox.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+/**
+ * Copy files and directories from the host repo root to the worktree root,
+ * using `cp -R --reflink=auto` for copy-on-write when the filesystem supports it.
+ * Missing paths are silently skipped.
+ */
+export declare const copyToSandbox: (paths: string[], hostRepoDir: string, worktreePath: string) => Effect.Effect<void, never, never>;
+//# sourceMappingURL=CopyToSandbox.d.ts.map

package/dist/CopyToSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CopyToSandbox.d.ts","sourceRoot":"","sources":["../src/CopyToSandbox.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;GAIG;AACH,eAAO,MAAM,aAAa,mGAyBtB,CAAC"}

package/dist/CopyToSandbox.js

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Effect } from "effect";
+/**
+ * Copy files and directories from the host repo root to the worktree root,
+ * using `cp -R --reflink=auto` for copy-on-write when the filesystem supports it.
+ * Missing paths are silently skipped.
+ */
+export const copyToSandbox = (paths, hostRepoDir, worktreePath) => Effect.gen(function* () {
+    for (const relativePath of paths) {
+        const src = join(hostRepoDir, relativePath);
+        if (!existsSync(src)) {
+            continue;
+        }
+        const dest = join(worktreePath, relativePath);
+        yield* Effect.async((resume) => {
+            execFile("cp", ["-R", "--reflink=auto", src, dest], (error) => {
+                if (error) {
+                    // Fall back to a regular copy if reflink is not supported
+                    execFile("cp", ["-R", src, dest], () => {
+                        resume(Effect.succeed(undefined));
+                    });
+                }
+                else {
+                    resume(Effect.succeed(undefined));
+                }
+            });
+        });
+    }
+});
+//# sourceMappingURL=CopyToSandbox.js.map

package/dist/CopyToSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CopyToSandbox.js","sourceRoot":"","sources":["../src/CopyToSandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,KAAe,EACf,WAAmB,EACnB,YAAoB,EACQ,EAAE,CAC9B,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,MAAM,YAAY,IAAI,KAAK,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAC5C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC9C,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAc,CAAC,MAAM,EAAE,EAAE;YAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC5D,IAAI,KAAK,EAAE,CAAC;oBACV,0DAA0D;oBAC1D,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE;wBACrC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;oBACpC,CAAC,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/Display.d.ts

@@ -0,0 +1,52 @@
+import { FileSystem } from "@effect/platform";
+import { Context, Effect, Layer, Ref } from "effect";
+export type Severity = "info" | "success" | "warn" | "error";
+export type DisplayEntry = {
+    readonly _tag: "intro";
+    readonly title: string;
+} | {
+    readonly _tag: "status";
+    readonly message: string;
+    readonly severity: Severity;
+} | {
+    readonly _tag: "spinner";
+    readonly message: string;
+} | {
+    readonly _tag: "summary";
+    readonly title: string;
+    readonly rows: Record<string, string>;
+} | {
+    readonly _tag: "taskLog";
+    readonly title: string;
+    readonly messages: ReadonlyArray<string>;
+} | {
+    readonly _tag: "text";
+    readonly message: string;
+};
+export interface DisplayService {
+    readonly intro: (title: string) => Effect.Effect<void>;
+    readonly status: (message: string, severity: Severity) => Effect.Effect<void>;
+    readonly spinner: <A, E, R>(message: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    readonly summary: (title: string, rows: Record<string, string>) => Effect.Effect<void>;
+    readonly taskLog: <A, E, R>(title: string, effect: (message: (msg: string) => void) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    readonly text: (message: string) => Effect.Effect<void>;
+}
+declare const Display_base: Context.TagClass<Display, "Display", DisplayService>;
+export declare class Display extends Display_base {
+}
+export declare const SilentDisplay: {
+    layer: (ref: Ref.Ref<readonly DisplayEntry[]>) => Layer.Layer<Display, never, never>;
+};
+export declare const FileDisplay: {
+    layer: (filePath: string) => Layer.Layer<Display, never, FileSystem.FileSystem>;
+};
+export declare const terminalStyle: {
+    status: (message: string) => string;
+    summaryTitle: (title: string) => string;
+    summaryRow: (key: string, value: string) => string;
+};
+export declare const ClackDisplay: {
+    layer: Layer.Layer<Display, never, never>;
+};
+export {};
+//# sourceMappingURL=Display.d.ts.map

package/dist/Display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Display.d.ts","sourceRoot":"","sources":["../src/Display.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAGrD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAEvD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE9E,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5B,QAAQ,CAAC,OAAO,EAAE,CAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACzB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAEzB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACxB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC/D,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5B,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACzD;;AAED,qBAAa,OAAQ,SAAQ,YAG1B;CAAG;AAEN,eAAO,MAAM,aAAa;;CAuDzB,CAAC;AAEF,eAAO,MAAM,WAAW;;CA6DvB,CAAC;AASF,eAAO,MAAM,aAAa;;;;CAKzB,CAAC;AAEF,eAAO,MAAM,YAAY;;CAoDxB,CAAC"}