@effected/github-actions 0.13.0 → 0.13.1

package/index.d.ts

@@ -1307,20 +1307,30 @@ export declare class CacheKey extends CacheKey_base {
    *
    * @remarks
    * Discovery and matching are **two different jobs**, and separating them is
-   * what makes this testable and correct. The walk is core
-   * `FileSystem.readDirectory(recursive)`; the matching is `@effected/glob`'s
-   * full minimatch dialect — the same dialect `@actions/glob` uses, so a workflow
-   * author's `!**\/node_modules/**` behaves here exactly as it does in every
-   * other cache step in the same workflow. `node:fs.globSync` would have welded
-   * the two together behind one non-stubbable call *and* changed the dialect,
-   * and a dialect divergence surfaces as a silent cache-key difference — the
-   * worst failure mode a cache key has.
-   *
-   * Candidates are matched by their path **relative to the workspace**, which
-   * is what makes "never hash a file outside the workspace" structural rather
-   * than a rule someone has to remember. Directories are excluded: a directory
+   * what makes this testable and correct. The walk is `@effected/walker`'s
+   * `descend`, run once per include from that include's own literal prefix
+   * (a literal include is one `stat`, never a walk) with nothing pruned
+   * implicitly; the matching is `@effected/glob`'s full minimatch dialect —
+   * the same dialect `@actions/glob` uses, so a workflow author's
+   * `!**\/node_modules/**` behaves here exactly as it does in every other
+   * cache step in the same workflow. `node:fs.globSync` would have welded the
+   * two together behind one non-stubbable call *and* changed the dialect, and
+   * a dialect divergence surfaces as a silent cache-key difference — the worst
+   * failure mode a cache key has.
+   *
+   * Candidates are matched by their path **relative to the workspace**, and a
+   * literal that climbs above it (`../lockfile`) is dropped, which is what
+   * makes "never hash a file outside the workspace" structural rather than a
+   * rule someone has to remember. Directories are excluded: a directory
    * called `notes.txt` matches `**\/*.txt` and is not a file, and hashing it
-   * would fail rather than being ignored.
+   * would fail rather than being ignored. An absent literal is a miss; any
+   * other failure to read one is a typed `CacheKeyReadError`, because a key
+   * derived from an incomplete file set is wrong in a way nothing reports.
+   *
+   * **One knowing divergence from the runner's `hashFiles()`:** `descend`
+   * never enters a symlinked directory (cycle safety), where `@actions/glob`
+   * follows links by default. A file reachable only through a symlinked
+   * directory does not contribute to the key.
    *
    * The answer is sorted, so a caller cannot make its key depend on the order
    * the filesystem happened to report.
@@ -3428,7 +3438,7 @@ export declare class DetachedProcess {
    * yet, and silently retrying the first is how a misconfigured probe becomes a
    * timeout six seconds later with nothing to show for it.
    */
-  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<void, E | DetachedProcessError, R>;
+  static readonly awaitReady: <E, R>(probe: Effect.Effect<boolean, E, R>, options?: ReadinessOptions | undefined) => Effect.Effect<undefined, E | DetachedNotReadyError, R>;
   /**
    * A readiness probe over HTTP: `true` when a `GET` answers 2xx.
    *
@@ -3550,15 +3560,6 @@ declare const DryRun_base: Context.ServiceClass<DryRun, "@effected/github-action
  * @public
  */
 export declare class DryRun extends DryRun_base {
-  /**
-   * Driven by the `dry-run` action input, defaulting to a real run.
-   *
-   * @remarks
-   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
-   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
-   * not quietly perform the mutations it meant to rehearse.
-   */
-  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
   /**
    * Driven by a named input.
    *
@@ -3568,6 +3569,15 @@ export declare class DryRun extends DryRun_base {
    * composition site.
    */
   static readonly layerFromInput: (name: string) => Layer.Layer<DryRun, Config.ConfigError>;
+  /**
+   * Driven by the `dry-run` action input, defaulting to a real run.
+   *
+   * @remarks
+   * Fails with a `ConfigError` when the input is present but is not a YAML 1.2
+   * core-schema boolean — a workflow that writes `dry-run: yes` should stop,
+   * not quietly perform the mutations it meant to rehearse.
+   */
+  static readonly layer: Layer.Layer<DryRun, Config.ConfigError>;
   /** Driven by an explicit decision the caller has already made. */
   static readonly layerFrom: (enabled: boolean) => Layer.Layer<DryRun>;
   /**
@@ -4130,6 +4140,7 @@ declare const ManagedDocument_base: Schema.Class<ManagedDocument, Schema.Struct<
  * @public
  */
 export declare class ManagedDocument extends ManagedDocument_base {
+  #private;
   /**
    * Read a document out of existing text, or begin a fresh one.
    *
@@ -4216,6 +4227,9 @@ export declare class ManagedDocument extends ManagedDocument_base {
    * synchronous callers can use that variant directly.
    */
   withRegions(entries: ReadonlyArray<readonly [key: string, content: string, meta?: Readonly<Record<string, string>>]>): Effect.Effect<ManagedDocument, ManagedDocumentError>;
+  private scan;
+  /** What every wire key of this document's regions begins with. */
+  private get wirePrefix();
   /** The marker key a region is written under: `namespace.key.region`. */
   private wireKey;
   /** The region key back out of a wire key, for error reporting. */

package/internal/actionsResults.js

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

package/internal/cacheService.js

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

package/internal/digest.js

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

package/internal/fsProbe.js

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+
+//#region src/internal/fsProbe.ts
+/**
+* The entry's type, or `undefined` when nothing readable is there. Absence
+* and unreadability collapse together on purpose: every caller's next move
+* (reinstall, write the shim, fail `layoutUnexpected`) is the same for both.
+*
+* @internal
+*/
+const typeAt = (fs, path) => Effect.map(Effect.option(fs.stat(path)), (info) => info._tag === "Some" ? info.value.type : void 0);
+
+//#endregion
+export { typeAt };

package/internal/jwt.js

@@ -0,0 +1,63 @@
+import { Encoding, Result } from "effect";
+
+//#region src/internal/jwt.ts
+/**
+* The JWT segment codec — read a payload, or frame an unsigned token — for the
+* two places this package reads a runner-issued token's claims.
+*
+* @remarks
+* **No signature verification, deliberately.** Every token read here was
+* handed to this process by the runner that started it, and the claim read
+* scopes a request (`actionsResults`) or is republished for a verifier
+* elsewhere (`OidcTokenIssuer`); neither authorizes anything on the strength
+* of the claim alone. Do not "fix" it here.
+*
+* Core `Encoding` does the base64url work, so no `Buffer` is involved: it is
+* strict about the alphabet where Node's decoder is forgiving, which is why
+* there is a test whose payload actually contains `-` and `_`.
+*
+* @internal
+*/
+/**
+* The decoded payload of `token` — the middle segment, base64url JSON —
+* without any check on the signature.
+*
+* @internal
+*/
+const payloadOf = (token) => {
+	const segments = token.split(".");
+	const payload = segments[1];
+	if (segments.length !== 3 || payload === void 0 || payload === "") return Result.fail({
+		kind: "segments",
+		detail: `expected three segments, got ${segments.length}`
+	});
+	const json = Encoding.decodeBase64UrlString(payload);
+	if (Result.isFailure(json)) return Result.fail({
+		kind: "payload",
+		detail: "the payload is not base64url JSON",
+		cause: json.failure
+	});
+	try {
+		return Result.succeed(JSON.parse(json.success));
+	} catch (cause) {
+		return Result.fail({
+			kind: "payload",
+			detail: "the payload is not base64url JSON",
+			cause
+		});
+	}
+};
+/**
+* An **unsigned** JWT: `header.payload.unsigned`, each JSON segment
+* base64url-encoded. For building test doubles and nothing else — the
+* signature segment is a placeholder, so this token fails any verifier.
+*
+* @internal
+*/
+const unsignedJwt = (header, payload) => {
+	const segment = (value) => Encoding.encodeBase64Url(JSON.stringify(value));
+	return `${segment(header)}.${segment(payload)}.unsigned`;
+};
+
+//#endregion
+export { payloadOf, unsignedJwt };

package/internal/runner.js

@@ -0,0 +1,31 @@
+import { Effect, Option } from "effect";
+
+//#region src/internal/runner.ts
+/**
+* Whether `RUNNER_OS` says Windows. `false` when unset — off a runner, the
+* POSIX shape is the honest default.
+*
+* @internal
+*/
+const isWindowsRunner = (env) => Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
+	onNone: () => false,
+	onSome: (os) => os.toLowerCase() === "windows"
+}));
+/**
+* The tool-cache root: `RUNNER_TOOL_CACHE`, or `/tmp/runner-tool-cache` off a
+* runner.
+*
+* @remarks
+* 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.
+*
+* @internal
+*/
+const toolCacheRoot = (env, path) => Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
+
+//#endregion
+export { isWindowsRunner, toolCacheRoot };

package/internal/runnerFile.js

@@ -0,0 +1,45 @@
+//#region src/internal/runnerFile.ts
+/**
+* The runner-file heredoc protocol — `GITHUB_OUTPUT`, `GITHUB_ENV` and
+* `GITHUB_STATE` all take `name<<DELIM\nvalue\nDELIM\n` — spelled once for
+* `ActionOutputs` and `ActionState`.
+*
+* @remarks
+* **Delimiters are derived, never random.** GitHub's own toolkit uses a
+* random UUID here and accepts the (tiny) chance of collision. Deriving the
+* delimiter instead makes collision **impossible** rather than improbable,
+* needs no randomness — so no `Crypto` in `R` and no unreproducible output —
+* and is trivially testable. A value that contains a delimiter would
+* terminate its block early and corrupt every entry after it, which is a
+* value-controlled injection into the runner's own file.
+*
+* @internal
+*/
+/** The base delimiter for a heredoc block. */
+const BASE_DELIMITER = "EFFECTED_EOF";
+/** A delimiter guaranteed absent from `value`. @internal */
+const delimiterFor = (value) => {
+	let delimiter = BASE_DELIMITER;
+	while (value.includes(delimiter)) delimiter = `${delimiter}_`;
+	return delimiter;
+};
+/**
+* Whether `name` can head a block without breaking the structure it lives
+* in: non-empty, and free of the line breaks that would end it early.
+*
+* @internal
+*/
+const isUsableName = (name) => name !== "" && !/[\r\n]/.test(name);
+/**
+* One heredoc block, ready to append. The caller has checked the name with
+* {@link isUsableName}.
+*
+* @internal
+*/
+const heredocBlock = (name, value) => {
+	const delimiter = delimiterFor(value);
+	return `${name}<<${delimiter}\n${value}\n${delimiter}\n`;
+};
+
+//#endregion
+export { delimiterFor, heredocBlock, isUsableName };

package/internal/sigv4.js

@@ -1,4 +1,5 @@
-import { createHash, createHmac } from "node:crypto";
+import { sha256Hex } from "./digest.js";
+import { createHmac } from "node:crypto";
 
 //#region src/internal/sigv4.ts
 /**
@@ -18,7 +19,6 @@ import { createHash, createHmac } from "node:crypto";
 * @internal
 */
 const ALGORITHM = "AWS4-HMAC-SHA256";
-const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
 const hmac = (key, value) => new Uint8Array(createHmac("sha256", key).update(value).digest());
 /**
 * Percent-encode one path segment the way SigV4 requires.
@@ -114,4 +114,4 @@ const sign = (request, credentials) => {
 };
 
 //#endregion
-export { canonicalize, sign, signingKey, uriEncode };
+export { canonicalize, sha256Hex as digestHex, sign, signingKey, uriEncode };

package/internal/spawn.js

@@ -0,0 +1,18 @@
+import { Effect, Stream } from "effect";
+
+//#region src/internal/spawn.ts
+/**
+* Spawn `command` once, drain `stdout`+`stderr`, then read the exit code from
+* the same handle. Never fails on a non-zero exit — that is the caller's
+* policy.
+*/
+const spawnOnce = (spawner, command) => Effect.scoped(Effect.gen(function* () {
+	const handle = yield* spawner.spawn(command);
+	return {
+		output: yield* Stream.mkString(Stream.decodeText(handle.all)),
+		code: yield* handle.exitCode
+	};
+}));
+
+//#endregion
+export { spawnOnce };

package/internal/twirp.js

@@ -14,6 +14,23 @@ import { HttpClientRequest } from "effect/unstable/http";
 */
 const CONFLICT = Symbol.for("@effected/github-actions/twirp/conflict");
 /**
+* The error fields a {@link TwirpFailure} contributes to a caller's own error
+* class — the cache, artifact and blob-store errors all carry `reason`,
+* `status`, `detail` and `cause` under the same names, so each spreads this
+* and adds its own identifier.
+*
+* @internal
+*/
+const twirpFailureFields = (failure) => failure.kind === "status" ? {
+	reason: "refused",
+	detail: failure.method,
+	...failure.status === void 0 ? {} : { status: failure.status }
+} : {
+	reason: "unreachable",
+	detail: `${failure.method} did not answer with a Twirp body`,
+	...failure.cause === void 0 ? {} : { cause: failure.cause }
+};
+/**
 * Whether retrying could plausibly help.
 *
 * @remarks
@@ -94,4 +111,4 @@ const stringField = (body, name) => {
 const isOk = (body) => field(body, "ok") === true;
 
 //#endregion
-export { CONFLICT, field, isOk, isRetryable, stringField, twirpCall };
+export { CONFLICT, field, isOk, isRetryable, stringField, twirpCall, twirpFailureFields };

package/internal/unstubbed.js

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+
+//#region src/internal/unstubbed.ts
+/**
+* The one way an unstubbed test-double member dies, for every `makeTest` in
+* this package.
+*
+* @remarks
+* A double's unstubbed member must die rather than silently succeed — a stub
+* that returns nothing teaches a test that nothing happened. The message names
+* the double, the member and the override that fixes it, and it is spelled
+* here once so a wording change is one edit rather than ten.
+*
+* @internal
+*/
+/**
+* The die-on-call members of `<double>.makeTest`: `dies("save")` is an
+* `Effect` that defects naming `save` when run. Each package double binds its
+* own name once, then lists its members.
+*
+* @internal
+*/
+const unstubbed = (double) => (member) => Effect.sync(() => {
+	throw new Error(`${double}: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+});
+
+//#endregion
+export { unstubbed };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github-actions",
-	"version": "0.13.0",
+	"version": "0.13.1",
 	"private": false,
 	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
 	"keywords": [
@@ -44,7 +44,8 @@
 		"@effected/markdown": "^0.10.0",
 		"@effected/npm": "^0.14.0",
 		"@effected/sbom": "^0.6.1",
-		"@effected/templates": "^0.6.0"
+		"@effected/templates": "^0.6.0",
+		"@effected/walker": "^0.9.0"
 	},
 	"peerDependencies": {
 		"@effect/platform-node": "4.0.0-rc.115",