@alchemy.run/boat 0.0.0 → 2.0.0-beta.86

package/src/SandboxClient.ts

@@ -0,0 +1,199 @@
+import type * as Boat from "@distilled.cloud/boat-dev";
+import type * as boat from "@distilled.cloud/boat-dev/boat";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Sandbox from "alchemy/Sandbox";
+import type * as Duration from "effect/Duration";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type * as Stream from "effect/Stream";
+import type { BoatUnexpectedResponse, ExecTimedOut, SnapshotFailed } from "./Errors.ts";
+
+/** Errors a Boat call can fail with. */
+export type BoatError =
+  | Boat.BoatOpError
+  | boat.BadRequest
+  | boat.Forbidden
+  | boat.NotFound
+  | boat.Conflict
+  | boat.SandboxNotRunning
+  | boat.SandboxStartLimitExceeded
+  | boat.FileNotFound
+  | boat.ForkNeedsSnapshot
+  | ExecTimedOut
+  | SnapshotFailed
+  | BoatUnexpectedResponse;
+
+/** A command: a shell line (run with `bash -lc`) or an argument vector. */
+export type Command = Sandbox.Command;
+
+/**
+ * `cwd` defaults to the home directory (`/home/user`). `timeout` (at most
+ * 10 minutes, Boat's default 30 seconds) stops the command and fails with
+ * `Boat.ExecTimedOut`.
+ */
+export type ExecOptions = Sandbox.ExecOptions;
+
+/** What a finished command printed, and its exit code. A non-zero exit code is returned, not failed. */
+export interface ExecResult extends Sandbox.ExecResult {
+  /** Boat's id for the command, for its history and logs. */
+  readonly commandId: string | undefined;
+}
+
+export interface StartOptions {
+  /** Working directory. @default "/home/user" */
+  readonly cwd?: string;
+  /** Environment variables for the command. */
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+/** A chunk of a process's output. */
+export type ProcessOutput = Sandbox.ProcessOutput;
+
+/**
+ * A command running in the background. It keeps running after the request
+ * that started it ends; `processes.attach(processId)` picks it up again.
+ * Boat has no stdin for background commands.
+ */
+export interface Process {
+  /** Boat's process id, as a string. */
+  readonly id: string;
+  readonly processId: number;
+  /** stdout and stderr from where it was started or attached, until it exits. */
+  readonly output: Stream.Stream<ProcessOutput, BoatError, RuntimeContext>;
+  /** Stops the process. */
+  kill(): Effect.Effect<void, BoatError, RuntimeContext>;
+  /** Waits for it to exit, with the tail of what it printed. */
+  readonly wait: Effect.Effect<ExecResult, BoatError, RuntimeContext>;
+}
+
+/** Background commands in the sandbox. */
+export interface Processes {
+  /** Picks up a background command by its process id. */
+  attach(processId: number): Effect.Effect<Process, BoatError, RuntimeContext>;
+}
+
+/** A file or directory in the sandbox. */
+export interface EntryInfo extends Sandbox.FileEntry {
+  /** Octal permission bits, e.g. `0644`. */
+  readonly mode: string;
+  readonly modifiedAt: string;
+}
+
+/**
+ * The sandbox's filesystem. Relative paths resolve in the home directory
+ * (`/home/user`); Boat reaches only paths under `/home/user` and `/tmp`.
+ * A missing path fails with `FileNotFound`.
+ */
+export interface Files extends Sandbox.Files<BoatError, EntryInfo> {
+  read(path: string): Effect.Effect<Uint8Array, BoatError, RuntimeContext>;
+  readText(path: string): Effect.Effect<string, BoatError, RuntimeContext>;
+  /** Writes a file, creating parent directories. Files up to 5 MiB. */
+  write(path: string, data: string | Uint8Array): Effect.Effect<void, BoatError, RuntimeContext>;
+  list(path: string): Effect.Effect<ReadonlyArray<EntryInfo>, BoatError, RuntimeContext>;
+  stat(path: string): Effect.Effect<EntryInfo, BoatError, RuntimeContext>;
+  /** Removes a file, or a directory and everything in it. */
+  remove(path: string): Effect.Effect<void, BoatError, RuntimeContext>;
+  /** Creates the directory and its parents. */
+  makeDir(path: string): Effect.Effect<void, BoatError, RuntimeContext>;
+  exists(path: string): Effect.Effect<boolean, BoatError, RuntimeContext>;
+  /** Moves a file or directory, creating the destination's parents. */
+  move(
+    source: string,
+    destination: string,
+    options?: { readonly overwrite?: boolean },
+  ): Effect.Effect<void, BoatError, RuntimeContext>;
+}
+
+/**
+ * A port inside a Boat sandbox, served at
+ * `https://<subdomain>-<port>.on.boat.dev`. A protected port needs its
+ * `token`, which `fetch` sends for you as Boat's `_port_auth` cookie.
+ */
+export interface Port extends Sandbox.SandboxPort<BoatError> {
+  /** The port's URL, without its token. */
+  readonly url: string;
+  /** The port's access token, or `undefined` for a public port. */
+  readonly token: Redacted.Redacted<string> | undefined;
+}
+
+export interface PortOptions {
+  /** Serve the port without a token, to anyone. @default false */
+  readonly public?: boolean;
+  /** Set when the program listens on `127.0.0.1` only; Boat relays to it. @default false */
+  readonly localhost?: boolean;
+}
+
+/**
+ * What you can do with a sandbox, however you got it. Calls into a stopped
+ * sandbox (`exec`, `start`, `files`, `getTcpPort`) fail with
+ * `SandboxNotRunning`: `resume()` it first.
+ */
+export interface SandboxOperations
+  extends
+    Sandbox.SandboxExec<BoatError, ExecResult, ExecOptions>,
+    Sandbox.SandboxFiles<BoatError, EntryInfo>,
+    Sandbox.SandboxPorts<BoatError, Port> {
+  /** Runs a command to completion. */
+  exec(
+    command: Command,
+    options?: ExecOptions,
+  ): Effect.Effect<ExecResult, BoatError, RuntimeContext>;
+  /** Starts a command in the background. */
+  start(
+    command: Command,
+    options?: StartOptions,
+  ): Effect.Effect<Process, BoatError, RuntimeContext>;
+  readonly processes: Processes;
+  readonly files: Files;
+  /** A port inside the sandbox. Boat hosts it on first use. */
+  getTcpPort(port: number, options?: PortOptions): Effect.Effect<Port, BoatError, RuntimeContext>;
+  /** Live details: state, size, environment, labels. */
+  describe(): Effect.Effect<boat.Sandbox, BoatError, RuntimeContext>;
+  /**
+   * Stops the sandbox, saving its disk. Stopping a stopped sandbox
+   * succeeds.
+   */
+  stop(): Effect.Effect<void, BoatError, RuntimeContext>;
+  /**
+   * Resumes a stopped sandbox (a no-op on a running one). `autoStop` sets
+   * how long it runs before stopping again; `false` never stops it.
+   */
+  resume(options?: {
+    readonly autoStop?: Duration.Input | false;
+  }): Effect.Effect<void, BoatError, RuntimeContext>;
+  /** Sets how long the sandbox runs from now before it stops; `false` never stops it. */
+  setAutoStop(autoStop: Duration.Input | false): Effect.Effect<void, BoatError, RuntimeContext>;
+  /** Saves the sandbox's disk as a named snapshot, and waits until it is ready. */
+  snapshot(name: string): Effect.Effect<boat.SavedSnapshot, BoatError, RuntimeContext>;
+}
+
+/**
+ * A sandbox created or connected at runtime (`CreateSandbox`). Holds only
+ * its id, so it can be rebuilt with `connect(id)` in any request.
+ */
+export interface BoatSandbox extends SandboxOperations {
+  readonly sandboxId: string;
+  /** What Boat returned for the sandbox when it was created or connected. */
+  readonly info: boat.Sandbox;
+  /**
+   * A copy of the sandbox from its last completed snapshot. Fails with
+   * `ForkNeedsSnapshot` until it has one; stopping a sandbox snapshots it.
+   */
+  fork(
+    options?: Omit<boat.ForkSandboxRequest, "sandboxId" | "ttlSeconds"> & {
+      /** How long the fork runs before Boat stops it; `false` never stops it. */
+      readonly autoStop?: Duration.Input | false;
+    },
+  ): Effect.Effect<BoatSandbox, BoatError, RuntimeContext>;
+  /** Deletes the sandbox with its disk. Deleting one that is gone succeeds. */
+  delete(): Effect.Effect<void, BoatError, RuntimeContext>;
+}
+
+/**
+ * A sandbox declared in the stack (`ConnectSandbox`). The same operations
+ * as {@link BoatSandbox} except `fork` and `delete`, which its key can't
+ * do; its id is read at runtime.
+ */
+export interface ConnectedSandbox extends SandboxOperations {
+  readonly sandboxId: Effect.Effect<string, never, RuntimeContext>;
+}

package/src/SandboxEvents.ts

@@ -0,0 +1,125 @@
+import { sanitizeKey } from "alchemy/RuntimeContext";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type { WebhookEvent } from "./Webhook.ts";
+
+/** A sandbox lifecycle event, as Boat delivers it to a webhook. */
+export interface SandboxEvent {
+  /** The event's id. A redelivered event keeps it: deduplicate on it. */
+  readonly id: string;
+  readonly type: WebhookEvent;
+  readonly createdAt: string;
+  readonly data: {
+    readonly sandbox: {
+      readonly id: string;
+      readonly name?: string;
+      /**
+       * The sandbox's labels, read from Boat when the event is scoped to the
+       * stack. `undefined` with `scope: "account"`.
+       */
+      readonly labels?: Readonly<Record<string, string>>;
+    };
+    /** On `sandbox.ready`, `sandbox.error` and `sandbox.archived`. */
+    readonly previousState?: string;
+    /** The state the sandbox is in now. */
+    readonly state?: string;
+    /** On `sandbox.degraded` and `sandbox.recovered`: why. */
+    readonly reason?: string;
+  };
+  /** Which delivery attempt this is, from 1. */
+  readonly attempt: number;
+}
+
+export interface SandboxEventsProps {
+  /**
+   * The events to receive.
+   * @default every sandbox lifecycle event
+   */
+  readonly events?: ReadonlyArray<WebhookEvent>;
+  /**
+   * Whose sandboxes. Boat sends a webhook every event in the account.
+   * `"stack"` hands the handler only the sandboxes this stack and stage own
+   * (declared, or created by its bindings), and adds each sandbox's labels
+   * to the event; `"account"` hands it everything.
+   * @default "stack"
+   */
+  readonly scope?: "stack" | "account";
+  /**
+   * The path on the host Boat delivers to.
+   * @default "/__alchemy/boat/events"
+   */
+  readonly path?: string;
+}
+
+/** Receives sandbox lifecycle events on a host. */
+export type SandboxEventsService = <Req = never>(
+  props: SandboxEventsProps,
+  process: (event: SandboxEvent) => Effect.Effect<void, never, Req>,
+) => Effect.Effect<void, never, never>;
+
+/**
+ * Receive Boat sandbox lifecycle events (`sandbox.ready`,
+ * `sandbox.hydrated`, `sandbox.error`, `sandbox.archived`,
+ * `sandbox.degraded`, `sandbox.recovered`) in a Cloudflare Worker or any
+ * other webhook host.
+ *
+ * At deploy, a {@link Webhook} is created pointing at the host, and its
+ * signing secret is given to the host as a secret (a Cloudflare secret on
+ * a Worker). While the host runs,
+ * each delivery's `X-Ascii-Signature` (HMAC-SHA256 over the delivery id,
+ * timestamp and raw body) is checked before the handler runs; an unsigned,
+ * wrongly signed, altered or stale (over five minutes old) request is
+ * refused with 401, and bodies over 1 MB are refused unread. Boat retries a
+ * failed delivery, so handlers should be idempotent on `event.id`.
+ *
+ * Boat sends a webhook the events of every sandbox in the account, and an
+ * account has at most 10 webhooks. With the default `scope: "stack"`, the
+ * host looks each sandbox up with a key of its own, created at deploy and
+ * deleted with the host, that can only read sandboxes (`sandbox.read`), and drops
+ * events for sandboxes other stacks or stages own, and for sandboxes
+ * already deleted. The scope is a filter, not an access boundary: anyone
+ * in the account who can create sandboxes can label one with the stack's
+ * labels.
+ *
+ * ### Handling lifecycle events
+ * **Example:** Record when a sandbox stops
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     yield* Boat.consumeSandboxEvents({ events: ["sandbox.archived"] }, (event) =>
+ *       Effect.log(`sandbox ${event.data.sandbox.id} stopped`),
+ *     );
+ *     return { fetch: Effect.succeed(HttpServerResponse.text("ok")) };
+ *   }).pipe(Effect.provide(Boat.SandboxEventsLive)),
+ * ) {}
+ * ```
+ *
+ * **Example:** Every sandbox in the account
+ * ```typescript
+ * yield* Boat.consumeSandboxEvents({ scope: "account", events: ["sandbox.error"] }, (event) =>
+ *   Effect.logError(`sandbox ${event.data.sandbox.id} failed`),
+ * );
+ * ```
+ *
+ * @binding
+ * @product Webhook
+ */
+export class SandboxEvents extends Context.Service<SandboxEvents, SandboxEventsService>()(
+  "Boat.SandboxEvents",
+) {}
+
+/** Subscribes the current host to sandbox lifecycle events. */
+export const consumeSandboxEvents = <Req = never>(
+  props: SandboxEventsProps,
+  process: (event: SandboxEvent) => Effect.Effect<void, never, Req>,
+) => SandboxEvents.use((source) => source(props, process));
+
+/** Where Boat delivers on the host. */
+export const sandboxEventsPath = (props: SandboxEventsProps): string =>
+  props.path ?? "/__alchemy/boat/events";
+
+/** The env var the signing secret is given to the host under. */
+export const sandboxEventsSecretEnvName = (path: string): string =>
+  `ALCHEMY_BOAT_WEBHOOK_SECRET_${sanitizeKey(path)}`;

package/src/SandboxEventsLive.ts

@@ -0,0 +1,88 @@
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import * as Namespace from "alchemy/Namespace";
+import * as Output from "alchemy/Output";
+import { RuntimeContext } from "alchemy/RuntimeContext";
+import { WebhookHost } from "alchemy/WebhookHost";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { bindBoat, bindOwnerLabels } from "./BoatBindings.ts";
+import { asSecret, handleDelivery } from "./internal/WebhookDelivery.ts";
+import {
+  type SandboxEvent,
+  SandboxEvents,
+  type SandboxEventsProps,
+  type SandboxEventsService,
+  sandboxEventsPath,
+  sandboxEventsSecretEnvName,
+} from "./SandboxEvents.ts";
+import { ALL_SANDBOX_EVENTS, Webhook } from "./Webhook.ts";
+
+/**
+ * {@link SandboxEvents} on any {@link WebhookHost}: every Cloudflare Worker
+ * is one.
+ *
+ * @layer
+ * @product Webhook
+ * @provides Boat.SandboxEvents
+ */
+export const SandboxEventsLive = Layer.effect(
+  SandboxEvents,
+  Effect.gen(function* () {
+    const host = yield* WebhookHost;
+    // Yielding the resource class erases its `Providers` requirement; the
+    // stack satisfies it at plan time.
+    const createWebhook = yield* Webhook;
+
+    return Effect.fn(function* (
+      props: SandboxEventsProps,
+      process: (event: SandboxEvent) => Effect.Effect<void, never, any>,
+    ) {
+      const path = sandboxEventsPath(props);
+
+      // Boat generates the signing secret. It goes to the host as a binding,
+      // not a prop: the webhook depends on the host's URL.
+      const runtime = yield* RuntimeContext;
+      const secretKey = sandboxEventsSecretEnvName(path);
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        yield* Namespace.push(
+          host.LogicalId,
+          Effect.gen(function* () {
+            // Boat delivers only to public HTTPS URLs, and under `alchemy dev`
+            // the host is on localhost: skip the webhook rather than fail.
+            const context = yield* Effect.serviceOption(AlchemyContext);
+            if (Option.isSome(context) && context.value.dev) {
+              yield* Effect.logWarning(
+                `Boat.consumeSandboxEvents: no webhook for ${path} under alchemy dev; Boat only delivers to public URLs, so deploy to receive events.`,
+              );
+              return;
+            }
+            const hook = yield* createWebhook(`BoatEvents${path}`, {
+              url: Output.interpolate`${host.url}${path}`,
+              events: [...(props.events ?? ALL_SANDBOX_EVENTS)],
+            });
+            yield* host.bind(`boat-webhook:${path}`, { env: { [secretKey]: hook.secret } });
+          }),
+        );
+      }
+      const boundSecret = Effect.map(runtime.get<unknown>(secretKey), asSecret);
+
+      // Scoped to the stack: the host reads each sandbox's labels with a
+      // key that may only read sandboxes.
+      const scope =
+        (props.scope ?? "stack") === "stack"
+          ? {
+              auth: yield* bindBoat("BoatEventsKey", "BOAT_EVENTS_KEY", {
+                actions: ["sandbox.read"],
+              }),
+              owner: yield* bindOwnerLabels,
+            }
+          : undefined;
+
+      const types = new Set<string>(props.events ?? ALL_SANDBOX_EVENTS);
+      yield* host.route(path, (request) =>
+        handleDelivery(request, boundSecret, types, scope, process),
+      );
+    }) as SandboxEventsService;
+  }),
+);

package/src/Snapshot.ts

@@ -0,0 +1,284 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { sha256Object } from "alchemy/Util/sha256";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { SnapshotFailed, SnapshotSetupFailed } from "./Errors.ts";
+import { declarable } from "./internal/Declared.ts";
+import { boatName, isGeneratedName, ownershipLabels } from "./internal/Ownership.ts";
+import type { Providers } from "./Providers.ts";
+import type { SandboxType } from "./Sandbox.ts";
+
+/** A snapshot to start from: a `Boat.Snapshot`, declared or yielded, or `{ name }`. */
+export interface SnapshotBase {
+  name: string;
+  /** A `Boat.Snapshot`'s setup hash. A rebuild replaces what starts from it. */
+  setupHash?: string;
+}
+
+export interface SnapshotProps {
+  /**
+   * Shell commands run in order before the snapshot is saved: clone a
+   * repository, install dependencies, warm a cache. A non-zero exit fails
+   * the deploy with `SnapshotSetupFailed`.
+   */
+  run: string[];
+  /**
+   * The snapshot to start from: another `Boat.Snapshot`, or `{ name }` of
+   * one saved elsewhere. Omit to start from a fresh sandbox. Rebuilding it
+   * takes this snapshot again.
+   */
+  from?: SnapshotBase;
+  /** Environment variables for the setup commands. */
+  env?: Record<string, string>;
+  /** Working directory for the setup commands. @default "/home/user" */
+  cwd?: string;
+  /**
+   * Machine size to build on. Sandboxes started from the snapshot default
+   * to it.
+   * @default "default"
+   */
+  type?: SandboxType;
+  /**
+   * Snapshot name: lowercase letters, digits and dashes, up to 63. If
+   * omitted, a unique name is generated from the stack, stage and logical
+   * ID. Changing it replaces the snapshot.
+   */
+  name?: string;
+}
+
+export interface SnapshotAttributes {
+  /** The name sandboxes start from. */
+  name: string;
+  /** Boat's id for the saved disk. */
+  snapshotId: string | undefined;
+  /** The machine size it was saved from. */
+  type: string | undefined;
+  /** Restored size, in bytes. */
+  sizeBytes: number | undefined;
+  /** Content hash of the base and setup. A deploy re-saves only when it changes. */
+  setupHash: string;
+}
+
+export interface Snapshot extends Resource<
+  "Boat.Snapshot",
+  SnapshotProps,
+  SnapshotAttributes,
+  never,
+  Providers,
+  { name: string }
+> {}
+
+/**
+ * A warm base for sandboxes: a sandbox set up with your commands and its
+ * disk saved under a name. Sandboxes started from it begin exactly where
+ * the setup left off: packages installed, a repository cloned, a build
+ * cache warm.
+ *
+ * Use a snapshot for work that is too slow to repeat per sandbox. Alchemy
+ * runs the commands in a sandbox of its own, saves it, and deletes the
+ * sandbox. A deploy re-runs the setup only when the commands or the base
+ * change, and a rebuild replaces the declared sandboxes started from it.
+ *
+ * ### Creating a Snapshot
+ * **Example:** A repository with its dependencies installed
+ * ```typescript
+ * export const Golden = Boat.Snapshot("Golden", {
+ *   run: [
+ *     "git clone https://github.com/alchemy-run/alchemy ~/alchemy",
+ *     "cd ~/alchemy && pnpm install",
+ *   ],
+ * });
+ * ```
+ *
+ * **Example:** Layer one snapshot on another
+ * ```typescript
+ * export const Tools = Boat.Snapshot("Tools", { run: ["npm i -g pnpm"] });
+ * export const Golden = Boat.Snapshot("Golden", { from: Tools, run: ["pnpm dlx playwright install"] });
+ * ```
+ *
+ * ### Starting sandboxes from a Snapshot
+ * **Example:** A declared sandbox
+ * ```typescript
+ * export const Box = Boat.Sandbox("Box", { snapshot: Golden });
+ * ```
+ *
+ * **Example:** Sandboxes created at run time
+ * ```typescript
+ * const sandboxes = yield* Boat.CreateSandbox(Golden);
+ * const sandbox = yield* sandboxes.create({ autoStop: "10 minutes" });
+ * ```
+ *
+ * ### Referencing a snapshot the stack doesn't manage
+ * **Example:** Look one up by name
+ * ```typescript
+ * const shared = Boat.Snapshot.lookup({ name: "team-base" });
+ * const sandboxes = yield* Boat.CreateSandbox(shared);
+ * ```
+ *
+ * @resource
+ * @product Snapshot
+ */
+export const Snapshot = declarable<Snapshot>()(Resource<Snapshot>("Boat.Snapshot"));
+
+/** Boat snapshot names: lowercase letters, digits and dashes. */
+const snapshotName = (id: string, name: string | undefined) =>
+  Effect.map(boatName(id, name, 63), (value) =>
+    name !== undefined ? value : value.replace(/[^a-z0-9-]/g, "-"),
+  );
+
+const setupHashOf = (props: SnapshotProps) =>
+  Effect.map(
+    sha256Object({
+      from: props.from === undefined ? null : [props.from.name, props.from.setupHash ?? null],
+      run: props.run,
+      env: props.env ?? {},
+      cwd: props.cwd ?? null,
+      type: props.type ?? "default",
+    }),
+    (hash) => hash.slice(0, 16),
+  );
+
+const observeSnapshot = (name: string) =>
+  boat.getSavedSnapshot({ name }).pipe(
+    Effect.map((got): boat.SavedSnapshot | undefined => got.snapshot),
+    Effect.catchTag("NotFound", () => Effect.undefined),
+  );
+
+const toAttributes = (snapshot: boat.SavedSnapshot, setupHash: string): SnapshotAttributes => ({
+  name: snapshot.name,
+  snapshotId: snapshot.snapshotId,
+  type: snapshot.type,
+  sizeBytes: snapshot.sizeBytes,
+  setupHash,
+});
+
+/** POSIX single quotes: the value verbatim. */
+const quote = (value: string) => `'${value.replaceAll("'", `'"'"'`)}'`;
+
+/** Saving takes seconds; poll until Boat reports `ready` or `failed` (about 90s at most). */
+const awaitSaved = (name: string) =>
+  boat.getSavedSnapshot({ name }).pipe(
+    Effect.map((got) => got.snapshot),
+    Effect.repeat({
+      schedule: Schedule.spaced("3 seconds"),
+      until: (snapshot) => snapshot.status !== "saving",
+      times: 30,
+    }),
+    Effect.flatMap((snapshot) =>
+      snapshot.status === "ready"
+        ? Effect.succeed(snapshot)
+        : new SnapshotFailed({
+            snapshot: name,
+            message:
+              snapshot.status === "failed"
+                ? `Boat could not save snapshot ${name}: ${snapshot.error ?? "unknown error"}`
+                : `Boat snapshot ${name} was still saving after 90 seconds`,
+          }),
+    ),
+  );
+
+/**
+ * Starts a setup sandbox (from `from`, with none of the account's secrets),
+ * runs the commands, saves it as `name`, and always deletes the sandbox.
+ */
+const takeSnapshot = Effect.fn(function* (id: string, name: string, props: SnapshotProps) {
+  const labels = yield* ownershipLabels(id);
+  return yield* Effect.acquireUseRelease(
+    boat.createSandbox({
+      noEnv: true,
+      ttlSeconds: 1800,
+      ...(props.type === undefined ? {} : { type: props.type }),
+      ...(props.from === undefined ? {} : { from: props.from.name }),
+      labels,
+    }),
+    ({ sandbox }) =>
+      Effect.gen(function* () {
+        const exports = Object.entries(props.env ?? {})
+          .map(([key, value]) => `export ${key}=${quote(value)}; `)
+          .join("");
+        for (const command of props.run) {
+          const result = yield* boat.executeSandboxCommand({
+            sandboxId: sandbox.id,
+            command: `${exports}${command}`,
+            timeoutSeconds: 600,
+            ...(props.cwd === undefined ? {} : { cwd: props.cwd }),
+          });
+          const exitCode = "exitCode" in result ? (result.exitCode ?? -1) : -1;
+          const timedOut = "timedOut" in result && result.timedOut === true;
+          if (exitCode !== 0 || timedOut) {
+            return yield* new SnapshotSetupFailed({
+              message: timedOut
+                ? `snapshot ${name}: \`${command}\` ran past 10 minutes`
+                : `snapshot ${name}: \`${command}\` exited with ${exitCode}`,
+              command,
+              exitCode,
+              stderr: "stderr" in result ? result.stderr.slice(-4000) : "",
+            });
+          }
+        }
+        yield* boat.saveSavedSnapshot({ sandboxId: sandbox.id, name });
+        return yield* awaitSaved(name);
+      }),
+    ({ sandbox }) =>
+      Effect.ignore(boat.deleteSandbox({ sandboxId: sandbox.id, xAsciiConfirmDelete: sandbox.id })),
+  );
+});
+
+export const SnapshotProvider = () =>
+  Provider.effect(
+    Snapshot,
+    Effect.gen(function* () {
+      return {
+        stables: ["name"],
+        diff: Effect.fn(function* ({ id, news, olds, output }) {
+          if (!isResolved(news) || olds === undefined) return undefined;
+          const name = yield* snapshotName(id, news.name ?? output?.name);
+          if (output !== undefined && name !== output.name) return { action: "replace" } as const;
+          if (output !== undefined && (yield* setupHashOf(news)) !== output.setupHash) {
+            return { action: "update" } as const;
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.name ?? (yield* snapshotName(id, olds?.name));
+          const snapshot = yield* observeSnapshot(name);
+          if (snapshot === undefined) return undefined;
+          const attrs = toAttributes(snapshot, output?.setupHash ?? "");
+          return output !== undefined || isGeneratedName(snapshot.name) ? attrs : Unowned(attrs);
+        }),
+        lookup: Effect.fn(function* ({ name }) {
+          const snapshot = yield* observeSnapshot(name);
+          return snapshot === undefined ? undefined : toAttributes(snapshot, "");
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name = yield* snapshotName(id, news.name ?? output?.name);
+          const setupHash = yield* setupHashOf(news);
+
+          // Observe — a ready snapshot of this exact setup is kept.
+          const observed = yield* observeSnapshot(name);
+          if (observed?.status === "ready" && output?.setupHash === setupHash) {
+            return toAttributes(observed, setupHash);
+          }
+
+          // Ensure — saving under an existing name replaces its disk.
+          yield* session.note(`Building snapshot ${name}...`);
+          return toAttributes(yield* takeSnapshot(id, name, news), setupHash);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* boat
+            .deleteSavedSnapshot({ name: output.name })
+            .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+          const listed = yield* boat.listSavedSnapshots({});
+          return listed.snapshots
+            .filter((snapshot) => isGeneratedName(snapshot.name))
+            .map((snapshot) => toAttributes(snapshot, ""));
+        }),
+      };
+    }),
+  );