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

package/README.md

@@ -8,153 +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.
 
-Requirements: Node.js 20.18.1+, Git, Docker, and credentials for your chosen
-agent. Run these commands in the repository Shipyard should change:
+Run:
 
 ```sh
-npm install --save-dev @snappedly-tools/shipyard
-npx shipyard init
+npx skills add snappedly/skills
 ```
 
-`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`.
-
-Add the requested credentials to `.shipyard/.env`, write a task in
-`.shipyard/prompt.md` when using the `blank` template, then run:
+Ask your coding agent to run `setup-snappedly-skills` in that repository.
 
 ```sh
-npx shipyard run
-```
-
-The first run builds the Docker image automatically. Reuse it when the
-Dockerfile has not changed:
-
-```sh
-npx shipyard run --skip-build
+npm install --save-dev @snappedly-tools/shipyard
+npx shipyard init
 ```
 
-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
+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.
 
-| Template                       | Best for              | Built-in flow                                     |
-| ------------------------------ | --------------------- | ------------------------------------------------- |
-| `blank`                        | One custom task       | One agent run                                     |
-| `simple-loop`                  | A small issue backlog | Implement issues sequentially                     |
-| `sequential-reviewer`          | Safer issue delivery  | Implement → review, one issue at a time           |
-| `parallel-planner`             | Independent issues    | Plan dependencies → implement in parallel → merge |
-| `parallel-planner-with-review` | Maximum autonomy      | Plan → implement and review in parallel → merge   |
+On a local Mac, the repository runner automatically wakes Shipyard when you label an issue.
+It runs as long as its terminal stays open.
 
-All templates are generated TypeScript. Adjust prompts, models, iteration
-limits, branch strategy, hooks, and checks in `.shipyard/main.ts` or
-`.shipyard/main.mts`.
+See the [getting started guide](docs/content/docs/index.mdx) for authentication and
+branch options.
 
-## Keep a repository running
+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).
 
-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.
-
-Accept runner installation during `init`, or install it later:
+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 runner install
-git add .github/workflows/shipyard-wake.yml .shipyard/.gitignore
-git commit -m "Add Shipyard wake workflow"
-git push
-npx shipyard runner start
+npx shipyard run
 ```
 
-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.
-
-## 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.
+Or for the automated runner:
 
-```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",
-});
+```sh
+npx shipyard runner start
 ```
 
-Docker is the default path. Vercel Sandbox is available for isolated cloud
-execution; `noSandbox()` is available only for trusted repositories and prompts.
+## Turn GitHub issues into pull requests
 
-## 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 };