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

package/src/Webhook.ts

@@ -0,0 +1,163 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import { Unowned } from "alchemy/AdoptPolicy";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { boatName, isGeneratedName } from "./internal/Ownership.ts";
+import type { Providers } from "./Providers.ts";
+
+/** A sandbox lifecycle event Boat delivers. */
+export type WebhookEvent =
+  | "sandbox.ready"
+  | "sandbox.hydrated"
+  | "sandbox.error"
+  | "sandbox.archived"
+  | "sandbox.degraded"
+  | "sandbox.recovered";
+
+/** Every sandbox lifecycle event Boat sends. */
+export const ALL_SANDBOX_EVENTS: ReadonlyArray<WebhookEvent> = [
+  "sandbox.ready",
+  "sandbox.hydrated",
+  "sandbox.error",
+  "sandbox.archived",
+  "sandbox.degraded",
+  "sandbox.recovered",
+];
+
+export interface WebhookProps {
+  /** The public HTTPS endpoint (port 443) Boat POSTs events to. Updated in place. */
+  url: string;
+  /** The events to deliver. Updated in place. */
+  events: WebhookEvent[];
+  /**
+   * Display name. If omitted, a unique name is generated from the stack,
+   * stage and logical ID. Renamed in place.
+   */
+  name?: string;
+}
+
+export interface WebhookAttributes {
+  /** Boat's webhook id (`wh_…`). */
+  webhookId: string;
+  name: string;
+  url: string;
+  events: WebhookEvent[];
+  /**
+   * The secret Boat signs deliveries with. Boat shows it once, at creation;
+   * Alchemy keeps it in state.
+   */
+  secret: Redacted.Redacted<string>;
+}
+
+export interface Webhook extends Resource<
+  "Boat.Webhook",
+  WebhookProps,
+  WebhookAttributes,
+  never,
+  Providers
+> {}
+
+/**
+ * A Boat webhook: Boat POSTs sandbox lifecycle events (`sandbox.ready`,
+ * `sandbox.error`, `sandbox.archived`, `sandbox.hydrated`,
+ * `sandbox.degraded`, `sandbox.recovered`) to your endpoint, signed with
+ * `secret`.
+ *
+ * ### Receiving sandbox events
+ * **Example:** Deliver events to a Worker
+ * ```typescript
+ * const receiver = yield* Receiver;
+ * const hook = yield* Boat.Webhook("Events", {
+ *   url: Output.interpolate`${receiver.url}/boat`,
+ *   events: ["sandbox.ready", "sandbox.archived"],
+ * });
+ * ```
+ *
+ * @resource
+ * @product Webhook
+ */
+export const Webhook = Resource<Webhook>("Boat.Webhook");
+
+const redact = (value: string | Redacted.Redacted<string>) =>
+  Redacted.isRedacted(value) ? value : Redacted.make(value);
+
+const observeWebhook = (webhookId: string) =>
+  boat.getWebhook({ webhookId }).pipe(
+    Effect.map((got): boat.Webhook | undefined => got.webhook),
+    Effect.catchTag("NotFound", () => Effect.undefined),
+  );
+
+const toAttributes = (
+  webhook: boat.Webhook,
+  secret: Redacted.Redacted<string>,
+): WebhookAttributes => ({
+  webhookId: webhook.id,
+  name: webhook.name ?? "",
+  url: webhook.url,
+  events: [...webhook.events],
+  secret,
+});
+
+const sameEvents = (a: ReadonlyArray<string>, b: ReadonlyArray<string>) =>
+  JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+
+export const WebhookProvider = () =>
+  Provider.effect(
+    Webhook,
+    Effect.gen(function* () {
+      return {
+        stables: ["webhookId"],
+        read: Effect.fn(function* ({ olds, output }) {
+          // Boat shows the signing secret only at creation, so a webhook is
+          // only usable through state.
+          if (output === undefined) return undefined;
+          const webhook = yield* observeWebhook(output.webhookId);
+          if (webhook === undefined) return undefined;
+          const attrs = toAttributes(webhook, output.secret);
+          return olds !== undefined || isGeneratedName(webhook.name) ? attrs : Unowned(attrs);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name = yield* boatName(id, news.name ?? output?.name, 100);
+
+          // Observe
+          let webhook = output === undefined ? undefined : yield* observeWebhook(output.webhookId);
+
+          // Ensure
+          if (webhook === undefined || output === undefined) {
+            yield* session.note(`Creating webhook ${name}...`);
+            const created = yield* boat.createWebhook({ name, url: news.url, events: news.events });
+            return toAttributes(created.webhook, redact(created.secret));
+          }
+
+          // Sync — name, URL and events, against what Boat reports.
+          if (
+            webhook.name !== name ||
+            webhook.url !== news.url ||
+            !sameEvents(webhook.events, news.events)
+          ) {
+            const updated = yield* boat.updateWebhook({
+              webhookId: webhook.id,
+              name,
+              url: news.url,
+              events: news.events,
+            });
+            webhook = updated.webhook;
+          }
+          return toAttributes(webhook, output.secret);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* boat
+            .deleteWebhook({ webhookId: output.webhookId })
+            .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+          const listed = yield* boat.listWebhooks({});
+          return listed.webhooks
+            .filter((webhook) => isGeneratedName(webhook.name))
+            .map((webhook) => toAttributes(webhook, Redacted.make("")));
+        }),
+      };
+    }),
+  );

package/src/globals.d.ts

@@ -0,0 +1,2 @@
+// `globalThis.__ALCHEMY_RUNTIME__`, declared by alchemy's Phase module.
+import type {} from "alchemy/Phase";

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from "./AiProxy.ts";
+export * from "./ApiKey.ts";
+export * from "./AuthProvider.ts";
+export * from "./ConnectSandbox.ts";
+export * from "./ConnectSandboxHttp.ts";
+export * from "./CreateSandbox.ts";
+export * from "./CreateSandboxHttp.ts";
+export * from "./CredentialProfile.ts";
+export * from "./Credentials.ts";
+export * from "./Environment.ts";
+export * from "./Errors.ts";
+export * from "./Providers.ts";
+export * from "./Sandbox.ts";
+export * from "./SandboxClient.ts";
+export * from "./SandboxEvents.ts";
+export * from "./SandboxEventsLive.ts";
+export * from "./Snapshot.ts";
+export * from "./Webhook.ts";

package/src/internal/Declared.ts

@@ -0,0 +1,87 @@
+import type { PropsInput } from "alchemy/Input";
+import * as Output from "alchemy/Output";
+import { isResource } from "alchemy/Resource";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Providers } from "../Providers.ts";
+
+type Leaf =
+  | string
+  | number
+  | boolean
+  | bigint
+  | symbol
+  | null
+  | undefined
+  | Redacted.Redacted<any>
+  | Uint8Array
+  | Date
+  | ((...args: any[]) => any);
+
+/**
+ * A prop value, or the declaration of a resource that has it: `template: Node`
+ * instead of `template: yield* Node`, at any depth.
+ */
+export type Declared<T> = T extends Leaf
+  ? T
+  : T extends Output.Output<any>
+    ? T
+    : T extends ReadonlyArray<infer U>
+      ? Declared<U>[] | Effect.Effect<T, never, Providers>
+      : { [K in keyof T]: Declared<T[K]> } | Effect.Effect<T, never, Providers>;
+
+/** Props where any value may be a resource declaration. */
+export type DeclaredProps<P> = { [K in keyof PropsInput<P>]: Declared<PropsInput<P>[K]> };
+
+const isPlain = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+/**
+ * A declaration still to be yielded: an Effect that isn't an Output, a
+ * resource, or a Config (which the engine resolves as a prop value).
+ */
+export const isDeclaration = (value: unknown): value is Effect.Effect<unknown, never, Providers> =>
+  Effect.isEffect(value) &&
+  !Output.isOutput(value) &&
+  !isResource(value) &&
+  !Config.isConfig(value);
+
+const hasDeclarations = (value: unknown): boolean =>
+  isDeclaration(value) ||
+  (Array.isArray(value) && value.some(hasDeclarations)) ||
+  (isPlain(value) && !isResource(value) && Object.values(value).some(hasDeclarations));
+
+/** Yield every declaration in `value`, at any depth. */
+export const resolveDeclarations = (value: unknown): Effect.Effect<unknown, never, Providers> =>
+  isDeclaration(value)
+    ? value
+    : Array.isArray(value)
+      ? Effect.forEach(value, resolveDeclarations)
+      : isPlain(value) && !isResource(value) && hasDeclarations(value)
+        ? Effect.map(
+            Effect.forEach(Object.entries(value), ([key, entry]) =>
+              Effect.map(resolveDeclarations(entry), (resolved) => [key, resolved] as const),
+            ),
+            Object.fromEntries,
+          )
+        : Effect.succeed(value);
+
+/**
+ * Let a resource's props hold declarations of other resources, which are
+ * yielded when the resource is: `Boat.Sandbox("Box", { snapshot: Golden })`.
+ * Props without declarations are passed through unchanged.
+ */
+export const declarable =
+  <R extends { readonly Props: any }>() =>
+  <C extends object>(
+    resource: C,
+  ): C & ((id: string, props: DeclaredProps<R["Props"]>) => Effect.Effect<R, never, Providers>) =>
+    new Proxy(resource as C & ((...args: unknown[]) => unknown), {
+      apply: (target, self, args: unknown[]) =>
+        typeof args[0] === "string" && hasDeclarations(args[1])
+          ? Reflect.apply(target, self, [args[0], resolveDeclarations(args[1])])
+          : Reflect.apply(target, self, args),
+    }) as never;

package/src/internal/Org.ts

@@ -0,0 +1,31 @@
+import { Credentials } from "@distilled.cloud/boat-dev/Credentials";
+import * as Effect from "effect/Effect";
+
+/**
+ * The stack's org (`Boat.providers({ org })`, or the profile's), or
+ * `undefined` for none, and for `personal`: both mean what is yours.
+ * `/environments` routes ignore `X-Boat-Org`, so the org the protocol sends
+ * on every other call is passed there as the `org` query.
+ */
+export const stackOrg = Effect.gen(function* () {
+  const { org } = yield* yield* Credentials;
+  const named = org?.trim();
+  return named && named.toLowerCase() !== "personal" ? named : undefined;
+});
+
+/** The same organization, however it was spelled (Boat ignores case). */
+export const sameOrg = (a: string | undefined, b: string | undefined) =>
+  (a?.toLowerCase() ?? "personal") === (b?.toLowerCase() ?? "personal");
+
+/** The `org` query parameter, when there is an org. */
+export const inOrg = (org: string | undefined) => (org ? { org } : {});
+
+/** Whether an account (a person or an organization) is the one `org` names. */
+export const isOrgAccount = (
+  account: { id: string; kind: "personal" | "org" | (string & {}); name: string },
+  org: string | undefined,
+) =>
+  org === undefined
+    ? account.kind === "personal"
+    : account.kind === "org" &&
+      (account.id === org || account.name.toLowerCase() === org.toLowerCase());

package/src/internal/Ownership.ts

@@ -0,0 +1,75 @@
+/**
+ * Naming and ownership helpers shared by every Boat resource and binding.
+ *
+ * Boat sandboxes carry labels, set once at create. Label keys can't hold
+ * `:`, so Alchemy's `alchemy::stack` / `alchemy::stage` / `alchemy::id`
+ * ownership tags are written as `alchemy.stack` / `alchemy.stage` /
+ * `alchemy.id`. Environments, snapshots, webhooks and API keys carry only a
+ * name, so a resource whose name the engine generated is recognised as ours
+ * by that name; an explicit name found without prior state is `Unowned`.
+ */
+import { createPhysicalName } from "alchemy/PhysicalName";
+import { createInternalTags } from "alchemy/Tags";
+import * as Effect from "effect/Effect";
+
+const INTERNAL_PREFIX = "alchemy::";
+
+/** Labels as Boat returns them. */
+export type Labels = Readonly<Record<string, string | undefined>> | null | undefined;
+
+/** The prefix Alchemy's ownership labels share. */
+export const ALCHEMY_LABEL_PREFIX = "alchemy.";
+
+/** `alchemy::stack` → `alchemy.stack`. */
+export const toLabelKey = (key: string) =>
+  key.startsWith(INTERNAL_PREFIX)
+    ? `${ALCHEMY_LABEL_PREFIX}${key.slice(INTERNAL_PREFIX.length)}`
+    : key;
+
+/** This resource's ownership labels: `alchemy.stack`, `alchemy.stage`, `alchemy.id`. */
+export const ownershipLabels = Effect.fn(function* (id: string) {
+  const tags = yield* createInternalTags(id);
+  return Object.fromEntries(
+    Object.entries(tags).map(([key, value]) => [toLabelKey(key), value]),
+  ) as Record<string, string>;
+});
+
+/** Whether labels carry this resource's ownership labels. */
+export const hasOwnershipLabels = Effect.fn(function* (id: string, labels: Labels) {
+  const expected = yield* ownershipLabels(id);
+  return Object.entries(expected).every(([key, value]) => labels?.[key] === value);
+});
+
+/** Whether labels were set by any Alchemy stack or binding (for nuke). */
+export const hasAnyAlchemyLabel = (labels: Labels) =>
+  labels !== undefined && labels !== null && `${ALCHEMY_LABEL_PREFIX}stack` in labels;
+
+/** Labels without Alchemy's own. */
+export const userLabels = (labels: Labels): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(labels ?? {}).filter(
+      (entry): entry is [string, string] =>
+        entry[1] !== undefined && !entry[0].startsWith(ALCHEMY_LABEL_PREFIX),
+    ),
+  );
+
+/** `key=value` filters for `listSandboxes`. */
+export const labelFilter = (labels: Readonly<Record<string, string>>) =>
+  Object.entries(labels).map(([key, value]) => `${key}=${value}`);
+
+/**
+ * A Boat name: the user's, or one generated from the stack, stage and
+ * logical id. Lowercase letters, digits and dashes fit every Boat name rule
+ * (snapshot names allow nothing else).
+ */
+export const boatName = (id: string, name: string | undefined, maxLength = 63) =>
+  name !== undefined
+    ? Effect.succeed(name)
+    : createPhysicalName({ id, lowercase: true, maxLength, delimiter: "-" });
+
+/**
+ * Whether a name looks generated by `createPhysicalName` (lowercase, ending
+ * in a base32 instance suffix). `list` reports only these, for nuke.
+ */
+export const isGeneratedName = (name: string | null | undefined): boolean =>
+  typeof name === "string" && /^[a-z0-9][a-z0-9_-]*-[a-z2-7]{8,16}$/.test(name);

package/src/internal/Program.ts

@@ -0,0 +1,250 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import * as Bundle from "alchemy/Bundle/Bundle";
+import { findCwdForBundle, resolveMainPath } from "alchemy/Bundle/TempRoot";
+import { sha256Object } from "alchemy/Util/sha256";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
+import type * as rolldown from "rolldown";
+
+/**
+ * INTERNAL — the program a `Boat.Sandbox` with `main` runs: bundled with
+ * rolldown, uploaded into the sandbox, and run with Node as a background
+ * command.
+ */
+
+/** The program didn't come up: it exited, or never listened on its port. */
+export class ProgramStartFailed extends Data.TaggedError("Boat.ProgramStartFailed")<{
+  readonly message: string;
+  readonly stdout: string;
+  readonly stderr: string;
+}> {}
+
+/** What a sandbox's program is: the props that shape its bundle. */
+export interface ProgramSource {
+  readonly main: string;
+  readonly handler?: string;
+  readonly isExternal?: boolean;
+  readonly build?: Bundle.BundleConfig;
+}
+
+/** The running program, as recorded in the sandbox's attributes. */
+export interface ProgramState {
+  /** Port the program listens on. */
+  readonly port: number;
+  /** Boat's process id for the background command running it. */
+  readonly processId: number;
+  /** Content hash of the bundled program. */
+  readonly codeHash: string;
+  /** Hash of the process environment. */
+  readonly envHash: string;
+}
+
+export const DEFAULT_PORT = 3000;
+const DIR = "/home/user/.alchemy/program";
+
+/** Boat writes files up to 5 MiB in one call; larger ones go through a signed upload URL. */
+const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+
+/** The generated entry: a shim importing only the bootstrap and `main`. */
+const makeBootstrap =
+  (handler: string) =>
+  (importPath: string): string =>
+    `
+import { bootstrap } from "@alchemy.run/boat/Bootstrap";
+import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};
+
+await bootstrap(entrypoint);
+`;
+
+const shellQuote = (value: unknown) => {
+  const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
+  return `'${text.replaceAll("'", `'\\''`)}'`;
+};
+
+/** The process environment as a shell file, sorted so its hash is stable. */
+export const renderEnv = (env: Record<string, unknown>) =>
+  Object.entries(env)
+    .filter(([, value]) => value !== undefined)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(
+      ([key, value]) =>
+        `${key}=${shellQuote(Redacted.isRedacted(value) ? Redacted.value(value) : value)}`,
+    )
+    .join("\n") + "\n";
+
+/** Bundle `main` for Node, with the Boat bootstrap around an Effect program. */
+export const bundleProgram = Effect.fn(function* (source: ProgramSource) {
+  const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
+  const realMain = yield* resolveMainPath(source.main);
+  const cwd = yield* findCwdForBundle(realMain);
+  const plugins: rolldown.RolldownPluginOption = source.isExternal
+    ? undefined
+    : virtualEntryPlugin(makeBootstrap(source.handler ?? "default"));
+  const output = yield* Bundle.build(
+    {
+      ...source.build?.input,
+      input: realMain,
+      cwd,
+      platform: "node",
+      resolve: {
+        conditionNames: [...Bundle.NODE_CONDITION_NAMES],
+        ...source.build?.input?.resolve,
+      },
+      plugins: [source.build?.input?.plugins, plugins],
+    },
+    {
+      ...source.build?.output,
+      format: "esm",
+      sourcemap: source.build?.output?.sourcemap ?? false,
+      minify: source.build?.output?.minify ?? false,
+      entryFileNames: "index.mjs",
+    },
+    source.build,
+  );
+  const files = output.files.map((file) => ({
+    path: file.path,
+    content:
+      typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content,
+  }));
+  return { files, hash: (yield* sha256Object({ bundle: output.hash })).slice(0, 16) };
+});
+
+/** The hash of a process environment. */
+export const envHashOf = (env: Record<string, unknown>) =>
+  Effect.map(sha256Object({ env: renderEnv(env) }), (hash) => hash.slice(0, 16));
+
+/**
+ * Whether the program's process still runs. A stopped or deleted sandbox,
+ * or a process Boat no longer knows, is not running.
+ */
+export const isProgramRunning = (sandboxId: string, state: ProgramState) =>
+  boat.getCommandStatus({ sandboxId, processId: state.processId, tailBytes: 0 }).pipe(
+    Effect.map((status) => status.running),
+    Effect.orElseSucceed(() => false),
+  );
+
+const toBase64 = (bytes: Uint8Array) => {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+
+/** Write one file into the sandbox, through a signed URL when it is too large for one call. */
+const upload = Effect.fn(function* (sandboxId: string, path: string, content: Uint8Array) {
+  if (content.byteLength <= MAX_INLINE_BYTES) {
+    yield* boat.writeSandboxFile({
+      sandboxId,
+      path,
+      content: toBase64(content),
+      encoding: "base64",
+    });
+    return;
+  }
+  const signed = yield* boat.createUploadUrl({ sandboxId, path, ttlSeconds: 600 });
+  const client = HttpClient.filterStatusOk(yield* HttpClient.HttpClient);
+  yield* client.execute(
+    HttpClientRequest.put(signed.url).pipe(HttpClientRequest.bodyUint8Array(content)),
+  );
+});
+
+/**
+ * Upload the bundle and (re)start the process, unless the same bundle and
+ * environment already run. Returns the program's state.
+ */
+export const deployProgram = Effect.fn(function* (input: {
+  readonly id: string;
+  readonly sandboxId: string;
+  readonly source: ProgramSource;
+  readonly port: number;
+  readonly env: Record<string, unknown>;
+  readonly previous: ProgramState | undefined;
+  readonly note: (message: string) => Effect.Effect<void>;
+}) {
+  const { id, sandboxId, port } = input;
+  const envFile = renderEnv(input.env);
+  const envHash = yield* envHashOf(input.env);
+  const { files, hash } = yield* bundleProgram(input.source);
+
+  const previous = input.previous;
+  const running =
+    previous !== undefined &&
+    previous.codeHash === hash &&
+    previous.envHash === envHash &&
+    previous.port === port &&
+    (yield* isProgramRunning(sandboxId, previous));
+  if (running) return previous;
+
+  const dir = `${DIR}/${hash}`;
+  yield* input.note(`Uploading ${id}'s program...`);
+  // Rolldown's entry chunk is `index.mjs`; other chunks keep their names.
+  yield* Effect.forEach(
+    files,
+    (file, i) => upload(sandboxId, `${dir}/${i === 0 ? "index.mjs" : file.path}`, file.content),
+    { concurrency: 4, discard: true },
+  );
+  yield* upload(sandboxId, `${dir}/.env`, new TextEncoder().encode(envFile));
+
+  // Replace the running process.
+  if (previous !== undefined) {
+    yield* boat.stopCommand({ sandboxId, processId: previous.processId }).pipe(Effect.ignore);
+  }
+  // Free the port from any earlier copy Boat lost track of (a crashed deploy).
+  yield* boat
+    .executeSandboxCommand({ sandboxId, command: `fuser -k ${port}/tcp 2>/dev/null; true` })
+    .pipe(Effect.ignore);
+  const started = yield* boat.executeSandboxCommand({
+    sandboxId,
+    command: `chmod 600 ${dir}/.env && cd ${dir} && set -a && . ./.env && set +a && exec node index.mjs`,
+    detached: true,
+  });
+  if (!("processId" in started) || typeof started.processId !== "number") {
+    return yield* new ProgramStartFailed({
+      message: `Boat started ${id}'s program without a process id`,
+      stdout: "",
+      stderr: "",
+    });
+  }
+  const processId = started.processId;
+
+  // Ready once the port listens; fail with the logs if the process exits.
+  yield* input.note(`Starting ${id}'s program on port ${port}...`);
+  const ready = yield* Effect.gen(function* () {
+    const status = yield* boat.getCommandStatus({ sandboxId, processId, tailBytes: 0 });
+    if (!status.running) return "exited" as const;
+    const probe = yield* boat.executeSandboxCommand({
+      sandboxId,
+      command: `(exec 3<>/dev/tcp/127.0.0.1/${port}) 2>/dev/null`,
+      timeoutSeconds: 5,
+    });
+    return "exitCode" in probe && probe.exitCode === 0
+      ? ("listening" as const)
+      : ("starting" as const);
+  }).pipe(
+    Effect.repeat({
+      schedule: Schedule.spaced("1 second"),
+      until: (state) => state !== "starting",
+      times: 60,
+    }),
+  );
+  if (ready !== "listening") {
+    const logs = yield* boat.getCommandStatus({ sandboxId, processId });
+    return yield* new ProgramStartFailed({
+      message:
+        ready === "exited"
+          ? `${id}'s program exited before listening on port ${port}`
+          : `${id}'s program did not listen on port ${port} within 60 seconds`,
+      stdout: logs.stdout,
+      stderr: logs.stderr,
+    });
+  }
+  // Keep only the running bundle.
+  yield* boat.executeSandboxCommand({
+    sandboxId,
+    command: `find ${DIR} -mindepth 1 -maxdepth 1 ! -name ${hash} -exec rm -rf {} +`,
+  });
+  return { port, processId, codeHash: hash, envHash } satisfies ProgramState;
+});

package/src/internal/Ref.ts

@@ -0,0 +1,15 @@
+import type * as Effect from "effect/Effect";
+import type { Providers } from "../Providers.ts";
+
+/**
+ * A prop that takes another resource, or a stub with the attributes it
+ * needs (`{ name }`, `{ volumeId }`). Users pass the declaration itself.
+ */
+export type Ref<T> = T | Effect.Effect<T, never, Providers>;
+
+/**
+ * A `Ref` prop as lifecycle operations see it. The engine resolves
+ * resource-valued props to their attributes before `diff`, `reconcile`
+ * and the other lifecycle operations run, so the value is always plain.
+ */
+export const resolved = <T>(ref: Ref<T>): T => ref as T;