@samebase/alchemy-convex 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",
@@ -31,6 +31,10 @@
     ".": {
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js"
+    },
+    "./state/convex.config": {
+      "types": "./src/store/component/convex.config.ts",
+      "default": "./src/store/component/convex.config.ts"
     }
   },
   "publishConfig": {

package/src/State.ts

@@ -1,9 +1,10 @@
 // Alchemy state in Convex: `state: Convex.state({ team })` in `Alchemy.Stack`.
 //
-// One project for each Convex team, `alchemy-state`, holds the state of
+// One project for each Convex team, `samebase`, holds the state of
 // every stack and stage of the team in its production deployment: the
 // tables `resources (stack, stage, fqn, value)` and `outputs (stack, stage,
-// value)`, served by the functions of src/store/convex. The store lives
+// value)` of the alchemyState component (src/store/component), served by the
+// functions of src/store/convex. The store lives
 // outside every resource that a stack manages, so a stack can create and
 // destroy its own project. See docs/design/convex-state.md.
 //
@@ -18,7 +19,7 @@
 // repository-scoped subscriptions with secret values removed. A key that stops working during a
 // long run (it expires after two hours) is replaced once per call.
 //
-// Two first runs of a team can both create a project named `alchemy-state`.
+// Two first runs of a team can both create a project named `samebase`.
 // The run whose project is not the oldest deletes its own, before it writes
 // anything, and uses the oldest: both runs end on one store.
 //
@@ -79,7 +80,7 @@ import { type RunRecord, runRecord, withRunRecord } from "./RunRecord.ts";
 import { STORE_VERSION } from "./store/convex/version.ts";
 
 /** The name of the state project in each team. */
-export const STORE_PROJECT_NAME = "alchemy-state";
+export const STORE_PROJECT_NAME = "samebase";
 
 /**
  * The actions of the key of one run: the internal queries and mutations of
@@ -244,13 +245,14 @@ const storeVersion = (api: FunctionApi) =>
  * The functions directory of the store app, `src/store/convex` of this
  * package. This file is `src/State.ts` in a checkout and a chunk in `lib/`
  * in the installed package, which ships `src` too, so the directory is
- * `../src/store/convex` from either place.
+ * `../src/store/convex` from either place. Its `convex.config.ts` mounts the
+ * alchemyState component of `src/store/component`, inside the same push root.
  */
 export const storeDirectory = () =>
   join(dirname(fileURLToPath(import.meta.url)), "..", "src", "store", "convex");
 
 export interface StoreOptions {
-  /** Team slug or numeric team id of the `alchemy-state` project, or undefined with a team access token, which names its team. */
+  /** Team slug or numeric team id of the `samebase` project, or undefined with a team access token, which names its team. */
   readonly team: string | number | undefined;
   readonly api: ManagementApiService;
   readonly spawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
@@ -327,7 +329,7 @@ const createStoreProject = (api: ManagementApiService, teamId: number, team: str
   });
 
 /**
- * The StateService over the `alchemy-state` project of the team: found or
+ * The StateService over the `samebase` project of the team: found or
  * created, its store pushed when it is missing or older, and read and
  * written with the keys of this run.
  */
@@ -355,7 +357,7 @@ export const makeConvexState = (options: StoreOptions) =>
         }),
       ),
     );
-    const mint = createDeployKey(api, deployment.name, "alchemy-state", RUN_KEY_ACTIONS).pipe(
+    const mint = createDeployKey(api, deployment.name, STORE_PROJECT_NAME, RUN_KEY_ACTIONS).pipe(
       Effect.map((key) => {
         keys.push(key);
         return makeFunctionApi(deployment.deploymentUrl, key);
@@ -439,7 +441,7 @@ export const makeConvexState = (options: StoreOptions) =>
   });
 
 /**
- * Alchemy state in the `alchemy-state` project of `team`, with the team token
+ * Alchemy state in the `samebase` 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

package/src/store/component/_generated/api.ts

@@ -0,0 +1,54 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as reader from "../reader.js";
+import type * as runRecord from "../runRecord.js";
+import type * as state from "../state.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  reader: typeof reader;
+  runRecord: typeof runRecord;
+  state: typeof state;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/store/component/_generated/component.ts

@@ -0,0 +1,193 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    reader: {
+      repository: FunctionReference<
+        "query",
+        "internal",
+        { repository: string },
+        {
+          stacks: Array<{
+            name: string;
+            stages: Array<{
+              deployedHeadCommit: string | null;
+              name: string;
+              output: string;
+              record: {
+                branch: string;
+                headCommit: string;
+                pullRequest: number | null;
+                recordedAt: string;
+                repository: string;
+                runUrl: string | null;
+                source: "github-actions" | "laptop";
+                stackFile: string;
+                version: 1;
+              };
+              resources: Array<{ fqn: string; value: string }>;
+            }>;
+          }>;
+          store: "found";
+        },
+        Name
+      >;
+    };
+    state: {
+      get: FunctionReference<
+        "query",
+        "internal",
+        { fqn: string; stack: string; stage: string },
+        string | null,
+        Name
+      >;
+      getOutput: FunctionReference<
+        "query",
+        "internal",
+        { stack: string; stage: string },
+        string | null,
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        { stack: string; stage: string },
+        Array<string>,
+        Name
+      >;
+      readStack: FunctionReference<
+        "query",
+        "internal",
+        { stack: string },
+        {
+          stages: Array<{
+            output: string | null;
+            record: {
+              branch: string;
+              headCommit: string;
+              pullRequest: number | null;
+              recordedAt: string;
+              repository: string;
+              runUrl: string | null;
+              source: "github-actions" | "laptop";
+              stackFile: string;
+              version: 1;
+            } | null;
+            resources: Array<{ fqn: string; value: string }>;
+            stage: string;
+          }>;
+        },
+        Name
+      >;
+      remove: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          fqn: string;
+          run: {
+            branch: string;
+            headCommit: string;
+            pullRequest: number | null;
+            recordedAt: string;
+            repository: string;
+            runUrl: string | null;
+            source: "github-actions" | "laptop";
+            stackFile: string;
+            version: 1;
+          } | null;
+          stack: string;
+          stage: string;
+        },
+        null,
+        Name
+      >;
+      removeStack: FunctionReference<
+        "mutation",
+        "internal",
+        { stack: string; stage: string | null },
+        null,
+        Name
+      >;
+      replaced: FunctionReference<
+        "query",
+        "internal",
+        { stack: string; stage: string },
+        Array<string>,
+        Name
+      >;
+      set: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          fqn: string;
+          run: {
+            branch: string;
+            headCommit: string;
+            pullRequest: number | null;
+            recordedAt: string;
+            repository: string;
+            runUrl: string | null;
+            source: "github-actions" | "laptop";
+            stackFile: string;
+            version: 1;
+          } | null;
+          stack: string;
+          stage: string;
+          value: string;
+        },
+        null,
+        Name
+      >;
+      setOutput: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          run: {
+            branch: string;
+            headCommit: string;
+            pullRequest: number | null;
+            recordedAt: string;
+            repository: string;
+            runUrl: string | null;
+            source: "github-actions" | "laptop";
+            stackFile: string;
+            version: 1;
+          } | null;
+          stack: string;
+          stage: string;
+          value: string;
+        },
+        null,
+        Name
+      >;
+      stacks: FunctionReference<"query", "internal", {}, Array<string>, Name>;
+      stages: FunctionReference<
+        "query",
+        "internal",
+        { stack: string },
+        Array<string>,
+        Name
+      >;
+    };
+  };

package/src/store/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/store/component/_generated/server.ts

@@ -0,0 +1,169 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+type Env = {
+  readonly CONVEX_CLOUD_URL: string;
+  readonly CONVEX_SITE_URL: string;
+};
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+export const env: Env = (globalThis as unknown as { process: { env: Env } })
+  .process.env;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/store/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("alchemyState");

package/src/store/component/reader.ts

@@ -0,0 +1,104 @@
+// The redacted read of one repository. The app checks the reader's verified
+// token and passes the repository that the token names: a component has no
+// `ctx.auth`.
+import { v, type Infer } from "convex/values";
+import { query } from "./_generated/server.js";
+import { runRecord, validate } from "./runRecord.ts";
+
+const stage = v.object({
+  name: v.string(),
+  record: runRecord,
+  deployedHeadCommit: v.union(v.string(), v.null()),
+  resources: v.array(v.object({ fqn: v.string(), value: v.string() })),
+  output: v.string(),
+});
+
+/** The reply of {@link repository}. */
+export const repositoryReply = v.object({
+  store: v.literal("found"),
+  stacks: v.array(v.object({ name: v.string(), stages: v.array(stage) })),
+});
+
+/** Alchemy encodes a secret as an object with __redacted__; discard that whole object's contents. */
+function withoutSecrets(text: string): unknown {
+  return JSON.parse(text, (_key, value: unknown) =>
+    typeof value === "object" && value !== null && "__redacted__" in value
+      ? { __redacted__: null }
+      : value,
+  );
+}
+
+/** The stacks of `repository`: the stack of that name and the stacks below `repository + "/"`. */
+export const repository = query({
+  args: { repository: v.string() },
+  returns: repositoryReply,
+  handler: async (ctx, args) => {
+    const name = args.repository;
+    // The exact name and its slash-prefixed children exclude names such as owner/app-other.
+    // All four reads share the query transaction, including writes made while provisioning.
+    const [rootResources, childResources, rootOutputs, childOutputs] = await Promise.all([
+      ctx.db
+        .query("resources")
+        .withIndex("by_fqn", (q) => q.eq("stack", name))
+        .collect(),
+      ctx.db
+        .query("resources")
+        .withIndex("by_fqn", (q) => q.gte("stack", `${name}/`).lt("stack", `${name}0`))
+        .collect(),
+      ctx.db
+        .query("outputs")
+        .withIndex("by_stage", (q) => q.eq("stack", name))
+        .collect(),
+      ctx.db
+        .query("outputs")
+        .withIndex("by_stage", (q) => q.gte("stack", `${name}/`).lt("stack", `${name}0`))
+        .collect(),
+    ]);
+    const stacks = new Map<string, Map<string, Infer<typeof stage>>>();
+    for (const row of [...rootOutputs, ...childOutputs]) {
+      const record = row.currentRun;
+      if (record === undefined || record.repository !== name) continue;
+      // The output keeps the record of the last completed deploy under `samebase.run`.
+      let output = row.value === undefined ? null : withoutSecrets(row.value);
+      let deployed: unknown = null;
+      if (typeof output === "object" && output !== null && "samebase.run" in output) {
+        ({ "samebase.run": deployed, ...output } = output);
+      }
+      let stages = stacks.get(row.stack);
+      if (stages === undefined) {
+        stages = new Map();
+        stacks.set(row.stack, stages);
+      }
+      stages.set(row.stage, {
+        name: row.stage,
+        record,
+        deployedHeadCommit:
+          validate(runRecord, deployed) && deployed.repository === name
+            ? deployed.headCommit
+            : null,
+        resources: [],
+        output: JSON.stringify(output),
+      });
+    }
+    for (const row of [...rootResources, ...childResources]) {
+      stacks
+        .get(row.stack)
+        ?.get(row.stage)
+        ?.resources.push({
+          fqn: row.fqn,
+          value: JSON.stringify(withoutSecrets(row.value)),
+        });
+    }
+    return {
+      store: "found" as const,
+      stacks: [...stacks]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([name, stages]) => ({
+          name,
+          stages: [...stages.values()].sort((a, b) =>
+            a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+          ),
+        })),
+    };
+  },
+});