alchemy 2.0.0-beta.54 → 2.0.0-beta.56

package/src/Planetscale/MySQL/MySQLPassword.ts

@@ -2,6 +2,7 @@ import { Credentials } from "@distilled.cloud/planetscale/Credentials";
 import * as planetscale from "@distilled.cloud/planetscale/Operations";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
 import { deepEqual, isResolved } from "../../Diff.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
@@ -292,6 +293,72 @@ export const MySQLPasswordProvider = () =>
         })
         .pipe(Effect.catchTag("NotFound", () => Effect.void));
     }),
+
+    list: Effect.fn(function* () {
+      const { organization } = yield* yield* Credentials;
+
+      const databases = yield* planetscale.listDatabases
+        .pages({ organization })
+        .pipe(
+          Stream.runCollect,
+          Effect.map((chunk) =>
+            Array.from(chunk).flatMap((page) =>
+              page.data.filter((db) => db.kind === "mysql"),
+            ),
+          ),
+        );
+
+      const rows = yield* Effect.forEach(
+        databases,
+        (db) =>
+          planetscale.listBranches
+            .pages({ organization, database: db.name })
+            .pipe(
+              Stream.runCollect,
+              Effect.map((branchPages) =>
+                Array.from(branchPages).flatMap((page) =>
+                  page.data.filter((branch) => branch.kind === "mysql"),
+                ),
+              ),
+              Effect.catchTag("NotFound", () =>
+                Effect.succeed([{ name: db.default_branch ?? "main" }]),
+              ),
+              Effect.flatMap((branches) =>
+                Effect.forEach(
+                  branches,
+                  (branch) =>
+                    planetscale.listPasswords
+                      .pages({
+                        organization,
+                        database: db.name,
+                        branch: branch.name,
+                      })
+                      .pipe(
+                        Stream.runCollect,
+                        Effect.map((passwordPages): MySQLPasswordAttributes[] =>
+                          Array.from(passwordPages).flatMap((page) =>
+                            page.data.map((password) =>
+                              buildAttributes(password, Redacted.make(""), {
+                                organization,
+                                database: db.name,
+                                branch: branch.name,
+                              }),
+                            ),
+                          ),
+                        ),
+                        Effect.catchTag("NotFound", () =>
+                          Effect.succeed([] as MySQLPasswordAttributes[]),
+                        ),
+                      ),
+                  { concurrency: 10 },
+                ).pipe(Effect.map((perBranch) => perBranch.flat())),
+              ),
+            ),
+        { concurrency: 10 },
+      );
+
+      return rows.flat();
+    }),
   });
 
 // At runtime, Resource references in props are resolved to their full

package/src/Planetscale/Postgres/PostgresDatabase.ts

@@ -1,17 +1,18 @@
 import { Credentials } from "@distilled.cloud/planetscale/Credentials";
 import * as planetscale from "@distilled.cloud/planetscale/Operations";
 import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { hashImports, hashMigrations } from "../../Sql/SqlFile.ts";
+import { recordsEqual } from "../../Util/equal.ts";
 import type { BaseDatabaseAttributes, BaseDatabaseProps } from "../Database.ts";
 import type { Providers } from "../Providers.ts";
 import {
   DEFAULT_MIGRATIONS_TABLE,
   PlanetscaleConflict,
-  recordsEqual,
   waitForBranchReady,
   waitForDatabaseReady,
 } from "../Util.ts";
@@ -378,6 +379,70 @@ export const PostgresDatabaseProvider = () =>
         })
         .pipe(Effect.catchTag("NotFound", () => Effect.void));
     }),
+
+    list: Effect.fn(function* () {
+      const { organization } = yield* yield* Credentials;
+
+      const databases = yield* planetscale.listDatabases
+        .pages({ organization })
+        .pipe(
+          Stream.runCollect,
+          Effect.map((chunk) =>
+            Array.from(chunk).flatMap((page) =>
+              page.data.filter((db) => db.kind === "postgresql"),
+            ),
+          ),
+        );
+
+      const rows = yield* Effect.forEach(
+        databases,
+        (data) =>
+          Effect.gen(function* () {
+            const defaultBranch = data.default_branch ?? "main";
+            const branch = yield* planetscale
+              .getBranch({
+                organization,
+                database: data.name,
+                branch: defaultBranch,
+              })
+              .pipe(
+                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+              );
+
+            const arch: "x86" | "arm" =
+              branch?.cluster_architecture === "aarch64" ? "arm" : "x86";
+            const clusterSize = branch?.cluster_name ?? "";
+
+            const attrs: PostgresDatabase["Attributes"] = {
+              id: data.id,
+              name: data.name,
+              organization,
+              state: data.state,
+              defaultBranch,
+              plan: data.plan ?? "hobby",
+              createdAt: data.created_at,
+              updatedAt: data.updated_at,
+              htmlUrl: data.html_url,
+              region: { slug: data.region.slug },
+              clusterSize,
+              migrationsDir: undefined,
+              migrationsTable: undefined,
+              migrationsHashes: {},
+              importHashes: {},
+              arch,
+              requireApprovalForDeploy:
+                data.require_approval_for_deploy ?? false,
+              restrictBranchRegion: data.restrict_branch_region ?? false,
+              productionBranchWebConsole:
+                data.production_branch_web_console ?? false,
+            };
+            return attrs;
+          }),
+        { concurrency: 10 },
+      );
+
+      return rows;
+    }),
   });
 
 const createDatabaseName = (id: string, name: string | undefined) =>

package/src/Planetscale/Postgres/PostgresDefaultRole.ts

@@ -2,6 +2,7 @@ import { Credentials } from "@distilled.cloud/planetscale/Credentials";
 import * as planetscale from "@distilled.cloud/planetscale/Operations";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
@@ -240,6 +241,78 @@ export const PostgresDefaultRoleProvider = () =>
         })
         .pipe(Effect.catchTag("NotFound", () => Effect.void));
     }),
+
+    list: Effect.fn(function* () {
+      const { organization } = yield* yield* Credentials;
+
+      const roles = yield* planetscale.listDatabases
+        .pages({ organization })
+        .pipe(
+          Stream.map((page) =>
+            page.data.filter((db) => db.kind === "postgresql"),
+          ),
+          Stream.flattenIterable,
+          Stream.flatMap(
+            (db) =>
+              planetscale.listBranches
+                .pages({ organization, database: db.name })
+                .pipe(
+                  Stream.map((page) =>
+                    page.data.filter((branch) => branch.kind === "postgresql"),
+                  ),
+                  Stream.flattenIterable,
+                  Stream.catchTag("NotFound", () =>
+                    Stream.succeed({ name: db.default_branch ?? "main" }),
+                  ),
+                  Stream.flatMap(
+                    (branch) =>
+                      planetscale.listRoles
+                        .pages({
+                          organization,
+                          database: db.name,
+                          branch: branch.name,
+                        })
+                        .pipe(
+                          Stream.map((page) =>
+                            page.data
+                              .filter((role) => role.default)
+                              .map(
+                                (role) =>
+                                  ({
+                                    id: role.id,
+                                    name: role.name,
+                                    expiresAt: role.expires_at,
+                                    host: role.access_host_url,
+                                    username: role.username,
+                                    password: Redacted.make(""),
+                                    ttl: role.ttl,
+                                    databaseName: role.database_name,
+                                    connectionUrl: Redacted.make(""),
+                                    connectionUrlPooled: Redacted.make(""),
+                                    inheritedRoles:
+                                      role.inherited_roles as InheritedRole[],
+                                    organization,
+                                    database: db.name,
+                                    branch: branch.name,
+                                  }) satisfies PostgresDefaultRoleAttributes as PostgresDefaultRoleAttributes,
+                              ),
+                          ),
+                          Stream.flattenIterable,
+                          Stream.catchTags({
+                            NotFound: () => Stream.empty,
+                            Forbidden: () => Stream.empty,
+                          }),
+                        ),
+                    { concurrency: 10 },
+                  ),
+                ),
+            { concurrency: 10 },
+          ),
+          Stream.runCollect,
+        );
+
+      return Array.from(roles);
+    }),
   });
 
 // Structural shapes for runtime-resolved Resource references — see

package/src/Planetscale/Postgres/PostgresRole.ts

@@ -2,6 +2,7 @@ import { Credentials } from "@distilled.cloud/planetscale/Credentials";
 import * as planetscale from "@distilled.cloud/planetscale/Operations";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
 import { deepEqual, isResolved } from "../../Diff.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
@@ -355,6 +356,80 @@ export const PostgresRoleProvider = () =>
           ),
         );
     }),
+
+    list: Effect.fn(function* () {
+      const { organization } = yield* yield* Credentials;
+
+      const databases = yield* planetscale.listDatabases
+        .pages({ organization })
+        .pipe(
+          Stream.runCollect,
+          Effect.map((chunk) =>
+            Array.from(chunk).flatMap((page) =>
+              page.data.filter((db) => db.kind === "postgresql"),
+            ),
+          ),
+        );
+
+      const rows = yield* Effect.forEach(
+        databases,
+        (db) =>
+          planetscale.listBranches
+            .pages({ organization, database: db.name })
+            .pipe(
+              Stream.runCollect,
+              Effect.map((branchPages) =>
+                Array.from(branchPages).flatMap((page) =>
+                  page.data.filter((branch) => branch.kind === "postgresql"),
+                ),
+              ),
+              Effect.catchTag("NotFound", () =>
+                Effect.succeed([{ name: db.default_branch ?? "main" }]),
+              ),
+              Effect.flatMap((branches) =>
+                Effect.forEach(
+                  branches,
+                  (branch) =>
+                    planetscale.listRoles
+                      .pages({
+                        organization,
+                        database: db.name,
+                        branch: branch.name,
+                      })
+                      .pipe(
+                        Stream.runCollect,
+                        Effect.map((rolePages): PostgresRoleAttributes[] =>
+                          Array.from(rolePages).flatMap((page) =>
+                            page.data
+                              .filter((role) => !role.default)
+                              .map((role) =>
+                                buildAttributes(role, Redacted.make(""), {
+                                  inheritedRoles:
+                                    role.inherited_roles as InheritedRole[],
+                                  successor: "postgres",
+                                  organization,
+                                  database: db.name,
+                                  branch: branch.name,
+                                }),
+                              ),
+                          ),
+                        ),
+                        Effect.catchTag("NotFound", () =>
+                          Effect.succeed([] as PostgresRoleAttributes[]),
+                        ),
+                        Effect.catchTag("Forbidden", () =>
+                          Effect.succeed([] as PostgresRoleAttributes[]),
+                        ),
+                      ),
+                  { concurrency: 10 },
+                ).pipe(Effect.map((perBranch) => perBranch.flat())),
+              ),
+            ),
+        { concurrency: 10 },
+      );
+
+      return rows.flat();
+    }),
   });
 
 // Structural shapes for runtime-resolved Resource references — see notes

package/src/Planetscale/Util.ts

@@ -146,17 +146,3 @@ export const isKnownError =
     error !== null &&
     (error as { readonly _tag?: unknown })._tag === tag &&
     (error as { readonly message?: unknown }).message === message;
-
-// todo: this repeats across Neon, D1, and PlanetScale resources so maybe we should move it to Diff? or Util?
-export const recordsEqual = (
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean => {
-  const aKeys = Object.keys(a);
-  const bKeys = Object.keys(b);
-  if (aKeys.length !== bKeys.length) return false;
-  for (const k of aKeys) {
-    if (a[k] !== b[k]) return false;
-  }
-  return true;
-};

package/src/Provider.ts

@@ -29,6 +29,7 @@ export interface Provider<
     DeleteReq = never,
     TailReq = never,
     LogsReq = never,
+    ListReq = never,
   >(
     service: Omit<
       ProviderService<
@@ -39,7 +40,8 @@ export interface Provider<
         ReconcileReq,
         DeleteReq,
         TailReq,
-        LogsReq
+        LogsReq,
+        ListReq
       >,
       "Type"
     >,
@@ -51,7 +53,8 @@ export interface Provider<
     ReconcileReq,
     DeleteReq,
     TailReq,
-    LogsReq
+    LogsReq,
+    ListReq
   >;
 }
 
@@ -91,6 +94,7 @@ export interface ProviderService<
   DeleteReq = never,
   TailReq = never,
   LogsReq = never,
+  ListReq = never,
 > {
   /**
    * The version of the provider.
@@ -98,6 +102,46 @@ export interface ProviderService<
    * @default 0
    */
   version?: number;
+  /**
+   * Account-wide teardown (`alchemy unsafe nuke`) behaviour. Providers whose
+   * resources can't meaningfully be deleted opt out here so nuke doesn't
+   * report an endless "deleted but still there" loop. `read`/import are
+   * unaffected.
+   */
+  nuke?: {
+    /**
+     * The resource is an account/zone **singleton setting** — always-present
+     * configuration (e.g. Bot Management, Email Routing, a zone's SSL
+     * settings) whose `delete` only *resets* it to defaults rather than
+     * removing a discrete resource. Skipped by nuke, since `list` always
+     * re-enumerates it and "deleting" it just resets config the operator
+     * never created.
+     */
+    singleton?: boolean;
+    /**
+     * The resource is skipped by nuke for any other reason — typically because
+     * it can never actually be deleted (no delete API, like RealtimeKit Apps;
+     * or a registration that is never released, like Registrar Domains). Unlike
+     * {@link singleton}, these are ordinary multi-instance resources.
+     */
+    skip?: boolean;
+  };
+  /**
+   * Enumerates every existing resource of this type in the ambient scope
+   * (account / region / zone resolved from the environment services), and
+   * returns the full {@link ProviderService} `Attributes` shape for each —
+   * the same shape {@link read} produces, so each item is directly usable
+   * with {@link delete} without a follow-up read.
+   *
+   * This powers account-wide operations such as `alchemy nuke`, which lists
+   * everything and then deletes it. It takes no input and must paginate
+   * exhaustively so the returned array is complete.
+   *
+   * Resources with no native enumeration API (account/zone singletons,
+   * existence-only resources, sub-resources keyed entirely by a parent)
+   * should return an empty array rather than throwing.
+   */
+  list(): Effect.Effect<Res["Attributes"][], any, ListReq>;
   /**
    * Returns a stream of log lines for a deployed resource.
    * Used by `alchemy tail` to stream real-time logs.
@@ -205,6 +249,7 @@ export const effect = <
   DeleteReq = never,
   TailReq = never,
   LogsReq = never,
+  ListReq = never,
 >(
   cls: ResourceClass<R> | Platform<R, any, any, any, any>,
   eff: Effect.Effect<
@@ -216,7 +261,8 @@ export const effect = <
       ReconcileReq,
       DeleteReq,
       TailReq,
-      LogsReq
+      LogsReq,
+      ListReq
     >,
     never,
     Req
@@ -225,7 +271,7 @@ export const effect = <
   Provider<R>,
   never,
   Exclude<
-    Req | ReadReq | DiffReq | PrecreateReq | ReconcileReq | DeleteReq,
+    Req | ReadReq | DiffReq | PrecreateReq | ReconcileReq | DeleteReq | ListReq,
     LifecycleServices
   >
 > =>
@@ -241,6 +287,7 @@ export const succeed = <
   DeleteReq = never,
   TailReq = never,
   LogsReq = never,
+  ListReq = never,
 >(
   cls: ResourceClass<R> | Platform<R, any, any, any, any>,
   service: ProviderService<
@@ -251,13 +298,14 @@ export const succeed = <
     ReconcileReq,
     DeleteReq,
     TailReq,
-    LogsReq
+    LogsReq,
+    ListReq
   >,
 ): Layer.Layer<
   Provider<R>,
   never,
   Exclude<
-    ReadReq | DiffReq | PrecreateReq | ReconcileReq | DeleteReq,
+    ReadReq | DiffReq | PrecreateReq | ReconcileReq | DeleteReq | ListReq,
     LifecycleServices
   >
 > =>
@@ -293,6 +341,13 @@ export interface ProviderCollectionService {
   get<Resource extends ResourceLike>(
     service: string,
   ): ProviderService<Resource> | undefined;
+  /**
+   * Every provider in this collection keyed by its resource type
+   * (e.g. `"Cloudflare.Worker"`). Used by account-wide operations such
+   * as `alchemy unsafe nuke` to enumerate and filter providers — the
+   * collection's closure-captured map would otherwise be unreachable.
+   */
+  readonly providers: Record<string, ProviderService>;
 }
 
 export const collection = <
@@ -333,6 +388,7 @@ export const collection = <
     return {
       kind: "ProviderCollection" as const,
       get: (service: string) => providers[service],
+      providers,
     };
   }) as any;
 
@@ -364,6 +420,22 @@ export const findProviderByType: {
     ),
   );
 
+/**
+ * Typed provider lookup by resource class (or {@link Platform} / {@link Policy})
+ * value. Infers `R` from the class so `provider.list()` / `provider.read(...)`
+ * return the resource's `Attributes` shape — prefer this over
+ * {@link findProviderByType}, which only takes the type string.
+ */
+export const findProvider: {
+  <R extends ResourceLike>(
+    resource: ResourceClass<R> | Platform<R, any, any, any, any>,
+  ): Effect.Effect<ProviderService<R>>;
+  <P extends Policy<any, any, any>>(
+    policy: P,
+  ): Effect.Effect<Effect.Success<P>>;
+} = (resource: { Type?: string; key?: string }) =>
+  findProviderByType((resource.Type ?? resource.key) as string) as any;
+
 export const tryFindProviderByType: {
   <R extends ResourceLike>(
     resourceType: R["Type"],

package/src/Random.ts

@@ -57,4 +57,8 @@ export const RandomProvider = () =>
       }),
     delete: () => Effect.void,
     read: ({ output }) => Effect.succeed(output),
+    // Non-listable: the value is generated client-side with
+    // `crypto.getRandomValues` and lives only in alchemy state. There is no
+    // remote service to enumerate, so listing yields nothing.
+    list: () => Effect.succeed([]),
   });

package/src/Test/Core.ts

@@ -207,6 +207,17 @@ export interface ScratchStack<ROut = any> {
   deploy<A, E, R>(
     effect: Effect.Effect<A, E, R>,
   ): Effect.Effect<Input.Resolve<A>, any, Exclude<R, ROut | StackServices>>;
+  /**
+   * Build a plan against the scratch's shared state WITHOUT applying it.
+   *
+   * Use this to assert on the planned action for a resource (e.g. that a
+   * downstream dependency stays `noop` when only an upstream resource
+   * changes) without mutating the cloud. Plans run against whatever state
+   * prior `deploy(...)` calls persisted.
+   */
+  plan<A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<Plan.Plan<A>, any, Exclude<R, ROut | StackServices>>;
   destroy(): Effect.Effect<void, any, never>;
 }
 
@@ -250,11 +261,27 @@ export const scratchStack = <ROut>(
       provideFreshArtifactStore,
     );
 
+  const buildPlan = (effect: Effect.Effect<any, any, any>) =>
+    (effect as Effect.Effect<any, any, never>).pipe(
+      makeStack({
+        name: stackName,
+        providers: options.providers,
+        state: stateLayer,
+      } as any) as any,
+      Effect.flatMap((compiled: any) =>
+        Plan.make(compiled).pipe(Effect.provide(compiled.services)),
+      ),
+      Effect.provide(Layer.succeed(Stage, stage)),
+      provideFreshArtifactStore,
+    );
+
   return {
     name: stackName,
     state: stateLayer,
     deploy: ((effect: Effect.Effect<any, any, any>) =>
       buildAndApply(effect)) as ScratchStack<ROut>["deploy"],
+    plan: ((effect: Effect.Effect<any, any, any>) =>
+      buildPlan(effect)) as ScratchStack<ROut>["plan"],
     destroy: () =>
       Plan.make({
         name: stackName,

package/src/Test/Vitest.ts

@@ -131,8 +131,20 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
   ) => {
     const scratch = Core.scratchStack(options, name);
+    // Guarantee teardown. `test.provider` has no built-in cleanup, so a body
+    // that fails (assertion, API error like a 409/Unauthorized) or is
+    // interrupted (vitest timeout) BEFORE its trailing `stack.destroy()` would
+    // otherwise leak every cloud resource it deployed: the scratch's in-memory
+    // state is discarded with the process, so no later run can reclaim the
+    // orphan (only an account-wide `nuke` can). `scratch.destroy()` is
+    // idempotent (empty-plan apply against the shared scratch state) — a no-op
+    // when the body already destroyed, and it reclaims the orphans otherwise.
+    // `Effect.ensuring` runs the finalizer on success, failure, AND interruption.
+    const body = Core.withProviders(fn(scratch), options, scratch.name).pipe(
+      Effect.ensuring(scratch.destroy().pipe(Effect.ignore)),
+    );
     return Core.toEffect(
-      Core.withProviders(fn(scratch), options, scratch.name),
+      body,
       { ...options, state: scratch.state },
       sharedScope,
     );

package/src/Util/equal.ts

@@ -0,0 +1,55 @@
+/**
+ * Shallow, order-sensitive array equality. `undefined`-tolerant: two
+ * `undefined`s are equal, an `undefined` and an array are not.
+ *
+ * Pass a custom `eq` comparator for non-primitive elements, e.g.
+ * `(x, y) => JSON.stringify(x) === JSON.stringify(y)`.
+ */
+export const arrayEquals = <T>(
+  a: ReadonlyArray<T> | undefined,
+  b: ReadonlyArray<T> | undefined,
+  eq: (x: T, y: T) => boolean = (x, y) => x === y,
+): boolean => {
+  if (a === b) return true;
+  if (a === undefined || b === undefined) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!eq(a[i], b[i])) return false;
+  }
+  return true;
+};
+
+/**
+ * Order-insensitive array equality for primitive elements (compares
+ * sorted copies). `undefined`-tolerant like {@link arrayEquals}.
+ */
+export const arrayEqualsUnordered = <T extends string | number>(
+  a: ReadonlyArray<T> | undefined,
+  b: ReadonlyArray<T> | undefined,
+): boolean => {
+  if (a === b) return true;
+  if (a === undefined || b === undefined) return false;
+  if (a.length !== b.length) return false;
+  const as = [...a].sort();
+  const bs = [...b].sort();
+  for (let i = 0; i < as.length; i++) {
+    if (as[i] !== bs[i]) return false;
+  }
+  return true;
+};
+
+/**
+ * Shallow equality of two string records (same keys, same values).
+ */
+export const recordsEqual = (
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean => {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+};

package/src/Util/index.ts

@@ -2,6 +2,7 @@ export * from "./base32.ts";
 export * from "./camel.ts";
 export * from "./data.ts";
 export * from "./dedent.ts";
+export * from "./equal.ts";
 export * from "./service.ts";
 export * from "./sha256.ts";
 export * from "./stable.ts";