@samebase/alchemy-convex 0.3.0 → 0.4.0

package/src/Deployment.ts

@@ -1,12 +1,28 @@
-// Convex.Deployment: one deployment of a Convex project, with the URLs that a
-// frontend or a Worker needs.
+// Convex.Deployment: one deployment of a Convex project, its environment
+// variables, and its functions, with the URLs that a frontend or a Worker
+// needs. This is the Convex plane of a stack: no deploy key leaves it.
 //
+// - `source` is the Convex functions directory, such as `./convex`. The
+//   update pushes it with the Convex CLI that the app installed (Push.ts).
+//   The content identity of the push is a hash of the source files, the
+//   app's package.json, convex.json, and lockfile, the deployment name, and
+//   `env`. The same hash is a no-op. The hash is taken again after the push,
+//   so files that `convex deploy` generates are part of it.
+//   `source.command` replaces `convex deploy`, such as `convex-hosting
+//   deploy`, and `source.include` adds the files that it reads to the hash.
+// - `env` is set on the deployment before the push. A name that leaves `env`
+//   is removed. A variable that exists with another value and that this
+//   resource did not set is someone else's: it is overwritten only with
+//   --adopt. Delete leaves the variables: they go with the deployment.
+// - Credentials by scope (see Access below): a deploy key of the deployment,
+//   a preview deploy key of the project, or the Management API token.
 // - `prod` is the project's default production deployment. Convex creates it
 //   with the project, so this resource never creates one. It takes the
 //   deployment over without --adopt: it never changes or deletes a production
 //   deployment, so the takeover cannot lose data. It follows the default:
 //   when another production deployment becomes the default, the next deploy
-//   outputs that one. To delete a production deployment, delete its project
+//   outputs that one. With a deploy key, `prod` is the production deployment
+//   of that key. To delete a production deployment, delete its project
 //   (Convex.Project with RemovalPolicy.destroy()). Delete reads the live type
 //   first, so a dev or preview deployment that became a production
 //   deployment is not deleted either.
@@ -28,37 +44,67 @@
 //   preview deployment with the resource, add RemovalPolicy.destroy().
 //
 // Patterns from Confect `packages/alchemy/src/Deployment.ts`
-// (https://github.com/rjdellecese/confect, ISC license).
+// (https://github.com/rjdellecese/confect, ISC license, see NOTICE).
 import { Resource } from "alchemy";
 import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
 import { isResolved } from "alchemy/Diff";
 import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
+import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
 import { shouldAdopt } from "./Adoption.ts";
-import { absentAsUndefined, ManagementApi, retryIdempotentWrite } from "./ManagementApi.ts";
+import { Credentials } from "./Credentials.ts";
+import {
+  absentAsUndefined,
+  type ConvexApiError,
+  ManagementApi,
+  type ManagementApiService,
+  retryIdempotentWrite,
+} from "./ManagementApi.ts";
 import type { Providers } from "./Providers.ts";
+import {
+  checkSource,
+  EnvironmentNeedsDeployKey,
+  type EnvValue,
+  keyTargetOf,
+  push,
+  pushHash,
+  type Source,
+  withPushKey,
+} from "./Push.ts";
+
+interface DeploymentInputs {
+  /** The project: a Convex.Project resource, or `{ projectId }`. Cannot change. */
+  readonly project: { readonly projectId: number };
+  /**
+   * The Convex functions directory, such as `./convex`, or that directory
+   * with a push command and more hashed files. The push runs in the nearest
+   * directory above it with a package.json. Without `source`, the resource
+   * pushes nothing.
+   */
+  readonly source?: Source;
+  /** Environment variables to set on the deployment before the push. */
+  readonly env?: Readonly<Record<string, EnvValue>>;
+}
 
 export type DeploymentProps =
-  | {
-      /** Numeric project id, such as `project.projectId`. Cannot change. */
-      readonly projectId: number;
+  | (DeploymentInputs & {
       /** The project's default production deployment. Cannot change. */
       readonly type: "prod";
-    }
-  | {
-      /** Numeric project id, such as `project.projectId`. Cannot change. */
-      readonly projectId: number;
+    })
+  | (DeploymentInputs & {
       /** A dev deployment or a preview deployment that this resource creates. Cannot change. */
       readonly type: "dev" | "preview";
       /**
-       * The dev reference, such as `staging`, or the preview name, such as a
-       * pull request or stage name. Unique in the project. Cannot change.
+       * The dev reference, such as `staging`, or the preview name, such as
+       * the stage name. Unique in the project. Cannot change.
        */
       readonly name: string;
-    };
+    });
 
-export interface DeploymentAttributes {
+/** The deployment itself, without the state of the push. */
+interface DeploymentTarget {
   readonly projectId: number;
   readonly type: DeploymentProps["type"];
   /** Deployment name, such as `happy-animal-123`. */
@@ -73,6 +119,13 @@ export interface DeploymentAttributes {
   readonly siteUrl: string;
 }
 
+export interface DeploymentAttributes extends DeploymentTarget {
+  /** Content identity of the last push and `env`. Undefined when the resource pushed nothing. */
+  readonly hash: string | undefined;
+  /** The names of the `env` variables that this resource set on the deployment, sorted. */
+  readonly envNames: readonly string[];
+}
+
 export type Deployment = Resource<
   "Convex.Deployment",
   DeploymentProps,
@@ -149,15 +202,31 @@ export const DeploymentRow = Schema.Struct({
   /** Set in list_deployments and create_deployment rows only: GET /deployments/{name} answers null. */
   previewIdentifier: Schema.optionalKey(Schema.NullOr(Schema.String)),
   deploymentUrl: Schema.String.check(Schema.isPattern(CLOUD_URL)),
+  /** Absent or null until the first push: list_deployments leaves it out for a new deployment. */
+  lastDeployTime: Schema.optionalKey(Schema.NullOr(Schema.Number)),
 });
 type DeploymentRow = typeof DeploymentRow.Type;
 const DeploymentRows = Schema.Array(DeploymentRow);
 
-const attributesOf = (
+/** GET https://<deployment>/api/v1/deployment_info, for a cloud deployment. Only the fields the provider uses. */
+const DeploymentInfo = Schema.Struct({
+  kind: Schema.Literal("cloud"),
+  projectId: Schema.Number,
+  deploymentType: Schema.String,
+  reference: Schema.optionalKey(Schema.NullOr(Schema.String)),
+});
+
+/** GET https://<deployment>/api/v1/get_canonical_urls */
+const CanonicalUrls = Schema.Struct({
+  convexCloudUrl: Schema.String,
+  convexSiteUrl: Schema.String,
+});
+
+const targetOf = (
   row: DeploymentRow,
   type: DeploymentProps["type"],
   previewName: string | undefined,
-): DeploymentAttributes => ({
+): DeploymentTarget => ({
   projectId: row.projectId,
   type,
   name: row.name,
@@ -167,19 +236,23 @@ const attributesOf = (
   siteUrl: siteUrlOf(row.deploymentUrl),
 });
 
-/** The `name` prop of the deployment in state: the dev reference or the preview name. */
-const nameOf = (attributes: DeploymentAttributes) =>
-  attributes.type === "dev"
-    ? attributes.reference
-    : attributes.type === "preview"
-      ? attributes.previewName
+/** True when the deployment has received a push. */
+const isDeployed = (row: DeploymentRow) =>
+  row.lastDeployTime !== undefined && row.lastDeployTime !== null;
+
+/** The `name` prop of a deployment: the dev reference or the preview name. */
+const nameOf = (target: DeploymentTarget) =>
+  target.type === "dev"
+    ? target.reference
+    : target.type === "preview"
+      ? target.previewName
       : undefined;
 
 /**
  * Fails with {@link DeploymentIdentityChange} when the props name another
- * deployment than `current`: the attributes in state, or a live row.
+ * deployment than `current`: the attributes in state, or a live deployment.
  */
-const checkIdentity = (current: DeploymentAttributes, news: DeploymentProps) => {
+const checkIdentity = (current: DeploymentTarget, news: DeploymentProps) => {
   const change = (field: "projectId" | "type" | "name", from: string, to: string) =>
     Effect.fail(
       new DeploymentIdentityChange({
@@ -189,8 +262,8 @@ const checkIdentity = (current: DeploymentAttributes, news: DeploymentProps) =>
         requested: to,
       }),
     );
-  if (current.projectId !== news.projectId) {
-    return change("projectId", String(current.projectId), String(news.projectId));
+  if (current.projectId !== news.project.projectId) {
+    return change("projectId", String(current.projectId), String(news.project.projectId));
   }
   if (current.type !== news.type) return change("type", current.type, news.type);
   const currentName = nameOf(current);
@@ -200,16 +273,78 @@ const checkIdentity = (current: DeploymentAttributes, news: DeploymentProps) =>
   return Effect.void;
 };
 
+/** The deployment that a resource addresses: its project, type, and dev or preview name. */
+interface Address {
+  readonly projectId: number;
+  readonly type: DeploymentProps["type"];
+  readonly name: string | undefined;
+}
+
+const addressOf = (props: DeploymentProps): Address => ({
+  projectId: props.project.projectId,
+  type: props.type,
+  name: props.type === "prod" ? undefined : props.name,
+});
+
+/** True when an update writes or removes variables: `env` has names, or state has names to remove. */
+const changesEnv = (news: DeploymentProps, output: DeploymentAttributes | undefined) =>
+  Object.keys(news.env ?? {}).length > 0 || envNamesOf(output).length > 0;
+
+/** The `env` names in state. State from 0.3 has none. */
+const envNamesOf = (output: DeploymentAttributes | undefined): readonly string[] =>
+  output?.envNames ?? [];
+
+/** The address of the deployment in state. */
+const addressInState = (output: DeploymentAttributes): Address => ({
+  projectId: output.projectId,
+  type: output.type,
+  name: nameOf(output),
+});
+
+/**
+ * How the provider reaches one deployment, by the narrowest credential that
+ * fits:
+ *
+ * - `deployKey`: the configured deploy key belongs to this deployment. The
+ *   deployment API answers its identity and URLs, the key sets variables and
+ *   pushes, and no Management API call is made.
+ * - `previewKey`: the configured preview deploy key belongs to this project.
+ *   The Management API takes it for the preview deployments of the project,
+ *   and the CLI pushes with it and `--preview-name`.
+ * - `token`: the Management API access token. Each push gets a short-lived
+ *   deploy key (Push.ts).
+ */
+type Access =
+  | {
+      readonly kind: "deployKey";
+      readonly key: Redacted.Redacted<string>;
+      readonly target: DeploymentTarget;
+    }
+  | {
+      readonly kind: "previewKey";
+      readonly key: Redacted.Redacted<string>;
+      readonly api: ManagementApiService;
+    }
+  | { readonly kind: "token"; readonly api: ManagementApiService };
+
+const ProjectSlugs = Schema.Struct({ slug: Schema.String, teamSlug: Schema.String });
+
+/** True for an answer that says this credential cannot read the object. */
+const isRefused = (error: ConvexApiError) =>
+  error.status === 400 || error.status === 401 || error.status === 403 || error.status === 404;
+
 export const DeploymentProvider = () =>
   Provider.effect(
     Deployment,
     Effect.gen(function* () {
       const api = yield* ManagementApi;
+      const credentials = yield* Credentials;
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 
       /** The live deployment, or undefined after a 404. GET /deployments/{name} answers no preview identifier. */
-      const getByName = (name: string) =>
+      const getByName = (management: ManagementApiService, name: string) =>
         absentAsUndefined(
-          api.request("get deployment", (client) =>
+          management.request("get deployment", (client) =>
             client.GET("/deployments/{deployment_name}", {
               params: { path: { deployment_name: name } },
             }),
@@ -221,11 +356,12 @@ export const DeploymentProvider = () =>
         );
 
       const listDeployments = (
+        management: ManagementApiService,
         projectId: number,
         type: DeploymentProps["type"],
         isDefault?: boolean,
       ) =>
-        api
+        management
           .request("list deployments", (client) =>
             client.GET("/projects/{project_id}/list_deployments", {
               params: {
@@ -236,24 +372,32 @@ export const DeploymentProvider = () =>
           )
           .pipe(Effect.map((body) => Schema.decodeUnknownSync(DeploymentRows)(body)));
 
+      /** The row of the project's default production deployment, or undefined. */
+      const productionRow = (management: ManagementApiService, projectId: number) =>
+        listDeployments(management, projectId, "prod", true).pipe(
+          Effect.map((rows) =>
+            rows.find((candidate) => candidate.deploymentType === "prod" && candidate.isDefault),
+          ),
+        );
+
       /** The project's default production deployment, or undefined. */
-      const production = (projectId: number) =>
-        listDeployments(projectId, "prod", true).pipe(
-          Effect.map((rows) => {
-            const row = rows.find(
-              (candidate) => candidate.deploymentType === "prod" && candidate.isDefault,
-            );
-            return row === undefined ? undefined : attributesOf(row, "prod", undefined);
-          }),
+      const production = (management: ManagementApiService, projectId: number) =>
+        productionRow(management, projectId).pipe(
+          Effect.map((row) => (row === undefined ? undefined : targetOf(row, "prod", undefined))),
         );
 
       /**
        * The one dev deployment with this reference, or the one preview
        * deployment with this preview name, or undefined.
        */
-      const findByName = (projectId: number, type: "dev" | "preview", name: string) =>
+      const findByName = (
+        management: ManagementApiService,
+        projectId: number,
+        type: "dev" | "preview",
+        name: string,
+      ) =>
         Effect.gen(function* () {
-          const matches = (yield* listDeployments(projectId, type)).filter(
+          const matches = (yield* listDeployments(management, projectId, type)).filter(
             (row) =>
               row.deploymentType === type &&
               (type === "dev" ? row.reference === name : row.previewIdentifier === name),
@@ -269,16 +413,114 @@ export const DeploymentProvider = () =>
           return matches[0];
         });
 
-      /** The deployment that the props name, for a resource without state. */
-      const lookup = (news: DeploymentProps) =>
-        news.type === "prod"
-          ? production(news.projectId)
-          : findByName(news.projectId, news.type, news.name).pipe(
+      /** The deployment that the address names, through the Management API, or undefined. */
+      const lookup = (management: ManagementApiService, address: Address) =>
+        address.type === "prod" || address.name === undefined
+          ? production(management, address.projectId)
+          : findByName(management, address.projectId, address.type, address.name).pipe(
               Effect.map((row) =>
-                row === undefined ? undefined : attributesOf(row, news.type, news.name),
+                row === undefined ? undefined : targetOf(row, address.type, address.name),
               ),
             );
 
+      /** The deployment of a deploy key, when it is the deployment that the address names. */
+      const deployKeyTarget = (
+        key: Redacted.Redacted<string>,
+        deployment: string,
+        address: Address,
+      ) =>
+        Effect.gen(function* () {
+          const info = Schema.decodeUnknownSync(DeploymentInfo)(
+            yield* api.deploymentRequest("get deployment info", deployment, key, (client) =>
+              client.GET("/deployment_info"),
+            ),
+          );
+          const reference = info.reference ?? "";
+          if (
+            info.projectId !== address.projectId ||
+            info.deploymentType !== address.type ||
+            (address.type === "dev" && reference !== address.name)
+          ) {
+            return undefined;
+          }
+          const urls = Schema.decodeUnknownSync(CanonicalUrls)(
+            yield* api.deploymentRequest("get canonical urls", deployment, key, (client) =>
+              client.GET("/get_canonical_urls"),
+            ),
+          );
+          return {
+            projectId: info.projectId,
+            type: address.type,
+            name: deployment,
+            reference,
+            previewName: undefined,
+            url: urls.convexCloudUrl,
+            siteUrl: urls.convexSiteUrl,
+          } satisfies DeploymentTarget;
+        }).pipe(Effect.catchIf(isRefused, () => Effect.succeed(undefined)));
+
+      /** True when the preview deploy key belongs to the project. */
+      const previewKeyFits = (
+        management: ManagementApiService,
+        slugs: { readonly team: string; readonly project: string },
+        projectId: number,
+      ) =>
+        management
+          .request("get project", (client) =>
+            client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } }),
+          )
+          .pipe(
+            Effect.map((body) => {
+              const project = Schema.decodeUnknownSync(ProjectSlugs)(body);
+              return project.slug === slugs.project && project.teamSlug === slugs.team;
+            }),
+            Effect.catchIf(isRefused, () => Effect.succeed(false)),
+          );
+
+      /**
+       * The narrowest credential that reaches the deployment. See {@link Access}.
+       * When `changesEnv`, a preview deploy key gives way to the access token,
+       * because it cannot change variables.
+       */
+      const accessFor = (address: Address, changesEnv: boolean) =>
+        Effect.gen(function* (): Effect.fn.Return<Access, ConvexApiError> {
+          const key = yield* credentials.deployKey;
+          if (key !== undefined) {
+            const target = keyTargetOf(Redacted.value(key));
+            if (target.kind === "deployment" && address.type !== "preview") {
+              const found = yield* deployKeyTarget(key, target.deployment, address);
+              if (found !== undefined) return { kind: "deployKey", key, target: found };
+            }
+            if (target.kind === "preview" && address.type === "preview") {
+              const scoped = api.withToken(key);
+              if (
+                !(changesEnv && (yield* credentials.hasAccessToken)) &&
+                (yield* previewKeyFits(scoped, target, address.projectId))
+              ) {
+                return { kind: "previewKey", key, api: scoped };
+              }
+            }
+          }
+          return { kind: "token", api };
+        });
+
+      /** The live deployment of a resource in state, or undefined when it is gone. */
+      const live = (access: Access, output: DeploymentAttributes) =>
+        Effect.gen(function* () {
+          if (access.kind === "deployKey") return access.target;
+          // 404 for a deleted project: its production deployment is gone too.
+          if (output.type === "prod")
+            return yield* absentAsUndefined(production(access.api, output.projectId));
+          const row = yield* getByName(access.api, output.name);
+          return row === undefined ? undefined : targetOf(row, output.type, output.previewName);
+        });
+
+      /** The content identity of `source` and `env` on a deployment, or undefined when there is nothing to push. */
+      const wantedHash = (news: DeploymentProps, deployment: string) =>
+        news.source === undefined && Object.keys(news.env ?? {}).length === 0
+          ? Effect.succeed(undefined)
+          : pushHash({ source: news.source, deployment, env: news.env ?? {} });
+
       return {
         // `name`, `reference`, and the URLs change when an expired preview is
         // created again, or when another production deployment becomes the
@@ -290,113 +532,210 @@ export const DeploymentProvider = () =>
         diff: Effect.fn(function* ({ news, output }) {
           if (!isResolved(news) || output === undefined) return undefined;
           yield* checkIdentity(output, news);
-          // `prod` follows the project's default production deployment,
-          // which can change in Convex. Reconcile then returns the new one.
-          if (news.type === "prod") {
-            // A 404 for a deleted project plans an update; reconcile then reports it.
-            const current = yield* absentAsUndefined(production(news.projectId));
-            return current?.name === output.name ? undefined : ({ action: "update" } as const);
-          }
-          // A preview expires, and anyone can delete a deployment. Reconcile
-          // then finds or creates it again, so the stack never hands out the
+          const access = yield* accessFor(addressOf(news), changesEnv(news, output));
+          // A preview expires, anyone can delete a deployment, and another
+          // production deployment can become the default. Reconcile then
+          // finds or creates the right one, so the stack never hands out the
           // URL of a deployment that is gone.
-          const live = yield* getByName(output.name);
-          return live === undefined ? ({ action: "update" } as const) : undefined;
+          const current = yield* live(access, output);
+          if (current?.name !== output.name) return { action: "update" } as const;
+          const hash = yield* wantedHash(news, output.name);
+          return hash === output.hash
+            ? ({ action: "noop" } as const)
+            : ({ action: "update" } as const);
         }),
 
         read: Effect.fn(function* ({ olds, output }) {
-          if (output?.type === "prod") {
-            // 404: the project is gone, and so is its production deployment.
-            return yield* absentAsUndefined(production(output.projectId));
-          }
           if (output !== undefined) {
-            const live = yield* getByName(output.name);
-            return live === undefined
-              ? undefined
-              : attributesOf(live, output.type, output.previewName);
+            const access = yield* accessFor(addressInState(output), false);
+            const current = yield* live(access, output);
+            return current === undefined ? undefined : { ...output, ...current };
+          }
+          const address = addressOf(olds);
+          const access = yield* accessFor(address, false);
+          if (access.kind === "deployKey") {
+            // The deployment API does not say whether the deployment has code.
+            return Unowned({ ...access.target, hash: undefined, envNames: [] });
+          }
+          if (olds.type === "prod") {
+            const row = yield* productionRow(access.api, address.projectId);
+            if (row === undefined) return undefined;
+            const attributes = {
+              ...targetOf(row, "prod", undefined),
+              hash: undefined,
+              envNames: [],
+            };
+            // A production deployment that never received a push, such as
+            // the one of a project that this stack created, loses nothing to
+            // a push. One with code is someone else's until --adopt.
+            return isDeployed(row) ? Unowned(attributes) : attributes;
           }
-          const found = yield* lookup(olds);
+          const found = yield* lookup(access.api, address);
           if (found === undefined) return undefined;
-          // The production deployment comes with the project, and this
-          // resource never changes or deletes it, so it is ours to read.
           // A dev or preview deployment that is not in state is someone
           // else's until the user passes --adopt.
-          return olds.type === "prod" ? found : Unowned(found);
+          return Unowned({ ...found, hash: undefined, envNames: [] });
         }),
 
         reconcile: Effect.fn(function* ({ fqn, news, output }) {
           // Also here: with an unresolved prop in plan, diff could not check.
           if (output !== undefined) yield* checkIdentity(output, news);
-          if (news.type === "prod") {
-            // Always the current default, also when another production
-            // deployment became the default after the last deploy.
-            const current = yield* production(news.projectId);
-            if (current === undefined) {
-              return yield* new ProductionDeploymentNotFound({ projectId: news.projectId });
-            }
-            return current;
+          // The functions directory and the program, before any change.
+          if (news.source !== undefined) yield* checkSource(news.source);
+          const address = addressOf(news);
+          const access = yield* accessFor(address, changesEnv(news, output));
+          const env = news.env ?? {};
+          // Before any create: a preview deploy key cannot change variables,
+          // and accessFor chose it because there is no access token.
+          if (access.kind === "previewKey" && changesEnv(news, output)) {
+            return yield* new EnvironmentNeedsDeployKey({
+              deployment: output?.name ?? address.name ?? "(new)",
+            });
           }
-          if (output !== undefined) {
-            const live = yield* getByName(output.name);
-            if (live !== undefined) {
-              if (live.deploymentType !== output.type) {
-                return yield* new DeploymentIdentityChange({
-                  deployment: live.name,
-                  field: "type",
-                  current: live.deploymentType,
-                  requested: news.type,
-                });
+          const adopt = yield* shouldAdopt(fqn);
+          const refuse = (name: string) =>
+            new OwnedBySomeoneElse({
+              message: `Project ${address.projectId} already has ${news.type} deployment ${name}${news.type === "prod" ? " with code" : ` named "${news.name}"`}. Re-run with --adopt to take it over${news.type === "prod" ? "" : ", or use another name"}.`,
+              resourceType: Deployment.Type,
+              physicalName: name,
+            });
+
+          // 1. The deployment. `created` is true when this reconcile created it.
+          const { target, created } = yield* Effect.gen(function* () {
+            if (access.kind === "deployKey") {
+              // read() refused it without --adopt; this covers an apply without a plan.
+              if (output === undefined && !adopt) return yield* refuse(access.target.name);
+              return { target: access.target, created: false };
+            }
+            if (news.type === "prod") {
+              // Always the current default, also when another production
+              // deployment became the default after the last deploy.
+              const row = yield* productionRow(access.api, address.projectId);
+              if (row === undefined) {
+                return yield* new ProductionDeploymentNotFound({ projectId: address.projectId });
               }
-              const current = attributesOf(live, output.type, output.previewName);
-              // The live deployment can have moved to another project.
-              yield* checkIdentity(current, news);
-              return current;
+              // Code that appeared after the plan is someone else's.
+              if (output === undefined && isDeployed(row) && !adopt) return yield* refuse(row.name);
+              return { target: targetOf(row, "prod", undefined), created: false };
             }
-            // The deployment in state is gone, such as an expired preview.
-            // Find or create it below like a resource without state.
-          }
-          // Never create over an existing deployment: a preview create
-          // replaces the preview deployment with the same name. Another
-          // writer can still create one between this lookup and the create.
-          const existing = yield* lookup(news);
-          if (existing !== undefined) {
-            if (!(yield* shouldAdopt(fqn))) {
-              return yield* new OwnedBySomeoneElse({
-                message: `Project ${news.projectId} already has ${news.type} deployment ${existing.name} named "${news.name}". Re-run with --adopt to take it over, or use another name.`,
-                resourceType: Deployment.Type,
-                physicalName: existing.name,
-              });
+            if (output !== undefined) {
+              const row = yield* getByName(access.api, output.name);
+              if (row !== undefined) {
+                if (row.deploymentType !== output.type) {
+                  return yield* new DeploymentIdentityChange({
+                    deployment: row.name,
+                    field: "type",
+                    current: row.deploymentType,
+                    requested: news.type,
+                  });
+                }
+                const current = targetOf(row, output.type, output.previewName);
+                // The live deployment can have moved to another project.
+                yield* checkIdentity(current, news);
+                return { target: current, created: false };
+              }
+              // The deployment in state is gone, such as an expired preview.
+              // Find or create it below like a resource without state.
             }
-            return existing;
+            // Never create over an existing deployment: a preview create
+            // replaces the preview deployment with the same name. Another
+            // writer can still create one between this lookup and the create.
+            const existing = yield* lookup(access.api, address);
+            if (existing !== undefined) {
+              if (!adopt) return yield* refuse(existing.name);
+              return { target: existing, created: false };
+            }
+            const row = yield* access.api.request("create deployment", (client) =>
+              client.POST("/projects/{project_id}/create_deployment", {
+                params: { path: { project_id: address.projectId } },
+                body: { type: news.type, reference: news.name },
+              }),
+            );
+            return {
+              target: targetOf(Schema.decodeUnknownSync(DeploymentRow)(row), news.type, news.name),
+              created: true,
+            };
+          });
+
+          // 2. The variables and the push, only when their content changed.
+          // Variables set on another deployment stay there: they are not ours
+          // on this one.
+          const previousEnvNames = output?.name === target.name ? envNamesOf(output) : [];
+          const before = yield* wantedHash(news, target.name);
+          if (before === undefined && previousEnvNames.length === 0) {
+            return { ...target, hash: undefined, envNames: [] };
           }
-          const created = yield* api.request("create deployment", (client) =>
-            client.POST("/projects/{project_id}/create_deployment", {
-              params: { path: { project_id: news.projectId } },
-              body: { type: news.type, reference: news.name },
-            }),
-          );
-          return attributesOf(
-            Schema.decodeUnknownSync(DeploymentRow)(created),
-            news.type,
-            news.name,
+          if (output?.name === target.name && before === output.hash) {
+            return { ...target, hash: output.hash, envNames: previousEnvNames };
+          }
+          const options = {
+            deployment: target.name,
+            url: target.url,
+            source: news.source,
+            env,
+            previousEnvNames,
+            adopt,
+          };
+          const pushed =
+            access.kind === "deployKey"
+              ? push(spawner, access.key, { ...options, previewName: undefined })
+              : access.kind === "previewKey"
+                ? push(spawner, access.key, { ...options, previewName: target.previewName })
+                : withPushKey(access.api, target.name, news.source, (key) =>
+                    push(spawner, key, { ...options, previewName: undefined }),
+                  );
+          yield* pushed.pipe(
+            // A deployment that this reconcile created and could not push to
+            // would be someone else's on the next run, and a dev deployment
+            // never expires. It is new and empty, so it goes.
+            Effect.onError(() =>
+              created && access.kind !== "deployKey"
+                ? absentAsUndefined(
+                    retryIdempotentWrite(
+                      access.api.requestVoid("delete deployment", (client) =>
+                        client.POST("/deployments/{deployment_name}/delete", {
+                          params: { path: { deployment_name: target.name } },
+                        }),
+                      ),
+                    ),
+                  ).pipe(
+                    Effect.catch((error) =>
+                      Effect.logWarning(
+                        `Convex.Deployment could not delete ${target.name} after the failed push (${error.message}). The next run takes it over only with --adopt.`,
+                      ),
+                    ),
+                  )
+                : Effect.void,
+            ),
           );
+          // Taken again after the push, so that files the push generates,
+          // such as convex/_generated, are part of the identity.
+          return {
+            ...target,
+            hash: yield* wantedHash(news, target.name),
+            envNames: Object.keys(env).sort(),
+          };
         }),
 
-        // Runs only with RemovalPolicy.destroy(): the default policy is `retain`.
+        // Runs only with RemovalPolicy.destroy(): the default policy is
+        // `retain`. The variables go with the deployment.
         delete: Effect.fn(function* ({ output }) {
           const keep = Effect.logWarning(
             `Convex.Deployment does not delete production deployment ${output.name}: it belongs to project ${output.projectId}. To delete it, delete the project with RemovalPolicy.destroy() on Convex.Project.`,
           );
           if (output.type === "prod") return yield* keep;
+          const access = yield* accessFor(addressInState(output), false);
+          // A deploy key cannot delete its deployment.
+          const management = access.kind === "deployKey" ? api : access.api;
           // The type in state can be old: a dev or preview deployment can
           // become a production deployment in Convex. The live type decides.
-          const live = yield* getByName(output.name);
+          const row = yield* getByName(management, output.name);
           // 404: an earlier attempt, the expiry, or someone else deleted it.
-          if (live === undefined) return;
-          if (live.deploymentType === "prod") return yield* keep;
+          if (row === undefined) return;
+          if (row.deploymentType === "prod") return yield* keep;
           yield* absentAsUndefined(
             retryIdempotentWrite(
-              api.requestVoid("delete deployment", (client) =>
+              management.requestVoid("delete deployment", (client) =>
                 client.POST("/deployments/{deployment_name}/delete", {
                   params: { path: { deployment_name: output.name } },
                 }),