@effected/github-actions 0.1.0

package/OidcTokenIssuer.js

@@ -0,0 +1,246 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { Context, Effect, Layer, Redacted, Schema } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+
+//#region src/OidcTokenIssuer.ts
+/**
+* Raised when an OIDC token cannot be issued or read.
+*
+* @public
+*/
+var OidcTokenError = class extends Schema.TaggedErrorClass()("OidcTokenError", {
+	/**
+	* `unavailable` — the runner did not publish the token-service variables,
+	* which almost always means the workflow is missing `permissions: id-token:
+	* write`. `requestFailed` — the token service could not be reached or refused
+	* the request. `malformedResponse` — it answered with something that is not a
+	* token envelope. `malformedToken` — the token is not a decodable JWT.
+	* `missingClaims` — it decoded, but without the claims a provenance statement
+	* needs.
+	*/
+	reason: Schema.Literals([
+		"unavailable",
+		"requestFailed",
+		"malformedResponse",
+		"malformedToken",
+		"missingClaims"
+	]),
+	/** What was wrong, in one line. */
+	detail: Schema.optionalKey(Schema.String),
+	/** The HTTP status, when the token service answered. */
+	status: Schema.optionalKey(Schema.Number),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "unavailable": return "The runner published no OIDC token service; the workflow needs `permissions: id-token: write`";
+			case "requestFailed": return `The OIDC token request failed${this.status === void 0 ? "" : ` with status ${this.status}`}`;
+			case "malformedResponse": return "The OIDC token service answered with an unexpected shape";
+			case "malformedToken": return `The OIDC token is not a decodable JWT${this.detail === void 0 ? "" : `: ${this.detail}`}`;
+			default: return "The OIDC token is missing claims a provenance statement needs";
+		}
+	}
+};
+/**
+* The claims a GitHub Actions OIDC token carries about the workflow that ran.
+*
+* @remarks
+* The field names are GitHub's own JWT claim names, kept verbatim rather than
+* translated to the kit's casing. They are an **external vocabulary** — the
+* same strings that appear in a SLSA provenance predicate and in every
+* published example of an Actions OIDC policy — and renaming them would put a
+* translation layer between a consumer and the specification they are reading.
+*
+* @public
+*/
+var OidcClaims = class extends Schema.Class("OidcClaims")({
+	/** The issuer, e.g. `https://token.actions.githubusercontent.com`. */
+	iss: Schema.String,
+	/** The full ref the workflow ran on. */
+	ref: Schema.String,
+	/** The commit. */
+	sha: Schema.String,
+	/** `owner/repo`. */
+	repository: Schema.String,
+	/** The event that triggered the run. */
+	event_name: Schema.String,
+	/** The reusable-workflow ref, which is what a verifier pins against. */
+	job_workflow_ref: Schema.String,
+	/** The calling workflow's ref. */
+	workflow_ref: Schema.String,
+	/** The numeric repository id, as a string. */
+	repository_id: Schema.String,
+	/** The numeric owner id, as a string. */
+	repository_owner_id: Schema.String,
+	/** `github-hosted` or `self-hosted`. */
+	runner_environment: Schema.String,
+	/** The run id, as a string. */
+	run_id: Schema.String,
+	/** The run attempt, as a string. */
+	run_attempt: Schema.String
+}) {};
+/** The token envelope the runner's token service answers with. */
+const TokenEnvelope = Schema.Struct({
+	value: Schema.String,
+	count: Schema.optionalKey(Schema.Number)
+});
+const REQUEST_TOKEN = "ACTIONS_ID_TOKEN_REQUEST_TOKEN";
+const REQUEST_URL = "ACTIONS_ID_TOKEN_REQUEST_URL";
+/**
+* Decode a JWT payload segment.
+*
+* @remarks
+* `base64url` states the intent, though it is not what makes this work: Node's
+* plain `base64` decoder happens to accept the url alphabet and unpadded input
+* too (probed at beta.101), so the two are interchangeable *here*. They are not
+* interchangeable everywhere — `atob` is not forgiving — which is why the
+* declaration is the strict one and there is a test whose payload actually
+* contains `-` and `_`.
+*/
+const decodeSegment = (segment) => JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
+/**
+* Read the claims out of a JWT **without verifying its signature**.
+*
+* @remarks
+* The absence of verification is deliberate and is documented on
+* {@link OidcTokenIssuerShape.claims}; do not "fix" it here.
+*/
+const readClaims = (token) => Effect.gen(function* () {
+	const parts = token.split(".");
+	const payload = parts[1];
+	if (parts.length !== 3 || payload === void 0 || payload === "") return yield* Effect.fail(new OidcTokenError({
+		reason: "malformedToken",
+		detail: `expected three segments, got ${parts.length}`
+	}));
+	const decoded = yield* Effect.try({
+		try: () => decodeSegment(payload),
+		catch: (cause) => new OidcTokenError({
+			reason: "malformedToken",
+			detail: "the payload is not base64url JSON",
+			cause
+		})
+	});
+	return yield* Schema.decodeUnknownEffect(OidcClaims)(decoded).pipe(Effect.mapError((cause) => new OidcTokenError({
+		reason: "missingClaims",
+		cause
+	})));
+});
+const make = Effect.gen(function* () {
+	const env = yield* ActionEnvironment;
+	const http = yield* HttpClient.HttpClient;
+	const required = (name) => env.get(name).pipe(Effect.mapError(() => new OidcTokenError({
+		reason: "unavailable",
+		detail: name
+	})));
+	/**
+	* The raw JWT, before it is wrapped.
+	*
+	* @remarks
+	* `claims` reads this rather than unwrapping what `token` returns, so
+	* `Redacted.value` does not appear in this module at all — the package's
+	* declassification invariant is that `Secret.ts` is the only place a secret
+	* becomes a string, and a wrap-then-immediately-unwrap here would be a
+	* genuine exception to it rather than a cosmetic one. A structural test over
+	* `src/` enforces this, and it caught exactly this call when the first draft
+	* did it the obvious way.
+	*/
+	const issue = Effect.fn("OidcTokenIssuer.token")(function* (audience) {
+		const bearer = yield* required(REQUEST_TOKEN);
+		const base = yield* required(REQUEST_URL);
+		const url = audience === void 0 ? base : `${base}&audience=${encodeURIComponent(audience)}`;
+		const response = yield* http.get(url, { headers: {
+			authorization: `Bearer ${bearer}`,
+			accept: "application/json"
+		} }).pipe(Effect.mapError((cause) => new OidcTokenError({
+			reason: "requestFailed",
+			cause
+		})));
+		if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new OidcTokenError({
+			reason: "requestFailed",
+			status: response.status
+		}));
+		return (yield* HttpClientResponse.schemaBodyJson(TokenEnvelope)(response).pipe(Effect.mapError((cause) => new OidcTokenError({
+			reason: "malformedResponse",
+			cause
+		})))).value;
+	});
+	return {
+		token: (audience) => Effect.map(issue(audience), Redacted.make),
+		claims: Effect.fn("OidcTokenIssuer.claims")(function* (audience) {
+			return yield* readClaims(yield* issue(audience));
+		})
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`OidcTokenIssuer.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* The runner's OIDC token service.
+*
+* @remarks
+* Lives here rather than with attestation because it reads
+* `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL`, which
+* exist only when a workflow declares `permissions: id-token: write` — that is
+* a fact about the runner, not about signing.
+*
+* @example
+* ```ts
+* import { OidcTokenIssuer } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const issuer = yield* OidcTokenIssuer;
+*   const claims = yield* issuer.claims("sigstore");
+*   return claims.job_workflow_ref;
+* });
+* ```
+*
+* @public
+*/
+var OidcTokenIssuer = class OidcTokenIssuer extends Context.Service()("@effected/github-actions/OidcTokenIssuer") {
+	static layer = Layer.effect(this, make);
+	/**
+	* An **unsigned** JWT carrying these claims.
+	*
+	* @remarks
+	* For building test doubles, and nothing else: the signature segment is a
+	* placeholder, so this token would fail any verifier. It exists because the
+	* alternative — a double returning a synthetic non-JWT — is what made the
+	* provenance path structurally unreachable in the source package, drawing
+	* four separate apologetic comments from one consumer.
+	*/
+	static unsignedTokenFor = (claims) => {
+		const segment = (value) => Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+		return Redacted.make(`${segment({
+			alg: "RS256",
+			typ: "JWT"
+		})}.${segment(Schema.encodeUnknownSync(OidcClaims)(claims))}.unsigned`);
+	};
+	/** A test double. Unstubbed members die rather than answering with a non-token. */
+	static makeTest = (overrides = {}) => ({
+		token: () => Effect.sync(() => unimplemented("token")),
+		claims: () => Effect.sync(() => unimplemented("claims")),
+		...overrides
+	});
+	/** {@link OidcTokenIssuer.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(OidcTokenIssuer, OidcTokenIssuer.makeTest(overrides));
+	/**
+	* A double that answers with these claims, consistently on both members.
+	*
+	* @remarks
+	* `token()` returns a real decodable JWT built from the same claims
+	* `claims()` returns, so a consumer that decodes the token itself and a
+	* consumer that asks the service both see the same thing. A double whose two
+	* members can disagree is how a test proves a path works while production
+	* takes the other one.
+	*/
+	static layerFor = (claims) => Layer.succeed(OidcTokenIssuer, {
+		token: () => Effect.succeed(OidcTokenIssuer.unsignedTokenFor(claims)),
+		claims: () => Effect.succeed(claims)
+	});
+};
+
+//#endregion
+export { OidcClaims, OidcTokenError, OidcTokenIssuer };

package/Secret.js

@@ -0,0 +1,106 @@
+import { ActionOutputs } from "./ActionOutputs.js";
+import { Config, Effect, Redacted } from "effect";
+
+//#region src/Secret.ts
+/**
+* The declassification seam: the **only** place in this package where a
+* `Redacted` value becomes a plain string.
+*
+* @remarks
+* Some boundaries cannot carry a `Redacted`. A detached child process reads
+* its configuration from environment variables; `GITHUB_STATE` is a plaintext
+* file by GitHub's protocol. `Redacted` refusing to serialize is the whole
+* value of the type, so this module does not try to make it serializable —
+* it makes declassification **explicit, auditable, and impossible to do
+* quietly**.
+*
+* The invariant: **masking and declassification are the same call.** Every
+* member registers the value with the runner's log filter (`::add-mask::`)
+* *before* returning plaintext, so a secret cannot reach a child's environment
+* or a state file without the runner already knowing to redact it from logs.
+*
+* `Redacted.value` appears nowhere else in this package, and a test asserts
+* that structurally — a reintroduction elsewhere fails the suite rather than
+* review.
+*
+* What this deliberately does **not** do is encrypt the handoff. The child
+* runs on the same runner, as the same user, as the parent; a key would have
+* to travel the same channel as the secret it protects.
+*
+* @example
+* ```ts
+* import { Secret } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const env = yield* Secret.forChildEnv({ MY_TOKEN: theToken });
+*   // every value in `env` is already masked in the runner log
+*   return env;
+* });
+* ```
+*
+* @public
+*/
+var Secret = class Secret {
+	constructor() {}
+	/**
+	* Declassify a set of secrets for a child process's environment.
+	*
+	* @remarks
+	* Every value is masked before any plaintext is returned — including when
+	* one of them fails, because masking happens for the whole set first.
+	*/
+	static forChildEnv = (entries) => Effect.gen(function* () {
+		const outputs = yield* ActionOutputs;
+		const declassified = {};
+		for (const [name, secret] of Object.entries(entries)) {
+			const plaintext = Redacted.value(secret);
+			yield* outputs.setSecret(plaintext);
+			declassified[name] = plaintext;
+		}
+		return declassified;
+	});
+	/**
+	* Declassify one secret for a runner file (`GITHUB_STATE`, `GITHUB_OUTPUT`).
+	*
+	* @remarks
+	* Masks first. The runner file is plaintext regardless; the mask is what
+	* keeps the value out of the visible log.
+	*/
+	static forRunnerFile = (secret) => Effect.gen(function* () {
+		const outputs = yield* ActionOutputs;
+		const plaintext = Redacted.value(secret);
+		yield* outputs.setSecret(plaintext);
+		return plaintext;
+	});
+	/**
+	* Declassify one secret for an in-process use that needs the raw bytes.
+	*
+	* @remarks
+	* Request signing is the case this exists for: an HMAC cannot be computed
+	* over a `Redacted`, so a signing key has to become a string somewhere, and
+	* the point of this module is that "somewhere" is here and nowhere else.
+	*
+	* It masks even though the value is never *written* anywhere, and that is
+	* deliberate rather than superstitious: a signing key that leaks does so
+	* through something nobody audited — a debug log of outgoing headers, a
+	* serialized error, a stack trace carrying the closure. Registering it with
+	* the runner's filter costs one call and makes every one of those redacted.
+	*
+	* Call it **once, at layer construction**, not per operation: masking is
+	* idempotent but a workflow command per request is noise in the log.
+	*/
+	static forSigning = (secret) => Secret.forRunnerFile(secret);
+	/**
+	* The far side of a handoff: re-wrap a plaintext environment variable.
+	*
+	* @remarks
+	* A `Config`, so a missing or empty handoff is an honest `ConfigError`
+	* naming the variable rather than an empty `Redacted` that fails much later
+	* as an authentication error.
+	*/
+	static adopt = (name) => Config.redacted(name);
+};
+
+//#endregion
+export { Secret };

package/ToolInstaller.js

@@ -0,0 +1,293 @@
+import { ActionEnvironment } from "./ActionEnvironment.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";
+
+//#region src/ToolInstaller.ts
+/**
+* Raised when a tool cannot be downloaded, extracted or cached.
+*
+* @public
+*/
+var ToolInstallerError = class extends Schema.TaggedErrorClass()("ToolInstallerError", {
+	/**
+	* `downloadFailed` — the archive could not be fetched. `extractFailed` — the
+	* extraction tool refused the archive or is not installed. `cacheFailed` —
+	* the tool could not be written into the runner's tool cache.
+	*/
+	reason: Schema.Literals([
+		"downloadFailed",
+		"extractFailed",
+		"cacheFailed"
+	]),
+	/** The HTTP status, when there was one. Drives the retry decision. */
+	status: Schema.optionalKey(Schema.Number),
+	/** What was being worked on — a url, an archive path, or a tool name. */
+	subject: Schema.optionalKey(Schema.String),
+	/** The extraction tool's own complaint, which is the only useful part of a tar failure. */
+	stderr: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "downloadFailed": return `Could not download ${this.subject}${this.status === void 0 ? "" : ` (HTTP ${this.status})`}`;
+			case "extractFailed": return `Could not extract ${this.subject}${this.stderr === void 0 ? "" : `: ${this.stderr}`}`;
+			default: return `Could not cache ${this.subject} into the tool cache`;
+		}
+	}
+	/**
+	* Whether retrying could plausibly help.
+	*
+	* @remarks
+	* A derived getter rather than a field, so it cannot be set inconsistently
+	* with the status it is derived from. `408`, `429` and any `5xx` are the
+	* server saying "later"; a `404` is it saying "never", and retrying that
+	* three times just makes a broken url take longer to fail.
+	*/
+	get retryable() {
+		if (this.reason !== "downloadFailed") return false;
+		if (this.status === void 0) return true;
+		return this.status >= 500 || this.status === 408 || this.status === 429;
+	}
+};
+/** How many times a retryable download is retried before giving up. */
+const DOWNLOAD_RETRIES = 2;
+const make = Effect.gen(function* () {
+	const env = yield* ActionEnvironment;
+	const fs = yield* FileSystem.FileSystem;
+	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 cachePath = (tool, version) => ToolInstaller.cachePath({
+		root,
+		tool,
+		version,
+		arch: process.arch
+	});
+	const destinationFor = (options) => {
+		const requested = options?.destination;
+		if (requested === void 0) return fs.makeTempDirectory({ prefix: "effected-extract-" }).pipe(Effect.mapError((cause) => new ToolInstallerError({
+			reason: "extractFailed",
+			cause
+		})));
+		return fs.makeDirectory(requested, { recursive: true }).pipe(Effect.as(requested), Effect.mapError((cause) => new ToolInstallerError({
+			reason: "extractFailed",
+			subject: requested,
+			cause
+		})));
+	};
+	/**
+	* Run an extraction command, keeping its stderr.
+	*
+	* @remarks
+	* `tar`'s exit code says only that it failed; its stderr says why, and it is
+	* the difference between "this is not a gzip archive" and "tar is not
+	* installed". Discarding it is what makes an extraction failure unactionable.
+	*/
+	const extractWith = (command, archive) => Effect.gen(function* () {
+		const output = yield* spawner.string(command, { includeStderr: true }).pipe(Effect.mapError((cause) => new ToolInstallerError({
+			reason: "extractFailed",
+			subject: archive,
+			cause
+		})));
+		if ((yield* spawner.exitCode(command).pipe(Effect.mapError((cause) => new ToolInstallerError({
+			reason: "extractFailed",
+			subject: archive,
+			cause
+		})))) !== 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.
+	*
+	* @remarks
+	* **Stage then swap**, and the reason is that the alternative is worse than a
+	* failed install: copying straight into the cache path leaves a *partial*
+	* tool behind when the copy fails halfway, and `find` reports a partial
+	* directory as a hit. Every later run then uses a half-extracted toolchain
+	* and never re-downloads it. A rename within one filesystem is atomic, so the
+	* cache only ever contains complete tools.
+	*/
+	const swapIntoCache = (staging, tool, version) => Effect.gen(function* () {
+		const destination = cachePath(tool, version);
+		yield* fs.makeDirectory(path.dirname(destination), { recursive: true });
+		yield* fs.remove(destination, {
+			recursive: true,
+			force: true
+		});
+		yield* fs.rename(staging, destination);
+		return destination;
+	}).pipe(Effect.mapError((cause) => new ToolInstallerError({
+		reason: "cacheFailed",
+		subject: tool,
+		cause
+	})));
+	/** 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 });
+		return yield* fs.makeTempDirectory({
+			directory: root,
+			prefix: ".staging-"
+		});
+	}).pipe(Effect.mapError((cause) => new ToolInstallerError({
+		reason: "cacheFailed",
+		subject: tool,
+		cause
+	})), Effect.flatMap((staging) => use(staging).pipe(Effect.tapCause(() => Effect.ignore(fs.remove(staging, {
+		recursive: true,
+		force: true
+	}))))));
+	return {
+		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()),
+		download: Effect.fn("ToolInstaller.download")(function* (url) {
+			return yield* Effect.gen(function* () {
+				const response = yield* http.get(url).pipe(Effect.mapError((cause) => new ToolInstallerError({
+					reason: "downloadFailed",
+					subject: url,
+					cause
+				})));
+				if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new ToolInstallerError({
+					reason: "downloadFailed",
+					subject: url,
+					status: response.status
+				}));
+				const directory = yield* fs.makeTempDirectory({ prefix: "effected-download-" }).pipe(Effect.mapError((cause) => new ToolInstallerError({
+					reason: "downloadFailed",
+					subject: url,
+					cause
+				})));
+				const file = path.join(directory, "download");
+				yield* Stream.run(response.stream, fs.sink(file)).pipe(Effect.mapError((cause) => new ToolInstallerError({
+					reason: "downloadFailed",
+					subject: url,
+					cause
+				})));
+				return file;
+			}).pipe(Effect.retry({
+				schedule: Schedule.exponential("1 second"),
+				times: DOWNLOAD_RETRIES,
+				while: (error) => error.retryable
+			}));
+		}),
+		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,
+				archive,
+				"-C",
+				destination
+			]), 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",
+				`Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${archive.replaceAll("'", "''")}', '${destination.replaceAll("'", "''")}')`
+			]) : ChildProcess.make("unzip", [
+				"-oq",
+				archive,
+				"-d",
+				destination
+			]);
+			yield* extractWith(command, archive);
+			return destination;
+		}),
+		cacheDir: Effect.fn("ToolInstaller.cacheDir")(function* (source, tool, version) {
+			yield* Effect.annotateCurrentSpan({
+				tool,
+				version
+			});
+			return yield* staged(tool, (staging) => fs.copy(source, staging, { overwrite: true }).pipe(Effect.mapError((cause) => new ToolInstallerError({
+				reason: "cacheFailed",
+				subject: tool,
+				cause
+			})), Effect.flatMap(() => swapIntoCache(staging, tool, version))));
+		}),
+		cacheFile: Effect.fn("ToolInstaller.cacheFile")(function* (source, name, tool, version) {
+			yield* Effect.annotateCurrentSpan({
+				tool,
+				version
+			});
+			return yield* staged(tool, (staging) => fs.copyFile(source, path.join(staging, name)).pipe(Effect.mapError((cause) => new ToolInstallerError({
+				reason: "cacheFailed",
+				subject: tool,
+				cause
+			})), Effect.flatMap(() => swapIntoCache(staging, tool, version))));
+		})
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`ToolInstaller.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* Download, extract and cache a toolchain in the runner's tool cache.
+*
+* @remarks
+* The primitives, not a workflow: a consumer composes `find` → `download` →
+* `extractTar` → `cacheDir` in whatever order its tool needs, because the
+* orders genuinely differ (a single binary skips extraction, a tarball with a
+* nested root directory needs a path fixup between extract and cache).
+*
+* No `@actions/tool-cache` dependency — the cache is a directory layout, and
+* this reproduces the layout rather than importing a package to compute it.
+*
+* @example
+* ```ts
+* import { ToolInstaller } from "@effected/github-actions";
+* import { Effect, Option } from "effect";
+*
+* const install = Effect.gen(function* () {
+*   const installer = yield* ToolInstaller;
+*   const cached = yield* installer.find("node", "22.11.0");
+*   if (Option.isSome(cached)) return cached.value;
+*   const archive = yield* installer.download("https://nodejs.org/dist/v22.11.0/node.tar.gz");
+*   const extracted = yield* installer.extractTar(archive);
+*   return yield* installer.cacheDir(extracted, "node", "22.11.0");
+* });
+* ```
+*
+* @public
+*/
+var ToolInstaller = class ToolInstaller extends Context.Service()("@effected/github-actions/ToolInstaller") {
+	static layer = Layer.effect(this, make);
+	/**
+	* Where a tool lives in the cache.
+	*
+	* @remarks
+	* Pure, exported and tested on its own, because the layout is a **contract
+	* with the runner**: `<root>/<tool>/<version>/<arch>` is what the hosted
+	* image populates and what `@actions/tool-cache` reads, so a tool cached at
+	* any other path is invisible to every other step in the workflow. The `arch`
+	* segment uses Node's `process.arch` spelling (`x64`) rather than the
+	* 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. */
+	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")),
+		...overrides
+	});
+	/** {@link ToolInstaller.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ToolInstaller, ToolInstaller.makeTest(overrides));
+};
+
+//#endregion
+export { ToolInstaller, ToolInstallerError };