@effected/github-actions 0.1.0

package/DetachedProcess.js

@@ -0,0 +1,231 @@
+import { Effect, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+
+//#region src/DetachedProcess.ts
+/**
+* Raised when a detached child cannot be started, waited for, or reaped.
+*
+* @public
+*/
+var DetachedProcessError = class extends Schema.TaggedErrorClass()("DetachedProcessError", {
+	/**
+	* `logUnavailable` — the log file could not be opened, so there is nowhere
+	* for the child's output to go. `spawnFailed` — the child did not start.
+	* `invalidPid` — a non-positive pid was handed to {@link DetachedProcess.reap};
+	* see there for why this is the most important value in the module.
+	* `signalFailed` — the signal was refused, e.g. the process belongs to
+	* another user. `notReady` — the readiness probe never held.
+	*/
+	reason: Schema.Literals([
+		"logUnavailable",
+		"spawnFailed",
+		"invalidPid",
+		"signalFailed",
+		"notReady"
+	]),
+	/** The pid involved, when one is. */
+	pid: Schema.optionalKey(Schema.Number),
+	/** The path involved, when one is. */
+	path: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "logUnavailable": return `Could not open the detached log file "${this.path}"`;
+			case "spawnFailed": return "The detached child did not start";
+			case "invalidPid": return `Refusing to signal pid ${this.pid}: a non-positive pid targets a process group, not a process`;
+			case "signalFailed": return `Could not signal pid ${this.pid}`;
+			default: return "The detached child never became ready";
+		}
+	}
+};
+/**
+* The schema a pid crosses the phase boundary through.
+*
+* @remarks
+* A pid is persisted in `GITHUB_STATE` by `main` and read back by `post`, which
+* means it makes the round trip as **text**. This is the boundary check on the
+* way back in: a truncated file, an absent key or a `Number("")` all decode to
+* `0`, and `0` is not a process — it is the current process's whole group.
+* Refusing it here means the bad value never reaches {@link DetachedProcess.reap}
+* in the first place, and reap's own guard is the second of two defenses rather
+* than the only one.
+*
+* **The brand is core's**, from `ChildProcessSpawner` — the subprocess
+* vocabulary belongs to core and this package does not get to re-declare it.
+* What core does not have is a *validating* way to reconstruct one: its
+* constructor is `Brand.nominal`, which applies no runtime check, so
+* `ChildProcessSpawner.ProcessId(0)` succeeds. That is exactly right for a pid
+* the spawner just produced, and exactly wrong for a pid that has been through a
+* text file. This schema is that missing check, and it decodes to core's type so
+* the two are interchangeable.
+*
+* @example
+* ```ts
+* import { ActionState, DetachedProcess, ProcessId } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const post = Effect.gen(function* () {
+*   const pid = yield* (yield* ActionState).get("server-pid", ProcessId);
+*   return yield* DetachedProcess.reap(pid);
+* });
+* ```
+*
+* @public
+*/
+const ProcessId = Schema.Number.pipe(Schema.check(Schema.makeFilter((value) => Number.isInteger(value) && value > 0 ? void 0 : "Expected a positive integer process id")), Schema.brand("ProcessId"));
+/** Whether a thrown value is a Node errno error with the given code. */
+const isErrno = (cause, code) => typeof cause === "object" && cause !== null && cause.code === code;
+/**
+* A long-lived child that outlives the phase that started it.
+*
+* @remarks
+* The shape an action needs is three separate things, because the child
+* survives the process that spawned it: `main` starts it and persists the pid,
+* `main` or `post` waits on a domain predicate rather than on time, and `post`
+* — a **different process**, holding no handle to the child — signals the pid
+* it read back out of `GITHUB_STATE`.
+*
+* That last step is why this lives here rather than in a command runner. There
+* is no `ChildProcess` to `.kill()`; there is only a number that has been
+* through a text file. See {@link DetachedProcess.reap}.
+*
+* @example
+* ```ts
+* import { DetachedProcess } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const pid = yield* DetachedProcess.spawn({
+*     command: "node",
+*     args: ["server.js"],
+*     logFile: "/tmp/server.log",
+*   });
+*   yield* DetachedProcess.awaitReady(healthCheck);
+*   return pid;
+* });
+* ```
+*
+* @public
+*/
+var DetachedProcess = class {
+	constructor() {}
+	/**
+	* Start a detached child with its output routed to a log file.
+	*
+	* @remarks
+	* The parent closes its own copy of the descriptor immediately — the child
+	* holds a duplicate, so the log keeps filling after the action's process
+	* exits, which is the entire point.
+	*/
+	static spawn = Effect.fn("DetachedProcess.spawn")(function* (options) {
+		const descriptor = yield* Effect.try({
+			try: () => openSync(options.logFile, "a"),
+			catch: (cause) => new DetachedProcessError({
+				reason: "logUnavailable",
+				path: options.logFile,
+				cause
+			})
+		});
+		const pid = yield* Effect.try({
+			try: () => {
+				try {
+					const child = spawn(options.command, [...options.args ?? []], {
+						...options.cwd === void 0 ? {} : { cwd: options.cwd },
+						env: {
+							...process.env,
+							...options.env
+						},
+						detached: true,
+						stdio: [
+							"ignore",
+							descriptor,
+							descriptor
+						]
+					});
+					child.on("error", () => {});
+					child.unref();
+					if (child.pid === void 0) throw new Error(`"${options.command}" produced no process id`);
+					return child.pid;
+				} finally {
+					closeSync(descriptor);
+				}
+			},
+			catch: (cause) => new DetachedProcessError({
+				reason: "spawnFailed",
+				cause
+			})
+		});
+		yield* Effect.annotateCurrentSpan({ pid });
+		return ChildProcessSpawner.ProcessId(pid);
+	});
+	/**
+	* Poll a predicate until it holds.
+	*
+	* @remarks
+	* A domain predicate rather than a sleep: "the server answers" is the thing
+	* being waited for, and any fixed delay is simultaneously too long on a fast
+	* runner and too short on a slow one. Two consumers hand-rolled this, one of
+	* them around an `Effect.suspend` footgun it had to explain in a comment.
+	*
+	* A probe *failure* is propagated rather than treated as "not ready" — a
+	* probe that cannot run is a different situation from a child that is not up
+	* yet, and silently retrying the first is how a misconfigured probe becomes a
+	* timeout six seconds later with nothing to show for it.
+	*/
+	static awaitReady = Effect.fn("DetachedProcess.awaitReady")(function* (probe, options) {
+		const interval = options?.interval ?? "150 millis";
+		const attempts = options?.attempts ?? 40;
+		const poll = (remaining) => Effect.flatMap(probe, (ready) => {
+			if (ready) return Effect.void;
+			if (remaining <= 0) return Effect.fail(new DetachedProcessError({ reason: "notReady" }));
+			return Effect.flatMap(Effect.sleep(interval), () => poll(remaining - 1));
+		});
+		return yield* poll(attempts);
+	});
+	/**
+	* Signal a pid that came back across the phase boundary.
+	*
+	* @remarks
+	* **The guard is the reason this function exists.** `process.kill(0, …)`
+	* signals the caller's entire process group and `process.kill(-1, …)` signals
+	* every process the user owns — so on a GitHub runner, an unguarded reap of a
+	* pid that decoded to `0` takes down the job that is running it. The value is
+	* exactly the one most likely to be wrong: it is what an absent state key, a
+	* truncated state file or a `Number("")` all produce.
+	*
+	* A non-positive pid therefore fails **typed and before any signal is sent**.
+	* The parameter is a plain `number` rather than a {@link ProcessId} on purpose:
+	* the value arrives as text from another process, so the type system stopped
+	* applying the moment it crossed that boundary, and a guard that only a
+	* well-typed caller can trip is not a guard.
+	*
+	* Returns `false` for a process that is already gone, because a `post` phase
+	* finding its child already dead is the normal ending, not a failure.
+	*/
+	static reap = Effect.fn("DetachedProcess.reap")(function* (pid, signal = "SIGTERM") {
+		yield* Effect.annotateCurrentSpan({ pid });
+		if (!Number.isInteger(pid) || pid <= 0) return yield* Effect.fail(new DetachedProcessError({
+			reason: "invalidPid",
+			pid
+		}));
+		return yield* Effect.suspend(() => {
+			try {
+				process.kill(pid, signal);
+				return Effect.succeed(true);
+			} catch (cause) {
+				return isErrno(cause, "ESRCH") ? Effect.succeed(false) : Effect.fail(new DetachedProcessError({
+					reason: "signalFailed",
+					pid,
+					cause
+				}));
+			}
+		});
+	});
+};
+
+//#endregion
+export { DetachedProcess, DetachedProcessError, ProcessId };

package/DryRun.js

@@ -0,0 +1,73 @@
+import { ActionInput } from "./ActionInput.js";
+import { Config, Context, Effect, Layer } from "effect";
+
+//#region src/DryRun.ts
+/** The input a workflow author sets to rehearse a run. */
+const DEFAULT_INPUT = "dry-run";
+const make = (enabled) => ({
+	isDryRun: Effect.succeed(enabled),
+	guard: (label, effect, fallback) => enabled ? Effect.as(Effect.logInfo(`[DRY-RUN] ${label}`), fallback) : effect
+});
+/**
+* The rehearsal guard: every mutation an action performs goes through it, so a
+* workflow can be run end to end without changing anything.
+*
+* @remarks
+* A service rather than a boolean threaded through call sites, because the
+* decision has to be available wherever a mutation is, and because a test that
+* wants to prove "this path mutates nothing" provides one layer instead of
+* auditing every branch.
+*
+* @example
+* ```ts
+* import { DryRun } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const dryRun = yield* DryRun;
+*   yield* dryRun.guard("publish @acme/thing@1.2.3", publish, undefined);
+* });
+* ```
+*
+* @public
+*/
+var DryRun = class DryRun extends Context.Service()("@effected/github-actions/DryRun") {
+	/**
+	* 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 layer = Layer.effect(this, Effect.map(ActionInput.boolean(DEFAULT_INPUT).pipe(Config.withDefault(false)), make));
+	/**
+	* Driven by a named input.
+	*
+	* @remarks
+	* 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 layerFromInput = (name) => Layer.effect(DryRun, Effect.map(ActionInput.boolean(name).pipe(Config.withDefault(false)), make));
+	/** Driven by an explicit decision the caller has already made. */
+	static layerFrom = (enabled) => Layer.succeed(DryRun, make(enabled));
+	/**
+	* A double that rehearses.
+	*
+	* @remarks
+	* **A recorded exception to the die-on-unstubbed rule.** The default is not a
+	* fabrication but the safe direction: a test that forgot to say which mode it
+	* wants gets the mode that mutates nothing. The members are the real
+	* implementation, so the double cannot drift from it.
+	*/
+	static makeTest = (overrides = {}) => ({
+		...make(true),
+		...overrides
+	});
+	/** {@link DryRun.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(DryRun, DryRun.makeTest(overrides));
+};
+
+//#endregion
+export { DryRun };

package/GitHubToken.js

@@ -0,0 +1,226 @@
+import { ActionState } from "./ActionState.js";
+import { Secret } from "./Secret.js";
+import { DateTime, Duration, Effect, Exit, Layer, Option, Result, Schema } from "effect";
+import { GitHubApp, GitHubClient, InstallationToken, TokenPermissions } from "@effected/github";
+
+//#region src/GitHubToken.ts
+/**
+* Raised when the token an earlier phase persisted cannot be used.
+*
+* @public
+*/
+var GitHubTokenError = class extends Schema.TaggedErrorClass()("GitHubTokenError", {
+	/**
+	* One reason, deliberately: everything else that can go wrong here already
+	* has an owner — persistence is an `ActionStateError`, minting is a
+	* `GitHubAppError`, and scope verification is a `TokenPermissionError`.
+	*/
+	reason: Schema.Literals(["expired"]),
+	/** When GitHub stopped accepting it, ISO-8601. */
+	expiresAt: Schema.String
+}) {
+	get message() {
+		return `The installation token persisted by an earlier phase expired at ${this.expiresAt}. An installation token lives about an hour and no later phase can re-mint one, so a long-running phase must provision its own.`;
+	}
+};
+/** The default `GITHUB_STATE` key the token is filed under. */
+const DEFAULT_KEY = "githubToken";
+/**
+* Resolve the app's identity onto a minted token, degrading rather than failing.
+*
+* @remarks
+* The identity is what makes a commit say `my-app[bot]` instead of
+* `github-actions[bot]`. It is worth a request and it is **not** worth an
+* action: a `GET /app` hiccup must not fail a release, so the failure is logged
+* and the token comes back without the identity fields. `botIdentity()` then
+* falls back on its own.
+*
+* The installation token is supplied to the lookup on purpose:
+* `GET /users/{slug}[bot]` rejects an app JWT, so without one the request runs
+* unauthenticated against GitHub's sixty-per-hour-per-IP limit.
+*/
+const identified = (app, options, minted) => Effect.gen(function* () {
+	const resolved = yield* Effect.result(app.identity({
+		appId: options.appId,
+		privateKey: options.privateKey,
+		installationToken: minted.token
+	}));
+	if (Result.isFailure(resolved)) {
+		yield* Effect.logWarning(`Could not resolve the app's identity; commits will be attributed to github-actions[bot]: ${resolved.failure.message}`);
+		return minted;
+	}
+	const identity = resolved.success;
+	return InstallationToken.make({
+		token: minted.token,
+		expiresAt: minted.expiresAt,
+		installationId: minted.installationId,
+		permissions: minted.permissions,
+		appSlug: identity.slug,
+		appName: identity.name,
+		...identity.userId === void 0 ? {} : { appUserId: identity.userId }
+	});
+});
+/**
+* The GitHub App token lifecycle, shaped like a workflow.
+*
+* @remarks
+* One of the two seams between this package and
+* [`@effected/github`](https://npmjs.com) — mint in `pre`, use in `main`,
+* revoke in `post`. The three phases are **three separate processes**, so
+* nothing survives between them except what `GITHUB_STATE` carries, which is
+* why this is a persistence problem rather than a `Scope`.
+*
+* That is also why `GitHubApp.scopedToken` is the wrong primitive here and
+* `GitHubApp.clientLayer` is a different thing entirely: both revoke when their
+* scope closes, and the scope closes at the end of `pre` — before `main` has
+* run a single request.
+*
+* **The token lives about an hour, and no later phase can re-mint one.** The
+* credentials that could are the app's private key, and persisting *that*
+* through `GITHUB_STATE` — a plaintext file by GitHub's protocol — would trade
+* a one-hour token for a permanent one. So the v1 contract is stated rather
+* than worked around: {@link GitHubToken.read} fails typed when the persisted
+* token is spent, and a phase that can outlive the hour calls
+* {@link GitHubToken.provision} itself.
+*
+* Grouped statics on one module reaching one dependency — the carve-out to the
+* no-namespace-objects rule, not the hazard it names. Every member's `R` says
+* exactly which services it needs, and the members below say which parts of
+* each they touch, so a partial double is built from the documentation rather
+* than from a stack trace:
+*
+* | Member | `ActionState` | `ActionOutputs` | `GitHubApp` |
+* | --- | --- | --- | --- |
+* | `provision` | `save` | `setSecret` | `token`, `identity`, `revoke` |
+* | `read` | `get` | — | — |
+* | `botIdentity` | `get` | — | — |
+* | `clientLayer` | `get` | — | — |
+* | `dispose` | `getOptional` | — | `revoke` |
+*
+* @example
+* ```ts
+* import { GitHubToken } from "@effected/github-actions";
+* import { Effect, Redacted } from "effect";
+*
+* const pre = Effect.gen(function* () {
+*   return yield* GitHubToken.provision({
+*     appId: "123456",
+*     privateKey: Redacted.make(pem),
+*     owner: "acme",
+*     required: { contents: "write", pull_requests: "write" },
+*   });
+* });
+* ```
+*
+* @public
+*/
+var GitHubToken = class GitHubToken {
+	constructor() {}
+	/**
+	* Mint a token, verify its scopes, mask it and persist it for later phases.
+	*
+	* @remarks
+	* An `acquireUseRelease`, and the release arm is the load-bearing part: if
+	* scope verification or persistence fails, the minted token is **revoked**
+	* rather than left live until GitHub expires it. A workflow that retries a
+	* failing `pre` would otherwise leave an hour's worth of unreferenced write
+	* tokens behind, each of which is a credential nobody is tracking.
+	*
+	* The masking happens **before** the persistence, through
+	* {@link Secret.forRunnerFile}, so the ordering is structural rather than
+	* remembered: `GITHUB_STATE` is plaintext by protocol, and the runner's log
+	* filter is the only defense available.
+	*/
+	static provision = Effect.fn("GitHubToken.provision")(function* (options) {
+		const app = yield* GitHubApp;
+		const state = yield* ActionState;
+		const key = options.stateKey ?? DEFAULT_KEY;
+		return yield* Effect.acquireUseRelease(app.token({
+			appId: options.appId,
+			privateKey: options.privateKey,
+			...options.installationId === void 0 ? {} : { installationId: options.installationId },
+			...options.owner === void 0 ? {} : { owner: options.owner }
+		}), (minted) => Effect.gen(function* () {
+			if (options.required !== void 0) yield* TokenPermissions.fromGitHub(minted.permissions).assertSufficient(options.required);
+			yield* Secret.forRunnerFile(minted.token);
+			const enriched = yield* identified(app, options, minted);
+			yield* state.save(key, enriched, InstallationToken);
+			return enriched;
+		}), (minted, exit) => Exit.isSuccess(exit) ? Effect.void : Effect.ignore(app.revoke(minted.token)));
+	});
+	/**
+	* The token an earlier phase persisted.
+	*
+	* @remarks
+	* Fails typed when it is spent. The package this replaces persisted the
+	* expiry and read it nowhere, so a `main` phase that outlived the hour simply
+	* started answering `401` with no explanation — which is the single hardest
+	* failure in this whole lifecycle to diagnose from a workflow log.
+	*/
+	static read = Effect.fn("GitHubToken.read")(function* (options = {}) {
+		const token = yield* (yield* ActionState).get(options.stateKey ?? DEFAULT_KEY, InstallationToken);
+		const now = yield* DateTime.now;
+		if (options.skew === void 0 ? token.isExpired(DateTime.toEpochMillis(now)) : token.isExpired(DateTime.toEpochMillis(now), options.skew)) return yield* Effect.fail(new GitHubTokenError({
+			reason: "expired",
+			expiresAt: DateTime.formatIso(token.expiresAt)
+		}));
+		return token;
+	});
+	/**
+	* The committer identity a commit made with the persisted token should carry.
+	*
+	* @remarks
+	* Pure once the token is in hand — the identity fields travel with it — so
+	* this costs one state read and no request.
+	*/
+	static botIdentity = Effect.fn("GitHubToken.botIdentity")(function* (options = {}) {
+		return (yield* GitHubToken.read(options)).botIdentity();
+	});
+	/**
+	* A client built from the persisted token.
+	*
+	* @remarks
+	* Built with `GitHubClient.layerFromToken` rather than through `GitHubApp`,
+	* and the difference matters: the App path links a JWT signer and needs the
+	* private key, neither of which a later phase has or should have. This path
+	* needs only the token the `pre` phase already minted.
+	*
+	* 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 clientLayer = (options = {}) => Layer.unwrap(Effect.map(GitHubToken.read(options), (token) => GitHubClient.layerFromToken({
+		token: token.token,
+		...options.retry === void 0 ? {} : { retry: options.retry },
+		...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+		...options.userAgent === void 0 ? {} : { userAgent: options.userAgent },
+		...options.fetch === void 0 ? {} : { fetch: options.fetch }
+	})));
+	/**
+	* Revoke the persisted token, if there is one.
+	*
+	* @remarks
+	* `getOptional`, so a `post` phase that runs after a `pre` that never got as
+	* far as provisioning is a **no-op rather than a failure** — which is the
+	* common shape of a workflow that failed early, and the last thing it needs
+	* is a second failure on the way out.
+	*
+	* An already-expired token is not revoked either: GitHub has already stopped
+	* accepting it, so the request would fail and the only thing it could
+	* accomplish is turning a successful run into a failed one.
+	*/
+	static dispose = Effect.fn("GitHubToken.dispose")(function* (options = {}) {
+		const app = yield* GitHubApp;
+		const found = yield* (yield* ActionState).getOptional(options.stateKey ?? DEFAULT_KEY, InstallationToken);
+		if (Option.isNone(found)) return;
+		const now = yield* DateTime.now;
+		if (found.value.isExpired(DateTime.toEpochMillis(now), Duration.zero)) {
+			yield* Effect.logDebug("The installation token had already expired; nothing to revoke.");
+			return;
+		}
+		yield* app.revoke(found.value.token);
+	});
+};
+
+//#endregion
+export { GitHubToken, GitHubTokenError };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.