@snappedly-tools/shipyard 0.7.0 → 0.9.0

package/README.md

@@ -23,86 +23,89 @@ a commit or pull request you can inspect.
 
 ## Try it on one task
 
-You need **Node.js 20.18.1+**, **Git**, **Docker running**, and **Codex or Claude
-Code** with a login or API key. Start with a clean Git repository you want
-Shipyard to change. If it is on GitHub, sign in with the
-[GitHub CLI](https://cli.github.com/) (`gh auth login`) before `init`; Shipyard
-creates its issue labels there.
+You need **Node.js 20.18.1+**, **Git**, **Docker running**, and **Codex or Claude Code**
+with a subscription login or API key.
 
 Run:
 
 ```sh
-git switch -c try-shipyard
 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
 ```
 
-Ask your coding agent to run `setup-snappedly-skills` in that repository. During
-`shipyard init`, choose your agent, **Docker**, and the **blank** template. Follow
-the authentication prompts. You can skip the optional repository runner for
-this first task.
+During `shipyard init`, choose your agent and template, then follow the
+authentication prompts. GitHub Issues is the built-in tracker. Init builds the
+Docker image and automatically installs the
+[repository runner](docs/content/docs/repository-runner.mdx).
+
+On a local Mac, the repository runner automatically wakes Shipyard when you label an issue.
+It runs as long as its terminal stays open.
 
-Open `.shipyard/prompt.md` and describe a small change. For example:
+See the [getting started guide](docs/content/docs/index.mdx) for authentication and
+branch options.
 
-```md
-# Task
+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.
 
-Document how to run this project locally using commands already in the repo.
-Run the relevant checks and commit the change.
+Set `SHIPYARD_ROUTINE_MODEL` and `SHIPYARD_STRONG_MODEL` in `.shipyard/.env`
+for the roles your template uses.
 
-# Done
+`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).
 
-Output <promise>COMPLETE</promise> when finished.
+```sh
+npx shipyard runner start
 ```
 
-Fill in any credentials requested in `.shipyard/.env`. Commit the setup and
-prompt so the sandbox can read them. The generated Git ignore file keeps
-`.shipyard/.env` out of the commit.
+To start Shipyard for a single run without the active runner, use:
 
 ```sh
-git add .
-git commit -m "Set up Shipyard"
 npx shipyard run
-git show --stat HEAD
 ```
 
-Shipyard builds the Docker image, runs the agent, and returns its commit to your
-current branch. `git show` lets you inspect what changed. See the
-[getting started guide](docs/content/docs/index.mdx) for authentication and
-branch options.
+To remove Shipyard from the repository:
+
+```sh
+npx shipyard uninstall
+```
 
 ## Turn GitHub issues into pull requests
 
-For a repository you want to automate from GitHub Issues, choose
-**sequential-reviewer** instead of **blank** during `shipyard init`. Set
-`GH_TOKEN` in `.shipyard/.env` to a token with Contents, Issues, and Pull
-requests read/write access and Metadata read access. Then:
+Then:
 
 1. Write an issue with a clear goal and add the `shipyard` and
    `ready-for-agent` labels.
-2. Run `npx shipyard run`. Shipyard checks the issue, implements it in Docker,
-   reviews the work, and opens a pull request.
+2. Run Shipyard to check for the issue, implement it in Docker,
+   review the work, and open a pull request.
 3. Inspect the pull request and merge it when you are happy with the result.
 
-On an Apple Silicon Mac, the optional [repository runner](docs/content/docs/repository-runner.mdx)
-can wake Shipyard when you label an issue. It runs while its terminal stays open.
-The guide covers installation, retries, and issue status labels.
-
 ## Choose a workflow
 
 | Template                       | What it does                                       |
 | ------------------------------ | -------------------------------------------------- |
-| `blank`                        | Runs your own task and prompt.                     |
-| `simple-loop`                  | Works through labelled issues one at a time.       |
+| `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.              |
 
-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).
+The package root exports the core run, interactive, and sandbox APIs. Import
+hosted workflow coordination and GitHub integration APIs from
+`@snappedly-tools/shipyard/workflow` and
+`@snappedly-tools/shipyard/integrations/github`. 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).
 
 ## Safety and license
 

package/dist/{MountConfig-bZoCs4Dd.d.ts → MountConfig-K5ILnfht.d.ts}

@@ -1,5 +1,5 @@
 /**
- * User-facing mount configuration for bind-mount sandbox providers.
+ * User-facing mount configuration for Docker.
  *
  * Each entry describes a host directory to mount into the sandbox container.
  */

package/dist/SandboxProvider-oUAwYlWm.d.ts

@@ -0,0 +1,120 @@
+/** 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;
+
+export { type BranchStrategy as B, type ExecResult as E, type IsolatedSandboxProvider as I, type MergeToHeadBranchStrategy as M, type NamedBranchStrategy as N, type SandboxProvider as S, type InteractiveExecOptions as a, type IsolatedCreateOptions as b, type IsolatedSandboxHandle as c, type IsolatedSandboxProviderConfig as d, createIsolatedSandboxProvider as e, type SessionTransferHandle as f };