@snappedly-tools/shipyard 0.2.0

package/LICENSE

@@ -0,0 +1,59 @@
+# PolyForm Strict License 1.0.0
+
+<https://polyformproject.org/licenses/strict/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose, other than distributing the software or making changes or new works based on the software.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/NOTICE

@@ -0,0 +1,4 @@
+Shipyard
+Copyright 2026 Snappedly
+
+This product includes software developed by Shipyard contributors.

package/README.md

@@ -0,0 +1,197 @@
+# Shipyard
+
+<p align="center">
+  <img src="assets/brand/shipyard-robot-on-boat.png" alt="A friendly robot steering a blue boat for Shipyard" width="320">
+</p>
+
+> **Source-available toolkit for running AI coding agents in isolated sandboxes.**
+
+[![CI](https://github.com/snappedly/shipyard/actions/workflows/ci.yml/badge.svg)](https://github.com/snappedly/shipyard/actions/workflows/ci.yml)
+
+Shipyard runs AI coding agents in isolated sandboxes. Choose an agent, a
+sandbox provider, and a prompt; Shipyard manages the sandbox lifecycle,
+branches, logs, sessions, and commits.
+
+## Why Shipyard
+
+- **Isolated by default.** Keep agent work inside Docker locally or Vercel
+  Sandbox remotely.
+- **Purpose-built agents.** Use Codex or Claude Code without carrying support
+  for unrelated coding-agent CLIs.
+- **Reviewable changes.** Control how branches and worktrees move changes back
+  to the host repository.
+
+## Quick start
+
+You need Node.js, Git, Docker, and credentials for your chosen coding agent.
+Run these commands inside the Git repository the agent should change:
+
+```sh
+npm install --save-dev @snappedly-tools/shipyard
+npx shipyard init
+cp .shipyard/.env.example .shipyard/.env
+```
+
+`init` asks which agent, sandbox provider, issue tracker, and starter template
+to use. Start with the `blank` template. Put the requested credentials in
+`.shipyard/.env`, then write one concrete task in `.shipyard/prompt.md`.
+
+Run it:
+
+```sh
+npx shipyard run
+```
+
+`shipyard run` builds the generated Docker image, executes the
+generated TypeScript entry point, and cleans up the sandbox. Reuse the cached
+image when its definition has not changed:
+
+```sh
+npx shipyard run --skip-build
+```
+
+Inspect the generated branch strategy and start from a clean working tree. A
+completion marker means the agent stopped; inspect its commits and run the
+repository's checks before keeping the result.
+
+## JavaScript API
+
+The generated `.shipyard/main.ts` or `.shipyard/main.mts` is ordinary
+TypeScript:
+
+```ts
+import { CODEX_MODELS, codex, run } from "@snappedly-tools/shipyard";
+import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
+
+const result = await run({
+  agent: codex(CODEX_MODELS.routine),
+  sandbox: docker(),
+  promptFile: ".shipyard/prompt.md",
+});
+
+console.log(result.commits);
+```
+
+Use a dedicated branch when the scaffold has already been committed:
+
+```ts
+const result = await run({
+  agent: codex(CODEX_MODELS.routine),
+  sandbox: docker(),
+  promptFile: ".shipyard/prompt.md",
+  branchStrategy: { type: "branch", branch: "agent/my-task" },
+  maxIterations: 1,
+  logging: { type: "stdout" },
+});
+```
+
+Shipyard supports Codex and Claude Code agents, with Docker, Vercel Sandbox,
+and no-sandbox providers. `shipyard init` scaffolds Docker; configure Vercel
+Sandbox or no-sandbox mode through the JavaScript interface.
+
+To run directly on the host without isolation:
+
+```ts
+import { CODEX_MODELS, codex, run } from "@snappedly-tools/shipyard";
+import { noSandbox } from "@snappedly-tools/shipyard/sandboxes/no-sandbox";
+
+const result = await run({
+  agent: codex(CODEX_MODELS.routine),
+  sandbox: noSandbox(),
+  promptFile: ".shipyard/prompt.md",
+});
+```
+
+No-sandbox mode grants the agent the permissions of the Shipyard process. Use
+it only with trusted repositories and prompts.
+
+## Branch behavior
+
+Docker keeps the repository and Git metadata inside the sandbox. It starts
+from committed history and syncs changes back. The generated blank
+template omits `branchStrategy`, which defaults to `merge-to-head`: commits
+are transferred to a temporary host branch and merged into your current
+branch. Direct `head` mode is not supported by Docker or Vercel Sandbox.
+
+The explicit `branch` strategy keeps commits on the named branch for review.
+Commit input files before either strategy, or use `copyToWorktree` for specific
+untracked or ignored files.
+
+## Authentication
+
+`shipyard init` generates the environment variables and mounts required by
+the chosen agent. Keep `.shipyard/.env`, agent login files, logs, and recovery
+patches private.
+
+For Codex, choose either:
+
+- ChatGPT authentication: select `chatgpt` during init and complete the
+  browser login. The generated configuration mounts `~/.codex/auth.json`
+  read-only.
+- API authentication: select `api-key` and put `OPENAI_API_KEY` in
+  `.shipyard/.env`.
+
+For Claude Code, run `claude setup-token` and put the resulting value in the
+generated `CLAUDE_CODE_OAUTH_TOKEN` entry.
+
+## Generated files
+
+| Path                              | Purpose                                                      |
+| --------------------------------- | ------------------------------------------------------------ |
+| `.shipyard/main.ts` or `main.mts` | Agent, sandbox, prompt, branch, hook, and iteration settings |
+| `.shipyard/prompt.md`             | Task given to the agent                                      |
+| `.shipyard/Dockerfile`            | Sandbox image definition                                     |
+| `.shipyard/.env`                  | Untracked credentials passed into the sandbox                |
+| `.shipyard/logs/`                 | Run logs                                                     |
+| `.shipyard/worktrees/`            | Worktrees for separate-branch runs                           |
+| `.shipyard/patches/`              | Recovery artifacts preserved after some failures             |
+
+## Workflow templates
+
+The bundled templates are:
+
+- `blank`: one agent and your prompt;
+- `simple-loop`: process issue-tracker tasks sequentially;
+- `sequential-reviewer`: implement and review each task;
+- `parallel-planner`: plan parallel work and merge its branches; and
+- `parallel-planner-with-review`: add review to each parallel branch.
+
+Read generated prompts before running an issue or merge workflow. Those
+templates can close issues, create branches, and merge work.
+
+The package also exports contracts for triage, implementation, review,
+repair, handoff, and release recording. They are building blocks for hosted
+automation, not a hosted service started by the quick-start commands.
+
+## Security
+
+Agents receive the permissions granted by their sandbox, mounts, credentials,
+and hooks. Docker isolates repository and Git storage; it does not
+mount the host checkout or Git metadata automatically. Explicit mounts must
+stay outside the sandbox workspace and its ancestors.
+
+Mounted credentials, devices, Docker sockets, groups, and network access can
+still broaden an agent's access. Host hooks, no-sandbox mode, and custom
+provider code retain their own trust requirements. Use
+least-privilege credentials and review generated configuration before running
+untrusted code.
+
+See the [security evaluation](docs/security-evaluation.md) for findings,
+fixes, and validation limits. Report vulnerabilities according to
+[SECURITY.md](SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The standard repository check is:
+
+```sh
+npm ci
+npm run check
+```
+
+## License
+
+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.

package/dist/MountConfig-bZoCs4Dd.d.ts

@@ -0,0 +1,26 @@
+/**
+ * User-facing mount configuration for bind-mount sandbox providers.
+ *
+ * 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 { MountConfig as M };

package/dist/SandboxProvider-KeFp_nju.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Sandbox provider types — the pluggable interface for sandbox runtimes.
+ *
+ * Provider authors implement a small Promise-based interface. Shipyard
+ * handles worktree creation, git mount resolution, and commit extraction.
+ */
+/** Result of executing a command inside a sandbox. */
+interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/** Options for interactiveExec — the streams the provider should wire to the spawned process. */
+interface InteractiveExecOptions {
+    readonly stdin: NodeJS.ReadableStream;
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly cwd?: string;
+}
+/** Handle to a running bind-mount sandbox. */
+interface BindMountSandboxHandle {
+    /** Absolute path to the worktree inside the sandbox. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command in the sandbox.
+     *
+     * Implementations MUST support line-by-line streaming via `onLine`. This is
+     * how Shipyard delivers live feedback to the user and enforces idle timeouts —
+     * without a streaming implementation, neither will work. A buffered/batch
+     * implementation that only calls `onLine` after the process exits does NOT
+     * satisfy this contract.
+     *
+     * When `stdin` is set, the implementation pipes the string to the child
+     * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.
+     */
+    exec(command: string, options?: {
+        onLine?: (line: string) => void;
+        cwd?: string;
+        sudo?: boolean;
+        stdin?: string;
+        /** Abort the command when the caller's operation is cancelled. */
+        signal?: AbortSignal;
+        /** Reject/terminate the command after this many combined output bytes. */
+        maxOutputBytes?: number;
+    }): Promise<ExecResult>;
+    /**
+     * Launch an interactive process inside the sandbox.
+     * Optional — providers that support interactive sessions implement this.
+     * The provider detects TTY mode from the streams (e.g. stdin.isTTY) and
+     * allocates a pseudo-terminal accordingly.
+     */
+    interactiveExec?(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** Copy a single file from the host into the sandbox. */
+    copyFileIn(hostPath: string, sandboxPath: string): Promise<void>;
+    /** Copy a single file from the sandbox to the host. */
+    copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;
+    /** Tear down the sandbox. */
+    close(): Promise<void>;
+}
+/** Options passed to a bind-mount provider's `create` function. */
+interface BindMountCreateOptions {
+    /** Host-side path to the worktree directory. */
+    readonly worktreePath: string;
+    /** Host-side path to the original repo root. */
+    readonly hostRepoPath: string;
+    /** Volume mounts to apply (host:sandbox pairs). */
+    readonly mounts: Array<{
+        hostPath: string;
+        sandboxPath: string;
+        readonly?: boolean;
+    }>;
+    /** Environment variables to inject into the sandbox. */
+    readonly env: Record<string, string>;
+}
+/** Configuration for createBindMountSandboxProvider. */
+interface BindMountSandboxProviderConfig {
+    /** Human-readable name for this provider (e.g. "docker"). */
+    readonly name: string;
+    /** Environment variables injected by this provider. Merged at launch time. */
+    readonly env?: Record<string, string>;
+    /**
+     * Absolute path to the home directory inside the sandbox (e.g. `"/home/agent"`).
+     * Used to expand `~` in user-provided `sandboxPath` mount configs.
+     * Set to `undefined` for providers that do not have a fixed home directory.
+     */
+    readonly sandboxHomedir?: string;
+    /** Create a sandbox handle from the given options. */
+    readonly create: (options: BindMountCreateOptions) => Promise<BindMountSandboxHandle>;
+}
+/** Handle to a running isolated sandbox (extends bind-mount with file transfer). */
+interface IsolatedSandboxHandle {
+    /** Absolute path to the worktree inside the sandbox. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command in the sandbox.
+     *
+     * Implementations MUST support line-by-line streaming via `onLine`. This is
+     * how Shipyard delivers live feedback to the user and enforces idle timeouts —
+     * without a streaming implementation, neither will work. A buffered/batch
+     * implementation that only calls `onLine` after the process exits does NOT
+     * satisfy this contract.
+     *
+     * When `stdin` is set, the implementation pipes the string to the child
+     * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.
+     */
+    exec(command: string, options?: {
+        onLine?: (line: string) => void;
+        cwd?: string;
+        sudo?: boolean;
+        stdin?: string;
+        /** Abort the command when the caller's operation is cancelled. */
+        signal?: AbortSignal;
+        /** Reject/terminate the command after this many combined output bytes. */
+        maxOutputBytes?: number;
+    }): Promise<ExecResult>;
+    /**
+     * Launch an interactive process inside the sandbox.
+     * Optional — providers that support interactive sessions implement this.
+     * The provider detects TTY mode from the streams (e.g. stdin.isTTY) and
+     * allocates a pseudo-terminal accordingly.
+     */
+    interactiveExec?(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** Copy a file or directory from the host into the sandbox. */
+    copyIn(hostPath: string, sandboxPath: string): Promise<void>;
+    /** Copy a single file from the sandbox to the host. */
+    copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;
+    /** Tear down the sandbox. */
+    close(): Promise<void>;
+}
+/** Options passed to an isolated provider's `create` function. */
+interface IsolatedCreateOptions {
+    /** Original host repository path, used only for image naming; never mounted. */
+    readonly hostRepoPath?: string;
+    /** Environment variables to inject into the sandbox. */
+    readonly env: Record<string, string>;
+}
+/** Configuration for createIsolatedSandboxProvider. */
+interface IsolatedSandboxProviderConfig {
+    /** Human-readable name for this provider (e.g. "vercel"). */
+    readonly name: string;
+    /** Environment variables injected by this provider. Merged at launch time. */
+    readonly env?: Record<string, string>;
+    /** Create an isolated sandbox handle from the given options. */
+    readonly create: (options: IsolatedCreateOptions) => Promise<IsolatedSandboxHandle>;
+}
+/** A bind-mount sandbox provider. */
+interface BindMountSandboxProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected by this provider. */
+    readonly env: Record<string, string>;
+    /**
+     * Absolute path to the home directory inside the sandbox (e.g. `"/home/agent"`).
+     * `undefined` when the provider does not declare a sandbox home directory.
+     */
+    readonly sandboxHomedir: string | undefined;
+}
+/** An isolated sandbox provider. */
+interface IsolatedSandboxProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected by this provider. */
+    readonly env: Record<string, string>;
+}
+/** Handle to a no-sandbox session — runs commands directly on the host. */
+interface NoSandboxHandle {
+    /** Absolute path to the worktree on the host. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command on the host.
+     *
+     * Implementations MUST support line-by-line streaming via `onLine`. This is
+     * how Shipyard delivers live feedback to the user and enforces idle timeouts —
+     * without a streaming implementation, neither will work.
+     *
+     * When `stdin` is set, the implementation pipes the string to the child
+     * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.
+     */
+    exec(command: string, options?: {
+        onLine?: (line: string) => void;
+        cwd?: string;
+        sudo?: boolean;
+        stdin?: string;
+        /** Abort the command when the caller's operation is cancelled. */
+        signal?: AbortSignal;
+        /** Reject/terminate the command after this many combined output bytes. */
+        maxOutputBytes?: number;
+    }): Promise<ExecResult>;
+    /**
+     * Launch an interactive process on the host with inherited stdio.
+     */
+    interactiveExec(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** No-op — no container to tear down. */
+    close(): Promise<void>;
+}
+/** A no-sandbox provider — runs the agent directly on the host with no container isolation. */
+interface NoSandboxProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected by this provider. */
+    readonly env: Record<string, string>;
+}
+/** Head strategy: agent writes directly to host working directory. Bind-mount only. */
+interface HeadBranchStrategy {
+    readonly type: "head";
+}
+/** Merge-to-head strategy: temp branch, merge back to HEAD, delete temp branch. */
+interface MergeToHeadBranchStrategy {
+    readonly type: "merge-to-head";
+}
+/** Branch strategy: commits land on an explicit named branch. */
+interface NamedBranchStrategy {
+    readonly type: "branch";
+    readonly branch: string;
+    /**
+     * Git ref to use as the starting point when creating a new branch.
+     * Only used when the branch doesn't already exist — ignored otherwise.
+     * Callers are responsible for ensuring the ref is current (e.g. `git fetch`).
+     * Defaults to `HEAD` when omitted.
+     */
+    readonly baseBranch?: string;
+}
+/** Branch strategy for bind-mount providers (all three variants). */
+type BindMountBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Branch strategy for isolated providers (no head — can't write to host). */
+type IsolatedBranchStrategy = MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Branch strategy for no-sandbox providers (all three — same as bind-mount). */
+type NoSandboxBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Union of all branch strategy variants. */
+type BranchStrategy = BindMountBranchStrategy | IsolatedBranchStrategy | NoSandboxBranchStrategy;
+/**
+ * A sandbox provider — the pluggable unit that `run()`, `interactive()`, and
+ * `createSandbox()` accept. Tagged for internal dispatch: "bind-mount",
+ * "isolated", or "none". When `NoSandboxProvider` is used, the agent runs
+ * directly on the host with no container isolation — opt in at your own risk.
+ */
+type SandboxProvider = BindMountSandboxProvider | IsolatedSandboxProvider | NoSandboxProvider;
+/** @deprecated Use `SandboxProvider` — it now includes `NoSandboxProvider`. */
+type AnySandboxProvider = SandboxProvider;
+/**
+ * Create a bind-mount sandbox provider from a config object.
+ * The returned provider can be passed to `run()` or `createSandbox()`.
+ */
+declare const createBindMountSandboxProvider: (config: BindMountSandboxProviderConfig) => BindMountSandboxProvider;
+/**
+ * Create an isolated sandbox provider from a config object.
+ * The returned provider can be passed to `run()` or `createSandbox()`.
+ */
+declare const createIsolatedSandboxProvider: (config: IsolatedSandboxProviderConfig) => IsolatedSandboxProvider;
+
+export { type AnySandboxProvider as A, type BindMountSandboxHandle as B, type ExecResult as E, type HeadBranchStrategy as H, type IsolatedSandboxProvider as I, type MergeToHeadBranchStrategy as M, type NoSandboxProvider as N, type SandboxProvider as S, type BranchStrategy as a, type NamedBranchStrategy as b, type BindMountBranchStrategy as c, type BindMountCreateOptions as d, type BindMountSandboxProvider as e, type BindMountSandboxProviderConfig as f, type InteractiveExecOptions as g, type IsolatedBranchStrategy as h, type IsolatedCreateOptions as i, type IsolatedSandboxHandle as j, type IsolatedSandboxProviderConfig as k, type NoSandboxBranchStrategy as l, type NoSandboxHandle as m, createBindMountSandboxProvider as n, createIsolatedSandboxProvider as o };