@samebase/alchemy-convex 0.6.1 → 0.8.0

package/package.json

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

package/src/Deployment.ts

@@ -2,8 +2,14 @@
 // variables, and its functions, with the URLs that a frontend or a Worker
 // needs. This is the Convex plane of a stack: no deploy key leaves it.
 //
-// - `source` is the Convex functions directory, such as `./convex`. The
-//   update pushes it with the Convex CLI that the app installed (Push.ts).
+// - `rootDir` is the app directory, relative to the directory where the
+//   deploy runs (the directory of the stack file), such as `apps/web`, and
+//   "." by default. The push runs in it, and `source` is relative to it.
+//   The constructor writes it into the props, "." included, so that a reader
+//   of the state row finds the app directory of every deployment.
+// - `source` is the Convex functions directory relative to `rootDir`, such
+//   as `./convex`. The update pushes it with the Convex CLI that the app
+//   installed (Push.ts).
 //   The content identity of the push is a hash of the source files, the
 //   app's package.json, convex.json, and lockfile, the deployment name, and
 //   `env`. The same hash is a no-op. The hash is taken again after the push,
@@ -45,9 +51,11 @@
 //
 // Patterns from Confect `packages/alchemy/src/Deployment.ts`
 // (https://github.com/rjdellecese/confect, ISC license, see NOTICE).
+import { posix, win32 } from "node:path";
 import { Resource } from "alchemy";
 import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
 import { isResolved } from "alchemy/Diff";
+import type { InputProps } from "alchemy/Input";
 import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
@@ -79,10 +87,16 @@ interface DeploymentInputs {
   /** The project: a Convex.Project resource, or `{ projectId }`. Cannot change. */
   readonly project: { readonly projectId: number };
   /**
-   * The Convex functions directory, such as `./convex`, or that directory
-   * with a push command and more hashed files. The push runs in the nearest
-   * directory above it with a package.json. Without `source`, the resource
-   * pushes nothing.
+   * The app directory, relative to the directory where the deploy runs (the
+   * directory of the stack file), such as `apps/web`. Default ".". It must
+   * have a package.json. The push runs in it, and `source` is relative to
+   * it. State from 0.7 has no `rootDir`.
+   */
+  readonly rootDir?: string;
+  /**
+   * The Convex functions directory relative to `rootDir`, such as
+   * `./convex`, or that directory with a push command and more hashed
+   * files. Without `source`, the resource pushes nothing.
    */
   readonly source?: Source;
   /** Environment variables to set on the deployment before the push. */
@@ -134,10 +148,61 @@ export type Deployment = Resource<
   never,
   Providers
 >;
-export const Deployment = Resource<Deployment>("Convex.Deployment", {
+/** The resource class. Stacks call {@link Deployment}, which writes `rootDir` into the props. */
+export const DeploymentResource = Resource<Deployment>("Convex.Deployment", {
   defaultRemovalPolicy: "retain",
 });
 
+/** The props of a `Convex.Deployment` call: Alchemy inputs, with `rootDir` a plain string. */
+export type DeploymentInput = DeploymentProps extends infer P
+  ? P extends DeploymentProps
+    ? InputProps<P, "rootDir">
+    : never
+  : never;
+
+/** `rootDir` in POSIX form, without "./" and a trailing slash, such as `apps/web` or ".". */
+const normalizeRootDir = (rootDir: string) => {
+  const normalized = posix.normalize(rootDir.replaceAll("\\", "/"));
+  return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+};
+
+/** `rootDir` is an absolute path. The declaration stops with it as a defect, before the plan. */
+export class AbsoluteRootDir extends Schema.TaggedError<AbsoluteRootDir>()("AbsoluteRootDir", {
+  rootDir: Schema.String,
+}) {
+  override get message() {
+    return `Convex.Deployment rootDir ${this.rootDir} is an absolute path. State keeps rootDir for every machine that runs the stack, so set it relative to the directory where the deploy runs, such as "apps/web".`;
+  }
+}
+
+/**
+ * `Convex.Deployment("id", props)`. The props go to state with `rootDir` in
+ * POSIX form, and with "." when it is not set, so that every row names the
+ * app directory of its deployment. An absolute `rootDir` stops the
+ * declaration, so it never reaches the plan or state. The check dies,
+ * because the program of `Alchemy.Stack` can fail only with a ConfigError.
+ * `win32.isAbsolute` also answers true for a POSIX absolute path. The other
+ * fields keep it usable where Alchemy takes a resource class, such as
+ * `Provider.collection`.
+ */
+export const Deployment = Object.assign(
+  (id: string, props: DeploymentInput) => {
+    const rootDir = props.rootDir ?? ".";
+    return win32.isAbsolute(rootDir)
+      ? Effect.die(new AbsoluteRootDir({ rootDir }))
+      : DeploymentResource(id, { ...props, rootDir: normalizeRootDir(rootDir) });
+  },
+  {
+    Type: DeploymentResource.Type,
+    Props: DeploymentResource.Props,
+    Self: DeploymentResource.Self,
+    Provider: DeploymentResource.Provider,
+    Aliases: DeploymentResource.Aliases,
+    ref: (id: string, options?: { stage?: string; stack?: string }) =>
+      DeploymentResource.ref(id, options),
+  },
+);
+
 /** The props name another deployment than the one in state. */
 export class DeploymentIdentityChange extends Schema.TaggedError<DeploymentIdentityChange>()(
   "DeploymentIdentityChange",
@@ -336,7 +401,7 @@ const isRefused = (error: ConvexApiError) =>
 
 export const DeploymentProvider = () =>
   Provider.effect(
-    Deployment,
+    DeploymentResource,
     Effect.gen(function* () {
       const api = yield* ManagementApi;
       const credentials = yield* Credentials;
@@ -517,10 +582,10 @@ export const DeploymentProvider = () =>
         });
 
       /** The content identity of `source` and `env` on a deployment, or undefined when there is nothing to push. */
-      const wantedHash = (news: DeploymentProps, deployment: string) =>
+      const wantedHash = (news: DeploymentProps, rootDir: string, deployment: string) =>
         news.source === undefined && Object.keys(news.env ?? {}).length === 0
           ? Effect.succeed(undefined)
-          : pushHash({ source: news.source, deployment, env: news.env ?? {} });
+          : pushHash({ rootDir, source: news.source, deployment, env: news.env ?? {} });
 
       return {
         // `name`, `reference`, and the URLs change when an expired preview is
@@ -529,10 +594,21 @@ export const DeploymentProvider = () =>
         stables: ["projectId", "type", "previewName"],
 
         // Compares with the attributes: after a refused change, `olds` are
-        // the refused props.
-        diff: Effect.fn(function* ({ news, output }) {
+        // the refused props. Only `rootDir` compares with `olds`, because it
+        // is in the props only. A refused update leaves the row `updating`,
+        // and the next plan updates it again anyway.
+        diff: Effect.fn(function* ({ news, olds, output }) {
           if (!isResolved(news) || output === undefined) return undefined;
           yield* checkIdentity(output, news);
+          // State from 0.7 has no rootDir; the constructor always writes it.
+          const rootDir = news.rootDir ?? ".";
+          // Also here, so that a wrong rootDir stops the plan before Apply
+          // writes the new props to the row.
+          if (news.source !== undefined) yield* checkSource(rootDir, news.source);
+          // State from 0.7 has no rootDir, and another rootDir is another
+          // app directory. The update writes the props to state; it pushes
+          // only when the hash changed.
+          if (olds.rootDir !== rootDir) return { action: "update" } as const;
           const access = yield* accessFor(addressOf(news), changesEnv(news, output));
           // A preview expires, anyone can delete a deployment, and another
           // production deployment can become the default. Reconcile then
@@ -540,7 +616,7 @@ export const DeploymentProvider = () =>
           // URL of a deployment that is gone.
           const current = yield* live(access, output);
           if (current?.name !== output.name) return { action: "update" } as const;
-          const hash = yield* wantedHash(news, output.name);
+          const hash = yield* wantedHash(news, rootDir, output.name);
           return hash === output.hash
             ? ({ action: "noop" } as const)
             : ({ action: "update" } as const);
@@ -581,8 +657,10 @@ export const DeploymentProvider = () =>
         reconcile: Effect.fn(function* ({ fqn, news, output }) {
           // Also here: with an unresolved prop in plan, diff could not check.
           if (output !== undefined) yield* checkIdentity(output, news);
-          // The functions directory and the program, before any change.
-          if (news.source !== undefined) yield* checkSource(news.source);
+          // The app directory, the functions directory, and the program,
+          // before any change.
+          const rootDir = news.rootDir ?? ".";
+          if (news.source !== undefined) yield* checkSource(rootDir, news.source);
           const address = addressOf(news);
           const access = yield* accessFor(address, changesEnv(news, output));
           const env = news.env ?? {};
@@ -597,7 +675,7 @@ export const DeploymentProvider = () =>
           const refuse = (name: string) =>
             new OwnedBySomeoneElse({
               message: `Project ${address.projectId} already has ${news.type} deployment ${name}${news.type === "prod" ? " with code" : ` named "${news.name}"`}. Re-run with --adopt to take it over${news.type === "prod" ? "" : ", or use another name"}.`,
-              resourceType: Deployment.Type,
+              resourceType: DeploymentResource.Type,
               physicalName: name,
             });
 
@@ -662,7 +740,7 @@ export const DeploymentProvider = () =>
           // Variables set on another deployment stay there: they are not ours
           // on this one.
           const previousEnvNames = output?.name === target.name ? envNamesOf(output) : [];
-          const before = yield* wantedHash(news, target.name);
+          const before = yield* wantedHash(news, rootDir, target.name);
           if (before === undefined && previousEnvNames.length === 0) {
             return { ...target, hash: undefined, envNames: [] };
           }
@@ -672,6 +750,7 @@ export const DeploymentProvider = () =>
           const options = {
             deployment: target.name,
             url: target.url,
+            rootDir,
             source: news.source,
             env,
             previousEnvNames,
@@ -719,7 +798,7 @@ export const DeploymentProvider = () =>
           // such as convex/_generated, are part of the identity.
           return {
             ...target,
-            hash: yield* wantedHash(news, target.name),
+            hash: yield* wantedHash(news, rootDir, target.name),
             envNames: Object.keys(env).sort(),
           };
         }),

package/src/Providers.ts

@@ -3,7 +3,7 @@
 import * as Provider from "alchemy/Provider";
 import * as Layer from "effect/Layer";
 import { type Credentials, fromConfig } from "./Credentials.ts";
-import { Deployment, DeploymentProvider } from "./Deployment.ts";
+import { DeploymentProvider, DeploymentResource } from "./Deployment.ts";
 import { ManagementApiLive } from "./ManagementApi.ts";
 import { Project, ProjectProvider } from "./Project.ts";
 
@@ -15,7 +15,7 @@ export class Providers extends Provider.ProviderCollection<Providers>()("Convex"
  * `CONVEX_DEPLOY_KEY`).
  */
 export const providers = (credentials: Layer.Layer<Credentials> = fromConfig()) =>
-  Layer.effect(Providers, Provider.collection([Project, Deployment])).pipe(
+  Layer.effect(Providers, Provider.collection([Project, DeploymentResource])).pipe(
     Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())),
     Layer.provide(ManagementApiLive()),
     Layer.provide(credentials),

package/src/Push.ts

@@ -48,13 +48,14 @@ import {
 export type EnvValue = string | Redacted.Redacted<string>;
 
 /**
- * The `source` prop: the Convex functions directory, such as `./convex`, or
- * that directory with a push command and more files for the content identity.
+ * The `source` prop: the Convex functions directory relative to the app
+ * directory (`rootDir`), such as `./convex`, or that directory with a push
+ * command and more files for the content identity.
  */
 export type Source =
   | string
   | {
-      /** The Convex functions directory, such as `./convex`. */
+      /** The Convex functions directory relative to the app directory, such as `./convex`. */
       readonly path: string;
       /**
        * Replaces `convex deploy`: a program and its arguments, run in the app
@@ -109,17 +110,20 @@ export class ConvexCliNotFound extends Schema.TaggedError<ConvexCliNotFound>()(
   { cwd: Schema.String },
 ) {
   override get message() {
-    return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set source to the functions directory of the app.`;
+    return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set rootDir to the directory of the app.`;
   }
 }
 
-/** No directory at or above the parent of `source` has a package.json. */
+/** The app directory (`rootDir`) has no package.json. */
 export class ConvexAppNotFound extends Schema.TaggedError<ConvexAppNotFound>()(
   "ConvexAppNotFound",
-  { source: Schema.String },
+  {
+    /** The app directory, resolved against the working directory of the deploy. */
+    rootDir: Schema.String,
+  },
 ) {
   override get message() {
-    return `Convex.Deployment found no package.json at or above the parent of ${this.source}. Set source to the functions directory of a Convex app, such as "./convex".`;
+    return `Convex.Deployment found no package.json in ${this.rootDir}. Set rootDir to the directory of the Convex app, relative to the directory where the deploy runs, such as "apps/web".`;
   }
 }
 
@@ -227,32 +231,27 @@ const outputTail = (text: string, secrets: readonly string[]) =>
 
 const valueOf = (value: EnvValue) => (Redacted.isRedacted(value) ? Redacted.value(value) : value);
 
-/** The app directory: the nearest directory at or above the parent of `source` with a package.json. */
-const appDirectoryOf = (source: string) =>
-  Effect.tryPromise({
-    try: async () => {
-      let directory = dirname(resolve(source));
-      while (true) {
-        try {
-          await access(join(directory, "package.json"));
-          return directory;
-        } catch {
-          const parent = dirname(directory);
-          if (parent === directory) throw new Error("no package.json");
-          directory = parent;
-        }
-      }
-    },
-    catch: () => new ConvexAppNotFound({ source }),
+/**
+ * The app directory: `rootDir` resolved against the working directory of the
+ * deploy. It must have a package.json. There is no search above it.
+ */
+const appDirectoryOf = (rootDir: string) => {
+  const directory = resolve(rootDir);
+  return Effect.tryPromise({
+    try: () => access(join(directory, "package.json")).then(() => directory),
+    catch: () => new ConvexAppNotFound({ rootDir: directory }),
   });
+};
 
-/** `source` is not the functions directory that the Convex CLI pushes from this app. */
+/** `source` is not the functions directory that the Convex CLI pushes from the app directory. */
 export class SourceMismatch extends Schema.TaggedError<SourceMismatch>()("SourceMismatch", {
+  /** The app directory, resolved. */
+  rootDir: Schema.String,
   source: Schema.String,
   functions: Schema.String,
 }) {
   override get message() {
-    return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} in this app (the "functions" field of convex.json, or convex/ by default). Set source to ${this.functions}.`;
+    return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} from the app directory ${this.rootDir} (the "functions" field of convex.json, or convex/ by default). Set rootDir to the directory of the Convex app, and source to its functions directory relative to rootDir, such as "./convex".`;
   }
 }
 
@@ -269,8 +268,8 @@ const checkFunctionsDirectory = (cwd: string, path: string) =>
         ? undefined
         : Schema.decodeUnknownSync(Schema.fromJsonString(ConvexJson))(text).functions;
     const functions = resolve(cwd, configured ?? "convex");
-    if (functions !== resolve(path)) {
-      return yield* new SourceMismatch({ source: resolve(path), functions });
+    if (functions !== path) {
+      return yield* new SourceMismatch({ rootDir: cwd, source: path, functions });
     }
   });
 
@@ -300,6 +299,8 @@ export const installedCli = (cwd: string) =>
  * A change in a workspace package outside the app directory is not seen.
  */
 export const pushHash = (options: {
+  /** The app directory, relative to the working directory of the deploy or absolute. */
+  readonly rootDir: string;
   readonly source: Source | undefined;
   readonly deployment: string;
   readonly env: Readonly<Record<string, EnvValue>>;
@@ -309,28 +310,32 @@ export const pushHash = (options: {
     const files =
       source === undefined
         ? undefined
-        : yield* appDirectoryOf(source.path).pipe(
-            Effect.flatMap((cwd) =>
-              hashDirectory({
+        : yield* appDirectoryOf(options.rootDir).pipe(
+            Effect.flatMap((cwd) => {
+              const functions = relative(cwd, resolve(cwd, source.path)).split("\\").join("/");
+              return hashDirectory({
                 cwd,
                 // By default every file of the app that git does not ignore,
-                // such as a module outside `source` that a function imports.
-                // `include` narrows it to the functions, the manifests, and
-                // the listed globs.
+                // such as a module outside `source` that a function imports,
+                // and the functions when convex.json puts them outside
+                // rootDir. `include` narrows it to the functions, the
+                // manifests, and the listed globs.
                 memo:
-                  source.include === undefined
-                    ? {}
-                    : {
+                  source.include !== undefined
+                    ? {
                         include: [
-                          `${relative(cwd, resolve(source.path)).split("\\").join("/")}/**`,
+                          `${functions}/**`,
                           "package.json",
                           "convex.json",
                           ...source.include,
                         ],
                         lockfile: true,
-                      },
-              }),
-            ),
+                      }
+                    : functions === ".." || functions.startsWith("../")
+                      ? { include: ["**/*", `${functions}/**`], lockfile: true }
+                      : {},
+              });
+            }),
           );
     const env = Object.entries(options.env)
       .map(([name, value]): readonly [string, string] => [name, valueOf(value)])
@@ -469,7 +474,9 @@ export interface PushOptions {
   readonly deployment: string;
   /** Client URL of the deployment. */
   readonly url: string;
-  /** The functions directory, or it with a push command. Without it, only the variables change. */
+  /** The app directory, relative to the working directory of the deploy or absolute. The push runs in it. */
+  readonly rootDir: string;
+  /** The functions directory relative to `rootDir`, or it with a push command. Without it, only the variables change. */
   readonly source: Source | undefined;
   readonly env: Readonly<Record<string, EnvValue>>;
   /** Names that an earlier push set on this deployment. Names that left `env` are removed. */
@@ -485,14 +492,14 @@ export interface PushOptions {
 
 /**
  * The app directory and the program of a push. Fails before any change when
- * `source` is not the functions directory of the app, or when the app has no
- * installed Convex CLI and no push command.
+ * `rootDir` has no package.json, when `source` is not the functions directory
+ * of the app, or when the app has no installed Convex CLI and no push command.
  */
-export const checkSource = (input: Source) =>
+export const checkSource = (rootDir: string, input: Source) =>
   Effect.gen(function* () {
     const source = sourceOf(input);
-    const cwd = yield* appDirectoryOf(source.path);
-    yield* checkFunctionsDirectory(cwd, source.path);
+    const cwd = yield* appDirectoryOf(rootDir);
+    yield* checkFunctionsDirectory(cwd, resolve(cwd, source.path));
     const program = source.command ?? (yield* installedCli(cwd));
     return { cwd, program };
   });
@@ -510,7 +517,10 @@ export const push = (
 ) =>
   Effect.gen(function* () {
     const source = options.source === undefined ? undefined : sourceOf(options.source);
-    const resolved = options.source === undefined ? undefined : yield* checkSource(options.source);
+    const resolved =
+      options.source === undefined
+        ? undefined
+        : yield* checkSource(options.rootDir, options.source);
     const cwd = resolved?.cwd;
     const program = resolved?.program;
     const env = Object.entries(options.env).sort(([a], [b]) => (a < b ? -1 : 1));

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;