@samebase/alchemy-convex 0.5.0 → 0.6.1

package/README.md

@@ -92,24 +92,32 @@ values explicitly: `Convex.providers(Convex.fromValues({ accessToken, deployKey
 
 ## State in Convex
 
-`state: Convex.state()` keeps the Alchemy state of every stage in the production deployment of the
-project, so the stack needs no Cloudflare token.
-[docs/design/convex-state.md](docs/design/convex-state.md) records the decisions.
+`state: Convex.state({ team })` keeps the Alchemy state of every stack and stage of a Convex team in
+one project of that team, `alchemy-state`, so a repository holds one secret and a stack can create
+and destroy its own project. [docs/design/convex-state.md](docs/design/convex-state.md) records the
+decisions and the measurements.
 
-1. Mount the state component in `convex/convex.config.ts` with its default name:
-
-   ```ts
-   import alchemyState from "@samebase/alchemy-convex/convex.config";
-   app.use(alchemyState);
-   ```
-
-2. Set `CONVEX_STATE_DEPLOY_KEY` in every run, a preview run too, to a production deploy key. A key
-   with only the actions `deployment:data:view` and `deployment:data:write` is sufficient.
+```ts
+export default Alchemy.Stack(
+  process.env["GITHUB_REPOSITORY"] ?? "my-org/my-app", // the stack name: the repository
+  { providers: Convex.providers(), state: Convex.state({ team: "my-team" }) },
+  Effect.gen(function* () {
+    /* ... */
+  }),
+);
+```
 
-The first run starts with empty state, keeps it in memory until `Convex.Deployment` has pushed the
-component, and then writes it. A run whose push does not mount the component fails at the end.
-Rows are in the `alchemyState` component tables `resources` and `outputs` in the dashboard. The
-store has no lock: run one deploy of a stage at a time, such as with a CI concurrency group.
+Every run needs the team token in `CONVEX_ACCESS_TOKEN`, or the Convex CLI login on a laptop. A
+team access token names its team, so `Convex.state()` needs no `team` with one; a `team` slug that
+is set must be the slug of that team, checked against its projects, and a token of another team
+fails the run. The Convex CLI login needs the slug or the id. The first run of a team creates
+the project `alchemy-state` and pushes the store functions to its
+production deployment with the Convex CLI of the app; a later version of this package pushes a
+newer store when it finds an older one, and never an older one over a newer one. Each run makes a
+deploy key of that deployment that can only run the store's internal functions, and deletes it at
+the end. Rows are in the tables `resources` and `outputs` in the dashboard, under the stack name.
+The store has no lock: run one deploy of a stage at a time, such as with a CI concurrency group.
+The names of the store functions are a wire contract: never renamed or removed.
 
 ## Resources
 

package/lib/index.d.ts

@@ -5,8 +5,9 @@ import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
 import { Resource } from "alchemy";
 import * as Provider from "alchemy/Provider";
-import "effect/process/ChildProcessSpawner";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import "effect/Scope";
 import { State, StateStoreError } from "alchemy/State";
 import { components } from "@convex-dev/platform/managementApi";
 //#region src/Credentials.d.ts
@@ -77,8 +78,14 @@ interface ManagementApiService {
   readonly requestVoid: (operation: string, run: (client: ManagementClient) => Promise<FetchResult<unknown>>) => Effect.Effect<void, ConvexApiError>;
   /** Run one deployment-scoped call authenticated with a deploy key. */
   readonly deploymentRequest: <T>(operation: string, deploymentUrlOrName: string, deployKey: Redacted.Redacted<string>, run: (client: DeploymentClient) => Promise<FetchResult<T>>) => Effect.Effect<T, ConvexApiError>;
-  /** Team id for a slug or numeric id. */
-  readonly resolveTeamId: (team: string | number) => Effect.Effect<number, ConvexApiError>;
+  /**
+   * Team id for a numeric id, a slug, or nothing. A team access token names
+   * its team (`GET /token_details`); a slug is then checked against the
+   * `teamSlug` of the team's projects, so a token of another team fails. The
+   * Convex CLI login and a personal token answer 403 there, so a slug goes to
+   * the dashboard's team list, and nothing is an error.
+   */
+  readonly resolveTeamId: (team: string | number | undefined) => Effect.Effect<number, ConvexApiError>;
   /**
    * True when a deploy key that Convex returned carries the token of the
    * Management API credential itself. With an OAuth token, create_deploy_key
@@ -341,15 +348,19 @@ export declare class ProjectNotFound extends ProjectNotFound_base {
 }
 //#endregion
 //#region src/State.d.ts
-/** Environment variable with the deploy key of the deployment that holds the state. */
-export declare const STATE_DEPLOY_KEY_ENV = "CONVEX_STATE_DEPLOY_KEY";
+/** The name of the state project in each team. */
+export declare const STORE_PROJECT_NAME = "alchemy-state";
 /**
- * Alchemy state in the alchemyState component of the deployment that the
- * deploy key in CONVEX_STATE_DEPLOY_KEY names: the production deployment of
- * the project. The key needs the actions `deployment:data:view` and
- * `deployment:data:write`.
+ * Alchemy state in the `alchemy-state` project of `team`, with the team token
+ * in CONVEX_ACCESS_TOKEN or the Convex CLI login. A team access token names
+ * its team, so `team` is optional with one; the Convex CLI login needs the
+ * slug or the id. The first use of the run finds or creates the project and
+ * pushes the store when it is missing or older. `alchemy plan` on another
+ * stack never touches Convex.
  */
-export declare const state: () => Layer.Layer<State>;
+export declare const state: (options?: {
+  readonly team?: string | number;
+}) => Layer.Layer<State, never, ChildProcessSpawner.ChildProcessSpawner>;
 //#endregion
 export type { DeploymentAttributes, DeploymentProps, DeploymentRegion, EnvValue, ProjectAttributes, ProjectProps, Source };
 //# 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/Push.ts","../src/Deployment.ts","../src/Project.ts","../src/State.ts"],"mappings":";;;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,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;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBClFtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC8BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBA2BF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UCzHR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KChJH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB;;;;;qBC7EF;;;;;;;qBAgQA,aAAY,MAAM,MAAM"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts","../src/State.ts"],"mappings":";;;;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,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;;;;;;;;WAQb,gBACP,sCACG,OAAO,eAAe;;;;;;;;WAQlB,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBC1FtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC+BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBAkCF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UChIR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KC5IH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB;;;;;qBChDF;;;;;;;;;qBAiVA,QACX;WAAoB;MACnB,MAAM,MAAM,cAAc,oBAAoB"}