@samebase/alchemy-convex 0.6.1 → 0.8.0

package/src/State.ts

@@ -23,13 +23,19 @@
 // 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.
 //
-// The function names are a wire contract: Samebase reads `stacks` and
-// `getOutput` by name, and an older client calls an older set of names. A
-// name is never renamed or removed. STORE_VERSION rises when a function
-// changes in a way that an older client cannot use, and a client never
-// pushes an older store over a newer one.
+// The function names are a wire contract: Samebase reads `stacks`,
+// `getOutput`, and `readStack` by name, and an older client calls an older
+// set of names. A name is never renamed or removed. STORE_VERSION rises when
+// a function is added or changes in a way that an older client cannot use,
+// and a client never pushes an older store over a newer one.
+//
+// The stage output that `setOutput` stores is the stack's output plus the
+// run record of src/RunRecord.ts under the key `samebase.run`: the
+// repository, stack file, branch, pull request, commit, and run that wrote
+// the stage. `getOutput` gives the document back as stored.
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
@@ -70,6 +76,7 @@ import {
   PUSH_KEY_ACTIONS,
   withPushKey,
 } from "./Push.ts";
+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. */
@@ -241,6 +248,8 @@ export interface StoreOptions {
   readonly scope: Scope.Scope;
   /** The functions directory that an outdated store gets: {@link storeDirectory}. */
   readonly store: string;
+  /** The record of this run, which `setOutput` adds to the stage output with the time of the write, or undefined for a run without one. */
+  readonly run: RunRecord | undefined;
 }
 
 /**
@@ -261,6 +270,7 @@ const pushStore = (
       push(options.spawner, key, {
         deployment: deployment.name,
         url: deployment.deploymentUrl,
+        rootDir: join(options.store, ".."),
         source: {
           path: options.store,
           command: [...cli, "deploy", "--typecheck", "disable", "--codegen", "disable"],
@@ -385,6 +395,21 @@ export const makeConvexState = (options: StoreOptions) =>
     }
 
     const remote = remoteOf(functions);
+    /** The stack's output plus the record, when the run has one and the output has a place for it. */
+    const documentOf = (request: { stack: string; stage: string; value: unknown }) =>
+      Effect.gen(function* () {
+        const { run } = options;
+        if (run === undefined) return request.value;
+        const recordedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
+        const document = withRunRecord(request.value, { ...run, recordedAt });
+        if (document === undefined) {
+          yield* Effect.logWarning(
+            `Convex state: the output of ${request.stack}/${request.stage} is not a plain object, so it carries no run record.`,
+          );
+          return request.value;
+        }
+        return document;
+      });
     const service: StateService = {
       id: "convex",
       getVersion: () => Effect.succeed(STATE_STORE_VERSION),
@@ -397,7 +422,13 @@ export const makeConvexState = (options: StoreOptions) =>
       set: (request) => remote.set(request).pipe(Effect.as(request.value)),
       delete: (request) => remote.delete(request).pipe(Effect.asVoid),
       deleteStack: (request) => remote.deleteStack(request).pipe(Effect.asVoid),
-      setOutput: (request) => remote.setOutput(request).pipe(Effect.as(request.value)),
+      // The document is the stack's output plus the record under `samebase.run`.
+      setOutput: (request) =>
+        Effect.gen(function* () {
+          const value = yield* documentOf(request);
+          yield* remote.setOutput({ stack: request.stack, stage: request.stage, value });
+          return value;
+        }),
     };
     return service;
   });
@@ -425,12 +456,25 @@ export const state = (
           const api = yield* ManagementApi.pipe(
             Effect.provide(ManagementApiLive().pipe(Layer.provide(fromConfig()))),
           );
+          // The record is derived once, before the first read. A checkout
+          // that gives none, such as a tarball without git, a checkout
+          // without origin, or a detached HEAD, still reads, plans, and
+          // destroys: its outputs are written without the record, and the
+          // log says why.
+          const run = yield* runRecord({ cwd: process.cwd(), env: process.env }).pipe(
+            Effect.catch((error) =>
+              Effect.logWarning(
+                `Convex state: the stage outputs of this run carry no record. ${error.message}`,
+              ).pipe(Effect.as(undefined)),
+            ),
+          );
           return yield* makeConvexState({
             team: options.team,
             api,
             spawner,
             scope,
             store: storeDirectory(),
+            run,
           });
         }).pipe(Effect.provideContext(context), Effect.orDie),
       );

package/src/index.ts

@@ -8,10 +8,12 @@ export {
   fromValues,
 } from "./Credentials.ts";
 export {
+  AbsoluteRootDir,
   AmbiguousDeployment,
   Deployment,
   type DeploymentAttributes,
   DeploymentIdentityChange,
+  type DeploymentInput,
   type DeploymentProps,
   ProductionDeploymentNotFound,
 } from "./Deployment.ts";
@@ -28,6 +30,13 @@ export {
   ProjectTeamChange,
 } from "./Project.ts";
 export { Providers, providers } from "./Providers.ts";
+export {
+  RUN_RECORD_KEY,
+  type RunRecord,
+  RunRecordError,
+  runRecord,
+  withRunRecord,
+} from "./RunRecord.ts";
 export { state, STORE_PROJECT_NAME } from "./State.ts";
 export {
   CodePushFailed,

package/src/store/convex/state.ts

@@ -7,8 +7,8 @@
 //
 // A stage holds one row for each resource of its stack, so the reads of one
 // stage collect all rows. The function names are a wire contract: Samebase
-// reads `stacks` and `getOutput` by name, and an older client calls an older
-// set of names. Add functions; never rename or remove one.
+// reads `stacks`, `getOutput`, and `readStack` by name, and an older client
+// calls an older set of names. Add functions; never rename or remove one.
 import { v } from "convex/values";
 import type { QueryCtx } from "./_generated/server.js";
 import { internalMutation, internalQuery } from "./_generated/server.js";
@@ -217,3 +217,49 @@ export const setOutput = internalMutation({
     return null;
   },
 });
+
+/**
+ * One call for a reader: every stage of a stack in name order, each with its
+ * resources in fqn order and its output, as the JSON texts that the rows
+ * hold. A stage with an output and no resource is listed with an empty
+ * resource list; a stage with resources and no output with `output: null`.
+ * One function reads at most 16 MiB (Convex limit): a stack whose rows go
+ * beyond that fails here and is read with `stages`, `list`, `get`, and
+ * `getOutput` instead. Since store version 2.
+ */
+export const readStack = internalQuery({
+  args: { stack: v.string() },
+  returns: v.object({
+    stages: v.array(
+      v.object({
+        stage: v.string(),
+        resources: v.array(v.object({ fqn: v.string(), value: v.string() })),
+        output: v.union(v.string(), v.null()),
+      }),
+    ),
+  }),
+  handler: async (ctx, args) => {
+    // Both indexes order by stack, then stage, then (for resources) fqn.
+    const resources = await ctx.db
+      .query("resources")
+      .withIndex("by_fqn", (q) => q.eq("stack", args.stack))
+      .collect();
+    const outputs = await ctx.db
+      .query("outputs")
+      .withIndex("by_stage", (q) => q.eq("stack", args.stack))
+      .collect();
+    const stages = union(
+      [...new Set(resources.map((row) => row.stage))],
+      [...new Set(outputs.map((row) => row.stage))],
+    );
+    return {
+      stages: stages.map((stage) => ({
+        stage,
+        resources: resources
+          .filter((row) => row.stage === stage)
+          .map((row) => ({ fqn: row.fqn, value: row.value })),
+        output: outputs.find((row) => row.stage === stage)?.value ?? null,
+      })),
+    };
+  },
+});

package/src/store/convex/version.ts

@@ -1,6 +1,10 @@
 // The wire version of the store: the `state:version` query answers it, and
 // Convex.state() pushes this directory when the store of the team answers an
-// older one or has no `version` yet. Raise it when a function changes in a way
-// that an older client cannot use. Never rename or remove a function: an
-// older client, and Samebase, call the store by these names.
-export const STORE_VERSION = 1;
+// older one or has no `version` yet. Raise it when a function is added or
+// changes in a way that an older client cannot use. Never rename or remove a
+// function: an older client, and Samebase, call the store by these names.
+//
+// 1: `version`, `stacks`, `stages`, `list`, `get`, `replaced`, `getOutput`,
+//    `set`, `remove`, `removeStack`, `setOutput` (0.6.0).
+// 2: `readStack` (0.7.0).
+export const STORE_VERSION = 2;