@effected/github-actions 0.14.0 → 0.16.0

package/ActionInput.js

@@ -176,6 +176,37 @@ var ActionInput = class ActionInput {
 		}));
 	}
 	/**
+	* An input that must be one of a closed set of strings, typed as their
+	* union.
+	*
+	* @remarks
+	* The match is **exact**: no trimming and no case folding, so `" pr"` and
+	* `"PR"` are both rejected for `["commit", "pr"]`. An action manifest
+	* declares the set in `options:`-style prose and the workflow author copies
+	* a value verbatim; the one thing worth tolerating there is nothing, because
+	* a tolerated near-miss is a value the manifest never named. Absent or `""`
+	* is **missing data** (see {@link ActionInput.string}) — `Config.withDefault`
+	* for an optional input. A present value outside the set fails carrying its
+	* `actual`, naming the input, the value and the allowed set, and is never
+	* swallowed by a default.
+	*
+	* Core's `Config.Literals` is the same idea over `Config.schema`; this one
+	* exists so the failure reads like every other `ActionInput` failure —
+	* naming the input by its action name, not its `INPUT_` variable.
+	*
+	* @example
+	* ```ts
+	* import { ActionInput } from "@effected/github-actions";
+	* import { Config } from "effect";
+	*
+	* // Config<"commit" | "pr">
+	* const mode = ActionInput.literals("mode", ["commit", "pr"]).pipe(Config.withDefault("commit"));
+	* ```
+	*/
+	static literals(name, allowed) {
+		return Config.String(inputVariable(name)).pipe(Config.mapEffect((raw) => allowed.includes(raw) ? Effect.succeed(raw) : Effect.fail(configError(`Input "${name}" must be one of: ${allowed.join(" | ")} — received "${raw}"`, raw))));
+	}
+	/**
 	* An integer input.
 	*
 	* @remarks
@@ -306,6 +337,12 @@ var ActionInput = class ActionInput {
 	* `Config.option` for an optional input. A present value that is not valid
 	* JSON, or does not satisfy the schema, fails carrying its `actual` and is
 	* never swallowed by a default.
+	*
+	* There is no `schemaOption`: `ActionInput.schema(name, S).pipe(Config.option)`
+	* yields `Config<Option<A>>` with missing → `None` and a malformed value
+	* still failing — core's documented `Config.option` behaviour ("validation
+	* errors ... still propagate", `Config.ts`), which is exactly the
+	* missing-versus-malformed split above.
 	*/
 	static schema(name, schema) {
 		return Config.String(inputVariable(name)).pipe(Config.mapEffect((raw) => {
@@ -352,7 +389,11 @@ var ActionInput = class ActionInput {
 	* to input-name entries too: `{ "flag": "" }` is an unsupplied input.
 	*
 	* Taking the environment as an argument rather than reading `process.env`
-	* is what makes inputs testable without mutating the test process.
+	* is what makes inputs testable without mutating the test process. The
+	* `process.env` default is a sanctioned exception to the package rule
+	* stated on `ChildEnv` (ambient process state is never read behind a
+	* caller's back) — a default the caller overrides by passing a value, the
+	* same class as `DetachedProcess.spawn`'s `base`.
 	*
 	* **A bare `ConfigProvider.fromEnv` cannot serve input-name keys.** Composed
 	* beneath this provider or {@link ActionInput.providerOver}, it uppercases

package/Artifact.js

@@ -6,10 +6,11 @@ import { CONFLICT, field, isOk, stringField, twirpCall, twirpFailureFields } fro
 import { digestFileHex } from "./internal/digest.js";
 import { isWindowsRunner } from "./internal/runner.js";
 import { spawnOnce } from "./internal/spawn.js";
+import { unzipCommand, zipCommand, zipManifest } from "./internal/archiveCommands.js";
 import { Context, Effect, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcessSpawner } from "effect/unstable/process";
 
 //#region src/Artifact.ts
 /**
@@ -195,31 +196,34 @@ const make = (transfer) => Effect.gen(function* () {
 		artifact,
 		cause
 	}));
-	const zip = (files, root, destination, level, artifact) => {
+	const zip = (files, root, destination, level, artifact) => Effect.gen(function* () {
 		const relative = files.map((file) => path.relative(root, file));
-		return windows ? archive(ChildProcess.make("pwsh", [
-			"-NoProfile",
-			"-NonInteractive",
-			"-Command",
-			`Compress-Archive -Path ${relative.map((file) => `'${file.replaceAll("'", "''")}'`).join(",")} -DestinationPath '${destination.replaceAll("'", "''")}' -Force`
-		], { cwd: root }), artifact) : archive(ChildProcess.make("zip", [
-			`-${Math.min(9, Math.max(0, Math.trunc(level)))}`,
-			"-qr",
+		const unrepresentable = relative.find((file) => file.includes("\n") || file.includes("\r"));
+		if (unrepresentable !== void 0) return yield* Effect.fail(new ArtifactError({
+			reason: "invalidOptions",
+			artifact,
+			detail: `a file path may not contain a line break: ${JSON.stringify(unrepresentable)}`
+		}));
+		const manifest = path.join(path.dirname(destination), "artifact.manifest");
+		if (windows) yield* fs.writeFileString(manifest, zipManifest(relative)).pipe(Effect.mapError((cause) => new ArtifactError({
+			reason: "archiveFailed",
+			artifact,
+			cause
+		})));
+		yield* archive(zipCommand({
+			windows,
+			root,
+			files: relative,
+			manifest,
 			destination,
-			...relative
-		], { cwd: root }), artifact);
-	};
-	const unzip = (source, destination, artifact) => windows ? archive(ChildProcess.make("pwsh", [
-		"-NoProfile",
-		"-NonInteractive",
-		"-Command",
-		`Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${source.replaceAll("'", "''")}', '${destination.replaceAll("'", "''")}')`
-	]), artifact) : archive(ChildProcess.make("unzip", [
-		"-oq",
+			level
+		}), artifact);
+	});
+	const unzip = (source, destination, artifact) => archive(unzipCommand({
+		windows,
 		source,
-		"-d",
 		destination
-	]), artifact);
+	}), artifact);
 	return {
 		upload: Effect.fn("Artifact.upload")(function* (name, files, rootDirectory, options) {
 			yield* Effect.annotateCurrentSpan({ name });

package/CacheKey.js

@@ -353,18 +353,22 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 	* 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
+	* literal that climbs above it (`../lockfile`) is dropped lexically — no
+	* literal reaches outside the workspace through path text. The walk is
+	* another matter: under `followSymlinks` a symlinked directory whose target
+	* lives outside the workspace IS descended, and its files DO contribute to
+	* the key — parity with `@actions/glob`, which follows links out of the
+	* tree too. Directories are excluded: a directory
 	* called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
 	* 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.
+	* Symlinked directories are followed (`descend` under
+	* `followSymlinks: true`), matching `@actions/glob`'s default
+	* `followSymbolicLinks: true` — a file reachable only through a symlinked
+	* directory contributes to the key, and `descend`'s real-path cycle guard
+	* keeps link loops finite.
 	*
 	* The answer is sorted, so a caller cannot make its key depend on the order
 	* the filesystem happened to report.
@@ -396,7 +400,8 @@ var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
 			if (wildcard.negated) continue;
 			const found = yield* descend(wildcard, {
 				cwd: workspace,
-				prune: []
+				prune: [],
+				followSymlinks: true
 			}).pipe(Effect.mapError((cause) => new CacheKeyReadError({
 				path: path.join(workspace, cause.path),
 				cause

package/ChildEnv.js

@@ -29,6 +29,16 @@
 * ambient process — the same species as `Secret`'s statics, one concern per
 * member.
 *
+* **The package rule, stated once: ambient process state is never read behind
+* a caller's back.** `process.env`, `process.arch` and `process.platform` are
+* read by `ActionEnvironment` (once, at layer construction) and otherwise
+* taken as an argument — which is what makes every platform branch
+* exercisable from a test on any host. The sanctioned exceptions are
+* *defaults a caller can override by passing the value*: `ActionInput.provider`'s
+* `env = process.env` and `DetachedProcess.spawn`'s `base`. A structural test
+* (`__test__/ambientReads.test.ts`) holds the list closed; a new default is
+* added there with its reason, never silently.
+*
 * @public
 */
 var ChildEnv = class ChildEnv {

package/DetachedProcess.js

@@ -1,4 +1,5 @@
 import { unstubbed } from "./internal/unstubbed.js";
+import { isErrno } from "./internal/fsProbe.js";
 import { Effect, Schedule, Schema } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
@@ -114,8 +115,6 @@ cause: Schema.optionalKey(Schema.Defect()) }) {
 * @public
 */
 const ProcessId = Schema.Number.pipe(Schema.check(Schema.makeFilter((value) => Number.isInteger(value) && value > 0 ? void 0 : "Expected a positive integer process id")), Schema.brand("ProcessId"));
-/** Whether a thrown value is a Node errno error with the given code. */
-const isErrno = (cause, code) => typeof cause === "object" && cause !== null && cause.code === code;
 /** See {@link DetachedProcess.makeTestOps}: an unstubbed member dies naming itself. */
 const dies = unstubbed("DetachedProcess.makeTestOps");
 /**
@@ -174,7 +173,7 @@ var DetachedProcess = class DetachedProcess {
 					const child = spawn(options.command, [...options.args ?? []], {
 						...options.cwd === void 0 ? {} : { cwd: options.cwd },
 						env: {
-							...process.env,
+							...options.base ?? process.env,
 							...options.env
 						},
 						detached: true,

package/PackageManagerInstaller.js

@@ -1,7 +1,7 @@
 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 { isWindowsRunner } from "./internal/runner.js";
 import { typeAt } from "./internal/fsProbe.js";
 import { PNPM_EXE_PREFIX, detectMusl, isNodeScript, pnpmExeTarget, strongestSri } from "./internal/pnpmExe.js";
 import { ToolInstaller } from "./ToolInstaller.js";
@@ -223,13 +223,6 @@ const make = Effect.gen(function* () {
 	const bunBinaryName = windows ? "bun.exe" : "bun";
 	const shimFileName = (name) => windows ? `${name}.cmd` : name;
 	const shimBody = windows ? cmdShim : posixShim;
-	const cacheRoot = yield* toolCacheRoot(env, path);
-	const finalCachePath = (tool, version) => ToolInstaller.cachePath({
-		root: cacheRoot,
-		tool,
-		version,
-		arch: process.arch
-	});
 	const errorFor = (pin) => (fields) => new PackageManagerInstallerError({
 		name: pin.name,
 		version: pin.version.toString(),
@@ -551,13 +544,9 @@ const make = Effect.gen(function* () {
 			yield* assertFile(pin, cli, "bin/yarn.js is missing from the cli-dist tarball");
 			yield* verifyIntegrity(pin, cli);
 		}
-		const destination = finalCachePath(name, version);
+		const destination = installer.cachePath(name, version);
 		yield* writeShims(pin, packageDir, destination, bins, { skipExisting: false });
 		const directory = yield* installer.cacheDir(packageDir, name, version).pipe(Effect.mapError(fromInstaller(pin)));
-		if (directory !== destination) return yield* Effect.fail(errorFor(pin)({
-			reason: "cacheFailed",
-			subject: `cache destination diverged: shims name ${destination}, entry landed at ${directory}`
-		}));
 		return CachedPackageManager.make({
 			name,
 			version,

package/ToolInstaller.js

@@ -2,10 +2,11 @@ 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 { tarExtractCommand, unzipCommand } from "./internal/archiveCommands.js";
+import { isErrno, 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";
+import { ChildProcessSpawner } from "effect/unstable/process";
 
 //#region src/ToolInstaller.ts
 /**
@@ -135,6 +136,29 @@ const make = Effect.gen(function* () {
 		subject: tool,
 		cause
 	})));
+	/**
+	* Move a source tree into the staging directory, consuming the source.
+	*
+	* @remarks
+	* A rename first: on the same filesystem it is O(1) however large the
+	* toolchain is, where a recursive copy of a hundreds-of-MB tree is the
+	* dominant cost of an install. The staging directory is removed before the
+	* rename because Windows refuses to rename onto an existing directory; its
+	* mktemp name stays reserved in practice. The copy fallback is taken ONLY
+	* for `EXDEV` — a cross-filesystem move, the one case a rename cannot do —
+	* and every other rename failure is reported as-is: a copy after a
+	* permission error would turn a real failure into a slow success. The
+	* fallback removes the source afterwards so the contract is the same on
+	* both paths; that removal is best-effort, since the entry is already
+	* complete and a leftover temp directory is not worth failing the install.
+	*/
+	const moveIntoStaging = (source, staging) => fs.remove(staging, {
+		recursive: true,
+		force: true
+	}).pipe(Effect.flatMap(() => fs.rename(source, staging)), Effect.catchIf((error) => isErrno(error.cause, "EXDEV"), () => fs.copy(source, staging, { overwrite: true }).pipe(Effect.andThen(Effect.ignore(fs.remove(source, {
+		recursive: true,
+		force: true
+	}))))));
 	/** A staging directory beside the cache, so the swap is a rename and not a copy. */
 	const staged = (tool, use) => Effect.gen(function* () {
 		yield* fs.makeDirectory(root, { recursive: true });
@@ -198,32 +222,24 @@ const make = Effect.gen(function* () {
 	});
 	return {
 		find,
+		cachePath,
 		download,
 		extractTar: Effect.fn("ToolInstaller.extractTar")(function* (archive, options) {
 			const destination = yield* destinationFor(options);
-			const flags = options?.flags === void 0 || options.flags.length === 0 ? ["xzf"] : [...options.flags];
-			yield* extractWith(ChildProcess.make("tar", [
-				...flags,
+			yield* extractWith(tarExtractCommand({
 				archive,
-				"-C",
-				destination
-			]), archive);
+				destination,
+				flags: options?.flags
+			}), archive);
 			return destination;
 		}),
 		extractZip: Effect.fn("ToolInstaller.extractZip")(function* (archive, options) {
 			const destination = yield* destinationFor(options);
-			const command = windows ? ChildProcess.make("pwsh", [
-				"-NoProfile",
-				"-NonInteractive",
-				"-Command",
-				`$ErrorActionPreference = 'Stop'; try { Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${archive.replaceAll("'", "''")}', '${destination.replaceAll("'", "''")}', $true) } catch { [Console]::Error.WriteLine($_.Exception.ToString()); exit 1 }`
-			]) : ChildProcess.make("unzip", [
-				"-oq",
-				archive,
-				"-d",
+			yield* extractWith(unzipCommand({
+				windows,
+				source: archive,
 				destination
-			]);
-			yield* extractWith(command, archive);
+			}), archive);
 			return destination;
 		}),
 		cacheDir: Effect.fn("ToolInstaller.cacheDir")(function* (source, tool, version) {
@@ -231,7 +247,7 @@ const make = Effect.gen(function* () {
 				tool,
 				version
 			});
-			return yield* staged(tool, (staging) => fs.copy(source, staging, { overwrite: true }).pipe(Effect.mapError((cause) => new ToolInstallerError({
+			return yield* staged(tool, (staging) => moveIntoStaging(source, staging).pipe(Effect.mapError((cause) => new ToolInstallerError({
 				reason: "cacheFailed",
 				subject: tool,
 				cause
@@ -266,6 +282,15 @@ const make = Effect.gen(function* () {
 });
 const dies = unstubbed("ToolInstaller.makeTest");
 /**
+* The root {@link ToolInstaller.makeTest}'s `cachePath` answers under: the
+* same resolution as `make`'s (`internal/runner.ts`), read from the ambient
+* environment because a double has no `ActionEnvironment` to ask. The literal
+* `/tmp/runner-tool-cache` is what `make`'s `path.join("/tmp", "runner-tool-cache")`
+* spells on POSIX, which is the only place a test double runs. Test-double
+* only; allowlisted as such in `__test__/ambientReads.test.ts`.
+*/
+const testRoot = () => process.env.RUNNER_TOOL_CACHE ?? "/tmp/runner-tool-cache";
+/**
 * Download, extract and cache a toolchain in the runner's tool cache.
 *
 * @remarks
@@ -311,9 +336,28 @@ var ToolInstaller = class ToolInstaller extends Context.Service()("@effected/git
 	* runner's `RUNNER_ARCH` (`X64`) for the same reason.
 	*/
 	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. */
+	/**
+	* A test double. Unstubbed members die rather than reporting a tool that is
+	* not there.
+	*
+	* @remarks
+	* `cachePath` is the one member with a default rather than a death: it is
+	* pure and total, and a caller composing it into shim contents would
+	* otherwise have to stub it in every test. The default is the static layout
+	* over `RUNNER_TOOL_CACHE`, or the same off-runner root `make` resolves
+	* (`internal/runner.ts`). **That is a read of the ambient environment**,
+	* sanctioned here only because a double has no `ActionEnvironment` to ask —
+	* test-double-only, and listed as such in the package's ambient-read
+	* allowlist (`__test__/ambientReads.test.ts`).
+	*/
 	static makeTest = (overrides = {}) => ({
 		find: () => dies("find"),
+		cachePath: (tool, version) => ToolInstaller.cachePath({
+			root: testRoot(),
+			tool,
+			version,
+			arch: process.arch
+		}),
 		download: () => dies("download"),
 		extractTar: () => dies("extractTar"),
 		extractZip: () => dies("extractZip"),

package/index.d.ts

@@ -1319,18 +1319,22 @@ export declare class CacheKey extends CacheKey_base {
    * 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
+   * literal that climbs above it (`../lockfile`) is dropped lexically — no
+   * literal reaches outside the workspace through path text. The walk is
+   * another matter: under `followSymlinks` a symlinked directory whose target
+   * lives outside the workspace IS descended, and its files DO contribute to
+   * the key — parity with `@actions/glob`, which follows links out of the
+   * tree too. Directories are excluded: a directory
    * called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
    * 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.
+   * Symlinked directories are followed (`descend` under
+   * `followSymlinks: true`), matching `@actions/glob`'s default
+   * `followSymbolicLinks: true` — a file reachable only through a symlinked
+   * directory contributes to the key, and `descend`'s real-path cycle guard
+   * keeps link loops finite.
    *
    * The answer is sorted, so a caller cannot make its key depend on the order
    * the filesystem happened to report.
@@ -1646,6 +1650,35 @@ export declare class ActionInput {
    * a malformed `dry-run` quietly reading as `false`.
    */
   static boolean(name: string): Config.Config<boolean>;
+  /**
+   * An input that must be one of a closed set of strings, typed as their
+   * union.
+   *
+   * @remarks
+   * The match is **exact**: no trimming and no case folding, so `" pr"` and
+   * `"PR"` are both rejected for `["commit", "pr"]`. An action manifest
+   * declares the set in `options:`-style prose and the workflow author copies
+   * a value verbatim; the one thing worth tolerating there is nothing, because
+   * a tolerated near-miss is a value the manifest never named. Absent or `""`
+   * is **missing data** (see {@link ActionInput.string}) — `Config.withDefault`
+   * for an optional input. A present value outside the set fails carrying its
+   * `actual`, naming the input, the value and the allowed set, and is never
+   * swallowed by a default.
+   *
+   * Core's `Config.Literals` is the same idea over `Config.schema`; this one
+   * exists so the failure reads like every other `ActionInput` failure —
+   * naming the input by its action name, not its `INPUT_` variable.
+   *
+   * @example
+   * ```ts
+   * import { ActionInput } from "@effected/github-actions";
+   * import { Config } from "effect";
+   *
+   * // Config<"commit" | "pr">
+   * const mode = ActionInput.literals("mode", ["commit", "pr"]).pipe(Config.withDefault("commit"));
+   * ```
+   */
+  static literals<const L extends readonly [string, ...Array<string>]>(name: string, allowed: L): Config.Config<L[number]>;
   /**
    * An integer input.
    *
@@ -1740,6 +1773,12 @@ export declare class ActionInput {
    * `Config.option` for an optional input. A present value that is not valid
    * JSON, or does not satisfy the schema, fails carrying its `actual` and is
    * never swallowed by a default.
+   *
+   * There is no `schemaOption`: `ActionInput.schema(name, S).pipe(Config.option)`
+   * yields `Config<Option<A>>` with missing → `None` and a malformed value
+   * still failing — core's documented `Config.option` behaviour ("validation
+   * errors ... still propagate", `Config.ts`), which is exactly the
+   * missing-versus-malformed split above.
    */
   static schema<A, I>(name: string, schema: Schema.Codec<A, I>): Config.Config<A>;
   /**
@@ -1776,7 +1815,11 @@ export declare class ActionInput {
    * to input-name entries too: `{ "flag": "" }` is an unsupplied input.
    *
    * Taking the environment as an argument rather than reading `process.env`
-   * is what makes inputs testable without mutating the test process.
+   * is what makes inputs testable without mutating the test process. The
+   * `process.env` default is a sanctioned exception to the package rule
+   * stated on `ChildEnv` (ambient process state is never read behind a
+   * caller's back) — a default the caller overrides by passing a value, the
+   * same class as `DetachedProcess.spawn`'s `base`.
    *
    * **A bare `ConfigProvider.fromEnv` cannot serve input-name keys.** Composed
    * beneath this provider or {@link ActionInput.providerOver}, it uppercases
@@ -2233,8 +2276,9 @@ interface UploadOptions {
    * The zlib level, 0–9, defaulting to 6 as `@actions/artifact` does.
    *
    * @remarks
-   * Out-of-range values are clamped. No effect on Windows, where
-   * `Compress-Archive` has no numeric equivalent.
+   * Out-of-range values are clamped. On Windows the level maps onto .NET's
+   * `CompressionLevel`: `0` is `NoCompression`, `1..3` `Fastest`, `4..8`
+   * `Optimal`, `9` `SmallestSize`.
    */
   readonly compressionLevel?: number | undefined;
 }
@@ -3068,9 +3112,9 @@ interface PathPrependOptions {
    * The environment the child will inherit — on a runner, `process.env`.
    *
    * @remarks
-   * Explicit rather than defaulted, matching this package's rule that ambient
-   * process state is never read behind a caller's back — which is also what
-   * makes the Windows casing branch exercisable from a test on any host.
+   * Explicit rather than defaulted, per the package rule stated on
+   * {@link ChildEnv} — which is also what makes the Windows casing branch
+   * exercisable from a test on any host.
    */
   readonly base: Readonly<Record<string, string | undefined>>;
   /**
@@ -3109,6 +3153,16 @@ interface PathPrependOptions {
  * ambient process — the same species as `Secret`'s statics, one concern per
  * member.
  *
+ * **The package rule, stated once: ambient process state is never read behind
+ * a caller's back.** `process.env`, `process.arch` and `process.platform` are
+ * read by `ActionEnvironment` (once, at layer construction) and otherwise
+ * taken as an argument — which is what makes every platform branch
+ * exercisable from a test on any host. The sanctioned exceptions are
+ * *defaults a caller can override by passing the value*: `ActionInput.provider`'s
+ * `env = process.env` and `DetachedProcess.spawn`'s `base`. A structural test
+ * (`__test__/ambientReads.test.ts`) holds the list closed; a new default is
+ * added there with its reason, never silently.
+ *
  * @public
  */
 export declare class ChildEnv {
@@ -3328,15 +3382,32 @@ interface DetachedSpawnOptions {
   readonly logFile: string;
   /** The working directory. */
   readonly cwd?: string | undefined;
+  /**
+   * The environment the child inherits, before `env` is merged over it.
+   *
+   * @remarks
+   * Defaults to the parent's `process.env` — **the one sanctioned ambient
+   * fallback in this module**, the same class of default as
+   * `ActionInput.provider`'s `env = process.env`, and an exception to the
+   * package rule stated on `ChildEnv` (ambient process state is never read
+   * behind a caller's back) precisely because passing a value here is how a
+   * caller opts out of it. Supply it to give the child a controlled block —
+   * a test proving exactly what a worker sees, or a worker that must not
+   * inherit the action's secrets — remembering that a base without `PATH`
+   * costs the child its runtime. An `undefined` value is dropped by Node's
+   * spawn, never stringified.
+   */
+  readonly base?: Readonly<Record<string, string | undefined>> | undefined;
   /**
    * Environment additions.
    *
    * @remarks
-   * **Merged over the parent's environment, not substituted for it.** A bare
-   * environment costs the child `PATH`, which usually means it cannot find its
-   * own runtime and dies before writing a word to the log — a failure that
-   * looks like a spawn bug and is not. Secrets belong here only via
-   * `Secret.forChildEnv`, which masks them on the way out.
+   * **Merged over `base` (the parent's environment by default), not
+   * substituted for it.** A bare environment costs the child `PATH`, which
+   * usually means it cannot find its own runtime and dies before writing a
+   * word to the log — a failure that looks like a spawn bug and is not.
+   * Secrets belong here only via `Secret.forChildEnv`, which masks them on
+   * the way out.
    */
   readonly env?: Readonly<Record<string, string>> | undefined;
 }
@@ -4393,13 +4464,38 @@ interface ToolInstallerShape {
    * say) to a foreign entry is a real shipped bug.
    */
   readonly find: (tool: string, version: string) => Effect.Effect<Option.Option<string>>;
+  /**
+   * Where this installer's `cacheDir` / `cacheFile` will land `tool@version`:
+   * the final `<root>/<tool>/<version>/<arch>`, over the root this layer
+   * resolved at construction.
+   *
+   * @remarks
+   * Pure — no IO, nothing is created — and exposed so a caller that must
+   * write the final path INTO the staged tree before the swap (a shim that
+   * names its own cached entry) reads the one answer `cacheDir` is about to
+   * use, instead of deriving root and arch a second time and guarding the
+   * two against drifting apart. {@link ToolInstaller.cachePath} is the same
+   * layout as a static function of an explicit root.
+   */
+  readonly cachePath: (tool: string, version: string) => string;
   /** Download a url to a temporary file, retrying what is worth retrying. */
   readonly download: (url: string, options?: ToolDownloadOptions) => Effect.Effect<string, ToolInstallerError>;
   /** Extract a tarball. Returns the directory its contents landed in. */
   readonly extractTar: (archive: string, options?: ExtractOptions) => Effect.Effect<string, ToolInstallerError>;
   /** Extract a zip. Returns the directory its contents landed in. */
   readonly extractZip: (archive: string, options?: ExtractOptions) => Effect.Effect<string, ToolInstallerError>;
-  /** Install a directory into the tool cache. Returns its cached path. */
+  /**
+   * Install a directory into the tool cache. Returns its cached path.
+   *
+   * @remarks
+   * **`source` is consumed.** On success it no longer exists at its original
+   * path: the tree is renamed into the cache when the two share a filesystem
+   * (`RUNNER_TEMP` and `RUNNER_TOOL_CACHE` do on hosted runners, making the
+   * install O(1) rather than a recursive copy of the whole toolchain), and
+   * otherwise copied and then removed. Write everything the cached entry must
+   * contain — shims, overlaid binaries — into `source` *before* this call,
+   * and read nothing from it afterwards.
+   */
   readonly cacheDir: (source: string, tool: string, version: string) => Effect.Effect<string, ToolInstallerError>;
   /** Install a single file into the tool cache under `name`. Returns the cached directory. */
   readonly cacheFile: (source: string, name: string, tool: string, version: string) => Effect.Effect<string, ToolInstallerError>;
@@ -4475,7 +4571,20 @@ export declare class ToolInstaller extends ToolInstaller_base {
     readonly version: string;
     readonly arch: string;
   }) => string;
-  /** A test double. Unstubbed members die rather than reporting a tool that is not there. */
+  /**
+   * A test double. Unstubbed members die rather than reporting a tool that is
+   * not there.
+   *
+   * @remarks
+   * `cachePath` is the one member with a default rather than a death: it is
+   * pure and total, and a caller composing it into shim contents would
+   * otherwise have to stub it in every test. The default is the static layout
+   * over `RUNNER_TOOL_CACHE`, or the same off-runner root `make` resolves
+   * (`internal/runner.ts`). **That is a read of the ambient environment**,
+   * sanctioned here only because a double has no `ActionEnvironment` to ask —
+   * test-double-only, and listed as such in the package's ambient-read
+   * allowlist (`__test__/ambientReads.test.ts`).
+   */
   static readonly makeTest: (overrides?: Partial<ToolInstallerShape>) => ToolInstallerShape;
   /** {@link ToolInstaller.makeTest} behind `Layer.succeed`. */
   static readonly layerTest: (overrides?: Partial<ToolInstallerShape>) => Layer.Layer<ToolInstaller>;

package/internal/archiveCommands.js

@@ -0,0 +1,153 @@
+import { ChildProcess } from "effect/unstable/process";
+
+//#region src/internal/archiveCommands.ts
+/**
+* The archiver command lines this package spawns, spelled once.
+*
+* @remarks
+* `Artifact` (pack and unpack) and `ToolInstaller` (unpack only) each spawn
+* the same three shapes — a zip, an unzip, a tar extraction — and each has a
+* Windows half that no test on a POSIX host can execute. Two hand-written
+* copies drifted: `ToolInstaller.extractZip` learned the overwrite overload
+* and the stderr capture below, `Artifact.download` did not, and a download
+* into a non-empty directory kept failing on Windows with an EMPTY stderr.
+* This module is the one spelling; the tests pin its text verbatim, which
+* is the only proof the Windows halves get.
+*
+* **The pwsh unzip is deliberately belt-and-braces.** The THREE-argument
+* `ExtractToDirectory(src, dest, $true)` overload overwrites existing files —
+* the two-argument one refuses, which is what turned a repeated extraction
+* into a hard failure — and the `$ErrorActionPreference = 'Stop'` plus
+* try/catch writes the actual .NET exception text plainly to stderr and
+* exits 1. pwsh's own error rendering does not reliably reach a captured
+* stream, and an empty complaint costs a source dive to even hypothesize
+* about.
+*
+* **The pwsh zip drives .NET's `ZipFile` directly, not `Compress-Archive`.**
+* Microsoft's own reference for `Compress-Archive -Path` states both faults:
+* handed individual file paths it stores every entry under its bare file
+* name — directory structure is kept only when `-Path` names a directory —
+* so `dir\b.txt` landed as `b.txt`, same-named files in different
+* directories collided, and a Windows artifact was structurally different
+* from the POSIX `zip -qr` one; and `-Path` expands wildcards, so a literal
+* `report[1].txt` matched nothing and failed the upload. Stating every entry
+* name explicitly through `CreateEntryFromFile(zip, source, entryName)`
+* removes both: the source is `Path.Combine(root, rel)`, taken literally,
+* and the entry name is `rel` with `\` turned to `/`, which is what `zip`
+* records on POSIX.
+*
+* **The Windows script is constant-size: the file list travels in a manifest
+* file, never in `-Command`.** `CreateProcessW` caps the whole command line
+* at 32,767 characters, and inlining one `CreateEntryFromFile` statement per
+* file (~214 characters each) hit that ceiling at roughly 150 files with
+* `ENAMETOOLONG` — fewer than the `Compress-Archive` form it replaced carried.
+* The script now reads {@link zipManifest}'s output (one relative path per
+* line) with `File.ReadAllLines` and loops. **The two branches deliberately
+* differ in mechanism**: POSIX `zip` takes the files as argv, whose ceiling
+* (`ARG_MAX`, megabytes on the hosted runners) is far larger, so the only
+* file-count ceiling left is that POSIX argv limit. The manifest is written by
+* the caller (`Artifact.zip`) as UTF-8 WITHOUT a BOM, which is what
+* `ReadAllLines` reads by default. Its BOM detection would consume a BOM
+* rather than leak it into the first path (measured), so this is a
+* plain-bytes preference, not a correctness guard.
+*
+* **Every `CreateEntryFromFile` is assigned to `$null`.** Unassigned, pwsh
+* writes the returned `ZipArchiveEntry` to stdout — roughly 430 bytes of
+* formatted object per file — and `internal/spawn.ts` interleaves stdout with
+* stderr into the captured output, which is what `ArtifactError.stderr`
+* carries. Left in, that chatter buried the one line that matters, the .NET
+* exception, under kilobytes of entry listings.
+*
+* Every path handed to PowerShell is single-quoted, and a single quote inside
+* one is doubled — the only escape a single-quoted PowerShell literal has.
+*
+* Pure: no filesystem, no environment, no spawn. `internal/spawn.ts` is the
+* execution half. Reaches `effect/unstable/process` alone, so it is safe for
+* any module to import (`__test__/reachability.test.ts`).
+*
+* @internal
+*/
+/** A PowerShell single-quoted literal: `'` becomes `''`, nothing else is special. */
+const pwshLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
+/** A non-interactive pwsh invocation of one command line. */
+const pwsh = (script, options) => ChildProcess.make("pwsh", [
+	"-NoProfile",
+	"-NonInteractive",
+	"-Command",
+	script
+], options);
+/** {@link ZipCommandOptions.level} clamped to `zip`'s `0..9` and truncated. */
+const clampLevel = (level) => Math.min(9, Math.max(0, Math.trunc(level)));
+/** The .NET `CompressionLevel` member a clamped zlib level maps onto. */
+const dotnetCompressionLevel = (level) => level === 0 ? "NoCompression" : level <= 3 ? "Fastest" : level <= 8 ? "Optimal" : "SmallestSize";
+/**
+* The manifest the Windows zip script reads: `files` one per line, `\n`-joined,
+* with a trailing newline. Pure; the caller writes it (UTF-8, no BOM).
+*
+* @remarks
+* A path containing `\n` or `\r` is unrepresentable — it would split into two
+* entries — and this function does not check; `Artifact.zip` rejects such a
+* file as `invalidOptions`, naming it, before anything is written.
+*
+* @internal
+*/
+const zipManifest = (files) => files.map((file) => `${file}\n`).join("");
+/**
+* Pack `files` into a zip: `zip -<level> -qr <destination> <files...>` with
+* `root` as the working directory, or on Windows a pwsh script that opens
+* `destination` with `ZipFile.Open(..., Create)` after a `File.Delete` (the
+* overwrite) and adds one `CreateEntryFromFile` per line of `manifest`,
+* naming each entry explicitly — under `$ErrorActionPreference = 'Stop'` and
+* a stderr-writing try/catch, and with the archive disposed in a `finally` so
+* a failed entry cannot leave the handle open (the module doc says why not
+* `Compress-Archive`, and why the list travels in a file).
+*
+* @internal
+*/
+const zipCommand = (options) => {
+	const level = clampLevel(options.level);
+	if (!options.windows) return ChildProcess.make("zip", [
+		`-${level}`,
+		"-qr",
+		options.destination,
+		...options.files
+	], { cwd: options.root });
+	const destination = pwshLiteral(options.destination);
+	const root = pwshLiteral(options.root);
+	const manifest = pwshLiteral(options.manifest);
+	const compression = `[System.IO.Compression.CompressionLevel]::${dotnetCompressionLevel(level)}`;
+	return pwsh(`\$ErrorActionPreference = 'Stop'; try { Add-Type -AssemblyName System.IO.Compression; Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.File]::Delete(${destination}); $zip = [System.IO.Compression.ZipFile]::Open(${destination}, [System.IO.Compression.ZipArchiveMode]::Create); try { foreach ($rel in [System.IO.File]::ReadAllLines(${manifest})) { if ($rel -ne '') { $null = [System.IO.Compression.ZipFileExtensions]::CreateEntryFromFile($zip, [System.IO.Path]::Combine(${root}, $rel), $rel.Replace('\\', '/'), ${compression}) } } } finally { \$zip.Dispose() } } catch { [Console]::Error.WriteLine(\$_.Exception.ToString()); exit 1 }`, { cwd: options.root });
+};
+/**
+* Unpack a zip into `destination`, overwriting: `unzip -oq <source> -d
+* <destination>`, or the three-argument `ExtractToDirectory` overload under
+* `$ErrorActionPreference = 'Stop'` and a stderr-writing try/catch on
+* Windows (the module doc says why both halves are load-bearing).
+*
+* @internal
+*/
+const unzipCommand = (options) => options.windows ? pwsh(`\$ErrorActionPreference = 'Stop'; try { Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory(${pwshLiteral(options.source)}, ${pwshLiteral(options.destination)}, $true) } catch { [Console]::Error.WriteLine(\$_.Exception.ToString()); exit 1 }`) : ChildProcess.make("unzip", [
+	"-oq",
+	options.source,
+	"-d",
+	options.destination
+]);
+/**
+* Extract a tarball: `tar <flags> <archive> -C <destination>`. The same on
+* every platform — bsdtar ships on the Windows runner image — so unlike the
+* zip pair there is no `windows` switch.
+*
+* @internal
+*/
+const tarExtractCommand = (options) => {
+	const flags = options.flags === void 0 || options.flags.length === 0 ? ["xzf"] : [...options.flags];
+	return ChildProcess.make("tar", [
+		...flags,
+		options.archive,
+		"-C",
+		options.destination
+	]);
+};
+
+//#endregion
+export { tarExtractCommand, unzipCommand, zipCommand, zipManifest };

package/internal/digest.js

@@ -6,11 +6,12 @@ import { createHash } from "node:crypto";
 * 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.
+* Core `Crypto` offers one-shot SHA digests over bytes already in memory, but
+* no HMAC and no incremental hasher, so this package's licence for a `node:`
+* import covers hashing (see the Module concept in `okf/`). 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
 */

package/internal/fsProbe.js

@@ -9,6 +9,14 @@ import { Effect } from "effect";
 * @internal
 */
 const typeAt = (fs, path) => Effect.map(Effect.option(fs.stat(path)), (info) => info._tag === "Some" ? info.value.type : void 0);
+/**
+* Whether a thrown value is a Node errno error with the given code — the
+* platform's `SystemError` keeps the raw exception as its `cause`, and codes
+* it maps to no named tag (`EXDEV`, `ESRCH`) are only recoverable from there.
+*
+* @internal
+*/
+const isErrno = (cause, code) => typeof cause === "object" && cause !== null && cause.code === code;
 
 //#endregion
-export { typeAt };
+export { isErrno, typeAt };

package/internal/runner.js

@@ -19,9 +19,9 @@ const isWindowsRunner = (env) => Effect.map(env.getOptional("RUNNER_OS"), (found
 * Resolved at layer construction, never at import: the source package read
 * the variable into a module-level constant, which fixed the root before any
 * layer could say otherwise and made it impossible to point a test elsewhere.
-* `PackageManagerInstaller` resolves the same root because the shims it
-* writes into a staged entry must name the FINAL cache path; sharing the
-* resolution is what keeps its post-swap equality check a formality.
+* `ToolInstaller` is its only reader: a consumer that needs the final cache
+* path (`PackageManagerInstaller`, for its shims) asks the installer's own
+* `cachePath` member rather than resolving the root a second time.
 *
 * @internal
 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github-actions",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"private": false,
 	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
 	"keywords": [
@@ -39,18 +39,18 @@
 	},
 	"dependencies": {
 		"@azure/storage-blob": "^12.33.0",
-		"@effected/github": "^0.11.0",
-		"@effected/glob": "^0.7.0",
-		"@effected/markdown": "^0.11.0",
-		"@effected/npm": "^0.15.0",
-		"@effected/sbom": "^0.7.0",
-		"@effected/semver": "^0.8.0",
-		"@effected/templates": "^0.7.0",
-		"@effected/walker": "^0.10.0"
+		"@effected/github": "^0.12.0",
+		"@effected/glob": "^0.8.0",
+		"@effected/markdown": "^0.12.0",
+		"@effected/npm": "^0.16.0",
+		"@effected/sbom": "^0.8.0",
+		"@effected/semver": "^0.9.0",
+		"@effected/templates": "^0.8.0",
+		"@effected/walker": "^0.12.0"
 	},
 	"peerDependencies": {
-		"@effect/platform-node": "4.0.0-rc.116",
-		"effect": "4.0.0-rc.116"
+		"@effect/platform-node": "4.0.0-rc.117",
+		"effect": "4.0.0-rc.117"
 	},
 	"engines": {
 		"node": ">=24.11.0"