@samebase/alchemy-convex 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,20 @@
 # @samebase/alchemy-convex
 
-Convex resources for [Alchemy v2](https://alchemy.run): projects, deploy keys, environment
-variables, project default environment variables, and a deploy step that hands the deployment URL
-to your frontend build. The Convex CLI keeps doing typecheck, codegen, bundling, and the code push.
-This package manages the control plane around it.
+Convex resources for [Alchemy v2](https://alchemy.run): projects, deployments, deploy keys,
+environment variables, project default environment variables, and the code push. One Alchemy stack
+can own a Convex app end to end: it creates the deployment, pushes the functions, and gives the
+deployment URLs to a Cloudflare Worker or a Vite site as ordinary outputs. The Convex CLI that
+your app installs keeps doing typecheck, codegen, bundling, and the push.
 
 Alchemy has no built-in Convex provider ([alchemy-run/alchemy-async#1306](https://github.com/alchemy-run/alchemy-async/issues/1306)).
 This is a community provider, maintained by [Samebase](https://samebase.com).
 
-Status: 0.2, pinned to `alchemy@2.0.0-beta.80` and Effect 4. Alchemy ships breaking changes
-between betas; upgrade this package and Alchemy together. Verified end to end on a Vite app with a
-Cloudflare Worker: production on `main`, a Convex preview deployment plus a Worker Preview per pull
-request, destroy on close.
+Status: 0.3, pinned to `alchemy@2.0.0-beta.80` and Effect 4. Alchemy ships breaking changes
+between betas; upgrade this package and Alchemy together. The 0.2 deploy step was verified end to
+end on a Vite app with a Cloudflare Worker: production on `main`, a Convex preview deployment plus
+a Worker Preview per pull request, destroy on close. `Convex.Deployment` and `Convex.Code` are
+verified by a live test with the real Convex CLI: a push to a production deployment and to a
+preview deployment, then a delete of the preview.
 
 ## Install
 
@@ -52,46 +55,70 @@ export default Alchemy.Stack(
     state: Cloudflare.state(),
   },
   Effect.gen(function* () {
-    const project = yield* Convex.Project("Project", {
-      team: "my-team",
-      name: "my-app",
-    });
-
-    const deployKey = yield* Convex.DeployKey("DeployKey", {
-      deployment: project.prodDeploymentName.as<string>(),
+    const project = yield* Convex.Project("Project", { team: 38516, name: "score-four" });
+    const prod = yield* Convex.Deployment("Prod", { projectId: project.projectId, type: "prod" });
+    const key = yield* Convex.DeployKey("DeployKey", {
+      deployment: prod.name,
       name: "alchemy",
+      allowedActions: ["deployment:deploy", "deployment:env:view", "deployment:env:write"],
     });
-
-    const backend = yield* Convex.Deploy("Backend", {
+    const backend = yield* Convex.Code("Backend", {
+      deployment: prod,
+      deployKey: key.deployKey,
       cwd: ".",
-      deployKey: deployKey.deployKey,
     });
 
-    const site = yield* Cloudflare.Website.StaticSite("Website", {
-      command: "npm run build",
-      outdir: "dist/client",
-      env: { VITE_CONVEX_URL: backend.url },
-      assets: { notFoundHandling: "single-page-application" },
+    // backend.url and backend.siteUrl feed a Cloudflare Worker or a Vite site.
+    const site = yield* Cloudflare.Website.Vite("Site", {
+      env: { VITE_CONVEX_URL: backend.url, VITE_CONVEX_SITE_URL: backend.siteUrl },
     });
 
-    yield* Convex.EnvironmentVariable("SiteUrl", {
-      deployment: backend.deploymentName,
-      deployKey: deployKey.deployKey,
-      name: "SITE_URL",
-      value: site.url,
-    });
-
-    return { url: site.url, backendUrl: backend.url };
+    return { url: site.url, convexUrl: backend.url };
   }),
 );
 ```
 
-Order follows the outputs: the project exists before its key, the key before the deploy, the
-deploy before the frontend build that embeds the URL.
+Order follows the outputs: the project exists before its deployment, the deployment before its key,
+the key before the push, and the push before the site build. On a Vite Worker, a `VITE_` key in
+`env` goes into the client bundle as `import.meta.env.VITE_*` and is also a Worker variable.
+`Cloudflare.Worker` takes the same `env`.
+
+### Preview stages
 
-Preview stages: give `Convex.Deploy` a `PreviewDeployKey` and `previewName: <branch>` on pull
-request stages, and the production key on `prod`. Variables that every preview deployment needs,
-such as auth keys, go on the project as `DefaultEnvironmentVariable` for `preview`.
+On a pull request stage, push to a preview deployment of the same project. Name the preview after
+the stage, and use a preview deploy key of the project:
+
+```ts
+const stack = yield * Alchemy.Stack; // stack.stage, such as "pr-42"
+// The project that the stage "prod" owns. A preview stage reads it and does not own it.
+const project = yield * Convex.Project.ref("Project", { stage: "prod" });
+const preview =
+  yield *
+  Convex.Deployment("Preview", {
+    projectId: project.projectId,
+    type: "preview",
+    name: stack.stage,
+  }).pipe(Alchemy.RemovalPolicy.destroy());
+const previewKey =
+  yield *
+  Convex.PreviewDeployKey("PreviewDeployKey", {
+    projectId: project.projectId,
+    name: "alchemy",
+  });
+const backend =
+  yield *
+  Convex.Code("Backend", {
+    deployment: preview,
+    deployKey: previewKey.previewDeployKey,
+    cwd: ".",
+  });
+```
+
+`alchemy destroy --stage pr-42` then deletes the preview deployment. Without
+`RemovalPolicy.destroy()`, the preview deployment stays until Convex deletes it at expiry (14 days
+by default). [`examples/app/alchemy.run.ts`](examples/app/alchemy.run.ts) has both stages in one
+stack. Variables that every preview deployment needs, such as auth keys, go on the project as
+`DefaultEnvironmentVariable` for `preview`.
 
 ## Data safety
 
@@ -124,8 +151,23 @@ replace, or overwrite your data by accident:
   with a new prefix. The key resources then stop with `DeployKeyIsCredential` and do not keep that
   value, because a delete would revoke the OAuth token. Use a team access token or the Convex CLI
   login.
+- `Convex.Deployment` has the removal policy `retain` for every type. It never deletes a
+  production deployment, also not with `RemovalPolicy.destroy()` and also not a dev deployment that
+  became a production deployment: delete the project for that. A
+  dev or preview deployment is deleted only with `RemovalPolicy.destroy()`.
+- `Convex.Deployment` takes over the project's production deployment without `--adopt`: Convex
+  creates it with the project, and the resource never changes or deletes it. A dev or preview
+  deployment that exists but is not in state belongs to someone else, such as a preview that CI
+  made with `npx convex deploy --preview-name`. The resource takes it over only with `--adopt`.
+  It never creates over it: a Convex create for an existing preview name deletes that preview.
+- A deployment keeps its `projectId`, `type`, and `name`. A change stops the deploy with
+  `DeploymentIdentityChange`. The resource is never replaced.
+- `Convex.Code` checks before the push that the deploy key fits the deployment, and after the push
+  that the CLI pushed to that deployment. A production deploy key on a preview stage stops the deploy
+  before the push.
 - An `EnvironmentVariable` or a `DefaultEnvironmentVariable` that exists but is not in state
-  belongs to someone else. The provider overwrites it only with `--adopt`.
+  belongs to someone else. The provider overwrites it only with `--adopt`. The same is true for a
+  `Convex.Code` `env` variable that exists with another value.
 - A variable keeps its name and deployment (a default keeps its project, name, and deployment
   type). A change stops the deploy with `VariableIdentityChange`. To rename or move a variable,
   create a new resource with a new logical id and remove the old one. A rename in place would
@@ -133,6 +175,11 @@ replace, or overwrite your data by accident:
 - A variable write runs again after a Convex write conflict or a 5xx answer, at most four more
   times. The write sets a value, so a second write has the same result.
 
+Upgrade from 0.2: `Convex.Deploy` keeps working. To move to `Convex.Code`, add a
+`Convex.Deployment` and a `Convex.Code` with a new logical id and remove the `Convex.Deploy`.
+Removing `Convex.Deploy` changes nothing in Convex. For a preview stage, use `previewName`, not
+`previewCreate`, while you still use `Convex.Deploy`.
+
 Upgrade from 0.1: state from 0.1 records the policy `destroy` for each project. Run
 `alchemy deploy` one time with 0.2 while the stack still declares the project. That deploy records
 `retain`. Do this before you remove a project from the stack or run `alchemy destroy`.
@@ -148,9 +195,53 @@ the Convex dashboard.
   changed `team`, `deploymentRegion`, or `deploymentType` stops the deploy. An existing project
   with the same name is adopted only with `--adopt`. The removal policy is `retain`: only a
   resource with `RemovalPolicy.destroy()` deletes the project with its deployments and data.
+- `Convex.Deployment`: `{ projectId, type: "prod" }` or
+  `{ projectId, type: "dev" | "preview", name }`. Outputs `name` (such as `happy-animal-123`),
+  `url` (`https://<name>.convex.cloud`, with the region outside US East), `siteUrl` (the same
+  host on `.convex.site`), `type`, `projectId`, `reference`, and `previewName`.
+  - `prod` takes over the project's default production deployment, and follows it when another
+    production deployment becomes the default. It never creates one: a project without one stops
+    the deploy with `ProductionDeploymentNotFound`.
+  - `dev` creates a dev deployment with `name` as its reference, through
+    `POST /projects/{project_id}/create_deployment`. Convex records the member of the access token
+    as its creator. It is not that member's default dev deployment, so `npx convex dev` does not
+    select it.
+  - `preview` creates a preview deployment with `name` as its preview name, through the same
+    call. `npx convex deploy --preview-name <name>` with a preview deploy key finds it.
+  - When the deployment in state is gone, such as an expired preview, the next deploy creates it
+    again. Two deployments with the name stop the deploy with `AmbiguousDeployment`.
+- `Convex.Code`: `{ deployment, deployKey, cwd, command?, env?, typecheck?, codegen? }`. Pushes
+  the functions of the Convex app in `cwd` with `convex deploy`. Outputs `deploymentName`,
+  `url`, `siteUrl`, `deployedAt` (milliseconds since the Unix epoch), and `envNames`.
+  - `deployment` is a `Convex.Deployment` resource or a deployment name. `deployKey` is a
+    deploy key of that deployment, or, for a preview deployment, a preview deploy key of the
+    project: Code then runs `convex deploy --preview-name <name>`. Any other key stops the deploy
+    with `DeployKeyMismatch` before the push.
+  - Code pushes on every deploy. It does not hash the sources: a preview can expire, a push from
+    outside Alchemy can change the deployment, and a hash misses workspace packages. The CLI
+    uploads only the modules that changed.
+  - Code runs the `convex` package that `cwd` resolves, with the Node.js that runs Alchemy, and
+    never downloads one (`ConvexCliNotFound`). `command`, such as `["pnpm", "exec", "convex"]`,
+    replaces it.
+  - The key goes to the CLI only in an env file with mode 0600 (`--env-file`), in a temporary
+    directory that is removed after the run, also after a failure or an interruption. That
+    directory is the home directory of the CLI, so the CLI cannot use the Convex login of the
+    machine. Variables named `CONVEX_*` are not passed on.
+  - The CLI output stays out of the logs. A failure (`CodePushFailed`) shows the last 20 lines
+    with the key removed. A push to another deployment stops the deploy with
+    `PushTargetMismatch`.
+  - `env` sets variables on the deployment before the push, with the deploy key. A name that
+    leaves `env` is removed from the deployment. A preview deploy key cannot set variables
+    (`EnvironmentNeedsDeployKey`).
+  - `typecheck` (`enable`, `try`, `disable`) and `codegen` (`enable`, `disable`) go to
+    `convex deploy` as flags.
+  - Deleting the resource does nothing. The functions and the `env` variables stay: the deployment
+    runs them.
 - `Convex.DeployKey`: `{ deployment, name, allowedActions? }`. Outputs `uniqueName`, `keyId`, and
   the `deployKey` secret. Any change replaces the key. Delete revokes the key by its secret; a key
-  from 0.1 state stays. Keys are never adopted: a key without its secret is useless.
+  from 0.1 state stays. Keys are never adopted: a key without its secret is useless. The live test
+  pushes with `Convex.Code` and sets `env` with a key that has only `deployment:deploy`,
+  `deployment:env:view`, and `deployment:env:write`.
 - `Convex.PreviewDeployKey`: `{ projectId, name }`. Project-level key for preview deployments.
   Outputs `uniqueName`, `keyId`, and `previewDeployKey`.
 - `Convex.EnvironmentVariable`: `{ deployment, deployKey, name, value }`. One variable on one
@@ -164,12 +255,28 @@ the Convex dashboard.
   existing default with the same name and type is adopted and overwritten only with `--adopt`. A
   new `value` is an update in place. A new `projectId`, `name`, or `deploymentType` stops the
   deploy with `VariableIdentityChange`: use a new logical id.
-- `Convex.Deploy`: `{ cwd?, env?, deployKey, previewName?, previewCreate?, previewRun?, extraArgs?,
-memo?, timeout? }`. Runs `npx convex deploy` with `CONVEX_DEPLOY_KEY` set and parses the
-  deployment URL from the CLI output. Outputs `url`, `deploymentName`, `hash`. Memoized by content
-  hash like Alchemy's own build steps, except with `previewName` or `previewCreate`: a preview
-  deployment can expire, so a preview deploy always pushes. Deleting the resource does nothing;
-  the deployment belongs to the project, and preview deployments expire on Convex's schedule.
+- `Convex.Deploy` (deprecated since 0.3, use `Convex.Code`): `{ cwd?, env?, deployKey,
+previewName?, previewCreate?, previewRun?, extraArgs?, memo?, timeout? }`. Runs
+  `npx convex deploy` with `CONVEX_DEPLOY_KEY` set and parses the deployment URL from the CLI
+  output. Outputs `url`, `deploymentName`, `hash`. It stays so that stacks and state from 0.1
+  and 0.2 keep working. Deleting the resource does nothing.
+
+### Which Convex call each operation uses
+
+| Operation                                | Path                                                                                |
+| ---------------------------------------- | ----------------------------------------------------------------------------------- |
+| Find the production deployment           | `GET /projects/{project_id}/list_deployments?deploymentType=prod&isDefault=true`    |
+| Find a dev or preview deployment by name | `GET /projects/{project_id}/list_deployments?deploymentType=<type>`                 |
+| Create a dev or preview deployment       | `POST /projects/{project_id}/create_deployment` with `type` and `reference`         |
+| Check that a deployment exists           | `GET /deployments/{deployment_name}`                                                |
+| Delete a dev or preview deployment       | `POST /deployments/{deployment_name}/delete`                                        |
+| Push to a deployment                     | `convex deploy --env-file <file>` with a deploy key of the deployment               |
+| Push to a preview deployment             | `convex deploy --preview-name <name> --env-file <file>` with a preview deploy key   |
+| Set `env` variables                      | `POST https://<deployment>/api/v1/update_environment_variables` with the deploy key |
+
+Code uses `--preview-name`, not `--preview-create`: `--preview-create` deletes and creates the
+preview deployment again on every push, so every deploy would lose the preview data and change its
+URL.
 
 ## Limits
 
@@ -181,8 +288,20 @@ memo?, timeout? }`. Runs `npx convex deploy` with `CONVEX_DEPLOY_KEY` set and pa
 - A run that stops between a key create and the state write leaves a key that state does not
   know. The next run stops with `DeployKeyRecoveryRequired`. Delete the listed key in the Convex
   dashboard, then run the deploy again.
-- Not covered: dev deployments, custom domains, log streams, teams and members, components,
-  snapshots.
+- A run that stops between a deployment create and the state write leaves a dev or preview
+  deployment that state does not know. The next run stops with `OwnedBySomeoneElse`. Run it with
+  `--adopt` to take that deployment over.
+- Between the lookup and the create of a preview deployment, another writer can create a preview
+  with the same name. The Convex create then replaces it. The Management API has no create that
+  fails for an existing preview name.
+- `siteUrl` is the `.convex.site` URL. A custom domain is not used.
+- When another production deployment becomes the default, a `DeployKey` with `deployment: prod.name`
+  gets a new key on the new deployment. Alchemy plans this as an update, not a replacement, so the
+  key on the old deployment stays. Delete it in the Convex dashboard.
+- Variables that `Convex.Code` set on a deployment stay there when `deployment` changes to
+  another deployment, and when the resource is removed.
+- Not covered: deployment regions and classes, custom domains, log streams, teams and members,
+  components, snapshots.
 
 ## Development
 
@@ -207,6 +326,10 @@ A file argument runs one live file only, for example
 through the Alchemy engine. It creates a project `tmp-alchemy-convex-<8 hex>` in
 `ALCHEMY_CONVEX_LIVE_TEAM` and deletes it at the end, also after a failure. It refuses to delete a
 project whose name does not start with `tmp-alchemy-convex-`.
+`test/live/deployment-code.live.test.ts` does the same for `Convex.Deployment` and
+`Convex.Code`: it pushes the app in `test/fixtures/convex-app` with the real Convex CLI to the
+production deployment and to a preview deployment, and it also refuses to delete a deployment of
+another project.
 
 Releases: change `version` in `package.json` in a pull request. After the merge,
 `.github/workflows/release.yml` publishes that version from `main` with npm trusted publishing.

package/lib/index.d.ts

@@ -1,11 +1,12 @@
-import * as Context from "effect/Context";
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
+import "effect/process/ChildProcessSpawner";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
-import { Resource } from "alchemy";
-import * as Provider from "alchemy/Provider";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
 import { CommandExecutor, CommandRunProps } from "alchemy/Command";
 import { MemoOptions } from "alchemy/Command/Memo";
 import { components } from "@convex-dev/platform/managementApi";
@@ -85,6 +86,162 @@ declare class Providers extends Providers_base {}
  */
 declare const providers: (credentials?: Layer.Layer<Credentials>) => Layer.Layer<Providers, never, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
 //#endregion
+//#region src/Deployment.d.ts
+type DeploymentProps = {
+  /** Numeric project id, such as `project.projectId`. Cannot change. */
+  readonly projectId: number;
+  /** The project's default production deployment. Cannot change. */
+  readonly type: "prod";
+} | {
+  /** Numeric project id, such as `project.projectId`. Cannot change. */
+  readonly projectId: number;
+  /** 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.
+   */
+  readonly name: string;
+};
+interface DeploymentAttributes {
+  readonly projectId: number;
+  readonly type: DeploymentProps["type"];
+  /** Deployment name, such as `happy-animal-123`. */
+  readonly name: string;
+  /** The reference that Convex lists, such as `production`, `staging`, or `preview/pr-42`. */
+  readonly reference: string;
+  /** The preview name of a preview deployment. Undefined for prod and dev. */
+  readonly previewName: string | undefined;
+  /** Client URL, such as `https://happy-animal-123.convex.cloud`. */
+  readonly url: string;
+  /** HTTP actions URL, such as `https://happy-animal-123.convex.site`. */
+  readonly siteUrl: string;
+}
+type Deployment = Resource<"Convex.Deployment", DeploymentProps, DeploymentAttributes, never, Providers>;
+declare const Deployment: import("alchemy").ResourceClass<Deployment>;
+declare const DeploymentIdentityChange_base: Schema.Class<DeploymentIdentityChange, Schema.TaggedStruct<"DeploymentIdentityChange", {
+  /** Name of the deployment in state, such as `happy-animal-123`. */
+  readonly deployment: Schema.String;
+  readonly field: Schema.Literals<readonly ["projectId", "type", "name"]>;
+  readonly current: Schema.String;
+  readonly requested: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The props name another deployment than the one in state. */
+declare class DeploymentIdentityChange extends DeploymentIdentityChange_base {
+  get message(): string;
+}
+declare const ProductionDeploymentNotFound_base: Schema.Class<ProductionDeploymentNotFound, Schema.TaggedStruct<"ProductionDeploymentNotFound", {
+  readonly projectId: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/** The project has no default production deployment for a `prod` resource to take over. */
+declare class ProductionDeploymentNotFound extends ProductionDeploymentNotFound_base {
+  get message(): string;
+}
+declare const AmbiguousDeployment_base: Schema.Class<AmbiguousDeployment, Schema.TaggedStruct<"AmbiguousDeployment", {
+  readonly projectId: Schema.Number;
+  readonly type: Schema.Literals<readonly ["dev", "preview"]>;
+  readonly name: Schema.String;
+  readonly deployments: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** More than one deployment of the project has the name, so the lookup cannot choose one. */
+declare class AmbiguousDeployment extends AmbiguousDeployment_base {
+  get message(): string;
+}
+//#endregion
+//#region src/Code.d.ts
+/** The attributes of a Convex.Deployment that a push needs. Pass the resource itself. */
+type CodeDeployment = Pick<DeploymentAttributes, "name" | "type" | "url" | "previewName">;
+interface CodeProps {
+  /**
+   * The deployment that receives the push: a Convex.Deployment resource, or a
+   * deployment name such as `happy-animal-123`. A preview deploy key needs the
+   * resource. For `env` on a deployment outside US East, pass the resource.
+   */
+  readonly deployment: string | CodeDeployment;
+  /**
+   * A deploy key of `deployment` (Convex.DeployKey), or, for a preview
+   * deployment, a preview deploy key of its project (Convex.PreviewDeployKey).
+   */
+  readonly deployKey: Redacted.Redacted<string>;
+  /** The Convex app directory: the one with `convex/` and the `convex` package installed. */
+  readonly cwd: string;
+  /**
+   * The program and first arguments that run the Convex CLI, such as
+   * `["pnpm", "exec", "convex"]`. Code adds `deploy` and its flags. By
+   * default, the `convex` package that `cwd` resolves, run with this Node.js.
+   */
+  readonly command?: readonly [string, ...string[]];
+  /** Environment variables to set on the deployment before the push. Needs a deploy key of the deployment. */
+  readonly env?: Readonly<Record<string, string | Redacted.Redacted<string>>>;
+  /** `convex deploy --typecheck`. The CLI default is `try`. */
+  readonly typecheck?: "enable" | "try" | "disable";
+  /** `convex deploy --codegen`. The CLI default is `enable`. */
+  readonly codegen?: "enable" | "disable";
+}
+interface CodeAttributes {
+  /** The deployment that received the push, such as `happy-animal-123`. */
+  readonly deploymentName: string;
+  /** Client URL, such as `https://happy-animal-123.convex.cloud`. */
+  readonly url: string;
+  /** HTTP actions URL, such as `https://happy-animal-123.convex.site`. */
+  readonly siteUrl: string;
+  /** When the push finished, in milliseconds since the Unix epoch. */
+  readonly deployedAt: number;
+  /** The names of the `env` variables that this resource set on the deployment, sorted. */
+  readonly envNames: readonly string[];
+}
+type Code = Resource<"Convex.Code", CodeProps, CodeAttributes, never, Providers>;
+declare const Code: import("alchemy").ResourceClass<Code>;
+/** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
+declare const parseDeployOutput: (text: string) => {
+  url: string;
+  deploymentName: string;
+} | undefined;
+declare const DeployKeyMismatch_base: Schema.Class<DeployKeyMismatch, Schema.TaggedStruct<"DeployKeyMismatch", {
+  /** The deployment that should receive the push. */
+  readonly deployment: Schema.String;
+  /** What the key targets. */
+  readonly key: Schema.Literals<readonly ["deployment", "preview", "project", "unknown"]>;
+  /** For a deployment key: the deployment in the key prefix. Never the secret. */
+  readonly keyDeployment: Schema.UndefinedOr<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** The deploy key does not fit the deployment. Checked before the push. */
+declare class DeployKeyMismatch extends DeployKeyMismatch_base {
+  get message(): string;
+}
+declare const EnvironmentNeedsDeployKey_base: Schema.Class<EnvironmentNeedsDeployKey, Schema.TaggedStruct<"EnvironmentNeedsDeployKey", {
+  readonly deployment: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** `env` needs the deployment API, which takes only a deploy key of the deployment. */
+declare class EnvironmentNeedsDeployKey extends EnvironmentNeedsDeployKey_base {
+  get message(): string;
+}
+declare const ConvexCliNotFound_base: Schema.Class<ConvexCliNotFound, Schema.TaggedStruct<"ConvexCliNotFound", {
+  readonly cwd: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** No `convex` package resolves from `cwd`. */
+declare class ConvexCliNotFound extends ConvexCliNotFound_base {
+  get message(): string;
+}
+declare const CodePushFailed_base: Schema.Class<CodePushFailed, Schema.TaggedStruct<"CodePushFailed", {
+  /** Exit code of the CLI. Undefined when it did not start or a signal stopped it. */
+  readonly exitCode: Schema.UndefinedOr<Schema.Number>;
+  /** The last lines of the CLI output, with the deploy key removed. */
+  readonly outputTail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The Convex CLI failed, or exited 0 without the deployment URL. The output tail never contains the key. */
+declare class CodePushFailed extends CodePushFailed_base {
+  get message(): string;
+}
+declare const PushTargetMismatch_base: Schema.Class<PushTargetMismatch, Schema.TaggedStruct<"PushTargetMismatch", {
+  readonly expected: Schema.String;
+  readonly actual: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The CLI pushed to another deployment than the one in the props. Checked after the push. */
+declare class PushTargetMismatch extends PushTargetMismatch_base {
+  get message(): string;
+}
+//#endregion
 //#region src/DefaultEnvironmentVariable.d.ts
 /** Deployment types a default can target, from the generated schema. */
 type DeploymentType = components["schemas"]["DeploymentType"];
@@ -153,12 +310,13 @@ interface DeployAttributes {
   readonly hash: string | undefined;
 }
 type Deploy = Resource<"Convex.Deploy", DeployProps, DeployAttributes, never, Providers>;
+/**
+ * @deprecated Since 0.3.0. Use Convex.Code with a Convex.Deployment: it
+ * runs the installed Convex CLI, keeps the deploy key out of the process
+ * environment, checks that the key fits the deployment, and outputs the site
+ * URL. Removing a Deploy resource changes nothing in Convex.
+ */
 declare const Deploy: import("alchemy").ResourceClass<Deploy>;
-/** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
-declare const parseDeployOutput: (text: string) => {
-  url: string;
-  deploymentName: string;
-} | undefined;
 /** The `convex deploy` argv, starting with `npx`. */
 declare const deployArgs: (props: Pick<DeployProps, "previewName" | "previewCreate" | "previewRun" | "extraArgs">) => readonly string[];
 declare const DeployArgumentError_base: Schema.Class<DeployArgumentError, Schema.TaggedStruct<"DeployArgumentError", {
@@ -349,5 +507,5 @@ declare class CreatedProjectNotFound extends CreatedProjectNotFound_base {
   get message(): string;
 }
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousProject, ConvexApiError, CreatedProjectNotFound, Credentials, CredentialsError, DefaultEnvironmentVariable, type DefaultEnvironmentVariableAttributes, type DefaultEnvironmentVariableProps, Deploy, DeployArgumentError, type DeployAttributes, DeployKey, type DeployKeyAction, type DeployKeyAttributes, DeployKeyIsCredential, type DeployKeyProps, DeployKeyRecoveryRequired, DeployOutputError, type DeployProps, type DeploymentRegion, type DeploymentType, EnvironmentVariable, type EnvironmentVariableAttributes, type EnvironmentVariableProps, ManagementApi, PreviewDeployKey, type PreviewDeployKeyAttributes, type PreviewDeployKeyProps, Project, type ProjectAttributes, ProjectDeploymentChange, type ProjectProps, ProjectTeamChange, Providers, VariableIdentityChange, deployArgs, fromConfig, fromToken, parseDeployOutput, providers };
+export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, Code, type CodeAttributes, type CodeDeployment, type CodeProps, CodePushFailed, ConvexApiError, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DefaultEnvironmentVariable, type DefaultEnvironmentVariableAttributes, type DefaultEnvironmentVariableProps, Deploy, DeployArgumentError, type DeployAttributes, DeployKey, type DeployKeyAction, type DeployKeyAttributes, DeployKeyIsCredential, DeployKeyMismatch, type DeployKeyProps, DeployKeyRecoveryRequired, DeployOutputError, type DeployProps, Deployment, type DeploymentAttributes, DeploymentIdentityChange, type DeploymentProps, type DeploymentRegion, type DeploymentType, EnvironmentNeedsDeployKey, EnvironmentVariable, type EnvironmentVariableAttributes, type EnvironmentVariableProps, ManagementApi, PreviewDeployKey, type PreviewDeployKeyAttributes, type PreviewDeployKeyProps, ProductionDeploymentNotFound, Project, type ProjectAttributes, ProjectDeploymentChange, type ProjectProps, ProjectTeamChange, Providers, PushTargetMismatch, VariableIdentityChange, deployArgs, fromConfig, fromToken, parseDeployOutput, providers };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/DefaultEnvironmentVariable.ts","../src/Deploy.ts","../src/DeployKey.ts","../src/EnvironmentVariable.ts","../src/PreviewDeployKey.ts","../src/Project.ts"],"mappings":";;;;;;;;;;;;UAgBiB;;WAEN,aAAa,SAAS;;WAEtB;;;cAGE,oBAAoB;;cAKpB;;;;cAyBA,yBAAyB;;;;;;;cAUzB,kBAAiB,MAAM,MAAM;;cAa7B,YAAa,aAAa,SAAS,qBAAmB,MAAM,MAAM;;;KC7DnE,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;cAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;cAM5C,sBAAsB;;;;cCrEtB,kBAAkB;;;;;cAMlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,+DAAA,kDAAA,mCAAA;;;;KCalE,iBAAiB;UAgGZ;;WAEN;WACA;WACA,gBAAgB,SAAS;;WAEzB,gBAAgB;;UAGV;WACN;WACA;WACA,gBAAgB;;KAGf,6BAA6B,8CAEvC,iCACA,6CAEA;cAEW,8CAA0B,cAAA;;;UCzItB,oBAAoB,KAAK;;;;;;WAM/B,WAAW,SAAS;;;;;WAKpB;;;;;WAKA;;;;;WAKA;;;;;;WAMA;;;;;;;;;;WAUA,OAAO;;UAGD;;WAEN;;WAEA;;WAEA;;KAGC,SAAS,0BAA0B,aAAa,yBAAyB;cACxE,0BAAM,cAAA;;cAYN,oBACX;EACG;EAAa;;;cAQL,aACX,OAAO,KAAK;;;;;cAeD,4BAA4B;MAI1B;;;;;;cAMF,0BAA0B;MAIxB;;;;;KC/EH,kBAAkB,YAC5B;;;;;;;;;;;;;;;;;;cA6DW,kCAAkC;MAahC;;;;;;;;;;;cAgBF,8BAA8B;MAI5B;;UAwEE;;WAEN;;;;;WAKA;;WAEA,0BAA0B;;UAGpB;;WAEN;;WAEA;WACA;;WAEA,WAAW,SAAS;;KAGnB,YAAY,6BAEtB,gBACA,4BAEA;cAEW,6BAAS,cAAA;;;UC/HL;;WAEN;;WAEA,WAAW,SAAS;WACpB;WACA,gBAAgB,SAAS;;UAGnB;WACN;WACA;;WAEA,WAAW,SAAS;;KAGnB,sBAAsB,uCAEhC,0BACA,sCAEA;cAEW,uCAAmB,cAAA;;;;;;;;;;;cAMnB,+BAA+B;MAS7B;;;;UCpHE;;WAEN;;;;;WAKA;;UAGM;;WAEN;;WAEA;WACA;;WAEA,kBAAkB,SAAS;;KAG1B,mBAAmB,oCAE7B,uBACA,mCAEA;cAEW,oCAAgB,cAAA;;;;KChCjB,mBAAmB;UAEd;;WAEN;;WAEA;;WAEA,mBAAmB;;WAEnB;;UAGM;WACN;WACA;WACA;WACA;WACA;WACA;;KAGC,UAAU,2BAA2B,cAAc,0BAA0B;cAC5E,2BAAO,cAAA;;;;;;;cAGP,0BAA0B;MAIxB;;;;;;;;;;;;cASF,gCAAgC;MAS9B;;;;;;;;cAOF,yBAAyB;MAKvB;;;;;;cAMF,+BAA+B;MAI7B"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Deployment.ts","../src/Code.ts","../src/DefaultEnvironmentVariable.ts","../src/Deploy.ts","../src/DeployKey.ts","../src/EnvironmentVariable.ts","../src/PreviewDeployKey.ts","../src/Project.ts"],"mappings":";;;;;;;;;;;;;UAgBiB;;WAEN,aAAa,SAAS;;WAEtB;;;cAGE,oBAAoB;;cAKpB;;;;cAyBA,yBAAyB;;;;;;;cAUzB,kBAAiB,MAAM,MAAM;;cAa7B,YAAa,aAAa,SAAS,qBAAmB,MAAM,MAAM;;;KC7DnE,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;cAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;cAM5C,sBAAsB;;;;cCnEtB,kBAAkB;;;;;cAMlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,+DAAA,kDAAA,mCAAA;;;KCgBlE;;WAGG;;WAEA;;;WAIA;;WAEA;;;;;WAKA;;UAGE;WACN;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;KAGC,aAAa,8BAEvB,iBACA,6BAEA;cAEW,8BAAU,cAAA;;;;;;;;;cAKV,iCAAiC;MAU/B;;;;;;cAMF,qCAAqC;MAInC;;;;;;;;;cAMF,4BAA4B;MAS1B;;;;;KCpEH,iBAAiB,KAAK;UAEjB;;;;;;WAMN,qBAAqB;;;;;WAKrB,WAAW,SAAS;;WAEpB;;;;;;WAMA;;WAEA,MAAM,SAAS,wBAAwB,SAAS;;WAEhD;;WAEA;;UAGM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;KAGC,OAAO,wBAAwB,WAAW,uBAAuB;cAChE,wBAAI,cAAA;;cAYJ,oBACX;EACG;EAAa;;;;;;;;;;;cAgCL,0BAA0B;MAWxB;;;;;;cAeF,kCAAkC;MAIhC;;;;;;cAMF,0BAA0B;MAIxB;;;;;;;;;cAMF,uBAAuB;MAMrB;;;;;;;cAQF,2BAA2B;MAIzB;;;;;KC5KH,iBAAiB;UAgGZ;;WAEN;WACA;WACA,gBAAgB,SAAS;;WAEzB,gBAAgB;;UAGV;WACN;WACA;WACA,gBAAgB;;KAGf,6BAA6B,8CAEvC,iCACA,6CAEA;cAEW,8CAA0B,cAAA;;;UCtItB,oBAAoB,KAAK;;;;;;WAM/B,WAAW,SAAS;;;;;WAKpB;;;;;WAKA;;;;;WAKA;;;;;;WAMA;;;;;;;;;;WAUA,OAAO;;UAGD;;WAEN;;WAEA;;WAEA;;KAGC,SAAS,0BAA0B,aAAa,yBAAyB;;;;;;;cAOxE,0BAAM,cAAA;;cAGN,aACX,OAAO,KAAK;;;;;cAeD,4BAA4B;MAI1B;;;;;;cAMF,0BAA0B;MAIxB;;;;;KCrEH,kBAAkB,YAC5B;;;;;;;;;;;;;;;;;;cA6DW,kCAAkC;MAahC;;;;;;;;;;;cAgBF,8BAA8B;MAI5B;;UAwEE;;WAEN;;;;;WAKA;;WAEA,0BAA0B;;UAGpB;;WAEN;;WAEA;WACA;;WAEA,WAAW,SAAS;;KAGnB,YAAY,6BAEtB,gBACA,4BAEA;cAEW,6BAAS,cAAA;;;UCpGL;;WAEN;;WAEA,WAAW,SAAS;WACpB;WACA,gBAAgB,SAAS;;UAGnB;WACN;WACA;;WAEA,WAAW,SAAS;;KAGnB,sBAAsB,uCAEhC,0BACA,sCAEA;cAEW,uCAAmB,cAAA;;;;;;;;;;;cAMnB,+BAA+B;MAS7B;;;;UC/IE;;WAEN;;;;;WAKA;;UAGM;;WAEN;;WAEA;WACA;;WAEA,kBAAkB,SAAS;;KAG1B,mBAAmB,oCAE7B,uBACA,mCAEA;cAEW,oCAAgB,cAAA;;;;KChCjB,mBAAmB;UAEd;;WAEN;;WAEA;;WAEA,mBAAmB;;WAEnB;;UAGM;WACN;WACA;WACA;WACA;WACA;WACA;;KAGC,UAAU,2BAA2B,cAAc,0BAA0B;cAC5E,2BAAO,cAAA;;;;;;;cAGP,0BAA0B;MAIxB;;;;;;;;;;;;cASF,gCAAgC;MAS9B;;;;;;;;cAOF,yBAAyB;MAKvB;;;;;;cAMF,+BAA+B;MAI7B"}