@samebase/alchemy-convex 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",
@@ -56,7 +56,7 @@
     "@effect/vitest": "4.0.4",
     "@types/node": "24.19.2",
     "alchemy": "2.0.0-beta.83",
-    "convex": "1.46.0",
+    "convex": "1.48.0",
     "convex-test": "0.0.60",
     "effect": "4.0.4",
     "publint": "0.3.25",
@@ -67,7 +67,7 @@
   "peerDependencies": {
     "@effect/platform-node": "^4.0.0",
     "alchemy": "2.0.0-beta.83",
-    "convex": "^1.46.0",
+    "convex": "^1.48.0",
     "effect": "^4.0.0"
   },
   "engines": {

package/src/State.ts

@@ -14,20 +14,19 @@
 // end; the `state:version` query says whether the deployment has the store
 // of this version. Without one, or with an older one, the installed Convex
 // CLI pushes src/store/convex to it, with a push key that is deleted after
-// the push. The functions are internal, so only POST /api/function with such
-// a key reaches them: a public function of a root app answers anyone who
-// knows the deployment URL (measured). A key that stops working during a
+// the push. The raw state functions are internal; authenticated readers get
+// 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`.
 // 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`,
-// `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.
+// Samebase reads `stacks`, `getOutput`, `readStack`, and `reader:repository`
+// by name. The store and its readers are released and upgraded together:
+// STORE_VERSION rises with each change of a function, and a client works only
+// with a store of its own version. An older store is pushed over; a newer one
+// fails the run.
 //
 // 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
@@ -157,7 +156,7 @@ export interface FunctionApi {
   /** POST /api/function, the call that `convex run` makes: the reply, which can be a function error. */
   readonly call: (
     path: string,
-    args: Record<string, string | undefined>,
+    args: Record<string, string | RunRecord | undefined>,
   ) => Effect.Effect<Reply, StateStoreError>;
 }
 
@@ -177,9 +176,20 @@ const valueOf = (reply: Reply) =>
     : Effect.fail(failure(reply.errorMessage.trim()));
 
 /** The functions of the store with Alchemy's encoding: the JSON text of encodeState. */
-const remoteOf = (api: FunctionApi) => {
-  const run = (name: string, args: Record<string, string | undefined>) =>
+const remoteOf = (api: FunctionApi, record: RunRecord | undefined) => {
+  const run = (name: string, args: Record<string, string | RunRecord | undefined>) =>
     api.call(`state:${name}`, args).pipe(Effect.flatMap(valueOf));
+  const write = (name: string, args: Record<string, string>) =>
+    Effect.gen(function* () {
+      const currentRun =
+        record === undefined
+          ? undefined
+          : {
+              ...record,
+              recordedAt: new Date(yield* Clock.currentTimeMillis).toISOString(),
+            };
+      return yield* run(name, { ...args, run: currentRun });
+    });
   const strings = (name: string, args: Record<string, string>) =>
     run(name, args).pipe(Effect.flatMap(decode(Schema.Array(Schema.String), name)));
   const optional = (name: string, args: Record<string, string>) =>
@@ -208,13 +218,13 @@ const remoteOf = (api: FunctionApi) => {
         Effect.map((text): unknown => (text === null ? undefined : JSON.parse(text, reviveState))),
       ),
     set: (r: { stack: string; stage: string; fqn: string; value: PersistedState }) =>
-      run("set", { stack: r.stack, stage: r.stage, fqn: r.fqn, value: encode(r.value) }),
+      write("set", { stack: r.stack, stage: r.stage, fqn: r.fqn, value: encode(r.value) }),
     delete: (r: { stack: string; stage: string; fqn: string }) =>
-      run("remove", { stack: r.stack, stage: r.stage, fqn: r.fqn }),
+      write("remove", { stack: r.stack, stage: r.stage, fqn: r.fqn }),
     deleteStack: (r: { stack: string; stage?: string }) =>
       run("removeStack", { stack: r.stack, stage: r.stage }),
     setOutput: (r: { stack: string; stage: string; value: unknown }) =>
-      run("setOutput", { stack: r.stack, stage: r.stage, value: encode(r.value) }),
+      write("setOutput", { stack: r.stack, stage: r.stage, value: encode(r.value) }),
   };
 };
 
@@ -248,7 +258,7 @@ 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. */
+  /** The run recorded with resource writes and output, or undefined for a run without one. */
   readonly run: RunRecord | undefined;
 }
 
@@ -367,7 +377,7 @@ export const makeConvexState = (options: StoreOptions) =>
         ),
     };
 
-    const version = yield* storeVersion(functions);
+    let version = yield* storeVersion(functions);
     if (version === undefined || version < STORE_VERSION) {
       // Code without `state:version` is another app with the name of the store.
       if (version === undefined && deployment.lastDeployTime) {
@@ -377,24 +387,19 @@ export const makeConvexState = (options: StoreOptions) =>
       }
       // Another run can push a newer store in the meantime: read again right
       // before the push. The push itself has no lock (see the design note).
-      const now = yield* storeVersion(functions);
-      if (now === undefined || now < STORE_VERSION) {
+      version = yield* storeVersion(functions);
+      if (version === undefined || version < STORE_VERSION) {
         yield* pushStore(options, deployment);
-        const pushed = yield* storeVersion(functions);
-        if (pushed === undefined || pushed < STORE_VERSION) {
-          return yield* failure(
-            `${deployment.name} answers store version ${pushed ?? "none"} after the push of version ${STORE_VERSION}.`,
-          );
-        }
+        version = yield* storeVersion(functions);
       }
-    } else if (version > STORE_VERSION) {
-      // The names are a wire contract, so a newer store serves this client.
-      yield* Effect.logInfo(
-        `Convex state: the store of team ${team} is version ${version}, newer than version ${STORE_VERSION} of this package, and it stays.`,
+    }
+    if (version !== STORE_VERSION) {
+      return yield* failure(
+        `${deployment.name} answers store version ${version ?? "none"}, and this package needs store version ${STORE_VERSION}.`,
       );
     }
 
-    const remote = remoteOf(functions);
+    const remote = remoteOf(functions, options.run);
     /** 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* () {

package/src/store/convex/_generated/api.d.ts

@@ -8,6 +8,8 @@
  * @module
  */
 
+import type * as reader from "../reader.js";
+import type * as runRecord from "../runRecord.js";
 import type * as state from "../state.js";
 import type * as version from "../version.js";
 
@@ -18,6 +20,8 @@ import type {
 } from "convex/server";
 
 declare const fullApi: ApiFromModules<{
+  reader: typeof reader;
+  runRecord: typeof runRecord;
   state: typeof state;
   version: typeof version;
 }>;

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

@@ -0,0 +1,14 @@
+import type { AuthConfig } from "convex/server";
+import { env } from "./_generated/server.js";
+
+export default {
+  providers: [
+    {
+      type: "customJwt",
+      issuer: env.CONVEX_CLOUD_URL,
+      applicationID: `${env.CONVEX_CLOUD_URL}/alchemy-reader`,
+      jwks: `${env.CONVEX_CLOUD_URL}/.well-known/jwks.json`,
+      algorithm: "ES256",
+    },
+  ],
+} satisfies AuthConfig;

package/src/store/convex/reader.ts

@@ -0,0 +1,131 @@
+import { v, type Infer } from "convex/values";
+import { env, internalMutation, query } from "./_generated/server.js";
+import { runRecord, validate } from "./runRecord.ts";
+
+const repositoryName = /^[^/]+\/[^/]+$/;
+
+/** Only a deployment credential can exchange an approved repository for a read token. */
+export const authorize = internalMutation({
+  args: { repository: v.string(), subject: v.string() },
+  returns: v.object({ token: v.string() }),
+  handler: async (ctx, args) => {
+    if (!repositoryName.test(args.repository) || args.subject === "") {
+      throw new Error("A repository and subject are required.");
+    }
+    return {
+      token: await ctx.auth.signJwt({
+        expiresInSeconds: 300,
+        claims: {
+          sub: args.subject,
+          aud: `${env.CONVEX_CLOUD_URL}/alchemy-reader`,
+          repository: args.repository,
+          scope: "alchemy:read",
+        },
+      }),
+    };
+  },
+});
+
+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(),
+});
+
+/** 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,
+  );
+}
+
+/** A native subscription reads only the repository named in its verified capability. */
+export const repository = query({
+  args: {},
+  returns: v.object({
+    store: v.literal("found"),
+    stacks: v.array(v.object({ name: v.string(), stages: v.array(stage) })),
+  }),
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (
+      identity === null ||
+      identity.scope !== "alchemy:read" ||
+      typeof identity.repository !== "string" ||
+      !repositoryName.test(identity.repository)
+    ) {
+      throw new Error("Alchemy repository read access is required.");
+    }
+    const name = identity.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,
+          ),
+        })),
+    };
+  },
+});

package/src/store/convex/runRecord.ts

@@ -0,0 +1,41 @@
+import { v, type GenericValidator, type Infer } from "convex/values";
+
+export const runRecord = v.object({
+  version: v.literal(1),
+  repository: v.string(),
+  stackFile: v.string(),
+  branch: v.string(),
+  pullRequest: v.union(v.number(), v.null()),
+  headCommit: v.string(),
+  runUrl: v.union(v.string(), v.null()),
+  source: v.union(v.literal("github-actions"), v.literal("laptop")),
+  recordedAt: v.string(),
+});
+
+/** Whether `value` passes `validator`. Only the kinds of {@link runRecord} pass; another kind fails. */
+export const validate = <V extends GenericValidator>(
+  validator: V,
+  value: unknown,
+): value is Infer<V> => {
+  switch (validator.kind) {
+    case "object": {
+      if (typeof value !== "object" || value === null) return false;
+      const fields = new Map(Object.entries(value));
+      return Object.entries(validator.fields).every(([key, field]) =>
+        validate(field, fields.get(key)),
+      );
+    }
+    case "union":
+      return validator.members.some((member) => validate(member, value));
+    case "literal":
+      return value === validator.value;
+    case "string":
+      return typeof value === "string";
+    case "float64":
+      return typeof value === "number";
+    case "null":
+      return value === null;
+    default:
+      return false;
+  }
+};

package/src/store/convex/schema.ts

@@ -1,5 +1,6 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
+import { runRecord } from "./runRecord.ts";
 
 // `value` is the JSON text of Alchemy's encodeState(...): the same text that
 // Alchemy's local state writes to a file. A Convex object would reject keys
@@ -14,6 +15,7 @@ export default defineSchema({
   outputs: defineTable({
     stack: v.string(),
     stage: v.string(),
-    value: v.string(),
+    value: v.optional(v.string()),
+    currentRun: v.optional(runRecord),
   }).index("by_stage", ["stack", "stage"]),
 });

package/src/store/convex/state.ts

@@ -1,17 +1,16 @@
 // The state functions of the alchemy-state project: one project for each
-// Convex team, pushed by Convex.state() from this directory. Every function
-// is internal: a public function of a root app answers anyone who knows the
-// deployment URL, with no key (measured). An internal function answers only
-// POST /api/function with a deploy key of the production deployment, the
-// call that `convex run` makes.
+// Convex team, pushed by Convex.state() from this directory. These raw state
+// functions are internal. reader.ts exposes authenticated, redacted reads.
 //
 // 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`, `getOutput`, and `readStack` by name, and an older client
-// calls an older set of names. Add functions; never rename or remove one.
+// stage collect all rows. Samebase reads `stacks`, `getOutput`, and
+// `readStack` by name: a renamed function is a version bump of the store and
+// of Samebase.
 import { v } from "convex/values";
-import type { QueryCtx } from "./_generated/server.js";
+import type { MutationCtx, QueryCtx } from "./_generated/server.js";
 import { internalMutation, internalQuery } from "./_generated/server.js";
+import { runRecord } from "./runRecord.ts";
+import type { RunRecord } from "../../RunRecord.ts";
 import { STORE_VERSION } from "./version.ts";
 
 /** The wire version of this store, compared with the client's STORE_VERSION. */
@@ -44,6 +43,18 @@ const outputOf = (ctx: QueryCtx, args: { stack: string; stage: string }) =>
     .withIndex("by_stage", (q) => q.eq("stack", args.stack).eq("stage", args.stage))
     .unique();
 
+/** A resource write and its current run become visible in one transaction. */
+const writeCurrentRun = async (
+  ctx: MutationCtx,
+  args: { stack: string; stage: string; run?: RunRecord | undefined },
+) => {
+  const output = await outputOf(ctx, args);
+  // A write without a run record clears the record of the previous run.
+  if (output !== null) await ctx.db.patch("outputs", output._id, { currentRun: args.run });
+  else if (args.run !== undefined)
+    await ctx.db.insert("outputs", { stack: args.stack, stage: args.stage, currentRun: args.run });
+};
+
 /** The sorted union of two lists of names. */
 const union = (a: readonly string[], b: readonly string[]) => [...new Set([...a, ...b])].sort();
 
@@ -153,22 +164,30 @@ export const replaced = internalQuery({
 });
 
 export const set = internalMutation({
-  args: { ...resource, value: v.string() },
+  args: { ...resource, value: v.string(), run: v.optional(runRecord) },
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await rowOf(ctx, args);
-    if (row === null) await ctx.db.insert("resources", args);
+    if (row === null)
+      await ctx.db.insert("resources", {
+        stack: args.stack,
+        stage: args.stage,
+        fqn: args.fqn,
+        value: args.value,
+      });
     else await ctx.db.patch("resources", row._id, { value: args.value });
+    await writeCurrentRun(ctx, args);
     return null;
   },
 });
 
 export const remove = internalMutation({
-  args: resource,
+  args: { ...resource, run: v.optional(runRecord) },
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await rowOf(ctx, args);
     if (row !== null) await ctx.db.delete("resources", row._id);
+    await writeCurrentRun(ctx, args);
     return null;
   },
 });
@@ -208,12 +227,14 @@ export const getOutput = internalQuery({
 });
 
 export const setOutput = internalMutation({
-  args: { ...stage, value: v.string() },
+  args: { ...stage, value: v.string(), run: v.optional(runRecord) },
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await outputOf(ctx, args);
-    if (row === null) await ctx.db.insert("outputs", args);
+    if (row === null)
+      await ctx.db.insert("outputs", { stack: args.stack, stage: args.stage, value: args.value });
     else await ctx.db.patch("outputs", row._id, { value: args.value });
+    await writeCurrentRun(ctx, args);
     return null;
   },
 });
@@ -235,6 +256,7 @@ export const readStack = internalQuery({
         stage: v.string(),
         resources: v.array(v.object({ fqn: v.string(), value: v.string() })),
         output: v.union(v.string(), v.null()),
+        record: v.union(runRecord, v.null()),
       }),
     ),
   }),
@@ -253,13 +275,17 @@ export const readStack = internalQuery({
       [...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,
-      })),
+      stages: stages.map((stage) => {
+        const output = outputs.find((row) => row.stage === stage);
+        return {
+          stage,
+          resources: resources
+            .filter((row) => row.stage === stage)
+            .map((row) => ({ fqn: row.fqn, value: row.value })),
+          output: output?.value ?? null,
+          record: output?.currentRun ?? null,
+        };
+      }),
     };
   },
 });

package/src/store/convex/version.ts

@@ -1,10 +1,12 @@
 // 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 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.
+// older one or has no `version` yet, and fails the run on a newer one. Raise
+// it with each change of a function. The store and its readers (Samebase) are
+// released and upgraded together: a renamed function is a version bump on
+// both sides.
 //
 // 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;
+// 3: authenticated subscriptions and current stage run records (0.9.0).
+export const STORE_VERSION = 3;

package/src/store/package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "convex": "^1.46.0"
+    "convex": "^1.48.0"
   }
 }