@rockclaver/sandcastle 0.7.0 → 0.8.1

package/README.md

@@ -30,13 +30,13 @@ Sandcastle is provider-agnostic — it ships with built-in providers for Docker,
 1. Install the package:
 
 ```bash
-npm install --save-dev @ai-hero/sandcastle
+npm install --save-dev @rockclaver/sandcastle
 ```
 
-2. Run `npx @ai-hero/sandcastle init`. This scaffolds a `.sandcastle` directory with all the files needed.
+2. Run `npx @rockclaver/sandcastle init`. This scaffolds a `.sandcastle` directory with all the files needed.
 
 ```bash
-npx @ai-hero/sandcastle init
+npx @rockclaver/sandcastle init
 ```
 
 3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`. If you want to use your Claude subscription instead of an API key, see [#191](https://github.com/mattpocock/sandcastle/issues/191).
@@ -53,8 +53,8 @@ npx tsx .sandcastle/main.ts
 
 ```typescript
 // 3. Run the agent via the JS API
-import { run, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { run, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 await run({
   agent: claudeCode("claude-opus-4-7"),
@@ -67,20 +67,20 @@ await run({
 
 Sandcastle uses a `SandboxProvider` to create isolated environments. The `sandbox` option on `run()`, `interactive()`, and `createSandbox()` accepts any provider, including `noSandbox()` — opt in to running the agent directly on the host when container isolation is undesired. Built-in providers:
 
-| Provider   | Import path                                | Type       | Accepted by                                 |
-| ---------- | ------------------------------------------ | ---------- | ------------------------------------------- |
-| Docker     | `@ai-hero/sandcastle/sandboxes/docker`     | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
-| Podman     | `@ai-hero/sandcastle/sandboxes/podman`     | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
-| Vercel     | `@ai-hero/sandcastle/sandboxes/vercel`     | Isolated   | `run()`, `createSandbox()`, `interactive()` |
-| No-sandbox | `@ai-hero/sandcastle/sandboxes/no-sandbox` | None       | `run()`, `createSandbox()`, `interactive()` |
+| Provider   | Import path                                   | Type       | Accepted by                                 |
+| ---------- | --------------------------------------------- | ---------- | ------------------------------------------- |
+| Docker     | `@rockclaver/sandcastle/sandboxes/docker`     | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
+| Podman     | `@rockclaver/sandcastle/sandboxes/podman`     | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
+| Vercel     | `@rockclaver/sandcastle/sandboxes/vercel`     | Isolated   | `run()`, `createSandbox()`, `interactive()` |
+| No-sandbox | `@rockclaver/sandcastle/sandboxes/no-sandbox` | None       | `run()`, `createSandbox()`, `interactive()` |
 
 Worktree methods (`wt.run()`, `wt.interactive()`, `wt.createSandbox()`) accept the same providers as their top-level counterparts. `wt.interactive()` defaults to `noSandbox()` when no sandbox is specified.
 
 ```typescript
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
-import { podman } from "@ai-hero/sandcastle/sandboxes/podman";
-import { vercel } from "@ai-hero/sandcastle/sandboxes/vercel";
-import { noSandbox } from "@ai-hero/sandcastle/sandboxes/no-sandbox";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
+import { podman } from "@rockclaver/sandcastle/sandboxes/podman";
+import { vercel } from "@rockclaver/sandcastle/sandboxes/vercel";
+import { noSandbox } from "@rockclaver/sandcastle/sandboxes/no-sandbox";
 
 // Docker, Podman, and Vercel are interchangeable in run() and createSandbox():
 await run({
@@ -106,8 +106,8 @@ You can also [create your own provider](#custom-sandbox-providers) using `create
 Sandcastle exports a programmatic `run()` function for use in scripts, CI pipelines, or custom tooling. The examples below use `docker()`, but any `SandboxProvider` works in its place.
 
 ```typescript
-import { run, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { run, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 const result = await run({
   agent: claudeCode("claude-opus-4-7"),
@@ -124,8 +124,8 @@ console.log(result.branch); // target branch name
 ### All options
 
 ```typescript
-import { run, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { run, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 const result = await run({
   // Agent provider — required. Pass a model string to claudeCode().
@@ -261,8 +261,8 @@ Use `run()` instead when you only need a single one-shot invocation — it handl
 #### Basic single-run usage
 
 ```typescript
-import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { createSandbox, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
@@ -280,8 +280,8 @@ console.log(result.commits); // [{ sha: "abc123" }]
 #### Multi-run implement-then-review
 
 ```typescript
-import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { createSandbox, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
@@ -386,7 +386,7 @@ Only `branch` and `merge-to-head` strategies are accepted; `head` is a compile-t
 Pass `cwd` to target a repo other than `process.cwd()`. Relative paths resolve against `process.cwd()`; absolute paths pass through. A `CwdError` is thrown if the path does not exist or is not a directory.
 
 ```typescript
-import { createWorktree } from "@ai-hero/sandcastle";
+import { createWorktree } from "@rockclaver/sandcastle";
 
 await using wt = await createWorktree({
   branchStrategy: { type: "branch", branch: "agent/fix-42" },
@@ -413,7 +413,7 @@ const result = await wt.run({
 console.log(result.commits); // commits made during the run
 
 // Create a long-lived sandbox from the worktree
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 await using sandbox = await wt.createSandbox({
   sandbox: docker(),
@@ -558,7 +558,7 @@ If any command exits with a non-zero code, the run fails immediately with an err
 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";
+import { run } from "@rockclaver/sandcastle";
 
 await run({
   promptFile: "./my-prompt.md",
@@ -646,8 +646,8 @@ This is independent of `idleTimeoutSeconds`. They cover different phases: `idleT
 Use `Output.object()` to extract a typed, schema-validated JSON payload from the agent's stdout. The agent emits its answer inside an XML tag you specify, and Sandcastle parses, validates, and returns it on `result.output`. The schema can be any [Standard Schema](https://standardschema.dev) validator — the examples below use [Zod](https://zod.dev), but Valibot, ArkType, and others work identically. See [ADR 0010](docs/adr/0010-structured-output.md) for design rationale.
 
 ```ts
-import { run, Output, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { run, Output, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 import { z } from "zod";
 
 const result = await run({
@@ -672,7 +672,7 @@ console.log(result.output.score); // typed as number
 When extraction or validation fails, `run()` throws a `StructuredOutputError`. Alongside `tag`, `rawMatched`, `cause`, `commits`, `branch`, and `preservedWorktreePath`, the error carries the `sessionId` (and `sessionFilePath`, when the session was captured) of the run that produced the bad output. You can resume that session to ask the agent to re-emit corrected output, without repeating the work:
 
 ```ts
-import { run, Output, StructuredOutputError } from "@ai-hero/sandcastle";
+import { run, Output, StructuredOutputError } from "@rockclaver/sandcastle";
 
 try {
   return await run({ ...opts, output });
@@ -689,9 +689,42 @@ try {
 }
 ```
 
+### Profiles
+
+A **profile** describes the language/stack of the repo Sandcastle is operating on, so the scaffolded prompts and `main` setup point your agent at the right toolchain instead of assuming npm. Profiles are an internal registry shipped with Sandcastle — in v1 they are not user-defined config, and selecting one does **not** install, pin, or manage any SDK. The built-in profiles are `js-ts`, `flutter`, `dart`, and `go`.
+
+Select one or more profiles during `sandcastle init`. The interactive prompt is a multi-select with `js-ts` selected by default; non-interactively, pass a comma-separated `--profile` flag:
+
+```bash
+# A Flutter app with a Go backend
+npx @rockclaver/sandcastle init --profile flutter,go
+
+# JS/TS only (the default when --profile is omitted)
+npx @rockclaver/sandcastle init --profile js-ts
+```
+
+Profile names are de-duplicated while preserving first-occurrence order, and an unknown name fails fast with an error listing the valid profiles.
+
+**Repository detection (advisory).** During init, Sandcastle does a shallow scan for stack signals — `package.json`/lockfiles (`js-ts`), `pubspec.yaml` (`flutter` or `dart`), and `go.mod` (`go`) — at the repo root **and** in any paths declared in `.gitmodules`, so signals living in a git submodule are still picked up. If your selected profiles don't match what was detected, init prints a warning and **continues anyway** — monorepos and custom layouts are valid, so detection never blocks scaffolding. It does not perform a full-tree walk, so signals nested in undeclared subdirectories won't be detected and may trigger an advisory mismatch warning.
+
+**Generated guidance files.** Each selected profile scaffolds a guidance markdown file plus a metadata file under `.sandcastle/profiles/`:
+
+```
+.sandcastle/profiles/
+├── profiles.json   # Metadata: selected profiles + the path to each guidance file
+├── flutter.md      # Per-profile guidance (one per selected profile)
+└── go.md
+```
+
+Each `<profile>.md` describes the stack and lists suggested **setup** and **validation** commands (e.g. `flutter pub get` / `flutter analyze` / `flutter test` for Flutter, `go build ./...` / `go vet ./...` / `go test ./...` for Go). `profiles.json` lets templates and tooling discover which profiles were selected and where their guidance lives.
+
+**How agents use them.** Every scaffolded prompt gains a "Project profiles" section that links the generated guidance files and instructs the agent to read each one and follow its setup and validation commands rather than assuming a fixed toolchain. When no JS/TS profile is selected, the generated `main` setup hook runs the primary profile's setup command (e.g. `flutter pub get`, `go mod download`) instead of `npm install`. The commands in the guidance files are advisory, not a contract — the agent should adapt them to the project's actual scripts.
+
+**Out of scope.** Profiles are guidance only. Sandcastle does **not** install Flutter, Dart, or Go; does **not** pin or manage SDK versions; and assumes the relevant toolchain is already available in the sandbox image. Pin or install SDKs yourself by editing the scaffolded `Dockerfile`/`Containerfile`.
+
 ### Templates
 
-`sandcastle init` prompts you to choose a sandbox provider (Docker or Podman), an issue tracker (GitHub Issues, Beads, or Custom), and a template, which scaffolds a ready-to-use prompt and `main.mts` suited to a specific workflow. If your project's `package.json` has `"type": "module"`, the file will be named `main.ts` instead. Choosing **Custom** scaffolds the project in a deliberately broken-until-configured state plus a `.sandcastle/SETUP_ISSUE_TRACKER.md` prompt you feed to your coding agent, which wires up your own tracker by editing the scaffolded files in place. Five templates are available:
+`sandcastle init` prompts you to choose project profiles, a sandbox provider (Docker or Podman), an issue tracker (GitHub Issues, Beads, or Custom), and a template, which scaffolds a ready-to-use prompt and `main.mts` suited to a specific workflow. If your project's `package.json` has `"type": "module"`, the file will be named `main.ts` instead. The scaffolded prompts reference your selected profile guidance under `.sandcastle/profiles/` instead of assuming a fixed toolchain, and when no JS/TS profile is selected the generated `main` setup hook uses that profile's setup command (e.g. `flutter pub get`, `go mod download`) rather than `npm install`. Choosing **Custom** scaffolds the project in a deliberately broken-until-configured state plus a `.sandcastle/SETUP_ISSUE_TRACKER.md` prompt you feed to your coding agent, which wires up your own tracker by editing the scaffolded files in place. Five templates are available:
 
 | Template                       | Description                                                               |
 | ------------------------------ | ------------------------------------------------------------------------- |
@@ -713,11 +746,14 @@ Init detects your host package manager (npm, pnpm, yarn, or bun) from a `package
 
 Every interactive prompt has a paired `--flag` so the entire init can run non-interactively (e.g. in CI or a scripted setup). When stdin is not a TTY and a required flag is missing, init fails fast with a clear error rather than wedging on a prompt.
 
+Init checks common repository signals against selected profiles and prints warning-only feedback when they do not appear to match. For example, selecting `--profile go` in a repo with only `package.json` warns but still scaffolds, so monorepos and custom layouts can continue.
+
 | Option                    | Required | Default                      | Description                                                                                                                                                                        |
 | ------------------------- | -------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--image-name`            | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                                                                                                                                  |
 | `--agent`                 | No       | Interactive multi-select     | One or more agents, comma-separated (e.g. `claude-code,codex`). The first is the generated `agent()` default. Valid: `claude-code`, `pi`, `codex`, `cursor`, `opencode`, `copilot` |
 | `--model`                 | No       | Agent's default model        | Pre-fills `AGENT_MODEL` in `.env.example` (e.g. `claude-sonnet-4-6`). Left commented out when unset                                                                                |
+| `--profile`               | No       | Interactive multi-select     | One or more project profiles, comma-separated (e.g. `js-ts,go`). Non-interactive init defaults to `js-ts` when unset. Valid: `js-ts`, `flutter`, `dart`, `go`                      |
 | `--sandbox`               | No       | Interactive prompt           | Sandbox provider to use (`docker`, `podman`)                                                                                                                                       |
 | `--template`              | No       | Interactive prompt           | Template to scaffold (e.g. `blank`, `simple-loop`)                                                                                                                                 |
 | `--issue-tracker`         | No       | Interactive prompt           | Issue tracker to use (`github-issues`, `beads`, `custom`)                                                                                                                          |
@@ -731,6 +767,7 @@ Creates the following files:
 .sandcastle/
 ├── Dockerfile      # Sandbox environment (customize as needed)
 ├── prompt.md       # Agent instructions
+├── profiles/       # Selected profile metadata and guidance
 ├── .env.example    # Token placeholders
 └── .gitignore      # Ignores .env, logs/
 ```
@@ -898,7 +935,7 @@ const [reviewA, reviewB] = await Promise.all([
 Use `agent()` when the provider should be selected at runtime rather than hard-coded in `main.ts`. The resolver reads `AGENT` to choose a provider, reads `AGENT_MODEL` to override that provider's default model, and falls back to `default` when `AGENT` is unset:
 
 ```typescript
-import { agent, run } from "@ai-hero/sandcastle";
+import { agent, run } from "@rockclaver/sandcastle";
 
 await run({
   agent: agent({
@@ -1019,7 +1056,7 @@ import {
   type BindMountCreateOptions,
   type BindMountSandboxHandle,
   type ExecResult,
-} from "@ai-hero/sandcastle";
+} from "@rockclaver/sandcastle";
 import { execFile, spawn } from "node:child_process";
 import { copyFile as fsCopyFile, mkdir as fsMkdir } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -1119,7 +1156,7 @@ import {
   createIsolatedSandboxProvider,
   type IsolatedSandboxHandle,
   type ExecResult,
-} from "@ai-hero/sandcastle";
+} from "@rockclaver/sandcastle";
 import { execFile, spawn } from "node:child_process";
 import { copyFile, mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -1235,8 +1272,8 @@ A branch strategy controls where the agent's commits land. Configure it when con
 Branch strategy is now configured on `run()`, not on the provider:
 
 ```typescript
-import { run, claudeCode } from "@ai-hero/sandcastle";
-import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { run, claudeCode } from "@rockclaver/sandcastle";
+import { docker } from "@rockclaver/sandcastle/sandboxes/docker";
 
 // head — direct write, bind-mount only (default for bind-mount providers)
 await run({
@@ -1264,7 +1301,7 @@ await run({
 Pass your custom provider via the `sandbox` option — it works the same as the built-in `docker()` provider:
 
 ```typescript
-import { run, claudeCode } from "@ai-hero/sandcastle";
+import { run, claudeCode } from "@rockclaver/sandcastle";
 
 const result = await run({
   agent: claudeCode("claude-opus-4-7"),

package/dist/index.d.ts

@@ -320,7 +320,7 @@ type OutputDefinition = OutputObjectDefinition<any> | OutputStringDefinition;
  * Helpers for declaring structured output on `run()`.
  *
  * ```ts
- * import { Output, run } from "@ai-hero/sandcastle";
+ * import { Output, run } from "@rockclaver/sandcastle";
  * import { z } from "zod";
  *
  * const result = await run({