@samebase/alchemy-convex 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",

package/src/RunRecord.ts

@@ -0,0 +1,208 @@
+// The run record: what the stage output says about the run that wrote it.
+// Alchemy state holds no time, author, commit, branch, or run (measured in
+// the Samebase research of 2026-10-21), so a state layer adds this record to
+// the output document under the reserved key `samebase.run`. The record
+// depends on no store: it comes from the GitHub Actions variables, or from
+// git on a laptop, and holds no secret. See docs/design/convex-state.md.
+import { execFile } from "node:child_process";
+import { readFile, realpath } from "node:fs/promises";
+import { relative, sep } from "node:path";
+import { promisify } from "node:util";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+/** The key of the record in the stage output document. */
+export const RUN_RECORD_KEY = "samebase.run";
+
+/** The name of the stack file. Alchemy resolves `--config` against the working directory and does not expose it to a state layer, so the record assumes the default name. */
+export const STACK_FILE_NAME = "alchemy.run.ts";
+
+/** Version 1 of the record. A reader validates `version` first. */
+export interface RunRecord {
+  readonly version: 1;
+  /** GitHub `owner/name`. */
+  readonly repository: string;
+  /** Path of the stack file from the repository root, POSIX separators, such as `apps/samebase/alchemy.run.ts`. */
+  readonly stackFile: string;
+  /** The branch that was deployed: the head branch of a pull request, else the pushed branch. */
+  readonly branch: string;
+  /** The pull request whose head was deployed, or null for a push and for a laptop. */
+  readonly pullRequest: number | null;
+  /** The commit that was deployed: the head of the pull request, else GITHUB_SHA, else git HEAD. */
+  readonly headCommit: string;
+  /** The GitHub Actions run and attempt, or null for a laptop. */
+  readonly runUrl: string | null;
+  readonly source: "github-actions" | "laptop";
+  /** ISO 8601, when the record was written. */
+  readonly recordedAt: string;
+}
+
+export class RunRecordError extends Schema.TaggedError<RunRecordError>()("RunRecordError", {
+  reason: Schema.String,
+}) {
+  override get message() {
+    return `The run record of the stage output cannot be made: ${this.reason}`;
+  }
+}
+
+/** Where the run happens: the working directory of the stack and the process environment. */
+export interface RunEnvironment {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/** The part of the GitHub Actions event payload that the record reads. A push event has no `pull_request`. */
+const EventPayload = Schema.Struct({
+  pull_request: Schema.optionalKey(
+    Schema.Struct({ number: Schema.Number, head: Schema.Struct({ sha: Schema.String }) }),
+  ),
+});
+
+/** `owner/name` of an https, ssh, or scp-like git URL with a host. A local path is not one. */
+const REMOTE_URL = /^(?:[a-z+]+:\/\/[^/]+\/|[^/@:]+@[^:/]+:)([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
+
+const execFileAsync = promisify(execFile);
+
+const now = Clock.currentTimeMillis.pipe(Effect.map((millis) => new Date(millis).toISOString()));
+
+const git = (cwd: string, args: readonly string[]) =>
+  Effect.tryPromise({
+    try: async () =>
+      (await execFileAsync("git", ["-C", cwd, ...args], { encoding: "utf8" })).stdout.trim(),
+    catch: (error) =>
+      new RunRecordError({
+        reason: `git ${args.join(" ")} failed in ${cwd} (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`,
+      }),
+  });
+
+/** The stack file from the repository root: the working directory below the git top level, plus {@link STACK_FILE_NAME}. */
+const stackFileOf = (cwd: string) =>
+  Effect.gen(function* () {
+    const top = yield* git(cwd, ["rev-parse", "--show-toplevel"]);
+    // git prints the real path, and the working directory can hold a symlink, such as macOS /tmp.
+    const [realTop, realCwd] = yield* Effect.tryPromise({
+      try: () => Promise.all([realpath(top), realpath(cwd)]),
+      catch: () => new RunRecordError({ reason: `${cwd} is gone` }),
+    });
+    const directory = relative(realTop, realCwd)
+      .split(sep)
+      .filter((part) => part !== "");
+    return [...directory, STACK_FILE_NAME].join("/");
+  });
+
+const variable = (env: RunEnvironment["env"], name: string) =>
+  Effect.suspend(() => {
+    const value = env[name];
+    return value === undefined || value === ""
+      ? Effect.fail(
+          new RunRecordError({ reason: `GITHUB_ACTIONS is true, and ${name} is not set` }),
+        )
+      : Effect.succeed(value);
+  });
+
+const fromGitHubActions = (where: RunEnvironment) =>
+  Effect.gen(function* () {
+    const { env } = where;
+    const repository = yield* variable(env, "GITHUB_REPOSITORY");
+    const refName = yield* variable(env, "GITHUB_REF_NAME");
+    const sha = yield* variable(env, "GITHUB_SHA");
+    const serverUrl = yield* variable(env, "GITHUB_SERVER_URL");
+    const runId = yield* variable(env, "GITHUB_RUN_ID");
+    const runAttempt = yield* variable(env, "GITHUB_RUN_ATTEMPT");
+    const eventPath = env["GITHUB_EVENT_PATH"];
+    const payload =
+      eventPath === undefined || eventPath === ""
+        ? undefined
+        : yield* Effect.tryPromise({
+            try: () => readFile(eventPath, "utf8"),
+            catch: () =>
+              new RunRecordError({ reason: `GITHUB_EVENT_PATH ${eventPath} cannot be read` }),
+          }).pipe(
+            Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(EventPayload))),
+            Effect.mapError((error) =>
+              error instanceof RunRecordError
+                ? error
+                : new RunRecordError({
+                    reason: `GITHUB_EVENT_PATH ${eventPath} is not an event payload`,
+                  }),
+            ),
+          );
+    const pullRequest = payload?.pull_request;
+    // GITHUB_SHA is the merge commit on a pull request event; the head of the pull request is what a person sees.
+    const headCommit = pullRequest?.head.sha ?? sha;
+    const headRef = env["GITHUB_HEAD_REF"];
+    const mergeRef = /^refs\/pull\/(\d+)\/merge$/.exec(env["GITHUB_REF"] ?? "");
+    const stackFile = yield* stackFileOf(where.cwd);
+    const record: RunRecord = {
+      version: 1,
+      repository,
+      stackFile,
+      branch: headRef === undefined || headRef === "" ? refName : headRef,
+      pullRequest: pullRequest?.number ?? (mergeRef === null ? null : Number(mergeRef[1])),
+      headCommit,
+      runUrl: `${serverUrl}/${repository}/actions/runs/${runId}/attempts/${runAttempt}`,
+      source: "github-actions",
+      recordedAt: yield* now,
+    };
+    return record;
+  });
+
+const fromGit = (where: RunEnvironment) =>
+  Effect.gen(function* () {
+    const { cwd } = where;
+    const origin = yield* git(cwd, ["remote", "get-url", "origin"]);
+    const match = REMOTE_URL.exec(origin);
+    if (match === null) {
+      return yield* new RunRecordError({
+        reason: `the origin remote of ${cwd} is not a git URL with a host and owner/name: ${origin}`,
+      });
+    }
+    const branch = yield* git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (branch === "HEAD") {
+      return yield* new RunRecordError({
+        reason: `the checkout at ${cwd} is on no branch (detached HEAD)`,
+      });
+    }
+    const record: RunRecord = {
+      version: 1,
+      repository: `${match[1]}/${match[2]}`,
+      stackFile: yield* stackFileOf(cwd),
+      branch,
+      pullRequest: null,
+      headCommit: yield* git(cwd, ["rev-parse", "HEAD"]),
+      runUrl: null,
+      source: "laptop",
+      recordedAt: yield* now,
+    };
+    return record;
+  });
+
+/**
+ * The record of this run: from the GitHub Actions variables and the event
+ * payload when GITHUB_ACTIONS is `true`, else from git in `cwd`, which needs
+ * a branch and an `origin` remote with `owner/name`. Fails when a value is
+ * missing; nothing is guessed.
+ */
+export const runRecord = (where: RunEnvironment): Effect.Effect<RunRecord, RunRecordError> =>
+  where.env["GITHUB_ACTIONS"] === "true" ? fromGitHubActions(where) : fromGit(where);
+
+/** A plain object, which a spread keeps whole. A Date, a Duration, or a Redacted value is an object too, and a spread loses it. */
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * The output document of a stage: the stack's output plus the record under
+ * {@link RUN_RECORD_KEY}, or undefined for an output with no place for the
+ * key: a string, an array, null, or an object that is not plain, such as a
+ * Date. A value that the stack itself put under the key stays.
+ */
+export const withRunRecord = (output: unknown, record: RunRecord): object | undefined =>
+  isPlainObject(output)
+    ? RUN_RECORD_KEY in output
+      ? output
+      : { ...output, [RUN_RECORD_KEY]: record }
+    : undefined;

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;
 }
 
 /**
@@ -385,6 +394,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 +421,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 +455,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

@@ -28,6 +28,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;