alchemy 2.0.0-beta.55 → 2.0.0-beta.57

package/src/Local/RpcProvider.ts

@@ -6,6 +6,7 @@ import * as Predicate from "effect/Predicate";
 import type { Scope } from "effect/Scope";
 import * as Stream from "effect/Stream";
 import { AlchemyContext } from "../AlchemyContext.ts";
+import { Artifacts, ArtifactStore, makeScopedArtifacts } from "../Artifacts.ts";
 import { InstanceId } from "../InstanceId.ts";
 import type { Platform } from "../Platform.ts";
 import * as Provider from "../Provider.ts";
@@ -45,6 +46,113 @@ import { RpcProviderProxy } from "./RpcProviderProxy.ts";
  * @param eff - The Effect to use to construct the provider.
  * @returns A layer containing the RpcProvider.
  */
+/**
+ * The provider shape accepted by {@link effect}. It is identical to
+ * {@link Provider.ProviderService} except that `list` is **optional**: local /
+ * dev RPC providers frequently have no cloud enumeration API, so the factory
+ * supplies a safe `() => Effect.succeed([])` default when one is not given. A
+ * provider that *can* enumerate its in-memory/local runtime state (e.g.
+ * `LocalWorkerProvider` enumerating its running instances) just defines `list`
+ * and the factory threads it straight through.
+ */
+type RpcProviderService<
+  R extends ResourceLike,
+  ReadReq = never,
+  DiffReq = never,
+  PrecreateReq = never,
+  ReconcileReq = never,
+  DeleteReq = never,
+  TailReq = never,
+  LogsReq = never,
+  ListReq = never,
+> = Omit<
+  Provider.ProviderService<
+    R,
+    ReadReq,
+    DiffReq,
+    PrecreateReq,
+    ReconcileReq,
+    DeleteReq,
+    TailReq,
+    LogsReq,
+    ListReq
+  >,
+  "list"
+> &
+  Partial<
+    Pick<
+      Provider.ProviderService<
+        R,
+        ReadReq,
+        DiffReq,
+        PrecreateReq,
+        ReconcileReq,
+        DeleteReq,
+        TailReq,
+        LogsReq,
+        ListReq
+      >,
+      "list"
+    >
+  >;
+
+/**
+ * Ensures a provider satisfies the now-required `list()` contract. If the
+ * provider already implements `list` (enumerating its local runtime state) it
+ * is returned untouched; otherwise a safe default that enumerates nothing
+ * (`() => Effect.succeed([])`) is injected. Local/dev providers have no cloud
+ * enumeration API, so `[]` is the correct default — never throw.
+ */
+const withDefaultList = <
+  R extends ResourceLike,
+  ReadReq,
+  DiffReq,
+  PrecreateReq,
+  ReconcileReq,
+  DeleteReq,
+  TailReq,
+  LogsReq,
+  ListReq,
+>(
+  provider: RpcProviderService<
+    R,
+    ReadReq,
+    DiffReq,
+    PrecreateReq,
+    ReconcileReq,
+    DeleteReq,
+    TailReq,
+    LogsReq,
+    ListReq
+  >,
+): Provider.ProviderService<
+  R,
+  ReadReq,
+  DiffReq,
+  PrecreateReq,
+  ReconcileReq,
+  DeleteReq,
+  TailReq,
+  LogsReq,
+  ListReq
+> =>
+  (provider.list
+    ? provider
+    : {
+        ...provider,
+        list: () => Effect.succeed([]),
+      }) as Provider.ProviderService<
+    R,
+    ReadReq,
+    DiffReq,
+    PrecreateReq,
+    ReconcileReq,
+    DeleteReq,
+    TailReq,
+    LogsReq,
+    ListReq
+  >;
+
 export const effect = <
   R extends ResourceLike,
   Req = never,
@@ -55,11 +163,12 @@ export const effect = <
   DeleteReq = never,
   TailReq = never,
   LogsReq = never,
+  ListReq = never,
 >(
   cls: ResourceClass<R> | Platform<R, any, any, any, any>,
   serverEntryUrl: string,
   eff: Effect.Effect<
-    Provider.ProviderService<
+    RpcProviderService<
       R,
       ReadReq,
       DiffReq,
@@ -67,7 +176,8 @@ export const effect = <
       ReconcileReq,
       DeleteReq,
       TailReq,
-      LogsReq
+      LogsReq,
+      ListReq
     >,
     never,
     Req
@@ -79,9 +189,10 @@ export const effect = <
       const client = yield* Effect.serviceOption(RpcProviderProxy);
       const context = yield* Effect.context();
       const stack = yield* Stack;
+      const store = yield* ArtifactStore;
 
       if (client._tag === "None") {
-        const provider = yield* eff;
+        const provider = withDefaultList(yield* eff);
         return new Proxy(provider, {
           get: (target, prop) => {
             const value = (target as any)[prop];
@@ -94,7 +205,13 @@ export const effect = <
                 layerFallback(Stage, stack.stage),
                 Predicate.hasProperty(args[0], "instanceId") &&
                   Predicate.isString(args[0].instanceId)
-                  ? layerFallback(InstanceId, args[0].instanceId)
+                  ? Layer.merge(
+                      layerFallback(InstanceId, args[0].instanceId),
+                      Layer.succeed(
+                        Artifacts,
+                        makeScopedArtifacts(store, args[0].instanceId),
+                      ),
+                    )
                   : Layer.empty,
               );
               return result.pipe(
@@ -106,7 +223,7 @@ export const effect = <
           },
         });
       }
-      return yield* client.value.get(serverEntryUrl, cls.Type);
+      return withDefaultList(yield* client.value.get(serverEntryUrl, cls.Type));
     }),
   );
 

package/src/Local/RpcServer.ts

@@ -6,6 +6,7 @@ import * as Layer from "effect/Layer";
 import type * as Scope from "effect/Scope";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import type { HttpClient } from "effect/unstable/http/HttpClient";
+import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
 import type { ProviderService } from "../Provider.ts";
 import type { ResourceLike } from "../Resource.ts";
 import {
@@ -78,12 +79,19 @@ export const launch = <ROut, E>(
     | RpcServerEnvironment.RpcEnvironmentServices
     | PlatformServices
     | HttpClient
+    | ArtifactStore
   >,
 ) =>
   serverPlatformLayer.pipe(
     Layer.provide(providers),
     Layer.provide(RpcServerEnvironment.fromEnv()),
-    Layer.provide(Layer.merge(PlatformServices, FetchHttpClient.layer)),
+    Layer.provide(
+      Layer.mergeAll(
+        PlatformServices,
+        FetchHttpClient.layer,
+        Layer.sync(ArtifactStore, createArtifactStore),
+      ),
+    ),
     Layer.launch,
     Effect.scoped,
     runMain,

package/src/Neon/Branch.ts

@@ -6,6 +6,8 @@ import {
   listProjectBranchDatabases,
   listProjectBranches,
   type ListProjectBranchesOutput,
+  listProjects,
+  type ListProjectsOutput,
   updateProjectBranch,
 } from "@distilled.cloud/neon";
 import * as Effect from "effect/Effect";
@@ -15,6 +17,7 @@ import { createPhysicalName } from "../PhysicalName.ts";
 import * as Provider from "../Provider.ts";
 import { Resource } from "../Resource.ts";
 import { listSqlFiles, readSqlFile } from "../Sql/SqlFile.ts";
+import { recordsEqual } from "../Util/equal.ts";
 import { applyMigrations, runSql } from "./Migrations.ts";
 import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts";
 import { type Project, waitForOperations } from "./Project.ts";
@@ -149,7 +152,7 @@ export type Branch = Resource<
  *
  * Branches are first-class, copy-on-write copies of a parent branch — they
  * share storage with the parent until the new branch starts diverging.
- *
+ * @resource
  * @section Branching from a project's default branch
  * @example Basic branch
  * ```typescript
@@ -426,8 +429,120 @@ export const BranchProvider = () =>
         branch_id: output.branchId,
       }).pipe(Effect.catchTag("NotFound", () => Effect.void));
     }),
+    // Parent fan-out: branches are scoped to a project, and there is no
+    // account-wide branch enumeration API. Enumerate every project, then
+    // list+hydrate the branches of each (bounded concurrency), producing
+    // the exact `read` Attributes shape for each branch.
+    list: Effect.fn(function* () {
+      const projects = yield* listAllProjects;
+      const perProject = yield* Effect.forEach(
+        projects,
+        (project) =>
+          Effect.gen(function* () {
+            const branches = yield* listAllBranches(project.id);
+            return yield* Effect.forEach(
+              branches,
+              (branch) => hydrateBranch(project.id, branch),
+              { concurrency: 10 },
+            );
+          }).pipe(
+            // The project may be deleted between enumeration and listing.
+            Effect.catchTag("NotFound", () => Effect.succeed([])),
+          ),
+        { concurrency: 10 },
+      );
+      return perProject
+        .flat()
+        .filter((row): row is Branch["Attributes"] => row !== undefined);
+    }),
+  });
+
+const listAllProjects = Effect.gen(function* () {
+  const projects: ListProjectsOutput["projects"][number][] = [];
+  let cursor: string | undefined;
+  while (true) {
+    const page = yield* listProjects({
+      ...(cursor !== undefined ? { cursor } : {}),
+    });
+    projects.push(...page.projects);
+    const nextCursor = page.pagination?.cursor;
+    // Neon returns a `pagination.cursor` on every response (the `created_at`
+    // of the last row), not a "has next page" flag — stop once a page comes
+    // back empty or the cursor stops advancing to avoid an infinite loop.
+    if (
+      page.projects.length === 0 ||
+      nextCursor === undefined ||
+      nextCursor === cursor
+    ) {
+      break;
+    }
+    cursor = nextCursor;
+  }
+  return projects;
+});
+
+const listAllBranches = (projectId: string) =>
+  Effect.gen(function* () {
+    const branches: ListProjectBranchesOutput["branches"][number][] = [];
+    let cursor: string | undefined;
+    do {
+      const page = yield* listProjectBranches({
+        project_id: projectId,
+        ...(cursor !== undefined ? { cursor } : {}),
+      });
+      branches.push(...page.branches);
+      cursor = page.pagination?.next;
+    } while (cursor);
+    return branches;
   });
 
+const hydrateBranch = (
+  projectId: string,
+  branch: ListProjectBranchesOutput["branches"][number],
+) =>
+  Effect.gen(function* () {
+    const dbs = yield* listProjectBranchDatabases({
+      project_id: projectId,
+      branch_id: branch.id,
+    });
+    const db = dbs.databases[0];
+    if (!db) return undefined;
+    const conn = yield* fetchConnection(
+      projectId,
+      branch.id,
+      db.name,
+      db.owner_name,
+    );
+    const attributes: Branch["Attributes"] = {
+      branchId: branch.id,
+      branchName: branch.name,
+      projectId,
+      parentBranchId: branch.parent_id,
+      parentLsn: branch.parent_lsn,
+      parentTimestamp: branch.parent_timestamp,
+      initSource: branch.init_source as
+        | "schema-only"
+        | "parent-data"
+        | undefined,
+      protected: branch.protected,
+      default: branch.default,
+      expiresAt: branch.expires_at,
+      databaseName: db.name,
+      roleName: db.owner_name,
+      connectionUri: conn.uri,
+      pooledConnectionUri: conn.pooled,
+      origin: parsePostgresOrigin(conn.uri),
+      migrationsDir: undefined,
+      migrationsTable: undefined,
+      migrationsHashes: {},
+      importHashes: {},
+    };
+    return attributes;
+  }).pipe(
+    // A branch/database/endpoint can disappear mid-enumeration — skip it.
+    Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+  );
+
 const rootDir = Effect.sync(() => process.cwd());
 const createBranchName = (id: string, name: string | undefined) =>
   Effect.gen(function* () {
@@ -585,16 +700,3 @@ const hashImports = (importFiles: ReadonlyArray<string>, rootDir: string) =>
     }
     return hashes;
   });
-
-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/Neon/Project.ts

@@ -27,6 +27,7 @@ import {
   listSqlFiles,
   readSqlFile,
 } from "../Sql/SqlFile.ts";
+import { recordsEqual } from "../Util/equal.ts";
 import { applyMigrations, runSql } from "./Migrations.ts";
 import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts";
 import type { Providers } from "./Providers.ts";
@@ -157,13 +158,15 @@ export type Project = Resource<
   Providers
 >;
 
+type ProjectAttributes = Project["Attributes"];
+
 /**
  * A Neon serverless Postgres project.
  *
  * Creating a project also provisions the project's default branch (named
  * "main" by default), an initial role, an initial database, and a
  * read-write compute endpoint, exposed as `connectionUri`.
- *
+ * @resource
  * @section Creating a Project
  * @example Basic project
  * ```typescript
@@ -208,6 +211,23 @@ export const Project = Resource<Project>("Neon.Project");
 export const ProjectProvider = () =>
   Provider.succeed(Project, {
     stables: ["projectId", "defaultBranchId"],
+    list: Effect.fn(function* () {
+      // Account-scoped collection: enumerate every project via the Neon
+      // projects list API, then hydrate each into the exact `read`
+      // Attributes shape with bounded concurrency.
+      const projects = yield* listAllProjects;
+      const rows = yield* Effect.forEach(
+        projects,
+        (project) =>
+          hydrateProjectAttributes(project).pipe(
+            // A project can be deleted between the list call and
+            // hydration — skip it rather than fail the whole enumeration.
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          ),
+        { concurrency: 10 },
+      );
+      return rows.filter((row): row is ProjectAttributes => row !== undefined);
+    }),
     diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
       if (!isResolved(news)) return undefined;
       const name = yield* createProjectName(id, news.name);
@@ -274,45 +294,11 @@ export const ProjectProvider = () =>
       const matches = yield* findProjectByName(name);
       const match = matches[0];
       if (!match) return undefined;
-      const branches = yield* listProjectBranches({
-        project_id: match.id,
-        search: olds?.defaultBranchName ?? "main",
-      });
-      const defaultBranch =
-        branches.branches.find((b) => b.default) ?? branches.branches[0];
-      if (!defaultBranch) return undefined;
-      const databases = yield* listProjectBranchDatabases({
-        project_id: match.id,
-        branch_id: defaultBranch.id,
-      });
-      const db = databases.databases[0];
-      if (!db) return undefined;
-      const conn = yield* resolveConnection(
-        match.id,
-        defaultBranch.id,
-        db.name,
-        db.owner_name,
-      );
-      return {
-        projectId: match.id,
-        projectName: match.name,
-        region: match.region_id as NeonRegion,
-        pgVersion: match.pg_version as NeonPgVersion,
-        defaultBranchId: defaultBranch.id,
-        defaultBranchName: defaultBranch.name,
-        databaseName: db.name,
-        roleName: db.owner_name,
-        connectionUri: conn.uri,
-        pooledConnectionUri: conn.pooled,
-        origin: parsePostgresOrigin(conn.uri),
-        historyRetentionSeconds: match.history_retention_seconds ?? 86400,
-        enableLogicalReplication:
-          match.settings?.enable_logical_replication === true,
+      return yield* hydrateProjectAttributes(match, {
+        defaultBranchName: olds?.defaultBranchName,
         migrationsDir: olds?.migrationsDir,
         migrationsTable: olds?.migrationsTable,
-        migrationsHashes: {},
-        importHashes: {},
-      };
+      });
     }),
     reconcile: Effect.fn(function* ({ id, news = {}, output }) {
       // Ensure — when no prior output exists we create the project
@@ -607,6 +593,87 @@ const findProjectByName = (name: string) =>
     return matches;
   });
 
+/**
+ * Exhaustively enumerate every project in the account. Uses the same
+ * cursor-stop heuristic as {@link findProjectByName} because Neon returns a
+ * `pagination.cursor` on every page (it's the last row's `created_at`, not a
+ * "has next page" flag), so we'd otherwise loop forever re-fetching.
+ */
+const listAllProjects = Effect.gen(function* () {
+  const projects: ListProjectsOutput["projects"][number][] = [];
+  let cursor: string | undefined;
+  while (true) {
+    const page = yield* listProjects(cursor !== undefined ? { cursor } : {});
+    projects.push(...page.projects);
+    const nextCursor = page.pagination?.cursor;
+    if (
+      page.projects.length === 0 ||
+      nextCursor === undefined ||
+      nextCursor === cursor
+    ) {
+      break;
+    }
+    cursor = nextCursor;
+  }
+  return projects;
+});
+
+/**
+ * Hydrate a project summary (from the list API) into the exact `read`
+ * Attributes shape — resolving the default branch, its primary database, and
+ * the direct + pooled connection URIs. Returns `undefined` when the project
+ * has no branch or database yet (mirrors `read`).
+ */
+const hydrateProjectAttributes = (
+  project: ListProjectsOutput["projects"][number],
+  opts: {
+    defaultBranchName?: string;
+    migrationsDir?: string;
+    migrationsTable?: string;
+  } = {},
+) =>
+  Effect.gen(function* () {
+    const branches = yield* listProjectBranches({
+      project_id: project.id,
+      search: opts.defaultBranchName ?? "main",
+    });
+    const defaultBranch =
+      branches.branches.find((b) => b.default) ?? branches.branches[0];
+    if (!defaultBranch) return undefined;
+    const databases = yield* listProjectBranchDatabases({
+      project_id: project.id,
+      branch_id: defaultBranch.id,
+    });
+    const db = databases.databases[0];
+    if (!db) return undefined;
+    const conn = yield* resolveConnection(
+      project.id,
+      defaultBranch.id,
+      db.name,
+      db.owner_name,
+    );
+    return {
+      projectId: project.id,
+      projectName: project.name,
+      region: project.region_id as NeonRegion,
+      pgVersion: project.pg_version as NeonPgVersion,
+      defaultBranchId: defaultBranch.id,
+      defaultBranchName: defaultBranch.name,
+      databaseName: db.name,
+      roleName: db.owner_name,
+      connectionUri: conn.uri,
+      pooledConnectionUri: conn.pooled,
+      origin: parsePostgresOrigin(conn.uri),
+      historyRetentionSeconds: project.history_retention_seconds ?? 86400,
+      enableLogicalReplication:
+        project.settings?.enable_logical_replication === true,
+      migrationsDir: opts.migrationsDir,
+      migrationsTable: opts.migrationsTable,
+      migrationsHashes: {},
+      importHashes: {},
+    } satisfies ProjectAttributes;
+  });
+
 const runMigrations = (
   connectionUri: Redacted.Redacted<string>,
   migrationsDir: string,
@@ -649,16 +716,3 @@ const runImports = (
     }
     return hashes;
   });
-
-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/Neon/index.ts

@@ -1,4 +1,5 @@
 export * from "./Branch.ts";
+export * from "./Credentials.ts";
 export * from "./PostgresOrigin.ts";
 export * from "./Project.ts";
 export * from "./Providers.ts";

package/src/Plan.ts

@@ -332,10 +332,11 @@ export const make = <A>(
                     .pipe(providePlanScope(resource.FQN, oldState.instanceId))
                 : Effect.succeed(undefined);
 
-              const stables: string[] = [
-                ...(provider.stables ?? []),
-                ...(diff?.stables ?? []),
-              ];
+              // A present `diff.stables` is authoritative for this update and
+              // overrides `provider.stables`. We only fall back to the
+              // provider-level "always stable" list when the diff does not
+              // return one (e.g. no diff fn, or a diff that omits `stables`).
+              const stables: string[] = diff?.stables ?? provider.stables ?? [];
 
               const withStables = (output: any) =>
                 stables.length > 0

package/src/Planetscale/Branch.ts

@@ -2,12 +2,14 @@ import * as planetscale from "@distilled.cloud/planetscale";
 import { Credentials } from "@distilled.cloud/planetscale/Credentials";
 import * as Effect from "effect/Effect";
 import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
 import { Unowned } from "../AdoptPolicy.ts";
 import { isResolved } from "../Diff.ts";
 import { createPhysicalName } from "../PhysicalName.ts";
 import * as Provider from "../Provider.ts";
 import type { ResourceClass, ResourceLike } from "../Resource.ts";
 import { hashImports, hashMigrations } from "../Sql/SqlFile.ts";
+import { recordsEqual } from "../Util/equal.ts";
 import { ensureMySQLProductionBranchClusterSize } from "./MySQL/MySQLClusterSize.ts";
 import {
   ensurePostgresProductionBranchClusterSize,
@@ -17,7 +19,6 @@ import {
   DEFAULT_MIGRATIONS_TABLE,
   PlanetscaleConflict,
   isKnownError,
-  recordsEqual,
   waitForBranchReady,
 } from "./Util.ts";
 
@@ -185,6 +186,66 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
 }) =>
   Provider.succeed(opts.resource, {
     stables: ["organization", "database"],
+
+    // PARENT FAN-OUT: PlanetScale branches are nested under a database within
+    // an organization, so there is no flat per-org branch enumeration API.
+    // Enumerate every database in the credentialed org, then list each
+    // database's branches concurrently (bounded), exhaustively paginating
+    // both levels, and keep only the branches whose engine kind matches this
+    // resource. Each item is hydrated into the exact `read` Attributes shape.
+    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)),
+        );
+
+      const rows = yield* Effect.forEach(
+        databases,
+        (db) =>
+          planetscale.listBranches
+            .pages({ organization, database: db.name })
+            .pipe(
+              Stream.runCollect,
+              Effect.map((chunk) =>
+                Array.from(chunk).flatMap((page) =>
+                  page.data
+                    .filter((branch) => branch.kind === opts.expectedKind)
+                    .map(
+                      (branch) =>
+                        ({
+                          name: branch.name,
+                          organization,
+                          database: db.name,
+                          parentBranch: branch.parent_branch ?? "main",
+                          production: branch.production,
+                          createdAt: branch.created_at,
+                          updatedAt: branch.updated_at,
+                          htmlUrl: branch.html_url,
+                          region: { slug: branch.region.slug },
+                          migrationsDir: undefined,
+                          migrationsTable: undefined,
+                          migrationsHashes: {},
+                          importHashes: {},
+                        }) satisfies BaseBranchAttributes,
+                    ),
+                ),
+              ),
+              // A database can be deleted between enumeration and the
+              // per-database branch list — skip it rather than fail.
+              Effect.catchTag("NotFound", () =>
+                Effect.succeed([] as BaseBranchAttributes[]),
+              ),
+            ),
+        { concurrency: 10 },
+      );
+
+      return rows.flat();
+    }),
+
     diff: Effect.fn(function* ({ news, olds, output }: any) {
       if (!isResolved(news)) return undefined;
 

package/src/Planetscale/MySQL/MySQLBranch.ts

@@ -98,6 +98,7 @@ export type MySQLBranch = Resource<
   Providers
 >;
 
+/** @resource */
 export const MySQLBranch = Resource<MySQLBranch>("Planetscale.MySQLBranch");
 
 export const MySQLBranchProvider = () =>