@effected/github-actions 0.2.0 → 0.4.0

package/PackageManagerInstaller.js

@@ -0,0 +1,494 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { ToolInstaller } from "./ToolInstaller.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema, Stream } from "effect";
+import { createHash } from "node:crypto";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { PackageManagerPinName } from "@effected/npm";
+
+//#region src/PackageManagerInstaller.ts
+/**
+* Raised when a package manager cannot be provisioned on the runner.
+*
+* @public
+*/
+var PackageManagerInstallerError = class extends Schema.TaggedErrorClass()("PackageManagerInstallerError", {
+	/**
+	* `downloadFailed`, `extractFailed` and `cacheFailed` mirror the
+	* {@link ToolInstallerError} that caused them, preserved on `cause`
+	* (`cacheFailed` also covers a shim that could not be written into the
+	* entry). `integrityMismatch` — the downloaded artifact does not hash to
+	* what the pin declares; nothing was cached. `integrityMissing` — the pin
+	* carries no integrity and the caller asked for `requireIntegrity`.
+	* `unsupportedPlatform` — bun publishes no build for this runner's
+	* OS/architecture pair. `layoutUnexpected` — the artifact extracted, but
+	* its contents are not shaped like the package manager it claims to be.
+	*/
+	reason: Schema.Literals([
+		"downloadFailed",
+		"extractFailed",
+		"integrityMismatch",
+		"integrityMissing",
+		"unsupportedPlatform",
+		"layoutUnexpected",
+		"cacheFailed"
+	]),
+	/** The package manager being installed. */
+	name: PackageManagerPinName,
+	/** The exact version being installed, in string form. */
+	version: Schema.String,
+	/** What was being worked on — a url, a path, or an OS/arch pair. */
+	subject: Schema.optionalKey(Schema.String),
+	/** The integrity the pin declares (`<algo>.<hex>`), on a mismatch. */
+	expected: Schema.optionalKey(Schema.String),
+	/** The integrity the artifact actually hashed to, on a mismatch. */
+	actual: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		const pin = `${this.name}@${this.version}`;
+		switch (this.reason) {
+			case "downloadFailed": return `Could not download ${pin}${this.subject === void 0 ? "" : ` from ${this.subject}`}`;
+			case "extractFailed": return `Could not extract ${pin}${this.subject === void 0 ? "" : ` (${this.subject})`}`;
+			case "integrityMismatch": return `Integrity mismatch for ${pin}: expected ${this.expected}, got ${this.actual}`;
+			case "integrityMissing": return `The pin for ${pin} carries no integrity hash and requireIntegrity is set`;
+			case "unsupportedPlatform": return `No ${pin} build is published for ${this.subject}`;
+			case "layoutUnexpected": return `The ${pin} artifact does not have the expected layout${this.subject === void 0 ? "" : `: ${this.subject}`}`;
+			default: return `Could not cache ${pin} into the tool cache${this.subject === void 0 ? "" : `: ${this.subject}`}`;
+		}
+	}
+};
+/**
+* A package manager the runner's own toolchain already had: nothing was
+* downloaded and nothing was cached, so there is no directory to publish.
+*
+* @remarks
+* `bins` values are bare command names (`npm`, `npx`) resolved through the
+* ambient `PATH` — the toolchain already put them there.
+*
+* @public
+*/
+var AmbientPackageManager = class extends Schema.Class("AmbientPackageManager")({
+	/** The discriminant: the runner's own toolchain answered. */
+	source: Schema.tag("ambient"),
+	/** The package-manager name (`npm`, `pnpm`, `yarn` or `bun`). */
+	name: PackageManagerPinName,
+	/** The exact installed version, in string form. */
+	version: Schema.String,
+	/** Bin name → the ambient command name that invokes it. */
+	bins: Schema.Record(Schema.String, Schema.String)
+}) {};
+/**
+* A package manager living in the runner's tool cache — found there, or
+* installed into it by this call.
+*
+* @remarks
+* `binDir` is the directory a consumer hands to `ActionOutputs.addPath` to
+* make the manager invokable by name in subsequent workflow steps. For the
+* npm-registry managers it is the entry's `.bin` directory of executable
+* shims this installer writes (`#!/bin/sh` exec wrappers, or `.cmd` wrappers
+* on Windows); for bun it is the entry directory itself, because the cached
+* `bun` binary is directly executable and a shim would add nothing but a
+* fork. `bins` still maps each published bin name to the underlying entry —
+* a Node script to run with `node` for npm/pnpm/yarn, the native binary for
+* bun. Calling `addPath` remains deliberately the consumer's move, and note
+* that `addPath` targets *subsequent* steps: a same-process probe must use
+* the absolute paths in `bins` or `binDir`.
+*
+* @public
+*/
+var CachedPackageManager = class extends Schema.Class("CachedPackageManager")({
+	/** The discriminant: the manager lives in the tool cache. */
+	source: Schema.tag("tool-cache"),
+	/** The package-manager name (`npm`, `pnpm`, `yarn` or `bun`). */
+	name: PackageManagerPinName,
+	/** The exact installed version, in string form. */
+	version: Schema.String,
+	/** The cached entry: `<tool-cache>/<name>/<version>/<arch>`. */
+	directory: Schema.String,
+	/** The directory to `addPath` — executable shims, or bun's own directory. */
+	binDir: Schema.String,
+	/** Bin name → the absolute path of the underlying entry point. */
+	bins: Schema.Record(Schema.String, Schema.String)
+}) {};
+/**
+* An installed package manager, discriminated by `source`: `ambient` carries
+* no directory, `tool-cache` carries the cached `directory` and the
+* `addPath`-able `binDir`. The union is a `Schema`, so the record round-trips
+* through `ActionState` for a later phase to read back.
+*
+* @remarks
+* **Construct the variant classes, never the union.** The union's inherited
+* `make` typechecks against *both* variants at once, so a wrong field yields
+* a confusing two-branch error instead of "this variant wants X" — reach for
+* {@link AmbientPackageManager}`.make` / {@link CachedPackageManager}`.make`,
+* whose `Schema.tag` fills `source` for you. The same tag is why an
+* overrides-style test helper should be typed
+* `Partial<Omit<typeof CachedPackageManager.Type, "source">>` — a plain
+* `Partial` offers `source`, which `make` auto-fills and rejects as input.
+*
+* @public
+*/
+const InstalledPackageManager = Schema.Union([AmbientPackageManager, CachedPackageManager]);
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+/** The shim directory name inside a cached npm-registry-manager entry. */
+const SHIM_DIR = ".bin";
+/**
+* The POSIX shim body: an `exec` wrapper so the shim's process *becomes*
+* node, and `"$@"` so arguments survive quoting intact.
+*/
+const posixShim = (target) => `#!/bin/sh\nexec node "${target}" "$@"\n`;
+/** The Windows shim body, CRLF-terminated as cmd expects. */
+const cmdShim = (target) => `@echo off\r\nnode "${target}" %*\r\n`;
+/**
+* The bun release asset name for a runner platform, or `None` when bun
+* publishes no build for it.
+*
+* Asset names verified against the `bun-v1.3.14` release: `bun-{linux,darwin,
+* windows}-{x64,aarch64}.zip`, with the runner's `RUNNER_OS` values mapped to
+* bun's spelling (`macOS` → `darwin`) and the Node arch spelling to bun's
+* (`arm64` → `aarch64`).
+*/
+const bunTarget = (runnerOs, arch) => {
+	const os = runnerOs.toLowerCase() === "linux" ? "linux" : runnerOs.toLowerCase() === "macos" ? "darwin" : runnerOs.toLowerCase() === "windows" ? "windows" : void 0;
+	const cpu = arch === "x64" ? "x64" : arch === "arm64" ? "aarch64" : void 0;
+	return os === void 0 || cpu === void 0 ? Option.none() : Option.some(`bun-${os}-${cpu}`);
+};
+/**
+* The registry tarball url for an npm-registry-distributed manager.
+*
+* The yarn split is corepack's own: `<2.0.0` is the `yarn` package, `>=2.0.0`
+* (Berry) ships as `@yarnpkg/cli-dist` — a scoped package, whose tarball
+* basename drops the scope (`/@yarnpkg/cli-dist/-/cli-dist-<v>.tgz`).
+*/
+const registryTarballUrl = (name, version, major, registry) => name === "yarn" && major >= 2 ? `${registry}/@yarnpkg/cli-dist/-/cli-dist-${version}.tgz` : `${registry}/${name}/-/${name}-${version}.tgz`;
+/** Normalize a package.json `bin` value into name → relative path entries. */
+const normalizeBins = (bin, fallbackName) => {
+	if (typeof bin === "string") return Option.some({ [fallbackName]: bin.replace(/^\.\//, "") });
+	if (typeof bin !== "object" || bin === null) return Option.none();
+	const entries = {};
+	for (const [name, value] of Object.entries(bin)) {
+		if (typeof value !== "string") return Option.none();
+		entries[name] = value.replace(/^\.\//, "");
+	}
+	return Object.keys(entries).length === 0 ? Option.none() : Option.some(entries);
+};
+/** Map a `RUNNER_ARCH` value (`X64`, `ARM64`) onto the Node arch spelling. */
+const archFromRunner = (runnerArch) => runnerArch.toLowerCase() === "x64" ? "x64" : runnerArch.toLowerCase() === "arm64" ? "arm64" : runnerArch;
+const make = Effect.gen(function* () {
+	const env = yield* ActionEnvironment;
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const installer = yield* ToolInstaller;
+	const runnerOs = yield* Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.getOrElse(found, () => ""));
+	const arch = yield* Effect.map(env.getOptional("RUNNER_ARCH"), (found) => Option.match(found, {
+		onNone: () => process.arch,
+		onSome: archFromRunner
+	}));
+	const windows = runnerOs.toLowerCase() === "windows";
+	const bunBinaryName = windows ? "bun.exe" : "bun";
+	const shimFileName = (name) => windows ? `${name}.cmd` : name;
+	const shimBody = windows ? cmdShim : posixShim;
+	const cacheRoot = yield* Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
+	const finalCachePath = (tool, version) => ToolInstaller.cachePath({
+		root: cacheRoot,
+		tool,
+		version,
+		arch: process.arch
+	});
+	const errorFor = (pin) => (fields) => new PackageManagerInstallerError({
+		name: pin.name,
+		version: pin.version.toString(),
+		...fields
+	});
+	/** Map a ToolInstaller failure onto this surface; the reasons line up 1:1. */
+	const fromInstaller = (pin) => (cause) => errorFor(pin)({
+		reason: cause.reason,
+		...cause.subject === void 0 ? {} : { subject: cause.subject },
+		cause
+	});
+	/** The hex digest of a file's bytes, streamed rather than buffered. */
+	const hashFile = (pin, file, algorithm) => Effect.suspend(() => {
+		const digest = createHash(algorithm);
+		return fs.stream(file).pipe(Stream.runForEach((chunk) => Effect.sync(() => {
+			digest.update(chunk);
+		})), Effect.map(() => digest.digest("hex")), Effect.mapError((cause) => errorFor(pin)({
+			reason: "integrityMismatch",
+			subject: file,
+			cause
+		})));
+	});
+	/**
+	* Verify a downloaded artifact against the pin's integrity, fail-closed.
+	*
+	* A pin with no integrity proceeds with a logged warning — in-the-wild
+	* `devEngines` pins routinely carry none, and the opt-in strictness lives in
+	* `requireIntegrity`, checked before anything is downloaded.
+	*/
+	const verifyIntegrity = (pin, file) => Effect.gen(function* () {
+		if (pin.integrity === void 0) {
+			yield* Effect.logWarning(`The pin ${pin.toString()} carries no integrity hash; the downloaded artifact was not verified.`);
+			return;
+		}
+		const dot = pin.integrity.indexOf(".");
+		const algorithm = pin.integrity.slice(0, dot);
+		const expectedHex = pin.integrity.slice(dot + 1);
+		const actualHex = yield* hashFile(pin, file, algorithm);
+		if (actualHex !== expectedHex) return yield* Effect.fail(errorFor(pin)({
+			reason: "integrityMismatch",
+			subject: file,
+			expected: pin.integrity,
+			actual: `${algorithm}.${actualHex}`
+		}));
+	});
+	/**
+	* The ambient `npm --version`, or `None` when the probe cannot answer.
+	*
+	* A failed probe is not an error — there is nothing a caller could do about
+	* it that the dist path does not already do.
+	*/
+	const ambientNpmVersion = Effect.map(Effect.result(spawner.string(ChildProcess.make("npm", ["--version"]))), (result) => result._tag === "Success" ? Option.some(result.success.trim()) : Option.none());
+	const assertFile = (pin, file, subject) => Effect.gen(function* () {
+		const stat = yield* Effect.result(fs.stat(file));
+		if (stat._tag !== "Success" || stat.success.type !== "File") return yield* Effect.fail(errorFor(pin)({
+			reason: "layoutUnexpected",
+			subject
+		}));
+	});
+	/**
+	* The bin entries a package directory publishes, from its own manifest.
+	*
+	* Read from the artifact rather than hardcoded per manager, because the
+	* layouts genuinely move — corepack's own table has pnpm's entry at
+	* `bin/pnpm.cjs` through v10 and `bin/pnpm.mjs` from v11.
+	*/
+	const readPackageBins = (pin, packageDir) => Effect.gen(function* () {
+		const manifestPath = path.join(packageDir, "package.json");
+		const raw = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((cause) => errorFor(pin)({
+			reason: "layoutUnexpected",
+			subject: "no package.json",
+			cause
+		})));
+		const manifest = yield* Effect.try({
+			try: () => JSON.parse(raw),
+			catch: (cause) => errorFor(pin)({
+				reason: "layoutUnexpected",
+				subject: "unparseable package.json",
+				cause
+			})
+		});
+		const bins = Option.getOrUndefined(normalizeBins(manifest.bin, pin.name));
+		if (bins === void 0) return yield* Effect.fail(errorFor(pin)({
+			reason: "layoutUnexpected",
+			subject: "package.json names no bin"
+		}));
+		for (const [name, relative] of Object.entries(bins)) {
+			const target = path.join(packageDir, relative);
+			const containment = path.relative(packageDir, target);
+			if (containment === ".." || containment.startsWith(`..${path.sep}`) || path.isAbsolute(containment)) return yield* Effect.fail(errorFor(pin)({
+				reason: "layoutUnexpected",
+				subject: `bin ${name} (${relative}) escapes the package directory`
+			}));
+			yield* assertFile(pin, target, `bin ${name} (${relative}) is missing`);
+		}
+		return bins;
+	});
+	const rootBins = (bins, directory) => Object.fromEntries(Object.entries(bins).map(([name, relative]) => [name, path.join(directory, relative)]));
+	/**
+	* Write one executable shim per bin into `<into>/.bin`, each invoking
+	* `node <finalDirectory>/<relative>`.
+	*
+	* @remarks
+	* `into` and `finalDirectory` are DIFFERENT on the install path on purpose:
+	* the shims are written into the *staged* tree so they are part of the entry
+	* ToolInstaller renames into place (the cache only ever contains complete
+	* entries), while their contents must name the *final* cache path the entry
+	* is about to land at. On the cache-hit regeneration path the two coincide.
+	* When `skipExisting` is set, a shim already present is left untouched — the
+	* regeneration path must not rewrite a shared cache entry another writer owns.
+	*/
+	const writeShims = (pin, into, finalDirectory, bins, options) => Effect.gen(function* () {
+		const shimDir = path.join(into, SHIM_DIR);
+		const cacheError = (subject) => (cause) => errorFor(pin)({
+			reason: "cacheFailed",
+			subject,
+			cause
+		});
+		yield* fs.makeDirectory(shimDir, { recursive: true }).pipe(Effect.mapError(cacheError(shimDir)));
+		for (const [name, relative] of Object.entries(bins)) {
+			const shim = path.join(shimDir, shimFileName(name));
+			if (options.skipExisting) {
+				const present = yield* Effect.result(fs.stat(shim));
+				if (present._tag === "Success" && present.success.type === "File") continue;
+			}
+			yield* fs.writeFileString(shim, shimBody(path.join(finalDirectory, relative))).pipe(Effect.mapError(cacheError(shim)));
+			if (!windows) yield* fs.chmod(shim, 493).pipe(Effect.mapError(cacheError(shim)));
+		}
+	});
+	/** The record for a directory already in the cache, regenerating absent shims. */
+	const cachedRecord = (pin, directory) => Effect.gen(function* () {
+		if (pin.name === "bun") {
+			const binary = path.join(directory, bunBinaryName);
+			yield* assertFile(pin, binary, `cached bun binary (${bunBinaryName}) is missing`);
+			return CachedPackageManager.make({
+				name: pin.name,
+				version: pin.version.toString(),
+				directory,
+				binDir: directory,
+				bins: { bun: binary }
+			});
+		}
+		const bins = yield* readPackageBins(pin, directory);
+		yield* writeShims(pin, directory, directory, bins, { skipExisting: true });
+		return CachedPackageManager.make({
+			name: pin.name,
+			version: pin.version.toString(),
+			directory,
+			binDir: path.join(directory, SHIM_DIR),
+			bins: rootBins(bins, directory)
+		});
+	});
+	/** Download bun's per-platform zip from GitHub releases and cache the binary. */
+	const installBun = (pin) => Effect.gen(function* () {
+		const version = pin.version.toString();
+		const target = Option.getOrUndefined(bunTarget(runnerOs, arch));
+		if (target === void 0) return yield* Effect.fail(errorFor(pin)({
+			reason: "unsupportedPlatform",
+			subject: `${runnerOs || "unknown"}/${arch}`
+		}));
+		const url = `https://github.com/oven-sh/bun/releases/download/bun-v${version}/${target}.zip`;
+		const archive = yield* installer.download(url).pipe(Effect.mapError(fromInstaller(pin)));
+		yield* verifyIntegrity(pin, archive);
+		const extracted = yield* installer.extractZip(archive).pipe(Effect.mapError(fromInstaller(pin)));
+		const binary = path.join(extracted, target, bunBinaryName);
+		yield* assertFile(pin, binary, `${target}/${bunBinaryName} is missing from the zip`);
+		if (!windows) yield* fs.chmod(binary, 493).pipe(Effect.mapError((cause) => errorFor(pin)({
+			reason: "cacheFailed",
+			subject: binary,
+			cause
+		})));
+		const directory = yield* installer.cacheFile(binary, bunBinaryName, pin.name, version).pipe(Effect.mapError(fromInstaller(pin)));
+		return CachedPackageManager.make({
+			name: pin.name,
+			version,
+			directory,
+			binDir: directory,
+			bins: { bun: path.join(directory, bunBinaryName) }
+		});
+	});
+	/** Download a registry tarball, verify, extract, shim, and cache the package dir. */
+	const installFromRegistry = (pin, name, registry) => Effect.gen(function* () {
+		const version = pin.version.toString();
+		const url = registryTarballUrl(name, version, pin.version.major, registry);
+		const archive = yield* installer.download(url).pipe(Effect.mapError(fromInstaller(pin)));
+		const berry = name === "yarn" && pin.version.major >= 2;
+		if (!berry) yield* verifyIntegrity(pin, archive);
+		const extracted = yield* installer.extractTar(archive).pipe(Effect.mapError(fromInstaller(pin)));
+		const packageDir = path.join(extracted, "package");
+		const stat = yield* Effect.result(fs.stat(packageDir));
+		if (stat._tag !== "Success" || stat.success.type !== "Directory") return yield* Effect.fail(errorFor(pin)({
+			reason: "layoutUnexpected",
+			subject: "tarball has no package/ root"
+		}));
+		const bins = yield* readPackageBins(pin, packageDir);
+		if (berry) {
+			const cli = path.join(packageDir, "bin/yarn.js");
+			yield* assertFile(pin, cli, "bin/yarn.js is missing from the cli-dist tarball");
+			yield* verifyIntegrity(pin, cli);
+		}
+		const destination = finalCachePath(name, version);
+		yield* writeShims(pin, packageDir, destination, bins, { skipExisting: false });
+		const directory = yield* installer.cacheDir(packageDir, name, version).pipe(Effect.mapError(fromInstaller(pin)));
+		if (directory !== destination) return yield* Effect.fail(errorFor(pin)({
+			reason: "cacheFailed",
+			subject: `cache destination diverged: shims name ${destination}, entry landed at ${directory}`
+		}));
+		return CachedPackageManager.make({
+			name,
+			version,
+			directory,
+			binDir: path.join(directory, SHIM_DIR),
+			bins: rootBins(bins, directory)
+		});
+	});
+	return { install: Effect.fn("PackageManagerInstaller.install")(function* (pin, options) {
+		const version = pin.version.toString();
+		yield* Effect.annotateCurrentSpan({
+			name: pin.name,
+			version
+		});
+		if (options?.requireIntegrity === true && pin.integrity === void 0) return yield* Effect.fail(errorFor(pin)({ reason: "integrityMissing" }));
+		const cached = yield* installer.find(pin.name, version);
+		if (Option.isSome(cached)) return yield* cachedRecord(pin, cached.value);
+		if (pin.name === "npm" && options?.allowAmbient !== false) {
+			const probed = yield* ambientNpmVersion;
+			if (Option.isSome(probed) && probed.value === version) return AmbientPackageManager.make({
+				name: pin.name,
+				version,
+				bins: {
+					npm: "npm",
+					npx: "npx"
+				}
+			});
+		}
+		if (pin.name === "bun") return yield* installBun(pin);
+		const registry = (options?.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "");
+		return yield* installFromRegistry(pin, pin.name, registry);
+	}) };
+});
+const unimplemented = (member) => {
+	throw new Error(`PackageManagerInstaller.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* First-class exact-version package-manager provisioning on a GitHub runner.
+*
+* @remarks
+* Takes a corepack pin (`@effected/npm`'s `PackageManagerPin`) and answers
+* with an installed manager: tool-cache `find` first, then — for npm — an
+* ambient `npm --version` probe (every Node toolchain ships npm), and only
+* then the manager's own dist: npm, pnpm and yarn 1.x from their registry
+* tarballs, yarn 2+ (Berry) from `@yarnpkg/cli-dist`, bun from its
+* per-platform GitHub-release zip. A pin that carries integrity is verified
+* fail-closed against what corepack itself hashes; one that does not proceeds
+* with a logged warning unless `requireIntegrity` says otherwise.
+*
+* Every tool-cache answer carries a `binDir` a consumer can hand straight to
+* `ActionOutputs.addPath`: the npm-registry managers get a `.bin` directory
+* of executable shims written as part of the cached entry, bun's entry is its
+* own `binDir`. Caching goes through {@link ToolInstaller}, so the
+* stage-then-swap invariant holds here for free — shims included, the tool
+* cache only ever contains complete package managers.
+*
+* @example
+* ```ts
+* import { ActionOutputs, PackageManagerInstaller } from "@effected/github-actions";
+* import { PackageManagerPin } from "@effected/npm";
+* import { Effect } from "effect";
+*
+* const provision = Effect.gen(function* () {
+*   const installer = yield* PackageManagerInstaller;
+*   const outputs = yield* ActionOutputs;
+*   const pin = yield* PackageManagerPin.parse("pnpm@10.13.1");
+*   const installed = yield* installer.install(pin);
+*   if (installed.source === "tool-cache") {
+*     yield* outputs.addPath(installed.binDir);
+*   }
+* });
+* ```
+*
+* @public
+*/
+var PackageManagerInstaller = class PackageManagerInstaller extends Context.Service()("@effected/github-actions/PackageManagerInstaller") {
+	static layer = Layer.effect(this, make);
+	/** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
+	static makeTest = (overrides = {}) => ({
+		install: () => Effect.sync(() => unimplemented("install")),
+		...overrides
+	});
+	/** {@link PackageManagerInstaller.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(PackageManagerInstaller, PackageManagerInstaller.makeTest(overrides));
+};
+
+//#endregion
+export { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError };

package/Secret.js

@@ -49,6 +49,16 @@ var Secret = class Secret {
 	* @remarks
 	* Every value is masked before any plaintext is returned — including when
 	* one of them fails, because masking happens for the whole set first.
+	*
+	* **Detached workers invert the masking model.** Masking works because the
+	* runner parses this process's stdout; a *detached* child's stdout is a log
+	* file no runner parses, so a mask emitted **inside** the worker is inert
+	* and writes the plaintext verbatim into that log — a shipped incident, not
+	* a hypothetical. The rule: **the parent masks, before the spawn** — call
+	* this member in the parent, where the runner is listening, and hand the
+	* already-masked plaintext to the worker's environment. Inside the worker,
+	* compose `ActionOutputs.layerDetached`, whose `setSecret` is a documented
+	* no-op, so the same code cannot re-leak what the parent already masked.
 	*/
 	static forChildEnv = (entries) => Effect.gen(function* () {
 		const outputs = yield* ActionOutputs;
@@ -102,6 +112,17 @@ var Secret = class Secret {
 	*
 	* Call it **once, at layer construction**, not per operation: masking is
 	* idempotent but a workflow command per request is noise in the log.
+	*
+	* **In a detached worker, the mask this member emits is a leak.** The
+	* `::add-mask::` command only masks when the runner parses this process's
+	* stdout; a detached worker's stdout is a log file no runner parses, so
+	* there the command masks nothing *and* spells the plaintext into the log
+	* — a signing key shipped exactly that way for one round. A worker that
+	* signs (an S3-style `BlobStore` is the canonical case) must compose
+	* `ActionOutputs.layerDetached`, under which this member still returns the
+	* raw key for the HMAC but the mask is a documented no-op; the masking
+	* itself is the **parent's** job, done before the spawn via
+	* {@link Secret.forChildEnv} under the real layer.
 	*/
 	static forSigning = (secret) => Secret.forRunnerFile(secret);
 	/**