@effected/github-actions 0.12.0 → 0.13.1

package/PackageManagerInstaller.js

@@ -1,9 +1,12 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
+import { unstubbed } from "./internal/unstubbed.js";
+import { digestFileHex } from "./internal/digest.js";
+import { isWindowsRunner, toolCacheRoot } from "./internal/runner.js";
+import { typeAt } from "./internal/fsProbe.js";
 import { ToolInstaller } from "./ToolInstaller.js";
-import { Context, Effect, FileSystem, Layer, Option, Path, Schema, Stream } from "effect";
-import { createHash } from "node:crypto";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { PackageManagerPinName } from "@effected/npm";
+import { DEFAULT_REGISTRY, PackageManagerPinName } from "@effected/npm";
 
 //#region src/PackageManagerInstaller.ts
 /**
@@ -130,7 +133,6 @@ var CachedPackageManager = class extends Schema.Class("CachedPackageManager")({
 * @public
 */
 const InstalledPackageManager = Schema.Union([AmbientPackageManager, CachedPackageManager]);
-const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 /** The shim directory name inside a cached npm-registry-manager entry. */
 const SHIM_DIR = ".bin";
 /**
@@ -149,9 +151,18 @@ const cmdShim = (target) => `@echo off\r\nnode "${target}" %*\r\n`;
 * bun's spelling (`macOS` → `darwin`) and the Node arch spelling to bun's
 * (`arm64` → `aarch64`).
 */
+const BUN_OS = {
+	linux: "linux",
+	macos: "darwin",
+	windows: "windows"
+};
+const BUN_CPU = {
+	x64: "x64",
+	arm64: "aarch64"
+};
 const bunTarget = (runnerOs, arch) => {
-	const os = runnerOs.toLowerCase() === "linux" ? "linux" : runnerOs.toLowerCase() === "macos" ? "darwin" : runnerOs.toLowerCase() === "windows" ? "windows" : void 0;
-	const cpu = arch === "x64" ? "x64" : arch === "arm64" ? "aarch64" : void 0;
+	const os = BUN_OS[runnerOs.toLowerCase()];
+	const cpu = BUN_CPU[arch];
 	return os === void 0 || cpu === void 0 ? Option.none() : Option.some(`bun-${os}-${cpu}`);
 };
 /**
@@ -174,7 +185,10 @@ const normalizeBins = (bin, fallbackName) => {
 	return Object.keys(entries).length === 0 ? Option.none() : Option.some(entries);
 };
 /** Map a `RUNNER_ARCH` value (`X64`, `ARM64`) onto the Node arch spelling. */
-const archFromRunner = (runnerArch) => runnerArch.toLowerCase() === "x64" ? "x64" : runnerArch.toLowerCase() === "arm64" ? "arm64" : runnerArch;
+const archFromRunner = (runnerArch) => {
+	const lowered = runnerArch.toLowerCase();
+	return lowered === "x64" || lowered === "arm64" ? lowered : runnerArch;
+};
 const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
 	const fs = yield* FileSystem.FileSystem;
@@ -186,11 +200,11 @@ const make = Effect.gen(function* () {
 		onNone: () => process.arch,
 		onSome: archFromRunner
 	}));
-	const windows = runnerOs.toLowerCase() === "windows";
+	const windows = yield* isWindowsRunner(env);
 	const bunBinaryName = windows ? "bun.exe" : "bun";
 	const shimFileName = (name) => windows ? `${name}.cmd` : name;
 	const shimBody = windows ? cmdShim : posixShim;
-	const cacheRoot = yield* Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
+	const cacheRoot = yield* toolCacheRoot(env, path);
 	const finalCachePath = (tool, version) => ToolInstaller.cachePath({
 		root: cacheRoot,
 		tool,
@@ -209,16 +223,11 @@ const make = Effect.gen(function* () {
 		cause
 	});
 	/** The hex digest of a file's bytes, streamed rather than buffered. */
-	const hashFile = (pin, file, algorithm) => Effect.suspend(() => {
-		const digest = createHash(algorithm);
-		return fs.stream(file).pipe(Stream.runForEach((chunk) => Effect.sync(() => {
-			digest.update(chunk);
-		})), Effect.map(() => digest.digest("hex")), Effect.mapError((cause) => errorFor(pin)({
-			reason: "integrityMismatch",
-			subject: file,
-			cause
-		})));
-	});
+	const hashFile = (pin, file, algorithm) => digestFileHex(fs, file, algorithm).pipe(Effect.mapError((cause) => errorFor(pin)({
+		reason: "integrityMismatch",
+		subject: file,
+		cause
+	})));
 	/**
 	* Verify a downloaded artifact against the pin's integrity, fail-closed.
 	*
@@ -250,8 +259,7 @@ const make = Effect.gen(function* () {
 	*/
 	const ambientNpmVersion = Effect.map(Effect.result(spawner.string(ChildProcess.make("npm", ["--version"]))), (result) => result._tag === "Success" ? Option.some(result.success.trim()) : Option.none());
 	const assertFile = (pin, file, subject) => Effect.gen(function* () {
-		const stat = yield* Effect.result(fs.stat(file));
-		if (stat._tag !== "Success" || stat.success.type !== "File") return yield* Effect.fail(errorFor(pin)({
+		if ((yield* typeAt(fs, file)) !== "File") return yield* Effect.fail(errorFor(pin)({
 			reason: "layoutUnexpected",
 			subject
 		}));
@@ -319,8 +327,7 @@ const make = Effect.gen(function* () {
 		for (const [name, relative] of Object.entries(bins)) {
 			const shim = path.join(shimDir, shimFileName(name));
 			if (options.skipExisting) {
-				const present = yield* Effect.result(fs.stat(shim));
-				if (present._tag === "Success" && present.success.type === "File") continue;
+				if ((yield* typeAt(fs, shim)) === "File") continue;
 			}
 			yield* fs.writeFileString(shim, shimBody(path.join(finalDirectory, relative))).pipe(Effect.mapError(cacheError(shim)));
 			if (!windows) yield* fs.chmod(shim, 493).pipe(Effect.mapError(cacheError(shim)));
@@ -386,8 +393,7 @@ const make = Effect.gen(function* () {
 		if (!berry) yield* verifyIntegrity(pin, archive);
 		const extracted = yield* installer.extractTar(archive).pipe(Effect.mapError(fromInstaller(pin)));
 		const packageDir = path.join(extracted, "package");
-		const stat = yield* Effect.result(fs.stat(packageDir));
-		if (stat._tag !== "Success" || stat.success.type !== "Directory") return yield* Effect.fail(errorFor(pin)({
+		if ((yield* typeAt(fs, packageDir)) !== "Directory") return yield* Effect.fail(errorFor(pin)({
 			reason: "layoutUnexpected",
 			subject: "tarball has no package/ root"
 		}));
@@ -437,9 +443,7 @@ const make = Effect.gen(function* () {
 		return yield* installFromRegistry(pin, pin.name, registry);
 	}) };
 });
-const unimplemented = (member) => {
-	throw new Error(`PackageManagerInstaller.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("PackageManagerInstaller.makeTest");
 /**
 * First-class exact-version package-manager provisioning on a GitHub runner.
 *
@@ -483,7 +487,7 @@ var PackageManagerInstaller = class PackageManagerInstaller extends Context.Serv
 	static layer = Layer.effect(this, make);
 	/** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
 	static makeTest = (overrides = {}) => ({
-		install: () => Effect.sync(() => unimplemented("install")),
+		install: () => dies("install"),
 		...overrides
 	});
 	/** {@link PackageManagerInstaller.makeTest} behind `Layer.succeed`. */

package/ToolInstaller.js

@@ -1,4 +1,8 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
+import { unstubbed } from "./internal/unstubbed.js";
+import { isWindowsRunner, toolCacheRoot } from "./internal/runner.js";
+import { spawnOnce } from "./internal/spawn.js";
+import { typeAt } from "./internal/fsProbe.js";
 import { Context, Effect, FileSystem, Layer, Option, Path, Schedule, Schema, Stream } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
@@ -61,11 +65,8 @@ const make = Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const http = yield* HttpClient.HttpClient;
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-	const root = yield* Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
-	const windows = yield* Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
-		onNone: () => false,
-		onSome: (os) => os.toLowerCase() === "windows"
-	}));
+	const root = yield* toolCacheRoot(env, path);
+	const windows = yield* isWindowsRunner(env);
 	const cachePath = (tool, version) => ToolInstaller.cachePath({
 		root,
 		tool,
@@ -93,30 +94,22 @@ const make = Effect.gen(function* () {
 	* the difference between "this is not a gzip archive" and "tar is not
 	* installed". Discarding it is what makes an extraction failure unactionable.
 	*
-	* **One spawn, not two — load-bearing.** The spawner's convenience members
-	* each spawn independently: `string` collects output without inspecting the
-	* exit code, and `exitCode` runs the command AGAIN (core's
-	* `ChildProcessSpawner.make` derives both from `spawn`). Calling them
-	* back-to-back double-executed every extraction — harmless for idempotent
-	* `tar`/`unzip -o`, but .NET's `ZipFile.ExtractToDirectory` refuses to
-	* overwrite, so the second run failed 5/5 on real Windows runners while the
-	* captured "complaint" was the FIRST run's silent success. Output and exit
-	* code must come from the same `spawn` handle.
+	* **One spawn, not two — load-bearing**, and why is spelled once in
+	* `internal/spawn.ts`: the double run failed 5/5 on real Windows runners
+	* because .NET's `ZipFile.ExtractToDirectory` refuses to overwrite.
 	*/
-	const extractWith = (command, archive) => Effect.scoped(Effect.gen(function* () {
-		const extractError = (cause) => new ToolInstallerError({
+	const extractWith = (command, archive) => Effect.gen(function* () {
+		const { output, code } = yield* spawnOnce(spawner, command).pipe(Effect.mapError((cause) => new ToolInstallerError({
 			reason: "extractFailed",
 			subject: archive,
 			cause
-		});
-		const handle = yield* spawner.spawn(command).pipe(Effect.mapError(extractError));
-		const output = yield* Stream.mkString(Stream.decodeText(handle.all)).pipe(Effect.mapError(extractError));
-		if ((yield* handle.exitCode.pipe(Effect.mapError(extractError))) !== 0) return yield* Effect.fail(new ToolInstallerError({
+		})));
+		if (code !== 0) return yield* Effect.fail(new ToolInstallerError({
 			reason: "extractFailed",
 			subject: archive,
 			stderr: output.trim()
 		}));
-	}));
+	});
 	/**
 	* Install a staged directory into the tool cache by renaming it into place.
 	*
@@ -191,7 +184,7 @@ const make = Effect.gen(function* () {
 			while: (error) => error.retryable
 		}));
 	});
-	const find = (tool, version) => Effect.map(Effect.result(fs.stat(cachePath(tool, version))), (result) => result._tag === "Success" && result.success.type === "Directory" ? Option.some(cachePath(tool, version)) : Option.none());
+	const find = (tool, version) => Effect.map(typeAt(fs, cachePath(tool, version)), (type) => type === "Directory" ? Option.some(cachePath(tool, version)) : Option.none());
 	const cacheFile = Effect.fn("ToolInstaller.cacheFile")(function* (source, name, tool, version) {
 		yield* Effect.annotateCurrentSpan({
 			tool,
@@ -252,8 +245,7 @@ const make = Effect.gen(function* () {
 			});
 			const cached = yield* find(options.tool, options.version);
 			if (Option.isSome(cached)) {
-				const present = yield* Effect.result(fs.stat(path.join(cached.value, options.binary)));
-				if (present._tag === "Success" && present.success.type === "File") return {
+				if ((yield* typeAt(fs, path.join(cached.value, options.binary))) === "File") return {
 					directory: cached.value,
 					binDir: cached.value
 				};
@@ -272,9 +264,7 @@ const make = Effect.gen(function* () {
 		})
 	};
 });
-const unimplemented = (member) => {
-	throw new Error(`ToolInstaller.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("ToolInstaller.makeTest");
 /**
 * Download, extract and cache a toolchain in the runner's tool cache.
 *
@@ -323,13 +313,13 @@ var ToolInstaller = class ToolInstaller extends Context.Service()("@effected/git
 	static cachePath = (options) => `${options.root}/${options.tool}/${options.version}/${options.arch}`;
 	/** A test double. Unstubbed members die rather than reporting a tool that is not there. */
 	static makeTest = (overrides = {}) => ({
-		find: () => Effect.sync(() => unimplemented("find")),
-		download: () => Effect.sync(() => unimplemented("download")),
-		extractTar: () => Effect.sync(() => unimplemented("extractTar")),
-		extractZip: () => Effect.sync(() => unimplemented("extractZip")),
-		cacheDir: () => Effect.sync(() => unimplemented("cacheDir")),
-		cacheFile: () => Effect.sync(() => unimplemented("cacheFile")),
-		provisionFile: () => Effect.sync(() => unimplemented("provisionFile")),
+		find: () => dies("find"),
+		download: () => dies("download"),
+		extractTar: () => dies("extractTar"),
+		extractZip: () => dies("extractZip"),
+		cacheDir: () => dies("cacheDir"),
+		cacheFile: () => dies("cacheFile"),
+		provisionFile: () => dies("provisionFile"),
 		...overrides
 	});
 	/** {@link ToolInstaller.makeTest} behind `Layer.succeed`. */

package/index.d.ts

@@ -586,6 +586,46 @@ export declare class DetachedOutputError extends DetachedOutputError_base {
  * @public
  */
 type ActionOutputError = RunnerFileUnavailableError | RunnerFileWriteError | InvalidOutputNameError | OutputEncodeError | DetachedOutputError;
+declare const RecordedOutput_base: Schema.Class<RecordedOutput, Schema.Struct<{
+  /** Which {@link ActionOutputsShape} member was called. */
+  readonly member: Schema.Literals<readonly ["set", "setJson", "summary", "exportVariable", "addPath", "setFailed", "setSecret"]>;
+  /** The output or variable name, for the members that take one. */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** What was published — value, message, path, content or secret — as the runner would have read it. */
+  readonly value: Schema.String;
+}>, {}>;
+/**
+ * One call an {@link ActionOutputs.recording} double observed.
+ *
+ * @remarks
+ * `value` is always the string the runner would have seen: for `setJson` that
+ * is the **encoded** JSON text, after the same schema encode the real layer
+ * performs, so a test asserting on it reads exactly what a later step's
+ * `steps.<id>.outputs.<name>` expression would. `name` is present for the
+ * members that take one (`set`, `setJson`, `exportVariable`) and absent
+ * otherwise.
+ *
+ * @public
+ */
+export declare class RecordedOutput extends RecordedOutput_base {}
+/**
+ * The member names a {@link RecordedOutput} can carry.
+ *
+ * @public
+ */
+type RecordedOutputMember = RecordedOutput["member"];
+/**
+ * What {@link ActionOutputs.recording} returns: the layer to provide and the
+ * journal it fills.
+ *
+ * @public
+ */
+interface RecordingOutputs {
+  /** An {@link ActionOutputs} whose every member records into this journal. */
+  readonly layer: Layer.Layer<ActionOutputs>;
+  /** A snapshot of every recorded call so far, in call order. */
+  readonly entries: () => ReadonlyArray<RecordedOutput>;
+}
 /**
  * The {@link ActionOutputs} service shape.
  *
@@ -674,10 +714,49 @@ export declare class ActionOutputs extends ActionOutputs_base {
    *   channel to fail through.
    */
   static readonly layerDetached: Layer.Layer<ActionOutputs>;
-  /** A test double. Unstubbed members die rather than silently succeeding. */
+  /**
+   * A test double. Unstubbed members die rather than silently succeeding.
+   *
+   * @remarks
+   * **`setJson` always encodes first.** The value is encoded through its
+   * schema exactly as the real layer does — failing typed with
+   * {@link OutputEncodeError} — and only then is a supplied `setJson`
+   * override called, with the original `(name, value, schema)`. An override
+   * that accepts `schema` and ignores it therefore **cannot disable
+   * output-schema checking**: a value/schema drift is a typed failure under
+   * this double whether or not the override looks at the schema. Without an
+   * override, a valid value still dies unimplemented as every other unstubbed
+   * member does. Most tests want neither: reach for
+   * {@link ActionOutputs.recording} instead.
+   */
   static readonly makeTest: (overrides?: Partial<ActionOutputsShape>) => ActionOutputsShape;
   /** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
   static readonly layerTest: (overrides?: Partial<ActionOutputsShape>) => Layer.Layer<ActionOutputs>;
+  /**
+   * A recording double: every member appends a {@link RecordedOutput} to a
+   * journal the test reads back, in call order.
+   *
+   * @remarks
+   * This is the double most tests of an action want — "what did it publish?"
+   * — shipped so that nobody hand-writes a `setJson` override that drops the
+   * schema encode (the trap `makeTest` now closes too). `setJson` encodes
+   * through its schema exactly as the real layer does, failing typed with
+   * {@link OutputEncodeError} and recording nothing on a drift, and records
+   * the **encoded JSON text** — what the runner would have read — not the
+   * decoded value. `set`, `exportVariable` and `setJson` refuse an unusable
+   * name with {@link InvalidOutputNameError}, as the real layer does, rather
+   * than recording it.
+   *
+   * `setSecret` records the secret's **plaintext** under
+   * `member: "setSecret"`. That is deliberate for a recording double: the
+   * journal never leaves the test, and a test asserting that a value *was*
+   * masked needs to see which one. Do not hand this journal to anything that
+   * logs.
+   *
+   * Each call returns a fresh, independent journal — there is no state shared
+   * between two `recording()` calls.
+   */
+  static readonly recording: () => RecordingOutputs;
 }
 //#endregion
 //#region src/ActionState.d.ts
@@ -1228,20 +1307,30 @@ export declare class CacheKey extends CacheKey_base {
    *
    * @remarks
    * Discovery and matching are **two different jobs**, and separating them is
-   * what makes this testable and correct. The walk is core
-   * `FileSystem.readDirectory(recursive)`; the matching is `@effected/glob`'s
-   * full minimatch dialect — the same dialect `@actions/glob` uses, so a workflow
-   * author's `!**\/node_modules/**` behaves here exactly as it does in every
-   * other cache step in the same workflow. `node:fs.globSync` would have welded
-   * the two together behind one non-stubbable call *and* changed the dialect,
-   * and a dialect divergence surfaces as a silent cache-key difference — the
-   * worst failure mode a cache key has.
-   *
-   * Candidates are matched by their path **relative to the workspace**, which
-   * is what makes "never hash a file outside the workspace" structural rather
-   * than a rule someone has to remember. Directories are excluded: a directory
+   * what makes this testable and correct. The walk is `@effected/walker`'s
+   * `descend`, run once per include from that include's own literal prefix
+   * (a literal include is one `stat`, never a walk) with nothing pruned
+   * implicitly; the matching is `@effected/glob`'s full minimatch dialect —
+   * the same dialect `@actions/glob` uses, so a workflow author's
+   * `!**\/node_modules/**` behaves here exactly as it does in every other
+   * cache step in the same workflow. `node:fs.globSync` would have welded the
+   * two together behind one non-stubbable call *and* changed the dialect, and
+   * a dialect divergence surfaces as a silent cache-key difference — the worst
+   * failure mode a cache key has.
+   *
+   * Candidates are matched by their path **relative to the workspace**, and a
+   * literal that climbs above it (`../lockfile`) is dropped, which is what
+   * makes "never hash a file outside the workspace" structural rather than a
+   * rule someone has to remember. Directories are excluded: a directory
    * called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
-   * would fail rather than being ignored.
+   * would fail rather than being ignored. An absent literal is a miss; any
+   * other failure to read one is a typed `CacheKeyReadError`, because a key
+   * derived from an incomplete file set is wrong in a way nothing reports.
+   *
+   * **One knowing divergence from the runner's `hashFiles()`:** `descend`
+   * never enters a symlinked directory (cycle safety), where `@actions/glob`
+   * follows links by default. A file reachable only through a symlinked
+   * directory does not contribute to the key.
    *
    * The answer is sorted, so a caller cannot make its key depend on the order
    * the filesystem happened to report.
@@ -3349,7 +3438,7 @@ export declare class DetachedProcess {
    * yet, and silently retrying the first is how a misconfigured probe becomes a
    * timeout six seconds later with nothing to show for it.
    */
-  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<void, E | DetachedProcessError, R>;
+  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<undefined, E | DetachedNotReadyError, R>;
   /**
    * A readiness probe over HTTP: `true` when a `GET` answers 2xx.
    *
@@ -3471,15 +3560,6 @@ declare const DryRun_base: Context.ServiceClass<DryRun, "@effected/github-action
  * @public
  */
 export declare class DryRun extends DryRun_base {
-  /**
-   * Driven by the `dry-run` action input, defaulting to a real run.
-   *
-   * @remarks
-   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
-   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
-   * not quietly perform the mutations it meant to rehearse.
-   */
-  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
   /**
    * Driven by a named input.
    *
@@ -3489,6 +3569,15 @@ export declare class DryRun extends DryRun_base {
    * composition site.
    */
   static readonly layerFromInput: (name: string) => Layer.Layer<DryRun, Config.ConfigError>;
+  /**
+   * Driven by the `dry-run` action input, defaulting to a real run.
+   *
+   * @remarks
+   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
+   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
+   * not quietly perform the mutations it meant to rehearse.
+   */
+  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
   /** Driven by an explicit decision the caller has already made. */
   static readonly layerFrom: (enabled: boolean) => Layer.Layer<DryRun>;
   /**
@@ -4051,6 +4140,7 @@ declare const ManagedDocument_base: Schema.Class<ManagedDocument, Schema.Struct<
  * @public
  */
 export declare class ManagedDocument extends ManagedDocument_base {
+  #private;
   /**
    * Read a document out of existing text, or begin a fresh one.
    *
@@ -4137,6 +4227,9 @@ export declare class ManagedDocument extends ManagedDocument_base {
    * synchronous callers can use that variant directly.
    */
   withRegions(entries: ReadonlyArray<readonly [key: string, content: string, meta?: Readonly<Record<string, string>>]>): Effect.Effect<ManagedDocument, ManagedDocumentError>;
+  private scan;
+  /** What every wire key of this document's regions begins with. */
+  private get wirePrefix();
   /** The marker key a region is written under: `namespace.key.region`. */
   private wireKey;
   /** The region key back out of a wire key, for error reporting. */
@@ -4791,5 +4884,5 @@ export declare class Secret {
   static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
 }
 //#endregion
-export type { ActionCacheShape, ActionEnvironmentShape, ActionLoggerShape, ActionOutputError, ActionOutputsShape, ActionRunOptions, ActionServices, ActionStateShape, AnnotationProperties, ArtifactItem, ArtifactRef, ArtifactShape, BlobEnvelopeError, BlobStoreShape, CacheKeyError, CheckDocumentOptions, CheckDocumentShape, CheckDocumentSink, CheckFlushOutcome, CheckRunConclusion, CheckRunProjection, ClientLayerOptions, DataBlobTransfer, DetachedProcessError, DetachedProcessOps, DetachedSpawnOptions, DownloadOptions, DownloadResult, DryRunShape, ExtractOptions, FileBlobTransfer, GitHubHeadingDepth, GitHubListOptions, GitHubRowSchema, GitHubSchemaTable, GitHubSchemaTableColumn, GitHubSchemaTableColumns, GitHubSchemaTableFormatRequiredKeys, GitHubSchemaTableFormattedColumn, GitHubSchemaTableOptions, ManagedDocumentSource, OidcTokenIssuerShape, PackageManagerInstallOptions, PackageManagerInstallerShape, PairsOptions, PathPrependEnv, PathPrependOptions, ProvisionFileOptions, ProvisionOptions, ProvisionedFile, ReadOptions, ReadinessOptions, S3Config, StoredBlob, ToolDownloadOptions, ToolInstallerShape, UploadOptions, UploadResult, WithBufferOptions, WithStepOptions };
+export type { ActionCacheShape, ActionEnvironmentShape, ActionLoggerShape, ActionOutputError, ActionOutputsShape, ActionRunOptions, ActionServices, ActionStateShape, AnnotationProperties, ArtifactItem, ArtifactRef, ArtifactShape, BlobEnvelopeError, BlobStoreShape, CacheKeyError, CheckDocumentOptions, CheckDocumentShape, CheckDocumentSink, CheckFlushOutcome, CheckRunConclusion, CheckRunProjection, ClientLayerOptions, DataBlobTransfer, DetachedProcessError, DetachedProcessOps, DetachedSpawnOptions, DownloadOptions, DownloadResult, DryRunShape, ExtractOptions, FileBlobTransfer, GitHubHeadingDepth, GitHubListOptions, GitHubRowSchema, GitHubSchemaTable, GitHubSchemaTableColumn, GitHubSchemaTableColumns, GitHubSchemaTableFormatRequiredKeys, GitHubSchemaTableFormattedColumn, GitHubSchemaTableOptions, ManagedDocumentSource, OidcTokenIssuerShape, PackageManagerInstallOptions, PackageManagerInstallerShape, PairsOptions, PathPrependEnv, PathPrependOptions, ProvisionFileOptions, ProvisionOptions, ProvisionedFile, ReadOptions, ReadinessOptions, RecordedOutputMember, RecordingOutputs, S3Config, StoredBlob, ToolDownloadOptions, ToolInstallerShape, UploadOptions, UploadResult, WithBufferOptions, WithStepOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,7 +2,7 @@ import { ActionEnvironment, ActionEnvironmentError, GitHubContext, RunnerContext
 import { ActionInput } from "./ActionInput.js";
 import { WorkflowCommand } from "./WorkflowCommand.js";
 import { ActionLogger } from "./ActionLogger.js";
-import { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RunnerFileUnavailableError, RunnerFileWriteError } from "./ActionOutputs.js";
+import { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RecordedOutput, RunnerFileUnavailableError, RunnerFileWriteError } from "./ActionOutputs.js";
 import { ActionState, ActionStateError } from "./ActionState.js";
 import { Action, ActionRuntime, describeCause } from "./Action.js";
 import { BlobTransferError } from "./BlobTransfer.js";
@@ -27,4 +27,4 @@ import { GitHubToken, GitHubTokenError } from "./GitHubToken.js";
 import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
 import { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError } from "./PackageManagerInstaller.js";
 
-export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcClaims, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };
+export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcClaims, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };

package/internal/actionsResults.js

@@ -1,3 +1,4 @@
+import { payloadOf } from "./jwt.js";
 import { Effect, Option, Redacted, Result } from "effect";
 
 //#region src/internal/actionsResults.ts
@@ -18,20 +19,13 @@ const RESULTS_URL = "ACTIONS_RESULTS_URL";
 /** The variable holding the run-scoped credential. Absent outside a `uses:` step. */
 const RUNTIME_TOKEN = "ACTIONS_RUNTIME_TOKEN";
 /**
-* Decode a JWT payload segment.
+* The `misconfigured` detail every results-backend consumer reports when
+* {@link resultsBackend} fails: names the missing variable, and says why it is
+* missing — the single most common misuse of these services.
 *
-* @remarks
-* No signature verification, deliberately and for the same reason
-* `OidcTokenIssuer` gives: the token was handed to this process by the runner
-* that started it, and the claim read here scopes a request rather than
-* authorizing one.
+* @internal
 */
-const payloadOf = (token) => {
-	const segments = token.split(".");
-	if (segments.length !== 3) throw new Error(`expected a three-segment JWT, got ${segments.length}`);
-	const json = Buffer.from(segments[1] ?? "", "base64url").toString("utf8");
-	return JSON.parse(json);
-};
+const misconfiguredDetail = (variable, service) => `${variable} is not set — the ${service} is only reachable from a \`uses:\` step, never from \`run:\``;
 /**
 * The run and job ids the artifact protocol needs, from the runtime token's
 * `scp` claim.
@@ -44,13 +38,9 @@ const payloadOf = (token) => {
 * @internal
 */
 const backendIdsFrom = (token) => {
-	let payload;
-	try {
-		payload = payloadOf(token);
-	} catch (cause) {
-		return Result.fail(`the runtime token is not a readable JWT: ${cause instanceof Error ? cause.message : cause}`);
-	}
-	const scope = payload.scp;
+	const payload = payloadOf(token);
+	if (Result.isFailure(payload)) return Result.fail(`the runtime token is not a readable JWT: ${payload.failure.detail}`);
+	const scope = payload.success?.scp;
 	if (typeof scope !== "string") return Result.fail("the runtime token carries no `scp` claim");
 	for (const entry of scope.split(" ")) {
 		const parts = entry.split(":");
@@ -95,4 +85,4 @@ const resultsBackend = (env) => Effect.gen(function* () {
 });
 
 //#endregion
-export { RESULTS_URL, RUNTIME_TOKEN, backendIdsFrom, resultsBackend };
+export { RESULTS_URL, RUNTIME_TOKEN, backendIdsFrom, misconfiguredDetail, resultsBackend };

package/internal/cacheService.js

@@ -0,0 +1,70 @@
+import { CONFLICT, isOk, stringField } from "./twirp.js";
+import { Effect, Option } from "effect";
+
+//#region src/internal/cacheService.ts
+/**
+* The Actions `CacheService` choreography — reserve, upload, finalize; look up
+* — spelled once for the two services that speak it.
+*
+* @remarks
+* `ActionCache` files a tar archive under a path-derived version and
+* `BlobStore.githubCache` files an envelope under a constant one, but the
+* three RPCs between them and their conflict semantics are identical. Each
+* caller supplies its own per-key `call` and its own `refused` constructor, so
+* the errors stay the caller's; this module owns only the protocol. It reaches
+* `effect` and the Twirp client and nothing heavier — the Azure transfer of
+* the bytes between the two RPCs stays in the three modules licensed to import
+* it (`__test__/reachability.test.ts`).
+*
+* @internal
+*/
+/** The Twirp service the Actions cache protocol lives under. @internal */
+const CACHE_SERVICE = "github.actions.results.api.v1.CacheService";
+/**
+* Reserve `(key, version)` for an upload. `Option.none()` means another job
+* saved this key first — entries are immutable, so the cache already holds
+* what the caller wanted and there is nothing left to do.
+*
+* @internal
+*/
+const reserveUpload = (client, key, version) => Effect.flatMap(client.call("CreateCacheEntry", {
+	key,
+	version
+}), (created) => {
+	if (created === CONFLICT) return Effect.succeedNone;
+	const url = stringField(created, "signedUploadUrl");
+	return !isOk(created) || url === void 0 ? Effect.fail(client.refused("CreateCacheEntry returned no upload url")) : Effect.succeedSome(url);
+});
+/**
+* Confirm an upload. Not folded in with the reservation: an unfinalized upload
+* leaves bytes in Azure that no lookup can reach — a silent no-op that reads
+* as a successful save — so it is a failure even though every byte arrived.
+*
+* @internal
+*/
+const finalizeUpload = (client, key, version, sizeBytes) => Effect.flatMap(client.call("FinalizeCacheEntryUpload", {
+	key,
+	version,
+	size_bytes: String(sizeBytes)
+}), (finalized) => finalized === CONFLICT || !isOk(finalized) ? Effect.fail(client.refused("FinalizeCacheEntryUpload did not confirm the upload")) : Effect.void);
+/**
+* The signed download url for a key, walking the restore-key ladder.
+* `Option.none()` is a miss, not a failure — a cold cache is the normal state.
+*
+* @internal
+*/
+const lookupDownload = (client, key, restoreKeys, version) => Effect.map(client.call("GetCacheEntryDownloadURL", {
+	key,
+	restore_keys: [...restoreKeys],
+	version
+}), (found) => {
+	if (found === CONFLICT || !isOk(found)) return Option.none();
+	const url = stringField(found, "signedDownloadUrl");
+	return url === void 0 ? Option.none() : Option.some({
+		url,
+		matchedKey: stringField(found, "matchedKey")
+	});
+});
+
+//#endregion
+export { CACHE_SERVICE, finalizeUpload, lookupDownload, reserveUpload };

package/internal/digest.js

@@ -0,0 +1,42 @@
+import { Effect, Encoding, Stream } from "effect";
+import { createHash } from "node:crypto";
+
+//#region src/internal/digest.ts
+/**
+* The sanctioned `node:crypto` digests, spelled once.
+*
+* @remarks
+* Core `Crypto` is RNG-only — no digest, no HMAC — so this package's licence
+* for a `node:` import covers hashing (`CLAUDE.md`). Keeping every `createHash`
+* behind this module is what makes that licence auditable in one place rather
+* than six, and keeps the streamed file digest — the shape a multi-gigabyte
+* toolchain archive needs — from being re-derived per caller.
+*
+* @internal
+*/
+/** The raw SHA-256 of a string or byte array held in memory. @internal */
+const sha256 = (value) => new Uint8Array(createHash("sha256").update(value).digest());
+/** The hex SHA-256 of a string or byte array held in memory. @internal */
+const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
+/**
+* The raw digest of a file's bytes under `algorithm`, streamed rather than
+* buffered. Raw, because a caller that folds several file digests into one
+* (`CacheKey.hashFiles`, byte-compatible with the runner's `hashFiles()`)
+* hashes the digest BYTES, not their hex spelling.
+*
+* `algorithm` must be one `node:crypto` supports — every caller's grammar
+* admits only `sha1`/`sha256`/`sha384`/`sha512`, so `createHash` cannot throw.
+*
+* @internal
+*/
+const digestFile = (fs, file, algorithm) => Effect.suspend(() => {
+	const accumulator = createHash(algorithm);
+	return Stream.runForEach(fs.stream(file), (chunk) => Effect.sync(() => {
+		accumulator.update(chunk);
+	})).pipe(Effect.map(() => new Uint8Array(accumulator.digest())));
+});
+/** {@link digestFile}, as hex. @internal */
+const digestFileHex = (fs, file, algorithm) => Effect.map(digestFile(fs, file, algorithm), Encoding.encodeHex);
+
+//#endregion
+export { digestFile, digestFileHex, sha256, sha256Hex };