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

package/src/Volume.ts

@@ -0,0 +1,229 @@
+import * as volumes from "@distilled.cloud/daytona/volumes";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { isOwnedName, resolveName } from "./internal/Names.ts";
+import { waitForState, waitUntilGone } from "./internal/Wait.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface VolumeProps {
+  /**
+   * Volume name, unique in the organization. If omitted, a unique name is
+   * generated from the stack, stage and logical ID. Changing it replaces
+   * the volume (and its files).
+   */
+  name?: string;
+}
+
+export interface VolumeAttributes {
+  /** Volume ID. */
+  volumeId: string;
+  /** Volume name. */
+  name: string;
+  /** Volume state (`ready` once usable). */
+  state: volumes.VolumeState;
+  /** When the volume was created. */
+  createdAt: string;
+}
+
+export type Volume = Resource<
+  "Daytona.Volume",
+  VolumeProps,
+  VolumeAttributes,
+  never,
+  Providers,
+  VolumeLookup
+>;
+
+/**
+ * Props for {@link Volume.lookup}: find a volume this stack
+ * doesn't manage by its name.
+ */
+export interface VolumeLookup {
+  /** Volume name. */
+  name: string;
+}
+
+/**
+ * A Daytona volume: a persistent disk, backed by object storage, that
+ * sandboxes mount at a path. Its files outlive every sandbox that mounts
+ * it, and several sandboxes can mount it at once.
+ *
+ * Declare a volume here for data your whole app shares, like a dataset or
+ * a package cache. For a volume per user or per session, create it at
+ * runtime with {@link CreateVolume}.
+ * @see https://www.daytona.io/docs/en/volumes/
+ *
+ * ### Creating a Volume
+ * **Example:** A shared cache volume
+ * ```typescript
+ * export const Cache = Daytona.Volume("Cache", {});
+ * ```
+ *
+ * ### Mounting a Volume
+ * **Example:** Mount it in a sandbox declared at deploy
+ * ```typescript
+ * export const DevBox = Daytona.Sandbox("DevBox", {
+ *   snapshot: Base,
+ *   mounts: [{ volume: Cache, path: "/cache" }],
+ * });
+ * ```
+ *
+ * **Example:** Mount it in sandboxes created at runtime
+ * ```typescript
+ * const cache = yield* Daytona.MountVolume(Cache, { path: "/cache" });
+ * const sandbox = yield* sandboxes.create({ mounts: [cache] });
+ * ```
+ *
+ * ### Looking up an existing volume
+ * `Volume.lookup` references a volume Alchemy doesn't manage (created in
+ * the Daytona dashboard or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Mount an existing volume
+ * ```typescript
+ * const data = Daytona.Volume.lookup({ name: "datasets" });
+ * ```
+ *
+ * @resource
+ * @product Volume
+ */
+export const Volume = Resource<Volume>("Daytona.Volume");
+
+export const toVolumeAttributes = (v: volumes.VolumeDto): VolumeAttributes => ({
+  volumeId: v.id,
+  name: v.name,
+  state: v.state,
+  createdAt: v.createdAt,
+});
+
+const isLive = (v: volumes.VolumeDto) =>
+  v.state !== "deleted" && v.state !== "deleting" && v.state !== "pending_delete";
+
+export const getVolumeByName = (name: string) =>
+  volumes.getVolumeByName({ name }).pipe(
+    Effect.map((v) => (isLive(v) ? v : undefined)),
+    Effect.catchTag("VolumeNotFound", () => Effect.undefined),
+  );
+
+export const getVolumeById = (volumeId: string) =>
+  volumes.getVolume({ volumeId }).pipe(
+    Effect.map((v) => (isLive(v) ? v : undefined)),
+    Effect.catchTag("VolumeNotFound", () => Effect.undefined),
+  );
+
+export const waitForVolume = (volumeId: string) =>
+  waitForState({
+    kind: "volume",
+    id: volumeId,
+    observe: volumes.getVolume({ volumeId }),
+    want: ["ready"],
+    fail: ["error"],
+    reason: (v) => v.errorReason,
+  });
+
+/**
+ * The volume named `name`, created if missing. A create racing another
+ * caller (`VolumeAlreadyExists`) re-reads the winner.
+ */
+export const ensureVolume = Effect.fn(function* (name: string) {
+  const existing = yield* getVolumeByName(name);
+  const volume =
+    existing ??
+    (yield* volumes
+      .createVolume({ name })
+      .pipe(Effect.catchTag("VolumeAlreadyExists", () => volumes.getVolumeByName({ name }))));
+  return volume.state === "ready" ? volume : yield* waitForVolume(volume.id);
+});
+
+/**
+ * Delete a volume. With `wait` (deploy), retry while a sandbox still
+ * mounts it and wait until it is gone. At run time `wait` is off: a
+ * request fails at once with `VolumeInUse` and returns as soon as Daytona
+ * accepts the delete. Daytona releases a volume about a minute after the
+ * sandbox that wrote to it is deleted, which is longer than a request
+ * should wait.
+ */
+export const deleteVolumeById = Effect.fn(function* (
+  volumeId: string,
+  options: { readonly wait: boolean } = { wait: true },
+) {
+  yield* volumes.deleteVolume({ volumeId }).pipe(
+    Effect.catchTags({
+      VolumeNotFound: () => Effect.void,
+      // Refused while the volume is still being created (wait for it) or is
+      // already being deleted (nothing left to do).
+      VolumeNotReady: (error) =>
+        Effect.flatMap(getVolumeById(volumeId), (live) =>
+          live === undefined ? Effect.void : Effect.fail(error),
+        ),
+    }),
+    // VolumeInUse: a sandbox still mounts it, e.g. while a destroy deletes
+    // the sandboxes alongside; it frees up once they are gone.
+    Effect.retry({
+      while: (e) => e._tag === "VolumeNotReady" || (options.wait && e._tag === "VolumeInUse"),
+      schedule: Schedule.spaced("2 seconds"),
+      times: 30,
+    }),
+  );
+  if (!options.wait) return;
+  yield* waitUntilGone(
+    "volume",
+    volumeId,
+    getVolumeById(volumeId).pipe(Effect.map((v) => v !== undefined)),
+  );
+});
+
+export const VolumeProvider = () =>
+  Provider.effect(
+    Volume,
+    Effect.succeed({
+      stables: ["volumeId", "createdAt"],
+      list: Effect.fn(function* () {
+        const all = yield* volumes.listVolumes({});
+        return all.filter(isLive).map(toVolumeAttributes);
+      }),
+      diff: Effect.fn(function* ({ id, news, output }) {
+        if (!isResolved(news) || output === undefined) return undefined;
+        const name = yield* resolveName(
+          id,
+          news.name,
+          news.name === undefined ? output.name : undefined,
+        );
+        if (name !== output.name) return { action: "replace", deleteFirst: true } as const;
+      }),
+      lookup: Effect.fn(function* ({ name }) {
+        const found = yield* getVolumeByName(name);
+        return found === undefined ? undefined : toVolumeAttributes(found);
+      }),
+
+      read: Effect.fn(function* ({ id, olds, output }) {
+        const name = yield* resolveName(id, olds?.name, output?.name);
+        const found =
+          (output ? yield* getVolumeById(output.volumeId) : undefined) ??
+          (yield* getVolumeByName(name));
+        if (found === undefined) return undefined;
+        const attrs = toVolumeAttributes(found);
+        return (yield* isOwnedName(id, found.name, output !== undefined)) ? attrs : Unowned(attrs);
+      }),
+      reconcile: Effect.fn(function* ({ id, news, output }) {
+        // Observe by id first: the name may already be taken by a peer.
+        const name = yield* resolveName(id, news.name, output?.name);
+        const byId = output ? yield* getVolumeById(output.volumeId) : undefined;
+        // Ensure — volumes have nothing mutable beyond existence.
+        const volume =
+          byId && byId.name === name
+            ? byId.state === "ready"
+              ? byId
+              : yield* waitForVolume(byId.id)
+            : yield* ensureVolume(name);
+        return toVolumeAttributes(volume);
+      }),
+      delete: Effect.fn(function* ({ output }) {
+        yield* deleteVolumeById(output.volumeId);
+      }),
+    }),
+  );

package/src/WarmPool.ts

@@ -0,0 +1,128 @@
+import * as warmPools from "@distilled.cloud/daytona/warm_pools";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import { declarable } from "./internal/Declared.ts";
+import { resolved, type Ref } from "./internal/Ref.ts";
+import type { Providers } from "./Providers.ts";
+
+/** A snapshot, by name. Accepts a `Daytona.Snapshot` or `{ name }`. */
+export type WarmPoolSnapshot = { readonly name: string };
+
+export interface WarmPoolProps {
+  /** Snapshot whose sandboxes are kept warm. Changing it replaces the pool. */
+  snapshot: Ref<WarmPoolSnapshot>;
+  /** How many started sandboxes to keep ready. Updated in place. */
+  size: number;
+  /** Region to keep them in. Changing it replaces the pool. */
+  target?: string;
+}
+
+export interface WarmPoolAttributes {
+  /** Warm pool ID. */
+  warmPoolId: string;
+  /** Snapshot name. */
+  snapshot: string;
+  /** Region. */
+  target: string;
+  /** Desired pool size. */
+  size: number;
+  /** Sandboxes currently ready in the pool. */
+  currentSize: number;
+}
+
+export type WarmPool = Resource<
+  "Daytona.WarmPool",
+  WarmPoolProps,
+  WarmPoolAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * Keeps started sandboxes of a {@link Snapshot} ready, so creating a
+ * sandbox from that snapshot hands one over instead of booting a new one.
+ * Daytona uses the pool automatically for matching creates.
+ *
+ * Deleting the snapshot deletes its warm pools. Daytona Cloud doesn't
+ * serve warm pools to every organization; where it doesn't, deploying one
+ * fails with `WarmPoolsUnavailable`.
+ * @see https://www.daytona.io/docs/en/warm-pools/
+ *
+ * ### Keeping Sandboxes Warm
+ * **Example:** Four ready sandboxes of a snapshot
+ * ```typescript
+ * export const Pool = Daytona.WarmPool("Pool", { snapshot: Base, size: 4 });
+ * ```
+ *
+ * @resource
+ * @product Warm Pool
+ */
+export const WarmPool = declarable<WarmPool>()(Resource<WarmPool>("Daytona.WarmPool"));
+
+const toAttributes = (p: warmPools.WarmPool): WarmPoolAttributes => ({
+  warmPoolId: p.id,
+  snapshot: p.snapshot,
+  target: p.target,
+  size: p.pool,
+  currentSize: p.currentSize,
+});
+
+const snapshotName = (snapshot: WarmPoolProps["snapshot"]) =>
+  Effect.succeed(resolved(snapshot).name);
+
+export const WarmPoolProvider = () =>
+  Provider.effect(
+    WarmPool,
+    Effect.succeed({
+      stables: ["warmPoolId", "snapshot", "target"],
+      list: Effect.fn(function* () {
+        // Organizations Daytona doesn't serve warm pools to have none.
+        const pools = yield* warmPools
+          .listWarmPools({})
+          .pipe(Effect.catchTag("WarmPoolsUnavailable", () => Effect.succeed([])));
+        return pools.map(toAttributes);
+      }),
+      diff: Effect.fn(function* ({ news, output }) {
+        if (!isResolved(news) || output === undefined) return undefined;
+        const snapshot = yield* snapshotName(news.snapshot);
+        if (
+          snapshot !== output.snapshot ||
+          (news.target !== undefined && news.target !== output.target)
+        ) {
+          return { action: "replace" } as const;
+        }
+      }),
+      read: Effect.fn(function* ({ output }) {
+        if (output === undefined) return undefined;
+        const found = (yield* warmPools.listWarmPools({})).find((p) => p.id === output.warmPoolId);
+        return found ? toAttributes(found) : undefined;
+      }),
+      reconcile: Effect.fn(function* ({ news, output }) {
+        const snapshot = yield* snapshotName(news.snapshot);
+        // Observe — a pool is identified by its snapshot and region.
+        const pools = yield* warmPools.listWarmPools({});
+        const current =
+          pools.find((p) => p.id === output?.warmPoolId) ??
+          pools.find(
+            (p) =>
+              p.snapshot === snapshot && (news.target === undefined || p.target === news.target),
+          );
+        // Ensure
+        if (current === undefined) {
+          return toAttributes(
+            yield* warmPools.createWarmPool({ snapshot, pool: news.size, target: news.target }),
+          );
+        }
+        // Sync size
+        if (current.pool === news.size) return toAttributes(current);
+        return toAttributes(yield* warmPools.updateWarmPool({ id: current.id, pool: news.size }));
+      }),
+      delete: Effect.fn(function* ({ output }) {
+        yield* warmPools
+          .deleteWarmPool({ id: output.warmPoolId })
+          .pipe(Effect.catchTag("WarmPoolNotFound", () => Effect.void));
+      }),
+    }),
+  );

package/src/Webhooks.ts

@@ -0,0 +1,121 @@
+import * as webhooks from "@distilled.cloud/daytona/webhooks";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import { declarable } from "./internal/Declared.ts";
+import {
+  movesOrganization,
+  organizationIdFor,
+  type OrganizationRef,
+} from "./internal/Organization.ts";
+import type { Ref } from "./internal/Ref.ts";
+import { waitForState } from "./internal/Wait.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface WebhooksProps {
+  /**
+   * Organization to act on, e.g. a `Daytona.Organization`. Defaults to the
+   * credentials' organization. Changing it replaces the resource.
+   */
+  organization?: Ref<OrganizationRef>;
+  /**
+   * Bump to re-sync the organization's webhook endpoints with Daytona's
+   * event types on the next deploy.
+   */
+  refresh?: number;
+}
+
+export interface WebhooksAttributes {
+  /** Organization ID. */
+  organizationId: string;
+  /** The Svix application Daytona delivers events through. */
+  svixApplicationId: string;
+  /** Refresh counter applied. */
+  refreshed: number;
+}
+
+export type Webhooks = Resource<
+  "Daytona.Webhooks",
+  WebhooksProps,
+  WebhooksAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * Turn on webhooks for the Daytona organization: sandbox, snapshot and
+ * volume events delivered to endpoints you register in Daytona's webhook
+ * portal. Daytona delivers through Svix, which owns the endpoints, so this
+ * resource only enables delivery; open the portal with
+ * `getWebhookControllerAppPortalAccess` (on {@link ReadOrganization}) to
+ * add endpoints. Webhooks can't be turned off again through the API, so
+ * destroy leaves them enabled.
+ * @see https://www.daytona.io/docs/en/webhooks/
+ *
+ * ### Enabling Webhooks
+ * **Example:** Enable delivery for the organization
+ * ```typescript
+ * export const Events = Daytona.Webhooks("Events", {});
+ * ```
+ *
+ * @resource
+ * @product Organization
+ */
+export const Webhooks = declarable<Webhooks>()(Resource<Webhooks>("Daytona.Webhooks"));
+
+const status = (organizationId: string) =>
+  webhooks.getWebhookControllerInitializationStatus({ organizationId }).pipe(
+    Effect.map((s) => ({
+      ...s,
+      state: s.svixApplicationId ? "ready" : s.lastError ? "error" : "pending",
+    })),
+    // Before initialization Daytona has no status to report.
+    Effect.catchTag("WebhooksNotInitialized", () =>
+      Effect.succeed({ svixApplicationId: undefined, lastError: undefined, state: "pending" }),
+    ),
+  );
+
+export const WebhooksProvider = () =>
+  Provider.effect(
+    Webhooks,
+    Effect.succeed({
+      stables: ["organizationId", "svixApplicationId"],
+      nuke: { singleton: true },
+      list: () => Effect.succeed([]),
+      diff: Effect.fn(function* ({ news, output }) {
+        if (!isResolved(news) || output === undefined) return undefined;
+        if (yield* movesOrganization(news.organization, output))
+          return { action: "replace" } as const;
+      }),
+      reconcile: Effect.fn(function* ({ news, output }) {
+        const organizationId = yield* organizationIdFor(news.organization);
+        // Observe
+        let current = yield* status(organizationId);
+        // Ensure
+        if (current.svixApplicationId == null) {
+          yield* webhooks.webhookControllerInitializeWebhooks({ organizationId });
+          current = yield* waitForState({
+            kind: "webhooks",
+            id: organizationId,
+            observe: status(organizationId),
+            want: ["ready"],
+            fail: ["error"],
+            reason: (s) => s.lastError,
+            budget: "2 minutes",
+          });
+        }
+        // Sync
+        const refresh = news.refresh ?? 0;
+        if (output !== undefined && refresh !== output.refreshed) {
+          yield* webhooks.refreshWebhookControllerEndpoints({ organizationId });
+        }
+        return {
+          organizationId,
+          svixApplicationId: current.svixApplicationId ?? "",
+          refreshed: refresh,
+        };
+      }),
+      delete: () => Effect.void,
+    }),
+  );

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,46 @@
+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 "./CreateSecret.ts";
+export * from "./CreateSecretHttp.ts";
+export * from "./CreateSnapshot.ts";
+export * from "./CreateSnapshotHttp.ts";
+export * from "./CreateVolume.ts";
+export * from "./CreateVolumeHttp.ts";
+export * from "./Credentials.ts";
+export * from "./DaytonaBindings.ts";
+export * from "./IdentityProvider.ts";
+export * from "./MountVolume.ts";
+export * from "./Organization.ts";
+export * from "./OrganizationInvitation.ts";
+export * from "./OrganizationMember.ts";
+export * from "./OrganizationOtelConfig.ts";
+export * from "./OrganizationRole.ts";
+export * from "./OrganizationSettings.ts";
+export * from "./Providers.ts";
+export * from "./ReadAuditLogs.ts";
+export * from "./ReadOrganization.ts";
+export * from "./ReadUsage.ts";
+export * from "./Region.ts";
+export * from "./Registry.ts";
+export * from "./Runner.ts";
+export * from "./Sandbox.ts";
+export * from "./Secret.ts";
+export * from "./Snapshot.ts";
+export * from "./Volume.ts";
+export * from "./WarmPool.ts";
+export * from "./Webhooks.ts";
+export type {
+  Command,
+  ConnectedSandbox,
+  DaytonaSandbox,
+  ExecOptions,
+  ExecResult,
+  PtyOpenOptions,
+  SandboxFiles,
+  SandboxProcess,
+  SandboxPty,
+} from "./SandboxClient.ts";

package/src/internal/BuildContext.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import * as BuildPlan from "@alchemy.run/docker/BuildPlan";
+import { fromCredentials } from "@distilled.cloud/aws/Credentials";
+import * as AwsEndpoint from "@distilled.cloud/aws/Endpoint";
+import type { RegionName } from "@distilled.cloud/aws/Region";
+import * as s3 from "@distilled.cloud/aws/s3";
+import * as objectStorage from "@distilled.cloud/daytona/object_storage";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { tar } from "./Tar.ts";
+
+const redact = (value: string | Redacted.Redacted<string>) =>
+  Redacted.isRedacted(value) ? value : Redacted.make(value);
+
+/**
+ * Upload a plan's context files to Daytona's build-context storage and
+ * return the hash `buildInfo.contextHashes` takes.
+ *
+ * Daytona's builders read each context from
+ * `<organizationId>/<hash>/context.tar` in the bucket `getPushAccess`
+ * names, with the temporary credentials it returns (the layout Daytona's
+ * own SDKs use). The files go in one archive at their context paths; an
+ * archive already uploaded under the same hash is reused.
+ */
+export const uploadBuildContext = Effect.fn(function* (plan: BuildPlan.BuildPlan) {
+  const hash = yield* Effect.sync(() =>
+    createHash("sha256")
+      .update(JSON.stringify(plan.files.map((f) => [f.path, f.mode, f.sha256])))
+      .digest("hex")
+      .slice(0, 32),
+  );
+  const access = yield* objectStorage.getPushAccess({});
+  const prefix = `${access.organizationId}/${hash}/`;
+  const storage = Layer.mergeAll(
+    fromCredentials(
+      {
+        accessKeyId: Redacted.make(access.accessKey),
+        secretAccessKey: redact(access.secret),
+        sessionToken: redact(access.sessionToken),
+      },
+      access.region as RegionName,
+    ),
+    AwsEndpoint.of(access.storageUrl),
+  );
+  const existing = yield* s3
+    .listObjectsV2({ Bucket: access.bucket, Prefix: prefix, MaxKeys: 1 })
+    .pipe(Effect.provide(storage));
+  if ((existing.KeyCount ?? 0) > 0) return hash;
+  const entries = yield* Effect.forEach(plan.files, (file) =>
+    Effect.map(BuildPlan.readContextFile(file), (bytes) => ({
+      path: file.path,
+      mode: file.mode,
+      bytes,
+    })),
+  );
+  const body = yield* Effect.sync(() => tar(entries));
+  yield* s3
+    .putObject({ Bucket: access.bucket, Key: `${prefix}context.tar`, Body: body })
+    .pipe(Effect.provide(storage));
+  return hash;
+});

package/src/internal/Declared.ts

@@ -0,0 +1,80 @@
+import type { PropsInput } from "alchemy/Input";
+import * as Output from "alchemy/Output";
+import { isResource } from "alchemy/Resource";
+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 or a resource. */
+const isDeclaration = (value: unknown): value is Effect.Effect<unknown, never, Providers> =>
+  Effect.isEffect(value) && !Output.isOutput(value) && !isResource(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;