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

package/lib/Providers.js

@@ -0,0 +1,47 @@
+import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
+import { ProfileStoreLive } from "alchemy/Auth/Profile";
+import * as Provider from "alchemy/Provider";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { AiProxy, AiProxyProvider } from "./AiProxy.js";
+import { ApiKey, ApiKeyProvider } from "./ApiKey.js";
+import { BoatAuth } from "./AuthProvider.js";
+import { CredentialProfile, CredentialProfileProvider } from "./CredentialProfile.js";
+import * as Credentials from "./Credentials.js";
+import { Environment, EnvironmentProvider } from "./Environment.js";
+import { Sandbox, SandboxProvider } from "./Sandbox.js";
+import { Snapshot, SnapshotProvider } from "./Snapshot.js";
+import { Webhook, WebhookProvider } from "./Webhook.js";
+/**
+ * Service tag bundling all Boat providers + auth + credentials. Use
+ * `Boat.providers()` to materialize the full layer.
+ */
+export class Providers extends Provider.ProviderCollection()("Boat") {
+}
+/**
+ * Build the complete Boat providers Layer: every Boat resource, the Boat
+ * AuthProvider registration (so `alchemy profile edit` can configure it),
+ * and credential resolution.
+ *
+ * `org` picks the organization (wallet) the stack's resources bill and the
+ * one whose shared environments `Boat.Environment` manages: an org id
+ * (`team_…`), an org name, or `personal`. It overrides the profile's `org`
+ * (or `BOAT_ORG`); with neither, Boat uses the account's active wallet and
+ * environments are your personal ones.
+ *
+ * @example
+ * ```ts
+ * Alchemy.Stack("App", { providers: Boat.providers() }, ...)
+ * Alchemy.Stack("App", { providers: Boat.providers({ org: "team_abc" }) }, ...)
+ * ```
+ */
+export const providers = (options) => Layer.effect(Providers, Provider.collection([
+    AiProxy,
+    ApiKey,
+    CredentialProfile,
+    Environment,
+    Sandbox,
+    Snapshot,
+    Webhook,
+])).pipe(Layer.provide(Layer.mergeAll(AiProxyProvider(), ApiKeyProvider(), CredentialProfileProvider(), EnvironmentProvider(), SandboxProvider(), SnapshotProvider(), WebhookProvider())), Layer.provideMerge(Credentials.fromAuthProvider(options)), Layer.provideMerge(FetchHttpClient.layer), Layer.provideMerge(BoatAuth), Layer.provideMerge(ProfileStoreLive), Layer.provideMerge(CredentialsStoreLive), Layer.orDie);
+//# sourceMappingURL=Providers.js.map

package/lib/Providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Providers.js","sources":["../src/Providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExD;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,QAAQ,CAAC,kBAAkB,EAAa,CAAC,MAAM,CAAC;CAAG;AAIlF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAmC,EAAE,EAAE,CAC/D,KAAK,CAAC,MAAM,CACV,SAAS,EACT,QAAQ,CAAC,UAAU,CAAC;IAClB,OAAO;IACP,MAAM;IACN,iBAAiB;IACjB,WAAW;IACX,OAAO;IACP,QAAQ;IACR,OAAO;CACR,CAAC,CACH,CAAC,IAAI,CACJ,KAAK,CAAC,OAAO,CACX,KAAK,CAAC,QAAQ,CACZ,eAAe,EAAE,EACjB,cAAc,EAAE,EAChB,yBAAyB,EAAE,EAC3B,mBAAmB,EAAE,EACrB,eAAe,EAAE,EACjB,gBAAgB,EAAE,EAClB,eAAe,EAAE,CAClB,CACF,EACD,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,EACzD,KAAK,CAAC,YAAY,CAAC,eAAe,CAAC,KAAK,CAAC,EACzC,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,EAC5B,KAAK,CAAC,YAAY,CAAC,gBAAgB,CAAC,EACpC,KAAK,CAAC,YAAY,CAAC,oBAAoB,CAAC,EACxC,KAAK,CAAC,KAAK,CACZ,CAAC"}

package/lib/Sandbox.d.ts

@@ -0,0 +1,205 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import type * as Bundle from "alchemy/Bundle/Bundle";
+import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { type HostRuntimeContext, type ServerHost } from "alchemy/Runtime/Process";
+import { Stack } from "alchemy/Stack";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { type ProgramState } from "./internal/Program.ts";
+import { type Ref } from "./internal/Ref.ts";
+import type { Providers } from "./Providers.ts";
+import type { SnapshotBase } from "./Snapshot.ts";
+/**
+ * Machine size. `small` runs at half the default rate and `large` at
+ * twice; `xlarge` needs the $100/month plan or higher.
+ */
+export type SandboxType = "small" | "default" | "large" | "xlarge";
+/** Where a sandbox is in its life. `archived` is stopped, with its disk saved. */
+export type SandboxState = "init" | "provisioning" | "provisioned" | "cloning" | "ready" | "idle" | "running" | "archiving" | "archived" | "error" | "cancelled";
+/** How the setup script went: `pending`, `running`, `done` or `failed`. */
+export type SandboxSetupStatus = "pending" | "running" | "done" | "failed";
+/** An environment, by name. Accepts a `Boat.Environment` or `{ name }`. */
+export interface SandboxEnvironmentRef {
+    name: string;
+}
+/** What bindings attach to a sandbox that runs a program: its process's environment. */
+export interface SandboxBinding {
+    env?: Record<string, any>;
+}
+export interface SandboxProps extends PlatformProps {
+    /**
+     * Display name. If omitted, a unique name is generated from the stack,
+     * stage and logical ID. Renamed in place.
+     */
+    name?: string;
+    /**
+     * Machine size. Changing it replaces the sandbox.
+     * @default "default"
+     */
+    type?: SandboxType;
+    /**
+     * How long the sandbox runs before Boat stops it, saving its disk;
+     * `false` never stops it. Updated in place: the next stop is then
+     * `autoStop` from the deploy.
+     * @default "1 hour", or `false` for a sandbox with `main`
+     */
+    autoStop?: Duration.Input | false;
+    /**
+     * Environment variables. On a sandbox without `main` they are the
+     * sandbox's, on top of its environment's, and changing them replaces it.
+     * On a sandbox with `main` they are the program's, and changing them
+     * restarts it.
+     */
+    env?: Record<string, string | Redacted.Redacted<string>>;
+    /**
+     * The `Boat.Environment` to attach (or `{ name }` of one): its
+     * variables, secret files and credential settings. Omit for the account's
+     * default environment (`base`). Changing it replaces the sandbox.
+     */
+    environment?: Ref<SandboxEnvironmentRef>;
+    /**
+     * Attach none of the account's secrets (no environment variables, secret
+     * files or credentials), and confine the sandbox so it can't act on the
+     * account. For sandboxes you give to your own users. Changing it replaces
+     * the sandbox.
+     * @default false
+     */
+    noEnv?: boolean;
+    /**
+     * `false` never snapshots the sandbox: stopping it erases its disk, and it
+     * can't be resumed, forked or saved. Changing it replaces the sandbox.
+     * @default true
+     */
+    snapshots?: boolean;
+    /**
+     * `false` keeps no command output, process list or metrics for the
+     * sandbox. Changing it replaces the sandbox.
+     * @default true
+     */
+    monitoring?: boolean;
+    /**
+     * A shell script run once, in the background, after the sandbox starts.
+     * Its outcome is `setupStatus`. Changing it replaces the sandbox.
+     */
+    setupScript?: string;
+    /**
+     * The `Boat.Snapshot` to start from (or `{ name }` of one saved
+     * elsewhere, or a share code `bsh_...`). Changing or rebuilding it
+     * replaces the sandbox, so it starts from the new disk.
+     */
+    snapshot?: Ref<SnapshotBase>;
+    /**
+     * Your own labels, at most 17 (Alchemy adds three). Boat sets labels
+     * only at create, so changing them replaces the sandbox.
+     */
+    labels?: Record<string, string>;
+    /**
+     * The sandbox's subdomain under `on.boat.dev`. Port `p` answers at
+     * `https://<subdomain>-<p>.on.boat.dev`. Renamed in place.
+     */
+    subdomain?: string;
+    /**
+     * Module entrypoint of a program to run in the sandbox, typically
+     * `import.meta.url` in the class form. Alchemy bundles it, uploads it
+     * into the sandbox and runs it with Node 24; a code change uploads it
+     * again and restarts the process, without replacing the sandbox.
+     */
+    main?: string;
+    /**
+     * Port the program listens on. Written to `PORT`; Boat serves it at
+     * `url`.
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * Serve the program's port to anyone. Otherwise requests need `urlToken`
+     * (as the `_token` query parameter, or the `_port_auth` cookie).
+     * Updated in place.
+     * @default false
+     */
+    public?: boolean;
+    /**
+     * Named export to load from `main`.
+     * @default "default"
+     */
+    handler?: string;
+    /** Bundler configuration for `main`. */
+    build?: Bundle.BundleConfig;
+    /**
+     * Who in the organization that pays for the sandbox can use it:
+     * `private`, only you; `shared`, every member. Omitted, the organization's
+     * default for new sandboxes applies. Updated in place. Sharing a sandbox
+     * that holds your logins (GitHub, Claude and Codex logins, environment
+     * secrets) wipes them at its next start and never pushes them again, so
+     * share one with `noEnv` or an environment that passes nothing. A
+     * personal sandbox is always private, and Boat refuses `shared` for one.
+     */
+    visibility?: "shared" | "private";
+}
+export interface SandboxAttributes {
+    /** Boat's sandbox id (`bx_…`). */
+    sandboxId: string;
+    name: string;
+    /** `ready`, `running`, `idle`, `archived` (stopped), … */
+    state: SandboxState;
+    type: SandboxType | undefined;
+    /** vCPUs and RAM (GB) the machine size guarantees. */
+    vcpu: number | undefined;
+    memoryGB: number | undefined;
+    /**
+     * The subdomain its ports are served under: port `p` answers at
+     * `https://<subdomain>-<p>.on.boat.dev`.
+     */
+    subdomain: string | undefined;
+    /** The machine's URL. */
+    machineUrl: string | undefined;
+    /** The environment the sandbox runs, and its version. */
+    environment: string | undefined;
+    environmentVersion: number | undefined;
+    /** Seconds it runs before stopping, or `undefined` when it never stops. */
+    ttlSeconds: number | undefined;
+    /** Your labels, without Alchemy's. */
+    labels: Record<string, string>;
+    /** The setup script's outcome: `pending`, `running`, `done` or `failed`. */
+    setupStatus: SandboxSetupStatus | undefined;
+    /** The program's URL, for a sandbox with `main`. */
+    url: string | undefined;
+    /**
+     * The token a request to `url` needs unless the sandbox is `public`: the
+     * `_token` query parameter, or the `_port_auth` cookie.
+     */
+    urlToken: Redacted.Redacted<string> | undefined;
+    /** The program the sandbox runs, for a sandbox with `main`. */
+    program: ProgramState | undefined;
+    /**
+     * The organization that pays for it, fixed when it was created;
+     * `undefined` when you do.
+     */
+    org: {
+        id: string;
+        name: string;
+    } | undefined;
+    /** `shared` or `private` for an organization's sandbox; `undefined` for yours. */
+    visibility: "shared" | "private" | undefined;
+}
+export type Sandbox = Resource<"Boat.Sandbox", SandboxProps, SandboxAttributes, SandboxBinding, Providers, {
+    sandboxId: string;
+}>;
+export type SandboxServices = ServerHost;
+/** A program's shape: a long-running server returning `{ fetch }`, or `host.run` loops. */
+export type SandboxShape = Main<SandboxServices>;
+export type SandboxRuntimeContext = HostRuntimeContext;
+export declare const Sandbox: Platform<Sandbox, SandboxServices, SandboxShape, SandboxRuntimeContext> & {
+    /** References a sandbox the stack doesn't manage, by id. */
+    readonly lookup: ReturnType<typeof Resource<Sandbox>>["lookup"];
+};
+/** A sandbox, or `undefined` when Boat no longer has it. */
+export declare const observeSandbox: (sandboxId: string) => Effect.Effect<boat.Sandbox | undefined, import("@distilled.cloud/boat-dev").BadGateway | import("@distilled.cloud/core/errors").BadRequest | import("@distilled.cloud/boat-dev").BoatParseError | import("@distilled.cloud/boat-dev").ConfigError | import("@distilled.cloud/core/errors").Conflict | import("@distilled.cloud/core/errors").Forbidden | import("@distilled.cloud/boat-dev").GatewayTimeout | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/boat-dev").InternalServerError | import("@distilled.cloud/core/protocol-http").InvalidInput | import("@distilled.cloud/boat-dev").Locked | import("@distilled.cloud/core/sdk-error").SdkError | import("@distilled.cloud/boat-dev").ServiceUnavailable | import("@distilled.cloud/boat-dev").TooManyRequests | import("@distilled.cloud/boat-dev").Unauthorized | import("@distilled.cloud/boat-dev").UnknownBoatError | import("@distilled.cloud/boat-dev").UnprocessableEntity, boat.BoatOpContext>;
+/** Delete a sandbox; deleting one that is gone succeeds. */
+export declare const deleteSandbox: (sandboxId: string) => Effect.Effect<void, import("@distilled.cloud/boat-dev").BadGateway | import("@distilled.cloud/core/errors").BadRequest | import("@distilled.cloud/boat-dev").BoatParseError | import("@distilled.cloud/boat-dev").ConfigError | import("@distilled.cloud/core/errors").Conflict | boat.Conflict | import("@distilled.cloud/core/errors").Forbidden | boat.Forbidden | import("@distilled.cloud/boat-dev").GatewayTimeout | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/boat-dev").InternalServerError | import("@distilled.cloud/core/protocol-http").InvalidInput | import("@distilled.cloud/boat-dev").Locked | import("@distilled.cloud/core/sdk-error").SdkError | import("@distilled.cloud/boat-dev").ServiceUnavailable | import("@distilled.cloud/boat-dev").TooManyRequests | import("@distilled.cloud/boat-dev").Unauthorized | import("@distilled.cloud/boat-dev").UnknownBoatError | import("@distilled.cloud/boat-dev").UnprocessableEntity, boat.BoatOpContext>;
+export declare const toAttributes: (sandbox: boat.Sandbox) => SandboxAttributes;
+export declare const SandboxProvider: () => import("effect/Layer").Layer<Provider.Provider<Sandbox>, never, import("effect/FileSystem").FileSystem | import("effect/Path").Path | Stack | import("alchemy/Stage").Stage | boat.BoatOpContext>;
+//# sourceMappingURL=Sandbox.d.ts.map

package/lib/Sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sandbox.d.ts","sources":["../src/Sandbox.ts"],"names":[],"mappings":"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"}

package/lib/Sandbox.js

@@ -0,0 +1,368 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import { Platform } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { createHostRuntimeContext, } from "alchemy/Runtime/Process";
+import { Stack } from "alchemy/Stack";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
+import { isDeclaration } from "./internal/Declared.js";
+import { boatName, hasAnyAlchemyLabel, hasOwnershipLabels, ownershipLabels, userLabels, } from "./internal/Ownership.js";
+import { bundleProgram, DEFAULT_PORT, deployProgram, isProgramRunning, } from "./internal/Program.js";
+import { resolved } from "./internal/Ref.js";
+/**
+ * A Boat sandbox the stack owns: a Linux machine with Docker, passwordless
+ * `sudo` and a desktop, that stops itself after `autoStop` and keeps its
+ * disk until it is resumed.
+ *
+ * Use it for a workspace that outlives requests (an agent's home, a dev
+ * box, a preview environment). Bindings create short-lived sandboxes at
+ * run time with `Boat.CreateSandbox`.
+ *
+ * Alchemy labels the sandbox with its stack, stage and logical ID
+ * (`alchemy.stack`, `alchemy.stage`, `alchemy.id`) to recognise the
+ * sandboxes it owns.
+ *
+ * The sandbox bills the stack's organization (`Boat.providers({ org })`,
+ * or the profile's), else your active wallet. Boat fixes the wallet at
+ * create, so changing the stack's `org` later leaves the sandbox where it
+ * is; `org` says which.
+ *
+ * :::caution
+ * Replacing the sandbox (a new `type`, `env`, `environment`, `noEnv`,
+ * `snapshots`, `monitoring`, `setupScript`, `labels`, or a new or rebuilt
+ * `snapshot`) creates a fresh sandbox and deletes the old one with its disk.
+ * :::
+ *
+ * ### Creating a Sandbox
+ * **Example:** A dev box that stops after an idle hour
+ * ```typescript
+ * import * as Boat from "@alchemy.run/boat";
+ *
+ * export const DevBox = Boat.Sandbox("DevBox", {
+ *   type: "large",
+ *   autoStop: "1 hour",
+ *   setupScript: "git clone https://github.com/alchemy-run/alchemy ~/alchemy",
+ * });
+ * ```
+ *
+ * **Example:** A sandbox with none of the account's secrets
+ * ```typescript
+ * export const Untrusted = Boat.Sandbox("Untrusted", {
+ *   noEnv: true,
+ *   env: { TASK: "lint" },
+ * });
+ * ```
+ *
+ * ### Running a Program
+ * The class form runs an Effect program in the sandbox: give it `main` and
+ * an implementation, and Alchemy bundles the program, uploads it and runs
+ * it with Node, served at `url`. A code change uploads the new bundle and
+ * restarts the process; the sandbox and its URL stay the same. A sandbox
+ * with `main` never stops on its own unless `autoStop` says so; if it
+ * stopped anyway, the next deploy resumes it and starts the program.
+ *
+ * **Example:** An HTTP server
+ * ```typescript
+ * export default class Api extends Boat.Sandbox<Api>()(
+ *   "Api",
+ *   { main: import.meta.url, public: true },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         return yield* HttpServerResponse.json({ ok: true });
+ *       }),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * ### Starting from a snapshot and an environment
+ * **Example:** A sandbox with a project set up and its secrets
+ * ```typescript
+ * export const Golden = Boat.Snapshot("Golden", { run: ["npm i -g pnpm"] });
+ * export const MyEnv = Boat.Environment("MyEnv", {
+ *   env: { API_TOKEN: Config.Redacted("API_TOKEN") },
+ * });
+ *
+ * export const Box = Boat.Sandbox("Box", {
+ *   snapshot: Golden,
+ *   environment: MyEnv,
+ *   autoStop: "30 minutes",
+ * });
+ * ```
+ *
+ * ### Sharing with an organization
+ * **Example:** A sandbox every member of the team can use
+ * ```typescript
+ * // with Boat.providers({ org: "acme" }) on the stack
+ * export const TeamBox = Boat.Sandbox("TeamBox", {
+ *   noEnv: true,
+ *   visibility: "shared",
+ * });
+ * ```
+ *
+ * ### Using it at runtime
+ * **Example:** Run a command in it from a Worker
+ * ```typescript
+ * const devBox = yield* Boat.ConnectSandbox(DevBox);
+ * // in fetch:
+ * yield* devBox.resume();
+ * const result = yield* devBox.exec("git pull && npm test", { cwd: "/home/user/repo" });
+ * ```
+ *
+ * ### Referencing a sandbox the stack doesn't manage
+ * **Example:** Look one up by id
+ * ```typescript
+ * const shared = Boat.Sandbox.lookup({ sandboxId: "bx_abc123" });
+ * const box = yield* Boat.ConnectSandbox(shared);
+ * ```
+ *
+ * @resource
+ * @product Sandbox
+ */
+/** The plain resource behind {@link Sandbox}, which carries `lookup`. */
+const SandboxResource = Resource("Boat.Sandbox");
+export const Sandbox = Object.assign(Platform("Boat.Sandbox", {
+    createRuntimeContext: createHostRuntimeContext("Boat.Sandbox"),
+    // A declaration passed as a prop (`snapshot: Golden`) is an Effect until
+    // yielded. Yield it here so it is registered and the prop resolves to
+    // its attributes, as with `yield* Golden` inside Effect.gen.
+    transformProps: (_id, props) => Effect.gen(function* () {
+        if (globalThis.__ALCHEMY_RUNTIME__)
+            return props;
+        // A lookup (`Boat.Environment.lookup({ name })`) is an Output, which
+        // the engine resolves; only a declaration is yielded.
+        const ref = (value) => isDeclaration(value)
+            ? value
+            : Effect.succeed(value);
+        return {
+            ...props,
+            snapshot: props.snapshot === undefined ? undefined : yield* ref(props.snapshot),
+            environment: props.environment === undefined ? undefined : yield* ref(props.environment),
+        };
+    }),
+}), { lookup: (props) => SandboxResource.lookup(props) });
+/** A sandbox, or `undefined` when Boat no longer has it. */
+export const observeSandbox = (sandboxId) => boat.getSandbox({ sandboxId }).pipe(Effect.map((got) => got.sandbox === undefined || got.sandbox.state === "cancelled" ? undefined : got.sandbox), Effect.catchTag("NotFound", () => Effect.undefined));
+/** Delete a sandbox; deleting one that is gone succeeds. */
+export const deleteSandbox = (sandboxId) => boat.deleteSandbox({ sandboxId, xAsciiConfirmDelete: sandboxId }).pipe(Effect.asVoid, Effect.catchTag("NotFound", () => Effect.void));
+const plainEnv = (env) => env === undefined
+    ? undefined
+    : Object.fromEntries(Object.entries(env).map(([key, value]) => [
+        key,
+        Redacted.isRedacted(value) ? Redacted.value(value) : value,
+    ]));
+export const toAttributes = (sandbox) => ({
+    sandboxId: sandbox.id,
+    name: sandbox.name,
+    state: sandbox.state,
+    type: sandbox.type,
+    vcpu: sandbox.vcpu,
+    memoryGB: sandbox.memoryGB,
+    subdomain: sandbox.subdomain ?? undefined,
+    machineUrl: sandbox.url ?? undefined,
+    environment: sandbox.environment ?? undefined,
+    environmentVersion: sandbox.environmentVersion ?? undefined,
+    ttlSeconds: sandbox.ttlSeconds ?? undefined,
+    labels: userLabels(sandbox.labels),
+    setupStatus: sandbox.setupStatus ?? undefined,
+    url: undefined,
+    urlToken: undefined,
+    program: undefined,
+    org: sandbox.team ? { id: sandbox.team.id, name: sandbox.team.name } : undefined,
+    visibility: sandbox.visibility ?? undefined,
+});
+/** The bindings still attached (a removed binding arrives as a `delete`). */
+const activeBindings = (bindings) => bindings.filter((binding) => binding.action !== "delete");
+/** The program's environment from its bindings. */
+const bindingEnv = (bindings) => activeBindings(bindings).reduce((acc, binding) => ({ ...acc, ...binding.data?.env }), {});
+/**
+ * Boat's `ttlSeconds` for `autoStop`: `null` never stops. Without
+ * `autoStop`, a program sandbox never stops and others keep Boat's default.
+ */
+const ttlSecondsOf = (autoStop, program) => autoStop === false
+    ? null
+    : autoStop === undefined
+        ? program
+            ? null
+            : undefined
+        : Math.max(1, Math.round(Duration.toMillis(Duration.fromInputUnsafe(autoStop)) / 1000));
+/** Props whose change means a new sandbox (Boat can't change them on a live one). */
+const replacingProps = (props) => JSON.stringify({
+    type: props.type ?? "default",
+    // A program's env is its process's: changing it restarts the program.
+    env: props.main === undefined ? (plainEnv(props.env) ?? {}) : undefined,
+    program: props.main !== undefined,
+    environment: props.environment === undefined ? undefined : resolved(props.environment).name,
+    noEnv: props.noEnv ?? false,
+    snapshots: props.snapshots ?? true,
+    monitoring: props.monitoring ?? true,
+    setupScript: props.setupScript,
+    snapshot: props.snapshot === undefined
+        ? undefined
+        : [resolved(props.snapshot).name, resolved(props.snapshot).setupHash ?? null],
+    labels: props.labels ?? {},
+});
+export const SandboxProvider = () => Provider.effect(Sandbox, Effect.gen(function* () {
+    const stack = yield* Stack;
+    // The bundled program's bootstrap reads these to rebuild the Stack at runtime.
+    const alchemyEnv = {
+        ALCHEMY_STACK_NAME: stack.name,
+        ALCHEMY_STAGE: stack.stage,
+        ALCHEMY_PHASE: "runtime",
+        HOST: "0.0.0.0",
+    };
+    return {
+        stables: ["sandboxId"],
+        diff: Effect.fn(function* ({ news, olds, output }) {
+            if (olds === undefined)
+                return undefined;
+            // A program's props are partly unresolved at plan (its bindings'
+            // env holds Outputs); the replacing ones are compared once known.
+            if (isResolved(news) && replacingProps(olds) !== replacingProps(news)) {
+                return { action: "replace" };
+            }
+            // The bundle depends only on `main`, `handler` and `build`, which
+            // are plain. A code change, or a process that ended (the sandbox
+            // stopped or rebooted), redeploys the program in place.
+            const props = news;
+            if (typeof props.main === "string" && output !== undefined) {
+                const { hash } = yield* bundleProgram({ ...props, main: props.main });
+                if (output.program === undefined || hash !== output.program.codeHash) {
+                    return { action: "update" };
+                }
+                if (!(yield* isProgramRunning(output.sandboxId, output.program))) {
+                    return { action: "update" };
+                }
+            }
+            return undefined;
+        }),
+        read: Effect.fn(function* ({ id, output }) {
+            if (output === undefined)
+                return undefined;
+            const sandbox = yield* observeSandbox(output.sandboxId);
+            if (sandbox === undefined)
+                return undefined;
+            // The program isn't visible on the sandbox; keep what the last deploy recorded.
+            const attrs = {
+                ...toAttributes(sandbox),
+                url: output.url,
+                urlToken: output.urlToken,
+                program: output.program,
+            };
+            return (yield* hasOwnershipLabels(id, sandbox.labels)) ? attrs : Unowned(attrs);
+        }),
+        lookup: Effect.fn(function* ({ sandboxId }) {
+            const sandbox = yield* observeSandbox(sandboxId);
+            return sandbox === undefined ? undefined : toAttributes(sandbox);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, bindings, session }) {
+            const name = yield* boatName(id, news.name ?? output?.name, 120);
+            const owner = yield* ownershipLabels(id);
+            const program = news.main !== undefined;
+            // A program serves for as long as the sandbox runs: don't stop it on a timer.
+            const ttlSeconds = ttlSecondsOf(news.autoStop, program);
+            // Observe — `output` caches the id; the sandbox may be gone.
+            let sandbox = output === undefined ? undefined : yield* observeSandbox(output.sandboxId);
+            // Ensure
+            if (sandbox === undefined) {
+                yield* session.note(`Creating sandbox ${name}...`);
+                const created = yield* boat.createSandbox({
+                    ...(news.type === undefined ? {} : { type: news.type }),
+                    ...(ttlSeconds === undefined ? {} : { ttlSeconds }),
+                    // A program's env is its process's, written at deploy, not the sandbox's.
+                    ...(news.env === undefined || program ? {} : { env: plainEnv(news.env) }),
+                    ...(news.environment === undefined
+                        ? {}
+                        : { environment: resolved(news.environment).name }),
+                    ...(news.noEnv === undefined ? {} : { noEnv: news.noEnv }),
+                    ...(news.snapshots === undefined ? {} : { snapshots: news.snapshots }),
+                    ...(news.monitoring === undefined ? {} : { monitoring: news.monitoring }),
+                    ...(news.setupScript === undefined ? {} : { setupScript: news.setupScript }),
+                    ...(news.snapshot === undefined ? {} : { from: resolved(news.snapshot).name }),
+                    ...(news.visibility === undefined ? {} : { visibility: news.visibility }),
+                    labels: { ...news.labels, ...owner },
+                });
+                sandbox = created.sandbox;
+            }
+            // Sync — a stopped program sandbox is resumed, so the program can run.
+            if (program && sandbox.state === "archived") {
+                yield* session.note(`Resuming sandbox ${name}...`);
+                const resumed = yield* boat.resumeSandbox({ sandboxId: sandbox.id });
+                sandbox = resumed.sandbox ?? sandbox;
+            }
+            // Sync — name, subdomain and auto-stop, against what Boat reports.
+            const ttlChanged = ttlSeconds !== undefined && (sandbox.ttlSeconds ?? null) !== ttlSeconds;
+            const subdomainChanged = news.subdomain !== undefined && sandbox.subdomain !== news.subdomain;
+            if (sandbox.name !== name || ttlChanged || subdomainChanged) {
+                const updated = yield* boat.updateSandbox({
+                    sandboxId: sandbox.id,
+                    ...(sandbox.name !== name ? { name } : {}),
+                    ...(ttlChanged ? { ttlSeconds } : {}),
+                    ...(subdomainChanged ? { subdomain: news.subdomain } : {}),
+                });
+                sandbox = updated.sandbox ?? sandbox;
+            }
+            // Sync — visibility, against what Boat reports.
+            if (news.visibility !== undefined &&
+                (sandbox.visibility ?? "private") !== news.visibility) {
+                yield* session.note(`Making sandbox ${name} ${news.visibility === "shared" ? "shared" : "private"}...`);
+                if (news.visibility === "shared") {
+                    const shared = yield* boat.shareSandbox({ sandboxId: sandbox.id });
+                    if (shared.restartRequired) {
+                        yield* session.note(`Sandbox ${name} is shared from its next start: stop and resume it to share it now.`);
+                    }
+                }
+                else {
+                    yield* boat.unshareSandbox({ sandboxId: sandbox.id });
+                }
+                sandbox = (yield* observeSandbox(sandbox.id)) ?? sandbox;
+            }
+            const attrs = toAttributes(sandbox);
+            if (news.main === undefined)
+                return attrs;
+            // Deploy the program into the running sandbox, then host its port.
+            const port = news.port ?? DEFAULT_PORT;
+            const state = yield* deployProgram({
+                id,
+                sandboxId: sandbox.id,
+                source: { ...news, main: news.main },
+                port,
+                env: { ...bindingEnv(bindings), ...alchemyEnv, PORT: String(port), ...news.env },
+                // A replaced sandbox runs nothing yet.
+                previous: output?.sandboxId === sandbox.id ? output.program : undefined,
+                note: session.note,
+            });
+            const hosted = yield* boat.hostPort({
+                sandboxId: sandbox.id,
+                port,
+                public: news.public ?? false,
+            });
+            const parsed = hosted.url === undefined ? undefined : new URL(hosted.url);
+            const token = parsed?.searchParams.get("_token") ?? undefined;
+            return {
+                ...attrs,
+                url: parsed?.origin,
+                urlToken: token === undefined ? undefined : Redacted.make(token),
+                program: state,
+            };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+            yield* deleteSandbox(output.sandboxId);
+        }),
+        // Declared sandboxes and the ones bindings create at run time both
+        // carry `alchemy.stack`, so `nuke` finds both.
+        list: Effect.fn(function* () {
+            const all = yield* Stream.runCollect(boat.listSandboxes.items({ limit: 100 }));
+            return Array.from(all)
+                .filter((sandbox) => sandbox.state !== "cancelled" && hasAnyAlchemyLabel(sandbox.labels))
+                .map(toAttributes);
+        }),
+    };
+}));
+//# sourceMappingURL=Sandbox.js.map