@samebase/alchemy-convex 0.27.3 → 0.28.0

package/README.md

@@ -275,9 +275,11 @@ call.
   - `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.
+  - `dev` creates a dev deployment with `name` as its reference. With `--adopt`, `name` can also be
+    the Convex name of a dev deployment that exists, such as `happy-animal-123` from `.env.local`,
+    which `npx convex dev` made: the resource takes it over. A name that matches nothing creates a
+    dev deployment with that reference. `preview` creates a preview deployment with `name` as its
+    preview name. An expired preview is created again on the next deploy.
   - `rootDir` is the app directory, relative to the directory where the deploy runs, `"."` by
     default. It must be relative (`AbsoluteRootDir`) and have a package.json (`ConvexAppNotFound`).
     There is no search in the directories above it. When convex.json puts the functions outside
@@ -371,27 +373,29 @@ variables. Each callback remains one exact registered URI.
 
 ### The development stage
 
-A laptop is a stage `dev-<name>` of the app's stack, with its own cloud development deployment. Run
-`alchemy deploy --stage dev-<name>` with `CONVEX_ACCESS_TOKEN` or the Convex CLI login of the app's
-team, before `convex dev`. The stage has the same three rows as a preview:
+A laptop gets its client from a stage `dev-<name>` of the app's stack, run on purpose, not at each
+dev start: `npx convex dev` has made and selected the dev deployment and pushed the code, and then
+`alchemy deploy --stage dev-<name>` gives that deployment its variables. The stage creates nothing
+and pushes nothing. It has three rows on the deployment that `.env.local` selects, taken over by its
+Convex name:
 
 ```ts
-// The stage is dev-<name>. `project` is the project of the deployment that the Convex CLI selects.
+// `selected` is the name in CONVEX_DEPLOYMENT of .env.local, such as happy-animal-123, and
+// `project` is the project of stage `prod`.
 const prod = Convex.SharedHubClient.read("HubClient", { stage: "prod" });
-const deployment =
+const site =
   yield *
-  Convex.Deployment("Deployment", {
+  Convex.Deployment("Verification", {
     project,
     type: "dev",
-    name: stage,
-    source: "./convex",
+    name: selected,
     env: { SAMEBASE_REPOSITORY_ID: prod.repository },
   }).pipe(adopt(true));
 const hub =
   yield *
   Convex.SharedHubClient("HubClient", {
     app: "scout",
-    redirectUri: Output.interpolate`${deployment.siteUrl}/auth/hub/callback`,
+    redirectUri: Output.interpolate`${site.siteUrl}/auth/hub/callback`,
     deploymentType: "development",
     initialAccessToken: prod.initialAccessToken,
   });
@@ -400,7 +404,7 @@ yield *
   Convex.Deployment("Site", {
     project,
     type: "dev",
-    name: stage,
+    name: selected,
     env: {
       HUB_ISSUER: variables.issuer,
       HUB_CLIENT_ID: variables.clientId,
@@ -412,11 +416,13 @@ yield *
 The imports are `alchemy/AdoptPolicy` for `adopt` and `alchemy/Output` for `Output`.
 
 1. `read` gives the initial access token and the repository id from the `HubClient` row of stage
-   `prod`. Before the first deploy to main, they are empty.
-2. "Deployment" finds the development deployment by its reference, or creates it. It sets
-   `SAMEBASE_REPOSITORY_ID`, which the site serves as `/samebase-verification.json`, and pushes.
-3. "HubClient" asks the hub for a development client on the deployment's site URL with the token.
-   Each later run renews it. A development client expires 14 days after its last run or use.
+   `prod`.
+2. "Verification" sets `SAMEBASE_REPOSITORY_ID`, which the site serves as
+   `/samebase-verification.json`. `adopt` takes over the deployment and the variables that the dev
+   start set before.
+3. "HubClient" asks the hub for a development client on the deployment's site URL with the token. A
+   later run renews it. A sign-in renews it too, so a laptop in use never needs the stage again; a
+   development client expires 14 days after its last run or sign-in.
 4. "Site" writes the three variables. It removes only a name that leaves its own `env`, so
    `SAMEBASE_REPOSITORY_ID` stays.
 

package/lib/{HubClient-Bs5_j18U.js → HubClient-BcegkjaP.js}

@@ -782,7 +782,8 @@ const checkIdentity = (current, news) => {
 	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);
-	if (news.type !== "prod" && currentName !== news.name) return change("name", currentName ?? "(none)", news.name);
+	const named = news.type === "dev" && current.name === news.name;
+	if (news.type !== "prod" && currentName !== news.name && !named) return change("name", currentName ?? "(none)", news.name);
 	return Effect.void;
 };
 const addressOf = (props) => ({
@@ -824,11 +825,13 @@ const DeploymentProvider = () => Provider.effect(DeploymentResource, Effect.gen(
 	/** The project's default production deployment, or undefined. */
 	const production = (management, projectId) => productionRow(management, projectId).pipe(Effect.map((row) => row === void 0 ? void 0 : targetOf(row, "prod", void 0)));
 	/**
-	* The one dev deployment with this reference, or the one preview
-	* deployment with this preview name, or undefined.
+	* The one dev deployment with this reference or this Convex name, or the
+	* one preview deployment with this preview name, or undefined. The name
+	* form takes the dev deployment that `npx convex dev` made, such as the
+	* one `.env.local` selects, which has a reference the stack never chose.
 	*/
 	const findByName = (management, projectId, type, name) => Effect.gen(function* () {
-		const matches = (yield* listDeployments(management, projectId, type)).filter((row) => row.deploymentType === type && (type === "dev" ? row.reference === name : row.previewIdentifier === name));
+		const matches = (yield* listDeployments(management, projectId, type)).filter((row) => row.deploymentType === type && (type === "dev" ? row.reference === name || row.name === name : row.previewIdentifier === name));
 		if (matches.length > 1) return yield* new AmbiguousDeployment({
 			projectId,
 			type,
@@ -843,7 +846,7 @@ const DeploymentProvider = () => Provider.effect(DeploymentResource, Effect.gen(
 	const deployKeyTarget = (key, deployment, 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;
+		if (info.projectId !== address.projectId || info.deploymentType !== address.type || address.type === "dev" && reference !== address.name && deployment !== address.name) return;
 		const urls = Schema.decodeUnknownSync(CanonicalUrls)(yield* api.deploymentRequest("get canonical urls", deployment, key, (client) => client.GET("/get_canonical_urls")));
 		return {
 			projectId: info.projectId,
@@ -1989,4 +1992,4 @@ const registerDevelopmentClient = (options) => Effect.gen(function* () {
 //#endregion
 export { PushTargetMismatch as A, DEPLOY_KEY_ENV as B, DeploymentProvider as C, ConvexAppNotFound as D, CodePushFailed as E, ManagementApi as F, fromValues as H, ManagementApiLive as I, ACCESS_TOKEN_ENV as L, installedCli as M, parseDeployOutput as N, ConvexCliNotFound as O, ConvexApiError as P, Credentials as R, DeploymentIdentityChange as S, ProductionDeploymentNotFound as T, fromConfig as V, ProjectProvider as _, registerDevelopmentClient as a, AmbiguousDeployment as b, RUN_RECORD_KEY as c, withRunRecord as d, AmbiguousProject as f, ProjectNotFound as g, ProjectDeploymentChange as h, HubClientProvider as i, VariablesOwnedBySomeoneElse as j, EnvironmentNeedsDeployKey as k, RunRecordError as l, Project as m, HubClient as n, STORE_PROJECT_NAME as o, CreatedProjectNotFound as p, HubClientFailed as r, state as s, HUB_PROJECT_NAME as t, runRecord as u, ProjectTeamChange as v, DeploymentResource as w, Deployment as x, AbsoluteRootDir as y, CredentialsError as z };
 
-//# sourceMappingURL=HubClient-Bs5_j18U.js.map
+//# sourceMappingURL=HubClient-BcegkjaP.js.map