alchemy 2.0.0-beta.66 → 2.0.0-beta.67

package/src/Prisma/App.ts

@@ -92,13 +92,26 @@ export interface App extends Resource<
 /**
  * A Prisma App, the long-lived application configuration that owns deployments.
  *
+ * Omit `branchId` and `branchGitName` to attach the App to the project's
+ * current default branch. App regions are immutable; create a second App and
+ * cut traffic over when moving regions. Use `Prisma.Compute` for the usual
+ * build, deployment, health-check, and promotion workflow; use `App` directly
+ * when managing standalone `Prisma.Deployment` resources.
+ *
  * @resource
  * @section Creating an App
- * @example App attached to a branch
+ * @example App on the default branch
  * ```typescript
  * const app = yield* Prisma.App("web", {
- *   project: project.projectId,
- *   branchGitName: "main",
+ *   project,
+ * });
+ * ```
+ *
+ * @example App on a preview branch
+ * ```typescript
+ * const app = yield* Prisma.App("preview-web", {
+ *   project,
+ *   branchId: preview.branchId,
  * });
  * ```
  */

package/src/Prisma/Branch.ts

@@ -35,6 +35,7 @@ export interface BranchProps {
    * Promote this branch to be the project's default branch. Setting this to
    * `false` does not demote a current default because the Management API only
    * supports promotion; promoting another branch atomically demotes it.
+   * Promotion changes `isDefault`, not the branch's immutable `preview` role.
    *
    * @default false
    */
@@ -86,6 +87,10 @@ export interface Branch extends Resource<
 /**
  * A Prisma project branch for preview-class databases and compute resources.
  *
+ * Standalone Branch resources always have the `preview` role. Promotion
+ * changes only the default branch; Alchemy restores the previous default
+ * before deleting a promoted branch.
+ *
  * @resource
  * @section Creating a Branch
  * @example Preview branch
@@ -94,6 +99,22 @@ export interface Branch extends Resource<
  *   project: project.projectId,
  *   gitName: "feature/search", // optional — omitted, a stable name is generated
  * });
+ *
+ * branch.role;      // "preview"
+ * branch.isDefault; // false
+ * ```
+ *
+ * @section Promoting a Branch
+ * @example Make a preview branch the default
+ * ```typescript
+ * const release = yield* Prisma.Branch("release", {
+ *   project,
+ *   gitName: "release/next",
+ *   isDefault: true,
+ * });
+ *
+ * release.role;      // still "preview"
+ * release.isDefault; // true
  * ```
  */
 export const Branch = Resource<Branch>("Prisma.Branch");

package/src/Prisma/Compute.ts

@@ -545,7 +545,7 @@ const isEffectNativeCompute = (props: ComputeProps) =>
   hasEffectNativeComputeInput(props);
 
 /**
- * A Prisma Compute deployment resource.
+ * Build and deploy an application to Prisma Compute.
  *
  * Prisma's create-deployment API exposes neither an idempotency key nor a
  * caller-defined recovery key. If the API commits a deployment but its create
@@ -578,7 +578,7 @@ const isEffectNativeCompute = (props: ComputeProps) =>
  *   },
  *   Effect.gen(function* () {
  *     return {
- *       fetch: HttpServerResponse.text("ok"),
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
  *     };
  *   }),
  * );
@@ -601,7 +601,7 @@ const isEffectNativeCompute = (props: ComputeProps) =>
  *     return {
  *       fetch: Effect.gen(function* () {
  *         const users = yield* sql`SELECT * FROM users`;
- *         return HttpServerResponse.json(users);
+ *         return yield* HttpServerResponse.json(users);
  *       }),
  *     };
  *   }).pipe(Effect.provide(Prisma.ConnectBinding)),
@@ -620,7 +620,9 @@ const isEffectNativeCompute = (props: ComputeProps) =>
  *   },
  *   port: 8080,
  *   env: {
- *     DATABASE_URL: database.directConnectionString,
+ *     // Use this for a standalone Connection. A project's default database
+ *     // is injected by Prisma without an explicit DATABASE_URL entry.
+ *     DATABASE_URL: connection.databaseUrl,
  *   },
  *   destroyOldDeployment: true,
  * });

package/src/Prisma/Connect.ts

@@ -85,6 +85,29 @@ export interface ConnectClient {
  * Context tag, its type, and the callable —
  * `yield* Prisma.Connect(connection)`.
  *
+ * Provide `Prisma.ConnectBinding` on the host implementation so Alchemy can
+ * register the deploy-time binding and resolve the client at runtime.
+ *
+ * @section Binding a Connection
+ * @example Use a connection inside Prisma Compute
+ * ```typescript
+ * export default Prisma.Compute(
+ *   "api",
+ *   { project, main: import.meta.filename },
+ *   Effect.gen(function* () {
+ *     const db = yield* Prisma.Connect(connection);
+ *     const sql = yield* SQL.Postgres({ url: db.databaseUrl });
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const users = yield* sql`SELECT * FROM users`;
+ *         return yield* HttpServerResponse.json(users);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Prisma.ConnectBinding)),
+ * );
+ * ```
+ *
  * @binding
  */
 export interface Connect extends Binding.Service<

package/src/Prisma/Connection.ts

@@ -47,7 +47,10 @@ export interface ConnectionProps {
    */
   name?: string;
   /**
-   * Rotate credentials during the next update while keeping the connection ID.
+   * Rotate credentials when this value changes from `false` to `true` while
+   * keeping the connection ID. Prisma revokes the previous credentials on a
+   * best-effort basis. Deploy `false` before changing back to `true` for a
+   * later rotation.
    *
    * @default false
    */
@@ -129,6 +132,11 @@ export interface Connection extends Resource<
 /**
  * A Prisma database connection/API key.
  *
+ * Prisma returns connection credentials only when it creates or rotates a
+ * connection. Alchemy stores those outputs as `Redacted` values. Changing the
+ * database or name replaces the connection; changing `rotate` from `false` to
+ * `true` keeps the connection ID and requests fresh credentials.
+ *
  * @section Creating a Connection
  * @example Application connection
  * ```typescript
@@ -146,8 +154,7 @@ export interface Connection extends Resource<
  *
  * const app = yield* Prisma.Compute("api", {
  *   project,
- *   appName: "api",
- *   main: import.meta.filename,
+ *   path: "./apps/api",
  *   env: {
  *     DATABASE_URL: connection.databaseUrl,
  *     DIRECT_URL: connection.directConnectionString,
@@ -195,19 +202,29 @@ export interface Connection extends Resource<
  * ```typescript
  * export default Cloudflare.Worker(
  *   "api",
- *   { main: import.meta.filename },
+ *   { main: import.meta.filename, compatibility: { flags: ["nodejs_compat"] } },
  *   Effect.gen(function* () {
  *     const db = yield* Prisma.Connect(connection);
+ *     const sql = yield* SQL.Postgres({ url: db.databaseUrl });
  *     return {
  *       fetch: Effect.gen(function* () {
- *         const databaseUrl = yield* db.databaseUrl;
- *         return yield* HttpServerResponse.text("connected");
+ *         const result = yield* sql`SELECT 1 AS ok`;
+ *         return yield* HttpServerResponse.json(result);
  *       }),
  *     };
  *   }).pipe(Effect.provide(Prisma.ConnectBinding)),
  * );
  * ```
  *
+ * @section Rotating Credentials
+ * @example Request one rotation
+ * ```typescript
+ * const connection = yield* Prisma.Connection("api", {
+ *   database,
+ *   rotate: true,
+ * });
+ * ```
+ *
  * @section Connecting over Hyperdrive
  * @example Front Prisma Postgres with Cloudflare Hyperdrive
  * ```typescript

package/src/Prisma/CustomDomain.ts

@@ -25,7 +25,8 @@ type AppReference = string | App | Compute;
 
 export interface CustomDomainProps {
   /**
-   * App ID or Compute output that owns the domain.
+   * App ID or Compute output that owns the domain. The App must be attached to
+   * the project's current default branch.
    */
   app: AppReference;
   /**
@@ -90,6 +91,15 @@ export interface CustomDomain extends Resource<
 /**
  * A Prisma app custom domain.
  *
+ * Domains can only attach to Apps on the project's current default branch.
+ * Creating this resource starts asynchronous DNS and certificate provisioning;
+ * configure the returned `dnsRecords` and inspect `status`, `foundryStatus`,
+ * and `failureReason` before routing production traffic.
+ *
+ * App and hostname changes are intentionally rejected because the Management
+ * API cannot replace a live domain atomically. Create a second resource,
+ * verify DNS and TLS, cut traffic over, and then remove the old resource.
+ *
  * @resource
  * @section Creating a Custom Domain
  * @example Attach a hostname to an app

package/src/Prisma/Database.ts

@@ -150,8 +150,9 @@ export interface DatabaseProps {
   dev?: false | DatabaseDev;
   /**
    * Rotate the adopted database's default connection to recover its one-time
-   * credentials. Rotation revokes the previous key and may interrupt existing
-   * consumers, so adoption leaves credentials unset unless explicitly opted in.
+   * credentials. Prisma revokes the previous key on a best-effort basis and
+   * rotation may interrupt existing consumers, so adoption leaves credentials
+   * unset unless explicitly opted in.
    *
    * @default false
    */
@@ -230,17 +231,30 @@ export interface Database extends Resource<
 /**
  * A Prisma Postgres database inside a Prisma project.
  *
+ * Standalone `Prisma.Database` resources cannot be the project's default
+ * database. Use `Prisma.Project` when the project should own a default
+ * database. Project, region, and source changes require replacement; display
+ * name and branch attachment can converge in place. Destroying this resource
+ * deletes its database and data.
+ *
  * @resource
  * @section Creating a Database
  * @example Database in a project
  * ```typescript
  * const project = yield* Prisma.Project("app", { createDatabase: false });
  * const database = yield* Prisma.Database("db", {
- *   project: project.projectId,
- *   name: "production",
+ *   project,
  *   region: "us-east-1",
  * });
  * ```
+ *
+ * @example Database attached to a preview branch
+ * ```typescript
+ * const database = yield* Prisma.Database("preview-db", {
+ *   project,
+ *   branchId: preview.branchId,
+ * });
+ * ```
  */
 export const Database = Resource<Database>("Prisma.Database");
 

package/src/Prisma/Deployment.ts

@@ -55,7 +55,8 @@ export interface DeploymentProps {
    */
   portMapping?: { http?: number | null };
   /**
-   * Create the deployment by reusing the latest artifact instead of uploading code.
+   * Create the deployment by reusing the App's currently promoted artifact
+   * instead of uploading code. Requires an existing promoted deployment.
    */
   skipCodeUpload?: boolean;
   /**
@@ -128,6 +129,11 @@ export interface Deployment extends Resource<
 /**
  * A Prisma deployment owned by an App.
  *
+ * This is the low-level resource: it can upload or reuse an artifact, start it,
+ * and promote it, but it does not provide `Prisma.Compute`'s preview/stable
+ * health checks or automatic rollback. Prefer `Prisma.Compute` for production
+ * application deployments.
+ *
  * Prisma's create-deployment API currently exposes neither an idempotency key
  * nor a caller-defined natural key. After a crash that loses state immediately
  * after creation, Alchemy deliberately does not adopt the App's latest
@@ -137,7 +143,7 @@ export interface Deployment extends Resource<
  *
  * @resource
  * @section Creating a Deployment
- * @example Fork the latest uploaded artifact
+ * @example Fork the currently promoted artifact
  * ```typescript
  * const deployment = yield* Prisma.Deployment("web-v2", {
  *   app: app.appId,

package/src/Prisma/EnvironmentVariable.ts

@@ -97,15 +97,31 @@ export interface EnvironmentVariable extends Resource<
 /**
  * A Prisma compute environment variable.
  *
+ * Values are write-only in Prisma. Alchemy stores them as `Redacted` values
+ * and reapplies the desired value to repair drift.
+ *
  * @resource
  * @section Creating a Variable
- * @example Production secret
+ * @example Project-level production variable
  * ```typescript
- * yield* Prisma.EnvironmentVariable("database-url", {
+ * yield* Prisma.EnvironmentVariable("api-url", {
  *   project: project.projectId,
+ *   // No branchId: this is a project-level template.
  *   class: "production",
- *   key: "DATABASE_URL",
- *   value: Redacted.make("postgres://..."),
+ *   key: "API_URL",
+ *   value: Redacted.make("https://api.example.com"),
+ * });
+ * ```
+ *
+ * @example Preview branch override
+ * ```typescript
+ * yield* Prisma.EnvironmentVariable("preview-api-url", {
+ *   project,
+ *   branchId: preview.branchId,
+ *   // Branch overrides always use the preview class.
+ *   class: "preview",
+ *   key: "API_URL",
+ *   value: Redacted.make("https://preview.example.com"),
  * });
  * ```
  */

package/src/Prisma/Postgres.ts

@@ -6,14 +6,15 @@ import { Database } from "./Database.ts";
  * `Prisma.Postgres(...)` and `Prisma.Database(...)` use the same underlying
  * Prisma Postgres resource provider. Prefer `Postgres` when you want the code
  * to read like the Prisma product name, and `Database` when you want to mirror
- * the Management API route names.
+ * the Management API route names. Like `Database`, this standalone resource
+ * cannot be the project's default database; use `Prisma.Project` to own the
+ * default.
  *
  * @example
  * ```typescript
  * const project = yield* Prisma.Project("app", { createDatabase: false });
  * const postgres = yield* Prisma.Postgres("db", {
  *   project,
- *   name: "main",
  *   region: "us-east-1",
  * });
  * ```

package/src/Prisma/Project.ts

@@ -54,8 +54,9 @@ export interface ProjectProps {
   settings?: Record<string, unknown>;
   /**
    * Rotate the adopted default database connection to recover its one-time
-   * credentials. Rotation revokes the previous key and may interrupt existing
-   * consumers, so adoption leaves credentials unset unless explicitly opted in.
+   * credentials. Prisma revokes the previous key on a best-effort basis and
+   * rotation may interrupt existing consumers, so adoption leaves credentials
+   * unset unless explicitly opted in.
    *
    * @default false
    */
@@ -126,6 +127,11 @@ export interface Project extends Resource<
 /**
  * A Prisma project, optionally with a default Prisma Postgres database.
  *
+ * A Project is the ownership boundary for its databases, branches, apps, and
+ * repository link. Destroying this resource deletes the project and its
+ * contained data. Set `createDatabase: false` when you want standalone
+ * `Prisma.Database` resources with independent lifecycles.
+ *
  * @resource
  * @section Creating a Project
  * @example Project with a default database

package/src/Prisma/Providers.ts

@@ -1,3 +1,4 @@
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import type * as Path from "effect/Path";
@@ -7,18 +8,24 @@ import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSp
 import { AlchemyContext } from "../AlchemyContext.ts";
 import { AuthProviders } from "../Auth/AuthProvider.ts";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
-import { ProfileLive } from "../Auth/Profile.ts";
+import { AlchemyProfile, ProfileLive } from "../Auth/Profile.ts";
 import * as Provider from "../Provider.ts";
 import type { ResourceClass, ResourceLike } from "../Resource.ts";
 import { PlatformServices } from "../Util/PlatformServices.ts";
+import { proxyChain } from "../Util/proxy-chain.ts";
 import { PrismaAuth } from "./AuthProvider.ts";
 import { App, AppProvider } from "./App.ts";
 import { Branch, BranchProvider } from "./Branch.ts";
-import { Compute, ComputeDevProvider, ComputeProvider } from "./Compute.ts";
-import { Deployment, DeploymentProvider } from "./Deployment.ts";
+import {
+  PrismaClient,
+  PrismaClientLive,
+  type PrismaManagementClient,
+} from "./Client.ts";
 import { Connection, ConnectionProvider } from "./Connection.ts";
+import { Compute, ComputeDevProvider, ComputeProvider } from "./Compute.ts";
 import { CustomDomain, CustomDomainProvider } from "./CustomDomain.ts";
 import { Database, DatabaseProvider } from "./Database.ts";
+import { Deployment, DeploymentProvider } from "./Deployment.ts";
 import {
   EnvironmentVariable,
   EnvironmentVariableProvider,
@@ -28,7 +35,6 @@ import {
   closePrismaDevDatabase,
   ensurePrismaDevDatabase,
 } from "./PrismaDevDatabase.ts";
-import { PrismaClientLive } from "./Client.ts";
 import {
   PrismaHttpClientLive,
   PrismaUploadClientLive,
@@ -48,7 +54,12 @@ export class Providers extends Provider.ProviderCollection<Providers>()(
 
 export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
 
-const managementApiLayer = () =>
+/**
+ * Standalone operation helpers own a private auth registry because they run
+ * outside a Stack. Credential resolution stays eager here so constructing
+ * `managementApi()` preserves its existing fail-fast behavior.
+ */
+const standaloneManagementApiLayer = () =>
   PrismaClientLive.pipe(
     Layer.provideMerge(fromProfile()),
     Layer.provideMerge(PrismaAuth),
@@ -71,6 +82,54 @@ const managementApiLayer = () =>
     Layer.provide(PrismaHttpClientLive),
   );
 
+/**
+ * Stack provider discovery must register auth without requiring credentials.
+ * The management client is resolved on its first API operation, after
+ * `alchemy login` has had a chance to configure the registered Prisma auth
+ * provider. The nested client layer shares the provider layer's lifetime.
+ */
+const stackManagementApiLayer = () =>
+  Layer.effect(
+    PrismaClient,
+    Effect.gen(function* () {
+      const scope = yield* Effect.scope;
+      const authProviders = yield* AuthProviders;
+      const profile = yield* AlchemyProfile;
+      const client = Layer.buildWithScope(
+        PrismaClientLive.pipe(
+          Layer.provideMerge(
+            fromProfile().pipe(
+              Layer.provide(
+                Layer.mergeAll(
+                  Layer.succeed(AuthProviders, authProviders),
+                  Layer.succeed(AlchemyProfile, profile),
+                ),
+              ),
+            ),
+          ),
+          Layer.provide(PrismaHttpClientLive),
+        ),
+        scope,
+      ).pipe(
+        Effect.map((context) => Context.get(context, PrismaClient)),
+        Effect.orDie,
+      );
+      const cached = yield* Effect.cached(client);
+      return proxyChain(cached) as PrismaManagementClient;
+    }),
+  ).pipe(
+    Layer.provideMerge(PrismaAuth),
+    Layer.provideMerge(
+      Layer.mergeAll(
+        // The Prisma-scoped upload client (node transport) rides the
+        // providers' output so artifact uploads can reach it at op time.
+        PrismaUploadClientLive,
+        Layer.provide(ProfileLive, PlatformServices),
+        Layer.provide(CredentialsStoreLive, PlatformServices),
+      ),
+    ),
+  );
+
 /**
  * Build a layer for Prisma Management API operation helpers.
  *
@@ -88,7 +147,8 @@ const managementApiLayer = () =>
  * );
  * ```
  */
-export const managementApi = () => managementApiLayer().pipe(Layer.orDie);
+export const managementApi = () =>
+  standaloneManagementApiLayer().pipe(Layer.orDie);
 
 /**
  * Build a layer that registers all Prisma Management API resource providers,
@@ -408,4 +468,4 @@ const liveProviderLayer = () =>
     CustomDomainProvider(),
     EnvironmentVariableProvider(),
     SourceRepositoryProvider(),
-  ).pipe(Layer.provideMerge(managementApiLayer()), Layer.orDie);
+  ).pipe(Layer.provideMerge(stackManagementApiLayer()), Layer.orDie);

package/src/Prisma/SourceRepository.ts

@@ -38,7 +38,12 @@ export interface SourceRepositoryProps {
    */
   provider?: "github";
   /**
-   * Numeric provider repository ID.
+   * GitHub's permanent numeric repository ID, not `owner/repo`, a Prisma
+   * project ID, or an SCM installation ID. Retrieve it with:
+   *
+   * ```bash
+   * gh api repos/OWNER/REPO --jq '.id'
+   * ```
    */
   providerRepositoryId: number;
   /**
@@ -104,6 +109,12 @@ export interface SourceRepository extends Resource<
 /**
  * A linked source repository for Prisma apps.
  *
+ * GitHub is currently the only supported provider. Linking requires an
+ * existing Prisma SCM installation. `providerRepositoryId` is GitHub's
+ * permanent numeric repository ID; retrieve it with
+ * `gh api repos/OWNER/REPO --jq '.id'`. When `installationId` is omitted,
+ * Prisma selects the workspace installation.
+ *
  * Linking creates or renames the repository-owned default branch. Observe
  * that branch through the Management API; do not declare it again as a
  * separate `Prisma.Branch` resource. Use this resource's outputs to order
@@ -111,12 +122,24 @@ export interface SourceRepository extends Resource<
  * Deleting the link does not roll those side effects back: existing branches,
  * databases, and apps remain in the project.
  *
+ * The project, repository ID, provider, and installation form an immutable
+ * link identity. Alchemy refuses an automatic relink because unlinking cannot
+ * roll back branch and resource attachments. Existing links require explicit
+ * adoption.
+ *
  * @resource
+ * @section Finding the Repository ID
+ * @example Read the numeric GitHub repository ID
+ * ```bash
+ * gh api repos/OWNER/REPO --jq '.id'
+ * ```
+ *
  * @section Linking a Repository
  * @example GitHub repository
  * ```typescript
  * const repo = yield* Prisma.SourceRepository("repo", {
  *   project: project.projectId,
+ *   // Replace with the value returned by the GitHub command above.
  *   providerRepositoryId: 123456789,
  * });
  * const database = yield* Prisma.Database("database", {