@effected/github-actions 0.2.0 → 0.4.0

package/CacheKey.js

@@ -48,6 +48,20 @@ const MAX_KEY_LENGTH = 512;
 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` }));
 /**
+* One explicit rung: how many leading segments it keeps. The upper bound is
+* cross-field (`segments.length - 1`) and lives on the class schema.
+*/
+const RestoreDepth = Schema.Number.check(Schema.isInt(), Schema.isBetween({
+	minimum: 1,
+	maximum: Number.MAX_SAFE_INTEGER
+}));
+/**
+* The explicit ladder: possibly empty, because **zero rungs is a policy** —
+* exact-match-only restores, spelled by {@link CacheKey.withoutRestoreKeys}.
+* Only *absence* means the default every-prefix ladder.
+*/
+const RestoreDepths = Schema.Array(RestoreDepth);
+/**
 * A GitHub Actions cache key and the restore-key ladder that goes with it.
 *
 * @remarks
@@ -58,6 +72,12 @@ const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values)
 * 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.
 *
+* By default every prefix is a rung. When some segments must never be dropped
+* — a rung without a version digest resurrects stale cross-version caches —
+* give the key an explicit ladder policy with
+* {@link CacheKey.withRestoreDepths}, or none at all with
+* {@link CacheKey.withoutRestoreKeys}, instead of bypassing the typed key.
+*
 * @example
 * ```ts
 * import { CacheKey } from "@effected/github-actions";
@@ -69,9 +89,18 @@ const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values)
 *
 * @public
 */
-var CacheKey = class CacheKey extends Schema.Class("CacheKey")({ 
-/** The components, most general first. */
-segments: Segments }) {
+var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
+	/** The components, most general first. */
+	segments: Segments,
+	/**
+	* The explicit ladder policy, when one was given: how many leading
+	* segments each rung keeps, in the order the rungs are tried. Absent for
+	* the default every-prefix ladder; **empty for no ladder at all** —
+	* exact-match-only. See {@link CacheKey.withRestoreDepths} and
+	* {@link CacheKey.withoutRestoreKeys}.
+	*/
+	restoreDepths: Schema.optionalKey(RestoreDepths)
+}).check(Schema.makeFilter((key) => key.restoreDepths === void 0 || key.restoreDepths.every((depth) => depth <= key.segments.length - 1) ? void 0 : "every restore depth must be between 1 and segments.length - 1 — a rung keeping every segment would just repeat the primary key"))) {
 	/** The primary key: every segment, joined. */
 	get key() {
 		return this.segments.join(SEPARATOR);
@@ -80,16 +109,85 @@ segments: Segments }) {
 	* 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.
+	* By default 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.
+	*
+	* **The default ladder is every prefix**, which is wrong for a key whose
+	* later segments must never be dropped alone: a
+	* `platform-arch-versionHash-branchHash-lockfileHash` key derives rungs
+	* without the version digest, and those resurrect stale cross-version
+	* caches. A key built with {@link CacheKey.withRestoreDepths} carries its
+	* own ladder instead, and this getter answers exactly that ladder — so
+	* `ActionCache.restore` picks the policy up through the same typed-key
+	* path, no hand-built restore-key list required. An **empty** policy
+	* ({@link CacheKey.withoutRestoreKeys}) answers no rungs at all: only
+	* *absence* selects the default ladder, so "none" is never mistaken for
+	* "every prefix".
 	*/
 	get restoreKeys() {
+		const rung = (length) => `${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`;
+		if (this.restoreDepths !== void 0) return this.restoreDepths.map(rung);
 		const rungs = [];
-		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(`${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`);
+		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(rung(length));
 		return rungs;
 	}
+	/**
+	* A copy of this key carrying an explicit restore-key ladder policy.
+	*
+	* @remarks
+	* Each depth is the number of **leading segments** the rung keeps, and the
+	* rungs are emitted in exactly the order given — GitHub tries restore keys
+	* in order, so the order IS the policy. Descending depths (most specific
+	* first) are what a fallback ladder almost always wants; that convention is
+	* recommended rather than enforced, because rung ordering is the consumer's
+	* policy where commas, newlines and the length limit are the runner's
+	* protocol. A depth outside `1..segments.length - 1` is refused at
+	* construction: `0` would match every cache in the repository, and
+	* `segments.length` would just repeat the primary key.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "X64", "v1hash", "main", "lockhash").withRestoreDepths([4, 3]);
+	* key.restoreKeys; // ["Linux-X64-v1hash-main-", "Linux-X64-v1hash-"]
+	* ```
+	*/
+	withRestoreDepths(depths) {
+		return CacheKey.make({
+			segments: this.segments,
+			restoreDepths: depths
+		});
+	}
+	/**
+	* A copy of this key that restores from its **exact key only** — no ladder.
+	*
+	* @remarks
+	* The third point in the policy space, and the one the typed key had no
+	* spelling for: absence of a policy means the default every-prefix ladder,
+	* so exact-match-only restores (a cache-bust mode, where a stale partial
+	* hit is worse than a cold start) previously forced the caller back to the
+	* string form. This is the same `restoreDepths` field carrying **zero
+	* rungs** — an honest value, not a sentinel: `ActionCache.restore` sends no
+	* `restore_keys` at all, so the backend answers this key or a miss.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "pnpm-store", "abc123").withoutRestoreKeys();
+	* key.key;          // "Linux-pnpm-store-abc123"
+	* key.restoreKeys;  // []
+	* ```
+	*/
+	withoutRestoreKeys() {
+		return CacheKey.make({
+			segments: this.segments,
+			restoreDepths: []
+		});
+	}
 	/** Build a key from its segments. */
 	static of(...segments) {
 		return CacheKey.make({ segments });
@@ -117,6 +215,47 @@ segments: Segments }) {
 		return CacheKey.make({ segments });
 	}
 	/**
+	* A segment-safe short digest of a string.
+	*
+	* @remarks
+	* {@link CacheKey.hashFiles} covers file *content*; this covers the key
+	* segments built from **non-file** inputs — a sorted version list, a branch
+	* name — that every compound key hashes and truncates by hand, each caller
+	* re-deciding the length and the placement. One home for the derivation:
+	* SHA-256, lowercase hex, the first `length` characters.
+	*
+	* The answer is **guaranteed to satisfy the segment grammar**: lowercase hex
+	* is nonempty (for any permitted `length`) and can never contain the comma
+	* or newline the restore-key protocol reserves, so the result drops straight
+	* into {@link CacheKey.of} with nothing to check at the call site.
+	*
+	* Deterministic and pure — the same input always answers the same digest,
+	* which is the entire point of putting one in a cache key. Distinct inputs
+	* are only *probably* distinct, as with any truncated hash; eight hex
+	* characters (32 bits) is the conventional balance between key legibility
+	* and collision risk for cache segments.
+	*
+	* A `length` outside `1..64` (or a fractional one) is a wiring mistake, not
+	* data, and **throws a `RangeError`** rather than failing typed: 64 is all
+	* SHA-256 has, and asking for more would silently answer fewer characters
+	* than the caller believes it got.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of(
+	*   "Linux",
+	*   CacheKey.digest("node:24.4.0,pnpm:10.13.1"),
+	*   CacheKey.digest("feat/my-branch"),
+	* );
+	* ```
+	*/
+	static digest(input, length = 8) {
+		if (!Number.isInteger(length) || length < 1 || length > 64) throw new RangeError(`A digest length must be an integer between 1 and 64, got ${length}`);
+		return createHash("sha256").update(input).digest("hex").slice(0, length);
+	}
+	/**
 	* Hash a set of files into a single digest.
 	*
 	* @remarks

package/ChildEnv.js

@@ -0,0 +1,124 @@
+//#region src/ChildEnv.ts
+/**
+* Child-process environment construction: prepending directories to `PATH`
+* without falling into the three traps that each cost a real consumer a
+* cross-OS matrix round.
+*
+* @remarks
+* Spawning a child with directories prepended to `PATH` is one tiny concern
+* with three sharp edges, and every one of them fails silently or only on
+* Windows:
+*
+* 1. **`env` without `extendEnv: true` strips the child's environment.**
+*    Core's `ChildProcess.CommandOptions.env` *replaces* the block unless
+*    `extendEnv` says to merge, so a bare `{ env }` costs the child everything
+*    — including the very `PATH` being extended.
+* 2. **Windows spells it `Path`, and casing decides who wins.** The
+*    environment block is case-insensitive on win32, and Node de-duplicates a
+*    merged block by keeping the **lexicographically first** spelling — an
+*    undocumented internal that happens to favour `PATH` over an inherited
+*    `Path`, and that nothing obliges Node to keep. Writing through the
+*    inherited key's own casing means never depending on it.
+* 3. **`.cmd` shims need a shell since CVE-2024-27980.** See
+*    {@link ChildEnv.needsShell}.
+*
+* The first two live in {@link ChildEnv.prependPath}; the third is a separate
+* predicate because it belongs on the spawn call, not in the environment.
+*
+* This class is total and pure — no service, no `R`, nothing read from the
+* ambient process — the same species as `Secret`'s statics, one concern per
+* member.
+*
+* @public
+*/
+var ChildEnv = class ChildEnv {
+	constructor() {}
+	/**
+	* The key `base` spells `PATH` with — `Path` on a typical Windows block,
+	* `PATH` elsewhere, and `PATH` when the base has no entry at all.
+	*
+	* @remarks
+	* The lookup is case-insensitive because the Windows environment block is;
+	* the answer preserves the base's own casing because that is the spelling a
+	* merged block must write through (trap 2 above).
+	*/
+	static pathKeyOf(base) {
+		return Object.keys(base).find((key) => key.toUpperCase() === "PATH") ?? "PATH";
+	}
+	/**
+	* The environment additions that prepend `dirs` to the child's `PATH`,
+	* paired with the `extendEnv: true` that keeps them a *prepend*.
+	*
+	* @remarks
+	* `dirs` are joined ahead of the inherited value **in the order given** —
+	* order is the caller's policy, because the first directory wins any name
+	* collision (a package manager's shim directory leads so it beats a runtime
+	* of the same name). The entry is written under the base's own `PATH`
+	* spelling ({@link ChildEnv.pathKeyOf}), so a Windows child never receives
+	* `PATH` beside its inherited `Path`. An absent or empty inherited value
+	* appends nothing — deliberately not an empty trailing entry, which both
+	* platforms historically read as "the current directory".
+	*
+	* Two consumers, two compositions, and the difference is exactly trap 1:
+	*
+	* - A spawner call takes the **whole pair** — spread it into the command
+	*   options, as in the example below, so the `extendEnv: true` that makes
+	*   `env` a merge rather than a replacement cannot be forgotten.
+	* - An API that already merges additions over the parent itself —
+	*   `DetachedProcess.spawn`, whose `env` is documented as merged — takes
+	*   `.env` alone; `extendEnv` would be meaningless there.
+	*
+	* On a runner, pass `{ base: process.env, platform: process.platform }`.
+	*
+	* @example
+	* ```ts
+	* import { ChildEnv } from "@effected/github-actions";
+	* import { ChildProcess } from "effect/unstable/process";
+	*
+	* const command = ChildProcess.make("pnpm", ["install"], {
+	*   ...ChildEnv.prependPath(["/opt/hostedtoolcache/pnpm/10.13.1/x64/bin"], {
+	*     base: process.env,
+	*     platform: process.platform,
+	*   }),
+	*   ...(ChildEnv.needsShell(process.platform) ? { shell: true } : {}),
+	* });
+	* ```
+	*/
+	static prependPath(dirs, options) {
+		const delimiter = options.platform === "win32" ? ";" : ":";
+		const key = ChildEnv.pathKeyOf(options.base);
+		const inherited = options.base[key];
+		const entries = inherited === void 0 || inherited === "" ? dirs : [...dirs, inherited];
+		return {
+			env: { [key]: entries.join(delimiter) },
+			extendEnv: true
+		};
+	}
+	/**
+	* Whether a bare-name command must be launched through a shell on this
+	* platform.
+	*
+	* @remarks
+	* On Windows every npm-installed tool on `PATH` is a `.cmd` batch shim, not
+	* an executable: `CreateProcess` cannot run one, and since CVE-2024-27980
+	* Node refuses to hand `.cmd`/`.bat` files to it at all unless a shell is
+	* asked for — so the spawn fails at launch, before the tool ever runs.
+	* Under `shell: true`, `cmd.exe` resolves the bare name off the **child's**
+	* `PATH` — the one {@link ChildEnv.prependPath} builds — through `PATHEXT`,
+	* where `.EXE` precedes `.CMD`, so a real binary of the same name is still
+	* found first and the prepends keep working exactly as they do without a
+	* shell.
+	*
+	* POSIX answers `false`: the direct spawn already works, and a shell would
+	* only add a quoting hazard between the caller and the exit code. Note the
+	* hazard `true` carries: under a shell Node concatenates the command line
+	* rather than passing an argv, so arguments must be static literals, never
+	* derived from input.
+	*/
+	static needsShell(platform) {
+		return platform === "win32";
+	}
+};
+
+//#endregion
+export { ChildEnv };