@effected/github-actions 0.1.0

package/Action.js

@@ -0,0 +1,138 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { ActionInput } from "./ActionInput.js";
+import { WorkflowCommand } from "./WorkflowCommand.js";
+import { ActionLogger } from "./ActionLogger.js";
+import { ActionOutputs } from "./ActionOutputs.js";
+import { ActionState } from "./ActionState.js";
+import { NodeServices } from "@effect/platform-node";
+import { Cause, Effect, Exit, Layer, Option, Result } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+
+//#region src/Action.ts
+/**
+* The default runtime an action executes inside.
+*
+* @remarks
+* The one place in the kit where `@effect/platform-node` is composed rather
+* than left to the consumer, and the reason is that there is no second answer:
+* a GitHub Action is a Node process on a GitHub-provided runner.
+*
+* **The cache, artifact and blob services are deliberately NOT in here.** They
+* are the only modules that import `@azure/storage-blob`, and folding them into
+* the default runtime would put a blob-storage client in the bundle of every
+* action that merely sets an output. Their requirements are all satisfied by
+* this layer, so taking one costs a caller exactly one line:
+* `Action.run(program, { layer: ActionCache.layer })`.
+*
+* @public
+*/
+var ActionRuntime = class {
+	constructor() {}
+	/**
+	* The composed default: the runner services, the platform, an HTTP client
+	* and the workflow-command `Logger`.
+	*
+	* @remarks
+	* A bound constant rather than a factory. A layer-returning function mints a
+	* fresh layer per call, and layers memoize by reference — a factory here
+	* would rebuild the environment snapshot for every composition site.
+	*/
+	static layer = Layer.mergeAll(ActionLogger.layer, ActionLogger.layerLogger, ActionState.layer, ActionInput.layerDefault).pipe(Layer.provideMerge(ActionOutputs.layer), Layer.provideMerge(ActionEnvironment.layer), Layer.provideMerge(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)));
+};
+/**
+* A readable one-line summary of why an action failed.
+*
+* @remarks
+* `[Tag] message` because a workflow log is read by a human scanning for the
+* first red line, and every error in this kit carries both. The `_tag` is what
+* makes two failures with the same wording distinguishable, and the `message`
+* getter is what makes the line worth reading.
+*
+* An interruption has neither, and `Cause.pretty` is the honest answer for it.
+*
+* @public
+*/
+const describeCause = (cause) => {
+	const failure = Cause.findErrorOption(cause);
+	if (Option.isSome(failure)) return describeError(failure.value);
+	const defect = Cause.findDefect(cause);
+	if (Result.isSuccess(defect)) return `[defect] ${describeError(defect.success)}`;
+	const pretty = Cause.pretty(cause);
+	return pretty.trim() === "" ? "the action failed with no diagnostic information" : pretty;
+};
+/** The `[Tag]: message` half, over anything a failure or a defect can be. */
+const describeError = (error) => {
+	if (typeof error === "object" && error !== null && "_tag" in error) {
+		const tagged = error;
+		const detail = typeof tagged.message === "string" && tagged.message !== "" ? `: ${tagged.message}` : "";
+		return `[${String(tagged._tag)}]${detail}`;
+	}
+	return error instanceof Error ? `[${error.name}]: ${error.message}` : `[unknown]: ${String(error)}`;
+};
+/**
+* The entry point an action's `main`, `pre` and `post` scripts call.
+*
+* @remarks
+* Everything an action entry point does that is not the action: compose the
+* runtime, run the program, render a failure as a `::error::` annotation, and
+* **set the exit code** — which is the piece
+* `ActionOutputs.setFailed` deliberately leaves alone, so an action that
+* reports a failure and then recovers is not doomed by a side effect it cannot
+* undo.
+*
+* Two things it deliberately does **not** do:
+*
+* - **It does not wrap the program in a log buffer.** The package this replaces
+*   did, and an unhandled defect inside the buffer swallowed the entire
+*   transcript — the run failed and printed nothing. `ActionLogger.withBuffer`
+*   is opt-in and flushes on every exit path including a defect, so the
+*   buffering is where the caller can see it.
+* - **It does not throw.** The returned promise always resolves; the failure is
+*   in `process.exitCode`, which is what the runner reads. An action entry
+*   point that rejected would produce an unhandled rejection *and* a failed
+*   step, and only the first would be legible.
+*
+* The rendering depth is deliberate too: one `::error::` line carrying
+* `[Tag]: message`, and the fiddly diagnostics — the full `Cause.pretty` render
+* with its span trace and stack — behind `::debug::`, which the runner shows
+* only when someone turns step debugging on. The package this replaces spliced
+* a JS stack into the visible error, which in a bundled action points at one
+* line of `dist/main.js`.
+*
+* @example
+* ```ts
+* import { Action, ActionCache } from "@effected/github-actions";
+*
+* await Action.run(program, { layer: ActionCache.layer });
+* ```
+*
+* @public
+*/
+var Action = class {
+	constructor() {}
+	/** {@link describeCause}, so an action can render its own failures the same way. */
+	static describeCause = describeCause;
+	/**
+	* Run an action program to completion.
+	*
+	* @remarks
+	* Resolves whether the program succeeded or not; read `process.exitCode` for
+	* the verdict.
+	*/
+	static run = (program, options = {}) => {
+		const extra = options.layer;
+		const composed = extra === void 0 ? ActionRuntime.layer : Layer.mergeAll(ActionRuntime.layer, Layer.provide(extra, ActionRuntime.layer));
+		const runnable = program.pipe(Effect.provide(composed), Effect.exit, Effect.flatMap((exit) => Exit.isSuccess(exit) ? Effect.void : Effect.sync(() => {
+			const detail = Cause.pretty(exit.cause);
+			if (detail.trim() !== "") console.log(WorkflowCommand.render("debug", {}, detail));
+			console.log(WorkflowCommand.render("error", {}, `Action failed: ${describeCause(exit.cause)}`));
+			process.exitCode = 1;
+		})));
+		return Effect.runPromise(runnable).catch(() => {
+			process.exitCode = 1;
+		});
+	};
+};
+
+//#endregion
+export { Action, ActionRuntime, describeCause };

package/ActionCache.js

@@ -0,0 +1,317 @@
+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 { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { createHash } from "node:crypto";
+import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+//#region src/ActionCache.ts
+/**
+* Raised when the runner's cache cannot be read or written.
+*
+* @public
+*/
+var ActionCacheError = class extends Schema.TaggedErrorClass()("ActionCacheError", {
+	/**
+	* `misconfigured` — the results backend is not reachable from here (see
+	* {@link ActionCache}). `unreachable` — it could not be contacted, or
+	* answered with something that is not a Twirp body. `refused` — it answered,
+	* unhappily. `archiveFailed` — `tar` would not pack or unpack the paths.
+	* `transferFailed` — the archive itself did not move.
+	*/
+	reason: Schema.Literals([
+		"misconfigured",
+		"unreachable",
+		"refused",
+		"archiveFailed",
+		"transferFailed"
+	]),
+	/** The cache key involved. A stable identifier, never a value. */
+	key: Schema.optionalKey(Schema.String),
+	/** The HTTP status, when the backend answered. */
+	status: Schema.optionalKey(Schema.Number),
+	/** What went wrong, when the reason alone does not say. */
+	detail: Schema.optionalKey(Schema.String),
+	/** `tar`'s own complaint, which is the only useful part of an archive failure. */
+	stderr: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		const about = this.key === void 0 ? "" : ` for "${this.key}"`;
+		const detail = this.detail === void 0 ? "" : `: ${this.detail}`;
+		switch (this.reason) {
+			case "misconfigured": return `The Actions cache is not reachable from here${detail}`;
+			case "unreachable": return `The Actions cache could not be reached${about}${detail}`;
+			case "refused": return `The Actions cache refused the request${about}${this.status === void 0 ? "" : ` with status ${this.status}`}${detail}`;
+			case "archiveFailed": return `The cache archive could not be built or extracted${about}${this.stderr === void 0 ? "" : `: ${this.stderr}`}`;
+			default: return `The cache archive did not transfer${about}`;
+		}
+	}
+};
+/** The Twirp service the Actions cache protocol lives under. */
+const SERVICE = "github.actions.results.api.v1.CacheService";
+/**
+* The entry version, byte-compatible with `actions/cache`.
+*
+* @remarks
+* A cache entry is keyed on `(key, version)`, and the version is a digest of
+* the archived paths plus the compression method. **The paths are not sorted**,
+* because upstream does not sort them: sorting here would compute a version no
+* other cache step in the workflow agrees with, and the entry a sibling step
+* wrote would simply never be found.
+*/
+const versionOf = (paths) => createHash("sha256").update([
+	...paths,
+	"gzip",
+	"1.0"
+].join("|")).digest("hex");
+/**
+* The Azure half, duplicated on purpose.
+*
+* @remarks
+* `@azure/storage-blob` may be imported here, by `Artifact` and by
+* `BlobStore.githubCache`, and nowhere else — hoisting these two calls into a
+* shared `internal/` helper is exactly how a heavy import leaks into the graph
+* of a module that only sets an output. `__test__/reachability.test.ts`
+* measures that these are the only three.
+*/
+const azure = {
+	uploadFile: (url, file) => Effect.tryPromise({
+		try: () => new BlockBlobClient(url).uploadFile(file, {
+			blockSize: 64 * 1024 * 1024,
+			concurrency: 8,
+			maxSingleShotSize: 128 * 1024 * 1024
+		}),
+		catch: (cause) => new BlobTransferError({
+			reason: "uploadFailed",
+			cause
+		})
+	}).pipe(Effect.asVoid),
+	downloadToFile: (url, file) => Effect.tryPromise({
+		try: () => new BlobClient(url).downloadToFile(file),
+		catch: (cause) => new BlobTransferError({
+			reason: "downloadFailed",
+			cause
+		})
+	}).pipe(Effect.asVoid)
+};
+const fromTwirp = (failure, key) => failure.kind === "status" ? new ActionCacheError({
+	reason: "refused",
+	key,
+	detail: failure.method,
+	...failure.status === void 0 ? {} : { status: failure.status }
+}) : new ActionCacheError({
+	reason: "unreachable",
+	key,
+	detail: `${failure.method} did not answer with a Twirp body`,
+	...failure.cause === void 0 ? {} : { cause: failure.cause }
+});
+/** The primary key and the ladder to fall back through. */
+const ladder = (key, restoreKeys) => typeof key === "string" ? {
+	primary: key,
+	fallbacks: restoreKeys ?? []
+} : {
+	primary: key.key,
+	fallbacks: restoreKeys ?? key.restoreKeys
+};
+const make = (transfer) => Effect.gen(function* () {
+	const http = yield* HttpClient.HttpClient;
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const env = yield* ActionEnvironment;
+	const windows = yield* Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
+		onNone: () => false,
+		onSome: (os) => os.toLowerCase() === "windows"
+	}));
+	const backend = resultsBackend(env).pipe(Effect.mapError((name) => new ActionCacheError({
+		reason: "misconfigured",
+		detail: `${name} is not set — the Actions cache 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)));
+	});
+	/**
+	* Run `tar`, keeping its stderr.
+	*
+	* @remarks
+	* On Windows, extraction runs with `-k` so a file another process holds
+	* open is skipped rather than failing the whole restore — and `tar` then
+	* exits 1 to say so, which is a warning rather than an error. Exit 2 and
+	* above stays a failure on every platform.
+	*/
+	const tar = (args, key, tolerateWarnings) => Effect.gen(function* () {
+		const command = ChildProcess.make("tar", [...args]);
+		const output = yield* spawner.string(command, { includeStderr: true }).pipe(Effect.mapError((cause) => new ActionCacheError({
+			reason: "archiveFailed",
+			key,
+			cause
+		})));
+		const code = yield* spawner.exitCode(command).pipe(Effect.mapError((cause) => new ActionCacheError({
+			reason: "archiveFailed",
+			key,
+			cause
+		})));
+		if (code !== 0 && !(tolerateWarnings && code === 1)) return yield* Effect.fail(new ActionCacheError({
+			reason: "archiveFailed",
+			key,
+			stderr: output.trim()
+		}));
+	});
+	/** A scratch archive path, removed on every exit path. */
+	const withArchive = (key, use) => Effect.acquireUseRelease(fs.makeTempDirectory({ prefix: "effected-cache-" }).pipe(Effect.mapError((cause) => new ActionCacheError({
+		reason: "archiveFailed",
+		key,
+		cause
+	}))), (directory) => use(path.join(directory, "cache.tar.gz")), (directory) => Effect.ignore(fs.remove(directory, {
+		recursive: true,
+		force: true
+	})));
+	const moved = (key) => Effect.mapError((cause) => new ActionCacheError({
+		reason: "transferFailed",
+		key,
+		cause
+	}));
+	return {
+		save: Effect.fn("ActionCache.save")(function* (paths, key) {
+			const { primary } = ladder(key, void 0);
+			yield* Effect.annotateCurrentSpan({ key: primary });
+			const version = versionOf(paths);
+			if (paths.length === 0) return yield* Effect.fail(new ActionCacheError({
+				reason: "archiveFailed",
+				key: primary,
+				detail: "no paths were given to cache"
+			}));
+			yield* withArchive(primary, (archive) => Effect.gen(function* () {
+				yield* tar([
+					"czPf",
+					archive,
+					...paths
+				], primary, false);
+				const size = yield* fs.stat(archive).pipe(Effect.mapError((cause) => new ActionCacheError({
+					reason: "archiveFailed",
+					key: primary,
+					cause
+				})));
+				const created = yield* call("CreateCacheEntry", {
+					key: primary,
+					version
+				}, primary);
+				if (created === CONFLICT) return;
+				const url = stringField(created, "signedUploadUrl");
+				if (!isOk(created) || url === void 0) return yield* Effect.fail(new ActionCacheError({
+					reason: "refused",
+					key: primary,
+					detail: "CreateCacheEntry returned no upload url"
+				}));
+				yield* transfer.uploadFile(url, archive).pipe(moved(primary));
+				const finalized = yield* call("FinalizeCacheEntryUpload", {
+					key: primary,
+					version,
+					size_bytes: String(size.size)
+				}, primary);
+				if (finalized === CONFLICT || !isOk(finalized)) return yield* Effect.fail(new ActionCacheError({
+					reason: "refused",
+					key: primary,
+					detail: "FinalizeCacheEntryUpload did not confirm the upload"
+				}));
+			}));
+		}),
+		restore: Effect.fn("ActionCache.restore")(function* (paths, key, restoreKeys) {
+			const { primary, fallbacks } = ladder(key, restoreKeys);
+			yield* Effect.annotateCurrentSpan({ key: primary });
+			const version = versionOf(paths);
+			const found = yield* call("GetCacheEntryDownloadURL", {
+				key: primary,
+				restore_keys: [...fallbacks],
+				version
+			}, primary);
+			if (found === CONFLICT || !isOk(found)) return Option.none();
+			const url = stringField(found, "signedDownloadUrl");
+			if (url === void 0) return Option.none();
+			yield* withArchive(primary, (archive) => Effect.gen(function* () {
+				yield* transfer.downloadToFile(url, archive).pipe(moved(primary));
+				yield* tar([windows ? "xzPkf" : "xzPf", archive], primary, windows);
+			}));
+			return Option.some(stringField(found, "matchedKey") ?? primary);
+		})
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`ActionCache.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* The runner's own cache: archive a set of paths under a key, and get them back
+* in a later job.
+*
+* @remarks
+* Speaks the Actions cache **Twirp v2** protocol at `ACTIONS_RESULTS_URL`,
+* which answers with a pre-signed Azure blob url for the archive itself. No
+* `@actions/cache` dependency — that package alone brings a dependency tree
+* larger than this one.
+*
+* **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 the identical code fails as
+* `misconfigured` when a workflow invokes it with `node ./main.js`. The failure
+* names the absent variable, because nothing else distinguishes the two cases.
+*
+* @example
+* ```ts
+* import { ActionCache, CacheKey } from "@effected/github-actions";
+* import { Effect, Option } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const cache = yield* ActionCache;
+*   const key = CacheKey.of("Linux", "pnpm-store", "abc123");
+*   const hit = yield* cache.restore(["~/.pnpm-store"], key);
+*   if (Option.isNone(hit)) {
+*     yield* cache.save(["~/.pnpm-store"], key);
+*   }
+* });
+* ```
+*
+* @public
+*/
+var ActionCache = class ActionCache extends Context.Service()("@effected/github-actions/ActionCache") {
+	/** The cache, over the real Azure client and the real `tar`. */
+	static layer = Layer.effect(this, make(azure));
+	/**
+	* The cache, over a supplied transport.
+	*
+	* @remarks
+	* The protocol, the version derivation, the conflict handling and the archive
+	* are what this package owns; the pre-signed `PUT` is not. Supplying the
+	* transport is what lets a test exercise all of the first group without the
+	* second, and what 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(ActionCache, make(transfer));
+	/** A test double. Unstubbed members die rather than reporting a miss. */
+	static makeTest = (overrides = {}) => ({
+		save: () => Effect.sync(() => unimplemented("save")),
+		restore: () => Effect.sync(() => unimplemented("restore")),
+		...overrides
+	});
+	/** {@link ActionCache.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ActionCache, ActionCache.makeTest(overrides));
+};
+
+//#endregion
+export { ActionCache, ActionCacheError };