@snappedly-tools/shipyard 0.6.0 → 0.7.0-staging.36081473933

package/README.md

@@ -8,201 +8,100 @@
 
 [![CI](https://github.com/snappedly/shipyard/actions/workflows/ci.yml/badge.svg)](https://github.com/snappedly/shipyard/actions/workflows/ci.yml)
 
-Give Shipyard a backlog and a policy. It plans dependencies, runs AI coding
-agents in isolated sandboxes, reviews their work, and returns reviewable
-commits—without babysitting.
+Give Shipyard a task or a GitHub issue. It runs Codex or Claude Code in an
+isolated sandbox, can plan and review larger jobs, and brings the result back as
+a commit or pull request you can inspect.
 
 ## The Shipyard advantage
 
-Most agent setups launch a CLI and hope for the best. Shipyard is the control
-plane around the agent:
+- **Isolated work.** Docker keeps the agent's files and Git work inside a
+  sandbox while it runs.
+- **Built for real projects.** Shipyard can sort issue dependencies, work on
+  independent tasks in parallel, and review the combined result.
+- **You stay in control.** Runs have limits and logs. Issue workflows return a
+  pull request for you to review and merge.
 
-- **Protected execution:** Run Codex or Claude Code in an isolated Docker-backed
-  sandbox with explicit mounts, credentials, and network access.
-- **Real orchestration:** Plan dependencies, parallelize safe work, leave
-  blocked work alone, review each branch, and merge completed work.
-- **Failure-aware by design:** Use finite budgets, no-progress detection,
-  cancellation, logs, and recovery artifacts instead of runaway loops.
-- **Reviewable output:** Runs preserve branches, worktrees, logs, and evidence;
-  completed work comes back as commits. You keep control of the repository and
-  the final release.
+## Try it on one task
 
-## Install and run
+You need **Node.js 20.18.1+**, **Git**, **Docker running**, and **Codex or Claude Code**
+with a subscription login or API key.
 
-Before running Shipyard, install the [Snappedly skills](https://github.com/snappedly/skills)
-and run `setup-snapedly-skills` in the target repository.
+Run:
 
-Requirements: Node.js 20.18.1+, Git, Docker, and credentials for your chosen
-agent. Run these commands in the repository Shipyard should change:
+```sh
+npx skills add snappedly/skills
+```
+
+Ask your coding agent to run `setup-snappedly-skills` in that repository.
 
 ```sh
 npm install --save-dev @snappedly-tools/shipyard
 npx shipyard init
 ```
 
-`init` asks for the agent, authentication, sandbox, issue tracker, and workflow
-template, then creates `.shipyard/`. For the first run, choose Docker and
-`blank` or `sequential-reviewer`.
+During `shipyard init`, choose your agent, **Docker**, the template you want, and install the optional
+[repository runner](docs/content/docs/repository-runner.mdx). Follow
+the authentication prompts.
 
-Add the requested credentials to `.shipyard/.env`, write a task in
-`.shipyard/prompt.md` when using the `blank` template, then run:
+On a local Mac, the repository runner automatically wakes Shipyard when you label an issue.
+It runs as long as its terminal stays open.
 
-```sh
-npx shipyard run
-```
+See the [getting started guide](docs/content/docs/index.mdx) for authentication and
+branch options.
+
+Fill in any credentials required in `.shipyard/.env`.
+`GH_TOKEN` in `.shipyard/.env` to a GH token with Contents, Issues, and Pull
+Requests read/write access and Metadata read access.
+Set `SHIPYARD_ROUTINE_MODEL` and `SHIPYARD_STRONG_MODEL` in `.shipyard/.env`
+for the roles your template uses. `simple-loop` uses routine for triage and
+implementation. `sequential-reviewer` also uses strong for issue reviews.
+Parallel planner templates use routine for ticket work and strong for planning,
+conflict resolution, and integration. The review-enabled planner also uses
+strong for ticket and final specification reviews. See
+[agent setup](docs/content/docs/agents.mdx).
 
-The first run builds the Docker image automatically. Reuse it when the
-Dockerfile has not changed:
+Commit the setup and prompt so the sandbox can read them. Make sure the Git ignore file keeps
+`.shipyard/.env` out of the commit.
 
 ```sh
-npx shipyard run --skip-build
+npx shipyard run
 ```
 
-For Codex, `init` can sign in with a ChatGPT subscription or configure an OpenAI
-API key. Claude Code supports a subscription token or an Anthropic API key. See
-the [agent guide](docs/content/docs/agents.mdx) for authentication details.
-
-## Pick the workflow you need
-
-| Template                       | Best for              | Built-in flow                                 |
-| ------------------------------ | --------------------- | --------------------------------------------- |
-| `blank`                        | One custom task       | One agent run                                 |
-| `simple-loop`                  | A small issue backlog | Implement issues sequentially → review PRs    |
-| `sequential-reviewer`          | Safer issue delivery  | Implement → review → review PR                |
-| `parallel-planner`             | Independent issues    | Plan → implement in parallel → review PRs     |
-| `parallel-planner-with-review` | Maximum autonomy      | Plan → implement and review in parallel → PRs |
-
-All templates are generated TypeScript. Adjust prompts, models, iteration
-limits, branch strategy, hooks, and checks in `.shipyard/main.ts` or
-`.shipyard/main.mts`.
-
-## Keep a repository running
-
-On Apple Silicon macOS, the optional repository runner keeps a foreground
-Shipyard controller ready for GitHub Issues. Label an issue `shipyard`; the
-controller wakes, drains a finite batch of eligible work, coalesces duplicate
-wake-ups, and stops when it makes no progress. Restarting it recovers work
-labelled while the host was offline.
-GitHub-backed `shipyard init` provisions `shipyard`, `shipyard:blocked`,
-`shipyard:pending`, `shipyard:complete`, and `shipyard:outstanding-tasks` in the repository.
-It also provisions the `bug`, `enhancement`, and five triage state labels.
-For a connected repository, init reports an error if any label cannot be created.
-
-The bundled issue workflows install Snappedly skills and the candidate's
-dependencies in Docker. When Shipyard takes an activated ticket, it runs
-`/triage` first and checks the current GitHub labels. Implementation requires
-both `shipyard` and `ready-for-agent`, with no conflicting triage state. Other
-triage outcomes follow the normal blocked flow: Shipyard adds
-`shipyard:blocked`, removes `shipyard`, and records the reason on the ticket.
-A standalone ready issue then runs through `/implement`. Activating
-a planning spec or a linked executable child resolves the parent and only
-linked tickets labelled `shipyard` into one `/implement-spec` scope. The sequential
-templates deliver selected tickets on one branch; the parallel templates assign
-ready tickets to `/implement` workers, integrate dependency waves, resolve ticket
-merge conflicts on the spec branch, and review the integrated change. One
-non-draft PR per spec awaits human merge. Later selected tickets update that PR.
-Shipyard also recognizes a ticket added to an open verified spec PR's `Source
-issues:` line as belonging to that spec, even without a GitHub sub-issue or
-`## Parent` link. Conflicting links block the selected ticket for correction.
-Selected tickets receive `shipyard:pending` while Shipyard works on them.
-Successful handoff replaces it with `shipyard:complete` and removes `shipyard`.
-The parent spec and PR show `shipyard:blocked` if an unfinished child is blocked,
-`shipyard:outstanding-tasks` if children remain, or `shipyard:complete` when all
-linked tickets are complete. Spec labels report child state; they never prevent
-a reactivated child from running. The issues remain open under the target
-repository's closure policy.
-With no labelled tickets yet, Shipyard marks the parent outstanding and waits
-to create the PR until a ticket is selected.
-If an attempted issue cannot be completed, Shipyard comments with the reason,
-marks the attempted tickets `shipyard:blocked`, clears `shipyard:pending`, and
-removes `shipyard` from the scope. The parent spec and any existing PR show
-`shipyard:blocked` while an unfinished child remains blocked. It does not
-publish a new PR for failed work. Resolve the problem, remove
-`shipyard:blocked` from a ticket, then add `shipyard` to retry that ticket;
-the parent spec's status label needs no manual change. Missing or ambiguous
-relationships block the affected selected issue and record the reason. If GitHub cannot confirm whether a
-PR became ready, Shipyard leaves the issue active for reconciliation. The GitHub token
-needs Contents, Issues, and Pull requests read/write permission plus Metadata
-read permission. Keep the Mac and foreground controller running for wake-ups.
-If GitHub rejects a failure comment, Shipyard keeps a local pending report for
-replay. A fresh `shipyard` activation on an unblocked ticket supersedes that
-report. Spec and PR status label failures are logged without stopping ticket
-work; retained activation lets the next invocation recalculate their labels.
-
-Accept runner installation during `init`, or install it later:
+Or for the automated runner:
 
 ```sh
-npx shipyard runner install
-git add .shipyard .github/workflows/shipyard-wake.yml
-git commit -m "Add Shipyard wake workflow"
-git push
 npx shipyard runner start
 ```
 
-Run `npx shipyard runner purge` to remove every dated run-log folder and
-root-level `.log` file under `.shipyard/logs/`. Shipyard automatically removes
-entries older than eight days before `shipyard run`, at runner startup, and
-daily while the runner stays active. Use a path outside `.shipyard/logs/` for
-logs that must be retained separately.
-
-See the [repository runner guide](docs/content/docs/repository-runner.mdx) for
-requirements, lifecycle commands, and the security model.
+## Turn GitHub issues into pull requests
 
-## Build your own coordinator
-
-Shipyard is also a TypeScript library. Compose your own workflow with
-`run()`, `createSandbox()`, and `createWorktree()` while reusing its agent,
-sandbox, branch, prompt, logging, cancellation, and session primitives.
-
-```ts
-import { CODEX_MODELS, codex, run } from "@snappedly-tools/shipyard";
-import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
-
-await run({
-  agent: codex(CODEX_MODELS.routine),
-  sandbox: docker(),
-  promptFile: ".shipyard/prompt.md",
-});
-```
-
-Docker is the default path. Vercel Sandbox is available for isolated cloud
-execution; `noSandbox()` is available only for trusted repositories and prompts.
-
-## What gets created
-
-```text
-.shipyard/
-├── main.ts or main.mts   # workflow configuration
-├── prompt.md              # task or issue instructions
-├── Dockerfile             # sandbox image definition
-├── .env                   # untracked credentials
-├── logs/                  # run logs
-├── worktrees/             # isolated branch worktrees
-└── patches/               # recovery artifacts
-```
+Then:
 
-## Security and control
+1. Write an issue with a clear goal and add the `shipyard` and
+   `ready-for-agent` labels.
+2. Make sure the runner is running, or start `npx shipyard run`. Shipyard checks the issue, implements it in Docker,
+   reviews the work, and opens a pull request.
+3. Inspect the pull request and merge it when you are happy with the result.
 
-Docker keeps the agent's repository and Git storage inside the sandbox by
-default. It is not a magic security boundary: mounts, credentials, devices,
-network access, host hooks, and `noSandbox()` can expand what an agent can do.
-Use least-privilege credentials and review generated configuration before
-running untrusted code. Read the [security evaluation](docs/security-evaluation.md)
-and [SECURITY.md](SECURITY.md).
+## Choose a workflow
 
-Shipyard runs in your infrastructure. There is no required hosted control
-plane; you control the host, Docker, model access, logs, and release policy.
+| Template                       | What it does                                       |
+| ------------------------------ | -------------------------------------------------- |
+| `simple-loop`                  | Works through labeled issues one at a time.        |
+| `sequential-reviewer`          | Implements and reviews issues before PR handoff.   |
+| `parallel-planner`             | Plans and works on independent issues in parallel. |
+| `parallel-planner-with-review` | Adds review to the parallel workflow.              |
 
-## Learn more
+Shipyard also exports TypeScript APIs for custom workflows. Configure prompts,
+branches, limits, and hooks in the generated `.shipyard/main.ts` or
+`.shipyard/main.mts`. See [configuration](docs/content/docs/configuration.mdx)
+and [agent setup](docs/content/docs/agents.mdx).
 
-- [Getting started](docs/content/docs/index.mdx)
-- [Configuration](docs/content/docs/configuration.mdx)
-- [Repository runner operations](docs/runbooks/repository-runner-macos-validation.md)
-- [Contributing](CONTRIBUTING.md)
+## Safety and license
 
-## License
+Shipyard runs on your machine or infrastructure. Sandbox access depends on the
+mounts, credentials, and network settings you choose. Read the
+[security guide](docs/security-evaluation.md) before using untrusted code.
 
-Shipyard is source-available under the
-[PolyForm Strict License 1.0.0](LICENSE). It is available for permitted
-noncommercial use; the license does not permit redistribution, modification, or
-derivative works. Contact Snappedly to request a commercial license.
+Shipyard is source-available under the [PolyForm Strict License 1.0.0](LICENSE)
+for permitted noncommercial use. Contact Snappedly for a commercial license.

package/dist/MountConfig-BHnKnA4h.d.ts

@@ -0,0 +1,145 @@
+/** Result of executing a command inside a sandbox. */
+interface ExecResult {
+    /** Collected standard output. */
+    readonly stdout: string;
+    /** Collected standard error. */
+    readonly stderr: string;
+    /** Process exit status. */
+    readonly exitCode: number;
+}
+/** Streams supplied when launching an interactive agent process. */
+interface InteractiveExecOptions {
+    /** Input stream forwarded to the agent process. */
+    readonly stdin: NodeJS.ReadableStream;
+    /** Output stream receiving agent standard output. */
+    readonly stdout: NodeJS.WritableStream;
+    /** Output stream receiving agent standard error. */
+    readonly stderr: NodeJS.WritableStream;
+    /** Working directory inside Docker. */
+    readonly cwd?: string;
+    /** Abort signal that terminates the interactive process. */
+    readonly signal?: AbortSignal;
+}
+/** Handle to a running isolated sandbox. Docker implements this contract. */
+interface IsolatedSandboxHandle {
+    /** Absolute Git workspace path inside Docker. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command in Docker. Deliver `onLine` as output arrives so idle
+     * timeouts and live feedback work; buffered delivery does not satisfy this
+     * contract. Pipe `stdin` to the child rather than passing it as an argument.
+     */
+    exec(command: string, options?: {
+        /** Live output callback. */
+        onLine?: (line: string) => void;
+        /** Working directory inside Docker. */
+        cwd?: string;
+        /** Execute as root when supported. */
+        sudo?: boolean;
+        /** Input piped to the child process. */
+        stdin?: string;
+        /** Abort signal that terminates the command. */
+        signal?: AbortSignal;
+        /** Maximum combined output bytes before termination. */
+        maxOutputBytes?: number;
+    }): Promise<ExecResult>;
+    /** Launch an interactive process and terminate it when `signal` aborts. */
+    interactiveExec?(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** Copy a file or directory from the host into Docker. */
+    copyIn(hostPath: string, sandboxPath: string): Promise<void>;
+    /** Copy a file from Docker to the host. */
+    copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;
+    /** Tear down the container. */
+    close(): Promise<void>;
+}
+/** File transfer shape used by agent session storage. */
+interface SessionTransferHandle {
+    /** Absolute Git workspace path inside Docker. */
+    readonly worktreePath: string;
+    /** Run a command in the sandbox. */
+    exec: IsolatedSandboxHandle["exec"];
+    /** Launch an interactive command when available. */
+    interactiveExec?: IsolatedSandboxHandle["interactiveExec"];
+    /** Copy one host file into the sandbox. */
+    copyFileIn(hostPath: string, sandboxPath: string): Promise<void>;
+    /** Copy one sandbox file to the host. */
+    copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;
+    /** Tear down the sandbox. */
+    close(): Promise<void>;
+}
+/** Inputs to Docker sandbox creation. */
+interface IsolatedCreateOptions {
+    /** Original repository path used to derive the image name; never mounted. */
+    readonly hostRepoPath?: string;
+    /** Environment injected into the Docker container. */
+    readonly env: Record<string, string>;
+}
+/** Configuration for the isolated Docker provider contract. */
+interface IsolatedSandboxProviderConfig {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Provider environment merged into sandbox startup. */
+    readonly env?: Record<string, string>;
+    /** Start a sandbox and return its command and file-transfer handle. */
+    readonly create: (options: IsolatedCreateOptions) => Promise<IsolatedSandboxHandle>;
+}
+/** Docker's isolated filesystem provider contract. */
+interface IsolatedSandboxProvider {
+    /** Isolated filesystem discriminator. */
+    readonly tag: "isolated";
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected into Docker. */
+    readonly env: Record<string, string>;
+    /** Start a sandbox. */
+    readonly create: (options: IsolatedCreateOptions) => Promise<IsolatedSandboxHandle>;
+}
+/** Provider accepted by Shipyard's Docker execution path. */
+type SandboxProvider = IsolatedSandboxProvider;
+/** Create a temporary branch and merge its commits back to host HEAD. */
+interface MergeToHeadBranchStrategy {
+    /** Branch strategy discriminator. */
+    readonly type: "merge-to-head";
+}
+/** Run on a caller-named branch. */
+interface NamedBranchStrategy {
+    /** Branch strategy discriminator. */
+    readonly type: "branch";
+    /** Branch to create or reuse. */
+    readonly branch: string;
+    /** Starting ref for a new branch. */
+    readonly baseBranch?: string;
+}
+/** Supported Docker branch strategies. */
+type BranchStrategy = MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Construct the isolated provider contract used by Docker. */
+declare const createIsolatedSandboxProvider: (config: IsolatedSandboxProviderConfig) => IsolatedSandboxProvider;
+
+/**
+ * User-facing mount configuration for Docker.
+ *
+ * Each entry describes a host directory to mount into the sandbox container.
+ */
+/** A single bind-mount descriptor for the Docker provider. */
+interface MountConfig {
+    /**
+     * Path on the host. Supports:
+     * - Absolute paths (`/data/cache`)
+     * - Tilde-expanded paths (`~/data` → `<home>/data`)
+     * - Relative paths (`data` or `./data`) — resolved from `process.cwd()`
+     */
+    readonly hostPath: string;
+    /**
+     * Path inside the sandbox container. Supports:
+     * - Absolute paths (`/mnt/data`)
+     * - Tilde-expanded paths (`~/.npm` → `/home/agent/.npm`) — expanded using the provider's sandbox home directory
+     * - Relative paths (`data` or `./data`) — resolved from the worktree directory (`/home/agent/workspace`)
+     */
+    readonly sandboxPath: string;
+    /** Mount as read-only. Defaults to `false`. */
+    readonly readonly?: boolean;
+}
+
+export { type BranchStrategy as B, type ExecResult as E, type IsolatedSandboxProvider as I, type MountConfig as M, type NamedBranchStrategy as N, type SessionTransferHandle as S, type SandboxProvider as a, type MergeToHeadBranchStrategy as b, type InteractiveExecOptions as c, type IsolatedCreateOptions as d, type IsolatedSandboxHandle as e, type IsolatedSandboxProviderConfig as f, createIsolatedSandboxProvider as g };