@samebase/alchemy-convex 0.2.0 → 0.4.0

package/NOTICE

@@ -0,0 +1,24 @@
+@samebase/alchemy-convex
+Copyright 2026 Samebase
+
+This product follows patterns from Confect (https://github.com/rjdellecese/confect),
+packages/alchemy, under the ISC license:
+
+- the adoption check order in src/Adoption.ts (internal/Lifecycle.ts),
+- the Convex CLI runner in src/Push.ts (internal/CommandRunner.ts),
+- the deployment lookup rules in src/Deployment.ts and the project listing in src/Project.ts.
+
+ISC License
+
+Copyright 2024 RJ Dellecese
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without
+fee is hereby granted, provided that the above copyright notice and this permission notice appear
+in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

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.
+The Convex plane for [Alchemy v2](https://alchemy.run): projects, deployments, their environment
+variables, and the push of the functions. One Alchemy stack owns a Convex app end to end. The
+deployment resource pushes your `convex/` folder when its content changes and gives the deployment
+URLs to a Cloudflare Worker or a Vite site as ordinary outputs. No deploy key goes from one resource
+to another. 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).
+This is a community provider, maintained by [Samebase](https://samebase.com). The resource model
+follows the "Convex Plain" mode of [rjdellecese/confect#408](https://github.com/rjdellecese/confect/issues/408).
+[docs/design/convex-plane.md](docs/design/convex-plane.md) records the decisions.
 
-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: pinned to `alchemy@2.0.0-beta.80` and Effect 4. Alchemy ships breaking changes between
+betas; upgrade this package and Alchemy together. A live test runs the full sequence with the real
+Convex CLI: create, push, no-op, change, preview, deploy keys alone, and destroy.
 
 ## Install
 
@@ -19,32 +22,9 @@ request, destroy on close.
 pnpm add -D @samebase/alchemy-convex alchemy@2.0.0-beta.80 effect@^4.0.0 @effect/platform-node@^4.0.0 convex
 ```
 
-## Credentials
-
-The provider calls the [Convex Management API](https://docs.convex.dev/management-api) with a
-bearer token. By default it reads `CONVEX_ACCESS_TOKEN` through the stack's config provider
-(process env, `.env`, stack secrets) and then falls back to the token the Convex CLI saved after
-`npx convex login` (`~/.convex/config.json`). A developer who is logged in needs no setup. CI sets
-the variable to a team access token.
-
-To pass a token explicitly:
-
-```ts
-Convex.providers(Convex.fromToken(Redacted.make(token)));
-```
-
-A team access token is team wide. The deploy keys this provider creates are scoped to one
-deployment or one project, and those are what CI deploys with.
-
 ## Example
 
 ```ts
-import * as Alchemy from "alchemy";
-import * as Cloudflare from "alchemy/Cloudflare";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import * as Convex from "@samebase/alchemy-convex";
-
 export default Alchemy.Stack(
   "MyApp",
   {
@@ -52,137 +32,134 @@ 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>(),
-      name: "alchemy",
-    });
-
-    const backend = yield* Convex.Deploy("Backend", {
-      cwd: ".",
-      deployKey: deployKey.deployKey,
+    const { stage } = yield* Alchemy.Stack;
+    const backend =
+      stage === "prod"
+        ? yield* Convex.Deployment("Backend", {
+            // An existing project. A new one: { team: "my-team", name: "my-app" }.
+            project: yield* Convex.Project("Project", { team: "my-team", slug: "my-app" }),
+            type: "prod",
+            source: "./convex",
+            env: { AUTH_SECRET: Config.Redacted("AUTH_SECRET") },
+          })
+        : yield* Convex.Deployment("Backend", {
+            // The project that the stage "prod" owns, read from its state.
+            project: yield* Convex.Project.ref("Project", { stage: "prod" }),
+            type: "preview",
+            name: stage, // such as "pr-42"
+            source: "./convex",
+          }).pipe(RemovalPolicy.destroy());
+    const site = yield* Cloudflare.Website.Vite("Site", {
+      env: { VITE_CONVEX_URL: backend.url, VITE_CONVEX_SITE_URL: backend.siteUrl },
     });
-
-    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" },
-    });
-
-    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.
+The imports are `alchemy`, `alchemy/Cloudflare`, `alchemy/RemovalPolicy`, `effect/Config`,
+`effect/Effect`, `effect/Layer`, and `@samebase/alchemy-convex` as `Convex`. Order follows the
+outputs: the project exists before its deployment, and the push finishes before the site build. The
+first `alchemy deploy --stage prod` takes over the existing project, and its production
+deployment if it has code, only with `--adopt`.
+`alchemy destroy --stage pr-42` deletes the preview deployment. Without `RemovalPolicy.destroy()`,
+it stays until Convex deletes it at expiry (14 days by default).
+[`examples/app/alchemy.run.ts`](examples/app/alchemy.run.ts) is the same stack.
 
-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`.
+## Credentials
 
-## Data safety
+Credentials are a layer, never props, so they do not go into Alchemy state. `Convex.providers()`
+reads them through the stack's config provider (process env, `.env`, stack secrets):
+
+- `CONVEX_ACCESS_TOKEN`, a team access token, for the Management API. Without it, the provider uses
+  the token that `npx convex login` saved (`~/.convex/config.json`). `Convex.Project` needs it, and
+  so does a deployment that the deploy key does not reach.
+- `CONVEX_DEPLOY_KEY`, optional, the same variable that the Convex CLI reads:
+  - A deploy key of one deployment (`prod:<name>|...`) sets variables and pushes to that deployment.
+    That stage then needs no access token if it passes `project: { projectId }` or a
+    `Convex.Project.ref`. The key must have `deployment:data:view` (dashboard keys have all
+    actions), because the provider reads the project and type of its deployment first.
+  - A preview deploy key of a project (`preview:<team>:<project>|...`) creates, pushes to, and
+    deletes preview deployments of that project. It cannot change variables: with `env`, the
+    provider uses the access token, and without one it stops with `EnvironmentNeedsDeployKey`
+    before it creates anything. Use project default variables in the Convex dashboard for previews.
+
+A key that does not fit the deployment is not used: the provider uses the access token. To pass
+values explicitly: `Convex.providers(Convex.fromValues({ accessToken, deployKey }))`.
 
-Deleting a Convex project deletes all of its deployments and data. This package does not delete,
-replace, or overwrite your data by accident:
-
-- `Convex.Project` has the removal policy `retain`. When you remove the resource or run
-  `alchemy destroy`, Alchemy forgets the project and Convex keeps it. To delete the project with
-  the resource, add `RemovalPolicy.destroy()`:
-
-  ```ts
-  yield * Convex.Project("Project", { team, name }).pipe(Alchemy.RemovalPolicy.destroy());
-  ```
-
-- A project is never replaced. A change to `name` renames the project in place
-  (`PATCH /projects/{project_id}`). The id, the slug, the deployments, and the data stay.
-- A change to `team`, `deploymentType`, or `deploymentRegion` stops the deploy with
-  `ProjectTeamChange` or `ProjectDeploymentChange`. Convex cannot move a project or change its
-  first deployment. Set the old value again, or create a new resource with a new logical id and
-  move the data yourself.
-- With state, the provider finds the project only by the id in state. Without state, it finds a
-  project by its exact name, on all pages of the team's project list, and takes it over only with
-  `--adopt`. When two projects have that name, the deploy stops with `AmbiguousProject`.
-- Each `DeployKey` and `PreviewDeployKey` requests a name that is unique to the resource: the
-  `name` prop, a dash, and a hash of the resource identity. The provider deletes a key only by its
-  secret, so it cannot revoke the key of another resource. When the key list does not show
-  exactly one key with the requested name, the deploy stops with `DeployKeyRecoveryRequired`,
-  which lists the key ids. The provider never revokes a key on a failed create.
-- With an OAuth token as the credential, Convex creates no new key: it returns the OAuth token
-  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.
-- An `EnvironmentVariable` or a `DefaultEnvironmentVariable` that exists but is not in state
-  belongs to someone else. The provider overwrites it only with `--adopt`.
-- 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
-  need a cleanup step that can fail and leave a variable or a revoked deploy key behind.
-- 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.
+## Resources
 
-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`.
-Deploy keys from 0.1 state keep working, but 0.2 does not delete them: their state cannot show that
-the secret is a new key and not an OAuth token. When you remove or replace such a key, delete it in
-the Convex dashboard.
+- `Convex.Project`: `{ team, name, deploymentRegion?, deploymentType? }` creates a project with its
+  default deployment, or takes over one with that exact name with `--adopt`. A changed `name`
+  renames the project in place. `{ team, slug }` is an existing project, found by its slug and
+  taken over with `--adopt`; it never creates or renames a project. Outputs `projectId`, `slug`,
+  `name`, `teamId`, `prodDeploymentName`, `prodDeploymentUrl`.
+- `Convex.Deployment`: `{ project, type: "prod" }` or `{ project, type: "dev" | "preview", name }`,
+  each with optional `source` and `env`. Outputs `name` (such as `happy-animal-123`), `url`,
+  `siteUrl`, `type`, `projectId`, `reference`, `previewName`, `hash`, and `envNames`.
+  - `prod` is the project's default production deployment (with a deploy key: the key's
+    production deployment). The resource never creates or deletes one. A production deployment
+    with code that is not in state is taken over only with `--adopt`.
+  - `dev` creates a dev deployment with `name` as its reference; `preview` creates a preview
+    deployment with `name` as its preview name. An expired preview is created again on the next
+    deploy.
+  - `source` is the Convex functions directory: `convex/`, or the `functions` field of
+    convex.json (`SourceMismatch`). The CLI runs in the nearest directory above it with a
+    package.json, with the Node.js that runs Alchemy, and is never downloaded (`ConvexCliNotFound`).
+  - The content identity is a hash of every file of that app directory that git does not ignore,
+    the nearest lockfile, the deployment name, and `env`. The same hash is a no-op. Otherwise the
+    update sets `env`, then pushes. A failed push sets the changed variables back, and deletes a
+    dev or preview deployment that the same run created.
+  - `env` values are strings or secrets such as `Config.Redacted("AUTH_SECRET")`. A name that
+    leaves `env` is removed from the deployment.
+  - `source: { path, command?, include? }` replaces `convex deploy` with `command`, run in the app
+    directory with the push key in `CONVEX_DEPLOY_KEY`, such as
+    `["node_modules/.bin/convex-hosting", "deploy", "--build", "node_modules/.bin/vp build", "--dist", "dist/client"]`.
+    The command must push with `convex deploy` (convex-hosting does, through `--cmd`). `include`
+    narrows the hash to `path`, package.json, convex.json, the lockfile, and the listed globs, such
+    as the build inputs `["src/**", "public/**", "vite.config.ts"]`. A minted key for a command
+    has every action, because the command can do more than a push.
 
-## Resources
+## Data safety
 
-- `Convex.Project`: `{ team: slug | id, name, deploymentRegion?, deploymentType? }`. Creates a
-  project with its default deployment. Outputs `projectId`, `slug`, `teamId`,
-  `prodDeploymentName`, `prodDeploymentUrl`. A changed `name` renames the project in place. A
-  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.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.
-- `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
-  deployment, set through the deployment API with that deployment's key. An existing variable with
-  the same name is adopted and overwritten only with `--adopt`. A new `value` or `deployKey` is an
-  update in place. A new `name` or `deployment` stops the deploy with `VariableIdentityChange`:
-  use a new logical id. Outputs `deployment`, `name`, and `deployKey`. Read and delete use the
-  deploy key in the outputs, not the props.
-- `Convex.DefaultEnvironmentVariable`: `{ projectId, name, value, deploymentType }`. A project
-  default that new deployments of that type inherit. Use it for preview and dev deployments. An
-  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.Project` and `Convex.Deployment` have the removal policy `retain`. `alchemy destroy`
+  forgets them and Convex keeps them. Add `RemovalPolicy.destroy()` to delete with the resource.
+- A project is never replaced. A change of `team`, `slug`, `deploymentType`, or `deploymentRegion`
+  stops the deploy with a typed error that names the fix.
+- A deployment keeps its `project`, `type`, and `name`; a change stops the deploy with
+  `DeploymentIdentityChange`. A production deployment is never deleted, also not with
+  `RemovalPolicy.destroy()`, and also not a dev deployment that became one.
+- A dev or preview deployment that exists but is not in state belongs to someone else, such as a
+  preview that CI made. The resource takes it over only with `--adopt`, and never creates over it:
+  a Convex create for an existing preview name deletes that preview.
+- With the access token, each push uses a new deploy key with only `deployment:deploy`,
+  `deployment:env:view`, and `deployment:env:write`, which expires after two hours and is deleted
+  after the push, also after a failure. With an OAuth token, Convex returns the token itself as the
+  key, so the delete is skipped. No other key is created or revoked.
+- The key reaches the CLI only in an env file with mode 0600, in a temporary home directory that is
+  removed after the run. 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`.
+- A variable in `env` that exists with another value and that the resource did not set stops the
+  deploy with `VariablesOwnedBySomeoneElse`. `--adopt` overwrites it. Destroy leaves variables in
+  place: they go with the deployment.
+- A variable write runs again after a Convex write conflict or a 5xx answer, at most four more
+  times.
 
 ## Limits
 
-- Team slugs resolve through an unofficial dashboard endpoint. Pass the numeric team id to avoid
-  it.
-- Deploy keys and other secret outputs are part of Alchemy state. Alchemy's Cloudflare state store
-  encrypts state at rest; the local file store does not.
-- A deleted deploy key keeps working on the deployment API for roughly 30 seconds.
-- 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.
+- `env` values are props, so Alchemy state holds them. Keep `.alchemy/` git-ignored, and use an
+  encrypted state store, such as `Cloudflare.state()`, in CI.
+- The hash does not see a change in a workspace package outside the app directory, or a push from
+  outside Alchemy. Change a file of the app to push again.
+- With a deploy key, the provider reaches the deployment at `https://<name>.convex.cloud`, so the
+  deployment must answer there.
+- A run that stops between a deployment create and the state write leaves a deployment that state
+  does not know. The next run stops with `OwnedBySomeoneElse`; run it with `--adopt`.
+- Team slugs for `{ team, name }` resolve through an unofficial dashboard endpoint. Pass the numeric
+  team id to avoid it. `{ team, slug }` uses the official endpoint.
+- Not covered: deployment regions and classes, custom domains, log streams, teams and members,
+  components, snapshots.
 
 ## Development
 
@@ -193,22 +170,16 @@ pnpm run build            # lib/ with declarations, then publint and attw
 pnpm run test:live        # real API calls, see below
 ```
 
-Use Node 24 (`.node-version`) and pnpm 11. `pnpm install` also installs a pre-commit hook that
-runs `vp staged`.
-
-Unit tests run against recorded Management API payloads in `test/fixtures/management/`. Live tests
-run only with `ALCHEMY_CONVEX_LIVE=1`, which `pnpm run test:live` sets. They need a Convex login or
-`CONVEX_ACCESS_TOKEN`, and a throwaway project.
-Point them at yours with `ALCHEMY_CONVEX_LIVE_TEAM`, `ALCHEMY_CONVEX_LIVE_PROJECT_ID`,
-`ALCHEMY_CONVEX_LIVE_DEPLOYMENT`, and `ALCHEMY_CONVEX_LIVE_PROJECT_DIR` (a Convex app directory for
-the deploy test). They create resources named `tmp-alchemy-convex-*` and remove them again.
-A file argument runs one live file only, for example
-`pnpm run test:live test/live/safety.live.test.ts`. That test runs the data safety contract
-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-`.
+Use Node 24 (`.node-version`) and pnpm 11. Unit tests run against recorded Management API payloads
+in `test/fixtures/management/` and a fake Convex CLI. Live tests run only with
+`ALCHEMY_CONVEX_LIVE=1`, which `pnpm run test:live` sets. They need a Convex login or
+`CONVEX_ACCESS_TOKEN` that can create projects in `ALCHEMY_CONVEX_LIVE_TEAM`. Each test creates a
+project whose name starts with `ALCHEMY_CONVEX_LIVE_PREFIX` (default `tmp-alchemy-convex-`),
+deletes it at the end, also after a failure, and refuses to delete a project, or a deployment of a
+project, without that prefix. A file argument runs one live file only, for example
+`pnpm run test:live test/live/plane.live.test.ts`.
 
 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.
 
-License: Apache 2.0.
+License: Apache 2.0. Parts follow Confect; see [NOTICE](NOTICE).