@effected/github-actions 0.1.0

package/BlobStore.githubCache.js

@@ -0,0 +1,183 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { BlobTransferError } from "./BlobTransfer.js";
+import { resultsBackend } from "./internal/actionsResults.js";
+import { CONFLICT, isOk, stringField, twirpCall } from "./internal/twirp.js";
+import { BlobEnvelope } from "./BlobEnvelope.js";
+import { BlobStore, BlobStoreError } from "./BlobStore.js";
+import { Effect, Layer, Option } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { createHash } from "node:crypto";
+import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
+
+//#region src/BlobStore.githubCache.ts
+/** The Twirp service the Actions cache protocol lives under. */
+const SERVICE = "github.actions.results.api.v1.CacheService";
+/**
+* The `version` every entry is filed under.
+*
+* @remarks
+* The cache protocol keys an entry on `(key, version)`, and `actions/cache`
+* derives the version from the *paths* it archives. A blob store has no paths —
+* the key is caller-supplied and the payload is opaque — so the version is a
+* constant, which is what makes any key map to a reproducible slot.
+*
+* It is deliberately **not** a format version: {@link BlobEnvelope} carries that
+* inside the blob, so a framing change is a clean miss rather than a key change
+* that strands every existing entry.
+*/
+const VERSION = createHash("sha256").update("blobstore|1.0").digest("hex");
+/**
+* The Azure half, ~15 lines and duplicated on purpose.
+*
+* @remarks
+* `@azure/storage-blob` may be imported by this module, `ActionCache` and
+* `Artifact` and by nothing else. Hoisting these two calls into a shared
+* `internal/` helper is exactly how the import would leak into the graph of a
+* module that only sets an output — so the three modules each carry their own,
+* and `__test__/reachability.test.ts` measures that they are the only three.
+*/
+const azure = {
+	uploadData: (url, data) => Effect.tryPromise({
+		try: () => new BlockBlobClient(url).uploadData(data),
+		catch: (cause) => new BlobTransferError({
+			reason: "uploadFailed",
+			cause
+		})
+	}).pipe(Effect.asVoid),
+	downloadToBuffer: (url) => Effect.tryPromise({
+		try: () => new BlobClient(url).downloadToBuffer(),
+		catch: (cause) => new BlobTransferError({
+			reason: "downloadFailed",
+			cause
+		})
+	}).pipe(Effect.map((buffer) => new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)))
+};
+const fromTwirp = (failure, key) => failure.kind === "status" ? new BlobStoreError({
+	reason: "refused",
+	key,
+	...failure.status === void 0 ? {} : { status: failure.status }
+}) : new BlobStoreError({
+	reason: "unreachable",
+	key,
+	detail: `${failure.method} answered with something that is not a Twirp body`,
+	...failure.cause === void 0 ? {} : { cause: failure.cause }
+});
+const make = (transfer) => Effect.gen(function* () {
+	const http = yield* HttpClient.HttpClient;
+	const backend = resultsBackend(yield* ActionEnvironment).pipe(Effect.mapError((name) => new BlobStoreError({
+		reason: "misconfigured",
+		detail: `${name} is not set — the Actions results backend is only reachable from a \`uses:\` step, never from \`run:\``
+	})));
+	const call = (method, body, key) => Effect.gen(function* () {
+		const { baseUrl, token } = yield* backend;
+		return yield* twirpCall({
+			http,
+			baseUrl,
+			service: SERVICE,
+			token,
+			method,
+			body
+		}).pipe(Effect.mapError((failure) => fromTwirp(failure, key)));
+	});
+	/** The signed download url for a key, or nothing — a miss is not a failure. */
+	const download = (key) => Effect.map(call("GetCacheEntryDownloadURL", {
+		key,
+		restore_keys: [],
+		version: VERSION
+	}, key), (answer) => answer === CONFLICT || !isOk(answer) ? Option.none() : Option.fromNullishOr(stringField(answer, "signedDownloadUrl")));
+	const moved = (key) => Effect.mapError((cause) => new BlobStoreError({
+		reason: "unreachable",
+		key,
+		cause
+	}));
+	return {
+		get: (key, schema) => Effect.gen(function* () {
+			const url = yield* download(key);
+			if (Option.isNone(url)) return Option.none();
+			const bytes = yield* transfer.downloadToBuffer(url.value).pipe(moved(key));
+			return Option.some(yield* Effect.fromResult(BlobEnvelope.decodeResult(bytes, schema)));
+		}),
+		put: (key, blob, schema) => Effect.gen(function* () {
+			const framed = yield* Effect.fromResult(BlobEnvelope.encodeResult(blob.metadata, blob.body, schema));
+			const created = yield* call("CreateCacheEntry", {
+				key,
+				version: VERSION
+			}, key);
+			if (created === CONFLICT) return;
+			const url = stringField(created, "signedUploadUrl");
+			if (!isOk(created) || url === void 0) return yield* Effect.fail(new BlobStoreError({
+				reason: "refused",
+				key,
+				detail: "CreateCacheEntry returned no upload url"
+			}));
+			yield* transfer.uploadData(url, framed).pipe(moved(key));
+			const finalized = yield* call("FinalizeCacheEntryUpload", {
+				key,
+				version: VERSION,
+				size_bytes: String(framed.byteLength)
+			}, key);
+			if (finalized === CONFLICT || !isOk(finalized)) return yield* Effect.fail(new BlobStoreError({
+				reason: "refused",
+				key,
+				detail: "FinalizeCacheEntryUpload did not confirm the upload"
+			}));
+		}),
+		has: (key) => Effect.map(download(key), Option.isSome)
+	};
+});
+/**
+* The {@link BlobStore} backend that stores blobs in the runner's own Actions
+* cache.
+*
+* @remarks
+* The Actions cache is reachable over a Twirp v2 protocol at
+* `ACTIONS_RESULTS_URL`, which answers a `CreateCacheEntry` /
+* `GetCacheEntryDownloadURL` RPC with a **pre-signed Azure blob url** — which is
+* why this backend lives in its own module rather than beside the S3 one, and
+* why the spec's "Azure is confined to the cache and the artifact service" is
+* three modules rather than two.
+*
+* **Only reachable from a `uses:` step.** The runner injects
+* `ACTIONS_RESULTS_URL` and `ACTIONS_RUNTIME_TOKEN` into action execution
+* contexts and not into `run:` shell steps, so a program that works when
+* invoked from a bundled action fails as `misconfigured` when the same code is
+* run by `node ./main.js` in a workflow step. The failure names the variable
+* for exactly that reason.
+*
+* The layer statics live here rather than on {@link BlobStore} because a static
+* belongs to the module that owns the dependency it needs: putting
+* `BlobStore.layerGitHubCache` on the service class would make `@azure/storage-blob`
+* reachable from every module that reads a blob.
+*
+* @example
+* ```ts
+* import { GitHubCacheBlobStore } from "@effected/github-actions";
+*
+* const layer = GitHubCacheBlobStore.layer;
+* ```
+*
+* @public
+*/
+var GitHubCacheBlobStore = class {
+	constructor() {}
+	/** The backend, over the real Azure client. */
+	static layer = Layer.effect(BlobStore, make(azure));
+	/**
+	* The backend, over a supplied transport.
+	*
+	* @remarks
+	* The Twirp protocol — the RPC sequence, the conflict handling, the retry
+	* policy, the framing — is what this package owns and what a test needs to
+	* exercise; the Azure client is a pre-signed `PUT` that owns none of it. This
+	* is also the seam an integration test uses to point the same protocol at a
+	* local blob endpoint.
+	*
+	* A parameterized layer factory mints a fresh layer per call and layers
+	* memoize by reference — bind it to a `const` rather than calling it at each
+	* composition site.
+	*/
+	static layerWith = (transfer) => Layer.effect(BlobStore, make(transfer));
+};
+
+//#endregion
+export { GitHubCacheBlobStore };

package/BlobStore.js

@@ -0,0 +1,203 @@
+import { BlobEnvelope } from "./BlobEnvelope.js";
+import { sign } from "./internal/sigv4.js";
+import { Secret } from "./Secret.js";
+import { Context, Effect, Layer, Option, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+
+//#region src/BlobStore.ts
+/**
+* Raised when a blob cannot be stored or retrieved.
+*
+* @public
+*/
+var BlobStoreError = class extends Schema.TaggedErrorClass()("BlobStoreError", {
+	/**
+	* `unreachable` — the store could not be contacted. `refused` — it answered,
+	* unhappily; `status` says how. `misconfigured` — the layer was built with
+	* settings the store cannot use.
+	*/
+	reason: Schema.Literals([
+		"unreachable",
+		"refused",
+		"misconfigured"
+	]),
+	/** The key involved. A stable identifier, never a value. */
+	key: Schema.optionalKey(Schema.String),
+	/** The HTTP status, when the store answered. */
+	status: Schema.optionalKey(Schema.Number),
+	/** What is wrong, when the reason alone does not say. */
+	detail: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "unreachable": return `The blob store could not be reached${this.key === void 0 ? "" : ` for "${this.key}"`}`;
+			case "refused": return `The blob store refused "${this.key}"${this.status === void 0 ? "" : ` with status ${this.status}`}${this.detail === void 0 ? "" : `: ${this.detail}`}`;
+			default: return `The blob store is misconfigured${this.detail === void 0 ? "" : `: ${this.detail}`}`;
+		}
+	}
+};
+/**
+* Durable blob storage with a metadata channel.
+*
+* @remarks
+* `get`/`put`/`has` over `Uint8Array` **plus the caller's own metadata**, framed
+* by {@link BlobEnvelope}. The metadata channel is the reason this exists: the
+* consumer it was designed against hand-rolled a binary frame
+* (`[4B tagLen][4B durationMs][tag][body]`) and namespaced its keys with a `v2`
+* prefix to represent a format change. Both are framing concerns that had
+* leaked into a consumer, and both are absorbed here.
+*
+* Deliberately no `list` and no `delete`: eviction belongs to the backend, both
+* backends already have one, and no consumer asked for either.
+*
+* @example
+* ```ts
+* import { BlobStore } from "@effected/github-actions";
+* import { Effect, Schema } from "effect";
+*
+* class Meta extends Schema.Class<Meta>("Meta")({ tag: Schema.String, durationMs: Schema.Number }) {}
+*
+* const program = Effect.gen(function* () {
+*   const store = yield* BlobStore;
+*   yield* store.put("build/1", { metadata: Meta.make({ tag: "x", durationMs: 12 }), body: bytes }, Meta);
+*   return yield* store.get("build/1", Meta);
+* });
+* ```
+*
+* @public
+*/
+var BlobStore = class BlobStore extends Context.Service()("@effected/github-actions/BlobStore") {
+	/**
+	* An S3-compatible backend, signed with SigV4.
+	*
+	* @remarks
+	* No `@aws-sdk/*` dependency: signing is a specified algorithm over strings
+	* and HMACs, and this package already has `node:crypto`. The SDK's weight is
+	* in credential management, retries and a service catalogue none of which
+	* this needs.
+	*
+	* A parameterized layer factory mints a fresh layer per call and layers
+	* memoize by reference — bind it to a `const` rather than calling it at each
+	* composition site.
+	*/
+	static layerS3 = (config) => Layer.effect(BlobStore, makeS3(config));
+	/** A test double. Unstubbed members die rather than reporting a miss. */
+	static makeTest = (overrides = {}) => ({
+		get: () => Effect.sync(() => unimplemented("get")),
+		put: () => Effect.sync(() => unimplemented("put")),
+		has: () => Effect.sync(() => unimplemented("has")),
+		...overrides
+	});
+	/** {@link BlobStore.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(BlobStore, BlobStore.makeTest(overrides));
+	/**
+	* An in-memory backend.
+	*
+	* @remarks
+	* Not a stub: it runs the real {@link BlobEnvelope} framing, so a round trip
+	* through it exercises encode and decode exactly as a network backend would.
+	* A test that wants to prove its metadata survives storage should use this
+	* rather than a double whose `get` returns whatever its `put` was handed.
+	*/
+	static layerMemory = Layer.sync(BlobStore, () => {
+		const entries = /* @__PURE__ */ new Map();
+		return {
+			get: (key, schema) => Effect.suspend(() => {
+				const stored = entries.get(key);
+				return stored === void 0 ? Effect.succeed(Option.none()) : Effect.map(Effect.fromResult(BlobEnvelope.decodeResult(stored, schema)), Option.some);
+			}),
+			put: (key, blob, schema) => Effect.suspend(() => Effect.map(Effect.fromResult(BlobEnvelope.encodeResult(blob.metadata, blob.body, schema)), (framed) => {
+				entries.set(key, framed);
+			})),
+			has: (key) => Effect.sync(() => entries.has(key))
+		};
+	});
+};
+const unimplemented = (member) => {
+	throw new Error(`BlobStore.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+const makeS3 = (config) => Effect.gen(function* () {
+	const http = yield* HttpClient.HttpClient;
+	let endpoint = config.endpoint ?? `https://s3.${config.region}.amazonaws.com`;
+	while (endpoint.endsWith("/")) endpoint = endpoint.slice(0, -1);
+	const host = new URL(endpoint).host;
+	const secretAccessKey = yield* Secret.forSigning(config.secretAccessKey);
+	const sessionToken = config.sessionToken === void 0 ? void 0 : yield* Secret.forSigning(config.sessionToken);
+	const objectPath = (key) => [
+		config.bucket,
+		...config.prefix === void 0 ? [] : [config.prefix],
+		key
+	].join("/").replaceAll(/\/{2,}/g, "/");
+	const request = (method, key, body) => {
+		const path = objectPath(key);
+		const headers = sign({
+			method,
+			path,
+			host,
+			headers: {},
+			body,
+			now: /* @__PURE__ */ new Date()
+		}, {
+			accessKeyId: config.accessKeyId,
+			secretAccessKey,
+			...sessionToken === void 0 ? {} : { sessionToken },
+			region: config.region,
+			service: "s3"
+		});
+		return {
+			url: `${endpoint}/${path}`,
+			headers
+		};
+	};
+	const send = (method, key, body) => Effect.suspend(() => {
+		const { url, headers } = request(method, key, body);
+		const base = HttpClientRequest.make(method)(url, { headers });
+		const built = body.length === 0 ? base : HttpClientRequest.bodyUint8Array(base, body);
+		return http.execute(built).pipe(Effect.mapError((cause) => new BlobStoreError({
+			reason: "unreachable",
+			key,
+			cause
+		})));
+	});
+	return {
+		get: (key, schema) => Effect.gen(function* () {
+			const response = yield* send("GET", key, /* @__PURE__ */ new Uint8Array(0));
+			if (response.status === 404) return Option.none();
+			if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new BlobStoreError({
+				reason: "refused",
+				key,
+				status: response.status
+			}));
+			const buffer = yield* response.arrayBuffer.pipe(Effect.mapError((cause) => new BlobStoreError({
+				reason: "unreachable",
+				key,
+				cause
+			})));
+			return Option.some(yield* Effect.fromResult(BlobEnvelope.decodeResult(new Uint8Array(buffer), schema)));
+		}),
+		put: (key, blob, schema) => Effect.gen(function* () {
+			const framed = yield* Effect.fromResult(BlobEnvelope.encodeResult(blob.metadata, blob.body, schema));
+			const response = yield* send("PUT", key, framed);
+			if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new BlobStoreError({
+				reason: "refused",
+				key,
+				status: response.status
+			}));
+		}),
+		has: (key) => Effect.gen(function* () {
+			const response = yield* send("HEAD", key, /* @__PURE__ */ new Uint8Array(0));
+			if (response.status === 404) return false;
+			if (response.status < 200 || response.status >= 300) return yield* Effect.fail(new BlobStoreError({
+				reason: "refused",
+				key,
+				status: response.status
+			}));
+			return true;
+		})
+	};
+});
+
+//#endregion
+export { BlobStore, BlobStoreError };

package/BlobTransfer.js

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+
+//#region src/BlobTransfer.ts
+/**
+* Raised when bytes could not be moved to or from a signed blob url.
+*
+* @public
+*/
+var BlobTransferError = class extends Schema.TaggedErrorClass()("BlobTransferError", {
+	/** Which direction failed. */
+	reason: Schema.Literals(["uploadFailed", "downloadFailed"]),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return this.reason === "uploadFailed" ? "Could not upload to the signed blob url" : "Could not download from the signed blob url";
+	}
+};
+
+//#endregion
+export { BlobTransferError };

package/CacheKey.js

@@ -0,0 +1,234 @@
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { createHash } from "node:crypto";
+import { GlobSet } from "@effected/glob";
+
+//#region src/CacheKey.ts
+/**
+* Raised when a cache key cannot be derived from the filesystem.
+*
+* @public
+*/
+var CacheKeyError = class extends Schema.TaggedErrorClass()("CacheKeyError", {
+	/**
+	* `readFailed` — a file or directory that was going to be hashed could not be
+	* read. `badPattern` — a glob pattern would not compile. Key *derivation*
+	* itself is pure and total once the bytes are in hand, so these are the only
+	* two things that can go wrong.
+	*/
+	reason: Schema.Literals(["readFailed", "badPattern"]),
+	/** The path being read when it went wrong. */
+	path: Schema.optionalKey(Schema.String),
+	/** The pattern that would not compile. */
+	pattern: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return this.reason === "readFailed" ? `Could not read "${this.path}" while deriving a cache key` : `"${this.pattern}" is not a usable glob pattern`;
+	}
+};
+/**
+* The separator between key segments.
+*
+* @remarks
+* `-` is not arbitrary: it is what every published Actions cache recipe uses,
+* and a restore key is a **prefix match**, so the separator is what makes a
+* partial key a meaningful boundary rather than a coincidence.
+*/
+const SEPARATOR = "-";
+/** GitHub refuses a cache key longer than this. */
+const MAX_KEY_LENGTH = 512;
+/**
+* One component of a cache key.
+*
+* @remarks
+* Commas and newlines are refused because the runner uses both to delimit the
+* restore-key list — a segment carrying one would silently become two keys.
+*/
+const Segment = Schema.String.check(Schema.isPattern(/^[^,\n\r]+$/));
+const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values) => values.join(SEPARATOR).length <= MAX_KEY_LENGTH, { title: `a cache key of at most ${MAX_KEY_LENGTH} characters` }));
+/**
+* A GitHub Actions cache key and the restore-key ladder that goes with it.
+*
+* @remarks
+* The ladder is the part every consumer re-derives and gets subtly wrong. A
+* restore key is a **prefix match** on GitHub's side, so `Linux-pnpm` would
+* also match `Linux-pnpm-store-…` from an unrelated cache; every rung here
+* therefore ends in the separator. Deriving the rungs from the segments makes
+* the primary key and its fallbacks impossible to drift apart, which is the
+* failure that produces a cache that never hits and never says why.
+*
+* @example
+* ```ts
+* import { CacheKey } from "@effected/github-actions";
+*
+* const key = CacheKey.of("Linux", "pnpm-store", "abc123");
+* key.key;          // "Linux-pnpm-store-abc123"
+* key.restoreKeys;  // ["Linux-pnpm-store-", "Linux-"]
+* ```
+*
+* @public
+*/
+var CacheKey = class CacheKey extends Schema.Class("CacheKey")({ 
+/** The components, most general first. */
+segments: Segments }) {
+	/** The primary key: every segment, joined. */
+	get key() {
+		return this.segments.join(SEPARATOR);
+	}
+	/**
+	* The restore keys, most specific first.
+	*
+	* @remarks
+	* Each rung drops the last segment and keeps the trailing separator, so a
+	* three-segment key falls back to two prefixes and a one-segment key falls
+	* back to nothing — there is no rung that would match every cache in the
+	* repository.
+	*/
+	get restoreKeys() {
+		const rungs = [];
+		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(`${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`);
+		return rungs;
+	}
+	/** Build a key from its segments. */
+	static of(...segments) {
+		return CacheKey.make({ segments });
+	}
+	/**
+	* A branch-aware key.
+	*
+	* @remarks
+	* Ordering the segments `os → scope → branch → hash` is what makes the
+	* derived ladder do the right thing: the first rung falls back to any earlier
+	* cache **on this branch**, and only the next one reaches across branches. The
+	* reverse order would make the first fallback jump branches, which is how a
+	* feature branch ends up warming its cache from `main` and never noticing its
+	* own.
+	*
+	* Every part is an explicit argument rather than read from the environment,
+	* so a key is reproducible outside a runner and a test needs no ambient
+	* state.
+	*/
+	static forBranch(options) {
+		const segments = [];
+		if (options.os !== void 0) segments.push(options.os);
+		segments.push(options.scope, options.branch);
+		if (options.hash !== void 0) segments.push(options.hash);
+		return CacheKey.make({ segments });
+	}
+	/**
+	* Hash a set of files into a single digest.
+	*
+	* @remarks
+	* **Byte-compatible with `@actions/glob`'s `hashFiles`**, and the three
+	* details that make it so are all easy to get wrong: the paths are sorted, each
+	* file is hashed on its own, and the per-file digest is fed into the
+	* accumulator as **binary** rather than hex. A hex-fed accumulator produces a
+	* perfectly plausible digest that simply never matches a cache entry written
+	* by any other action.
+	*
+	* Sorting and de-duplication happen here rather than at the call site, so a
+	* caller cannot accidentally make its key depend on the order it discovered
+	* files in.
+	*
+	* `Option.none()` for an empty set, because "nothing matched" is not a
+	* digest — it is the signal that the pattern is wrong, and a caller that
+	* folds it into a key silently caches against a constant.
+	*/
+	static hashFiles = Effect.fn("CacheKey.hashFiles")(function* (files) {
+		const fs = yield* FileSystem.FileSystem;
+		const ordered = [...new Set(files)].sort();
+		if (ordered.length === 0) return Option.none();
+		const accumulator = createHash("sha256");
+		for (const path of ordered) {
+			const bytes = yield* fs.readFile(path).pipe(Effect.mapError((cause) => new CacheKeyError({
+				reason: "readFailed",
+				path,
+				cause
+			})));
+			accumulator.update(createHash("sha256").update(bytes).digest());
+		}
+		return Option.some(accumulator.digest("hex"));
+	});
+	/**
+	* Every file under `workspace` that the pattern set matches.
+	*
+	* @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
+	* called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
+	* would fail rather than being ignored.
+	*
+	* The answer is sorted, so a caller cannot make its key depend on the order
+	* the filesystem happened to report.
+	*/
+	static matchingFiles = Effect.fn("CacheKey.matchingFiles")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const set = yield* GlobSet.compile(options.patterns).pipe(Effect.mapError((cause) => new CacheKeyError({
+			reason: "badPattern",
+			pattern: cause.pattern,
+			cause
+		})));
+		const entries = yield* fs.readDirectory(options.workspace, { recursive: true }).pipe(Effect.mapError((cause) => new CacheKeyError({
+			reason: "readFailed",
+			path: options.workspace,
+			cause
+		})));
+		const matched = [];
+		for (const entry of entries) {
+			if (!set.matches(entry.replaceAll("\\", "/"))) continue;
+			const absolute = path.join(options.workspace, entry);
+			if ((yield* fs.stat(absolute).pipe(Effect.mapError((cause) => new CacheKeyError({
+				reason: "readFailed",
+				path: absolute,
+				cause
+			})))).type === "File") matched.push(absolute);
+		}
+		return matched.sort();
+	});
+	/**
+	* Hash every file under `workspace` that the pattern set matches.
+	*
+	* @remarks
+	* {@link CacheKey.matchingFiles} into {@link CacheKey.hashFiles}, which is
+	* the pairing every consumer writes by hand — and the pairing whose two
+	* halves have to agree about ordering and about what counts as a file for the
+	* digest to match anything anyone else computed.
+	*
+	* `Option.none()` when nothing matched, for the same reason `hashFiles` gives:
+	* "no files" is not a digest, it is the signal that the patterns are wrong,
+	* and folding it into a key silently caches against a constant.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	* import { Effect, Option } from "effect";
+	*
+	* const key = Effect.gen(function* () {
+	*   const hash = yield* CacheKey.hashMatching({
+	*     workspace: "/home/runner/work/repo/repo",
+	*     patterns: ["**\/pnpm-lock.yaml", "!**\/node_modules/**"],
+	*   });
+	*   return CacheKey.of("Linux", "pnpm-store", Option.getOrElse(hash, () => "empty"));
+	* });
+	* ```
+	*/
+	static hashMatching = Effect.fn("CacheKey.hashMatching")(function* (options) {
+		return yield* CacheKey.hashFiles(yield* CacheKey.matchingFiles(options));
+	});
+};
+
+//#endregion
+export { CacheKey, CacheKeyError };