@effected/workspaces 0.25.0 → 0.27.0

package/PackedInstall.js

@@ -0,0 +1,761 @@
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { PackageManagerName } from "./PackageManagerName.js";
+import { binConflict, binTargetOf, closureOf, consumerFiles, fileOverridesOf, installArgs, overridePath, readPackedManifest, scrubEnv, versionOf } from "./internal/packedInstallPlan.js";
+import { Duration, Effect, FileSystem, Option, Path, Redacted, Result, Schema } from "effect";
+import { Yaml } from "@effected/yaml";
+import { Run } from "@effected/commands";
+import { ChildProcess } from "effect/unstable/process";
+
+//#region src/PackedInstall.ts
+/**
+* Why a packed install could not be proven.
+*
+* @public
+*/
+var PackedInstallError = class extends Schema.TaggedError()("PackedInstallError", {
+	/** What failed. */
+	reason: Schema.Literals([
+		"UnsupportedPlatform",
+		"NoManagerAvailable",
+		"ManagerUnavailable",
+		"UnknownPackage",
+		"PackSourceMissing",
+		"PackFailed",
+		"UnresolvedProtocol",
+		"InvalidOverride",
+		"BinConflict",
+		"InstallFailed",
+		"MissingBin",
+		"BinFailed",
+		"UnownedBin",
+		"Discovery",
+		"Io"
+	]),
+	/** One line, naming the package or manager involved. */
+	message: Schema.String,
+	/** The package manager involved. */
+	manager: Schema.optionalKey(PackageManagerName),
+	/** The workspace package involved. */
+	package: Schema.optionalKey(Schema.String),
+	/** The tail of the failing command's output. */
+	output: Schema.optionalKey(Schema.String),
+	/** The originating failure. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {};
+const DEFAULT_BIN_TIMEOUT = "1 minute";
+/**
+* Whether a failed `readLink` means "this entry is not a symlink". Node reports
+* that as `EINVAL`, which its platform layer tags `Unknown` with the errno on
+* the cause, and `@effected/memfs` raises the same shape. Anything else,
+* `PermissionDenied` and `BadResource` included, is a real failure.
+*/
+const isNotALink = (error) => error.reason._tag === "Unknown" && typeof error.reason.cause === "object" && error.reason.cause !== null && error.reason.cause.code === "EINVAL";
+/**
+* One scratch project, outside the workspace, with the carrier installed.
+*
+* @public
+*/
+var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
+	/** The package manager that installed it. */
+	manager: PackageManagerName,
+	/** The version it reported and was pinned to. */
+	managerVersion: Schema.String,
+	/** The consumer project directory (realpath'd). */
+	directory: Schema.String,
+	/**
+	* The scrubbed environment the install ran under, which {@link InstalledConsumer.runBin}
+	* starts from. Redacted, so printing a consumer never prints a token.
+	* `PackedInstall.run` always sets it; a hand-made consumer without it runs
+	* its bins under only `RunBinOptions.env`.
+	*/
+	env: Schema.optionalKey(Schema.Redacted(Schema.Record(Schema.String, Schema.String))),
+	/**
+	* The carrier the consumer depends on, which {@link InstalledConsumer.carrierCommand}
+	* resolves bins through. `PackedInstall.run` always sets it.
+	*/
+	carrier: Schema.optionalKey(Schema.String)
+}) {
+	/** The installed bin `name`, in `node_modules/.bin`. POSIX: `PackedInstall` runs only there. */
+	binPath(name) {
+		return `${this.directory}/node_modules/.bin/${name}`;
+	}
+	/**
+	* Which installed package the `node_modules/.bin` entry `name` resolves into.
+	*
+	* @remarks
+	* Under a flat layout (npm, bun, and Yarn with the `node-modules` linker
+	* this run configures), a hoisted bin of the same name from another package
+	* can shadow the carrier's, and running it cannot tell you which one ran.
+	* Those managers write each `.bin` entry as a symlink, so this reads the
+	* link, realpaths its target, and walks up to the nearest `package.json`
+	* with a string `name`, staying inside the consumer directory (itself
+	* realpath'd first, so a `/var` alias of `/private/var` or a trailing
+	* slash does not move the bound). A manifest that is valid JSON but not an
+	* object, or has no string `name` (a `dist/package.json` carrying only
+	* `type`), is passed over. Assert `package` is your carrier.
+	*
+	* `undefined` means one thing: the entry exists and is not a symlink.
+	* pnpm writes `.bin` entries as shell shims, whose target this does not
+	* parse; its isolated layout links only the consumer's direct dependencies
+	* at the top level, so a shadowing bin needs a direct dependency there.
+	*
+	* An entry that does not exist, or a link whose target does not, fails
+	* `MissingBin`. A link into no named package inside the consumer fails
+	* `UnownedBin`, naming the target. Any other read failure, a
+	* `package.json` that is not JSON included, fails `Io`.
+	*
+	* @param name - The bin, as named in `node_modules/.bin`.
+	*/
+	binProvenance(name) {
+		const bin = this.binPath(name);
+		const directory = this.directory;
+		const manager = this.manager;
+		const entry = `node_modules/.bin/${name}`;
+		return Effect.gen(function* () {
+			const fs = yield* FileSystem.FileSystem;
+			const path = yield* Path.Path;
+			const io = (message) => (cause) => failure("Io", message, {
+				manager,
+				cause
+			});
+			const missing = (why) => failure("MissingBin", `${manager}: ${entry} ${why}`, { manager });
+			if (!(yield* fs.readLink(bin).pipe(Effect.as(true), Effect.catch((error) => isNotALink(error) ? Effect.succeed(false) : error.reason._tag === "NotFound" ? Effect.fail(missing("does not exist")) : Effect.fail(io(`could not read the link ${bin}`)(error)))))) {
+				if (!(yield* fs.exists(bin).pipe(Effect.mapError(io(`could not inspect ${bin}`))))) return yield* missing("does not exist");
+				return;
+			}
+			const target = yield* fs.realPath(bin).pipe(Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.fail(missing("is a link to nothing")) : Effect.fail(io(`could not resolve ${bin}`)(error))));
+			const root = yield* fs.realPath(directory).pipe(Effect.mapError(io(`could not resolve ${directory}`)));
+			for (let dir = path.dirname(target); dir.startsWith(`${root}/`); dir = path.dirname(dir)) {
+				const manifest = path.join(dir, "package.json");
+				if (!(yield* fs.exists(manifest).pipe(Effect.mapError(io(`could not inspect ${manifest}`))))) continue;
+				const text = yield* fs.readFileString(manifest).pipe(Effect.mapError(io(`could not read ${manifest}`)));
+				const parsed = yield* Effect.try({
+					try: () => JSON.parse(text),
+					catch: io(`${manifest} is not JSON`)
+				});
+				const named = typeof parsed === "object" && parsed !== null ? parsed.name : void 0;
+				if (typeof named === "string") return {
+					package: named,
+					target
+				};
+			}
+			return yield* failure("UnownedBin", `${manager}: ${entry} links to ${target}, which lies in no named package inside ${root}`, { manager });
+		});
+	}
+	/**
+	* The command {@link InstalledConsumer.runBin} spawns for the bin `name`,
+	* for a caller that drives the child itself, such as `McpProbe.initialize`
+	* from `@effected/mcp/testing`.
+	*
+	* @remarks
+	* {@link InstalledConsumer.binPath}, from the consumer's directory, under
+	* the install's scrubbed environment with `options.env` layered over it
+	* after the scrub, and nothing inherited beyond that. `runBin` builds its
+	* command here and then ignores stdin; this one leaves stdin as the
+	* spawner's default pipe, so a probe can write to it. Spawn it inside the
+	* scope that ran `PackedInstall.run`: the scratch directory is removed
+	* when that scope closes.
+	*
+	* @example
+	* ```ts
+	* import { McpProbe } from "@effected/mcp/testing";
+	* import type { InstalledConsumer } from "@effected/workspaces/testing";
+	*
+	* declare const consumer: InstalledConsumer;
+	* declare const xdg: string;
+	*
+	* const probe = McpProbe.initialize(consumer.command("my-tool-mcp", [], { env: { XDG_DATA_HOME: xdg } }));
+	* ```
+	*
+	* @param name - The bin, as named in `node_modules/.bin`.
+	* @param args - Its arguments.
+	* @param options - Extra environment and working directory.
+	*/
+	command(name, args = [], options = {}) {
+		return ChildProcess.make(this.binPath(name), args, {
+			cwd: options.cwd ?? this.directory,
+			env: layeredEnv(this, options),
+			extendEnv: false
+		});
+	}
+	/**
+	* Run the installed bin `name` to completion and collect what it wrote.
+	*
+	* @remarks
+	* Spawns {@link InstalledConsumer.command} with stdin ignored: the bin
+	* from the consumer's directory, under the install's scrubbed environment
+	* with `options.env` layered over it after the scrub, and nothing
+	* inherited beyond that. A
+	* non-zero exit is a result, read from `exitCode`, never a failure. A bin
+	* that cannot spawn, outlives `options.timeout` or floods its output fails
+	* `BinFailed` naming the manager and the bin. Run it inside the scope that
+	* ran `PackedInstall.run`: the scratch directory is removed when that
+	* scope closes.
+	*
+	* @param name - The bin, as named in `node_modules/.bin`.
+	* @param args - Its arguments.
+	* @param options - Extra environment, working directory and ceiling.
+	*/
+	runBin(name, args = [], options = {}) {
+		return collectBin(this.command(name, args, options), this.manager, name, options.timeout);
+	}
+	/**
+	* The command that runs the CARRIER's own bin `name`, whichever package
+	* won the `node_modules/.bin` slot.
+	*
+	* @remarks
+	* With `allowSharedBins`, a flat layout (npm, bun, Yarn's `node-modules`
+	* linker) can link a front end's same-named bin into `.bin`, so
+	* {@link InstalledConsumer.runBin} proves only that SOME package's bin runs.
+	* This reads the carrier's installed `node_modules/<carrier>/package.json`,
+	* takes `name` from its `bin` map (a `bin` string answers to the unscoped
+	* package name), and returns `node <that file> ...args`: the carrier's shim
+	* itself, run by the `node` on the environment's `PATH`.
+	*
+	* Running it through `node` has three limits. It assumes a Node script, so
+	* a non-Node shim misruns. It drops any flags in the shim's shebang (a
+	* `#!/usr/bin/env -S node --enable-source-maps` runs without them). And it
+	* bypasses the file's executable bit, so under shared bins it does not
+	* prove the carrier's shim is executable, only that it runs: the manager
+	* that linked a front end's bin into the slot may never have made the
+	* carrier's target executable. Environment and working directory are built as
+	* {@link InstalledConsumer.command} builds them, stdin left open for a probe
+	* such as `McpProbe.initialize`.
+	*
+	* A consumer with no `carrier`, a carrier that is not installed or does not
+	* declare `name`, or a declared file that does not exist fails
+	* `MissingBin`; a manifest that cannot be read or is not JSON fails `Io`.
+	*
+	* @param name - The bin, as the carrier's `bin` map names it.
+	* @param args - Its arguments.
+	* @param options - Extra environment and working directory.
+	*/
+	carrierCommand(name, args = [], options = {}) {
+		const consumer = this;
+		const manager = this.manager;
+		return Effect.gen(function* () {
+			const fs = yield* FileSystem.FileSystem;
+			const path = yield* Path.Path;
+			const missing = (why) => failure("MissingBin", `${manager}: the carrier's bin ${name} ${why}`, {
+				manager,
+				...consumer.carrier === void 0 ? {} : { package: consumer.carrier }
+			});
+			if (consumer.carrier === void 0) return yield* missing("cannot be found: this consumer records no carrier");
+			const root = path.join(consumer.directory, "node_modules", ...consumer.carrier.split("/"));
+			const manifestPath = path.join(root, "package.json");
+			const text = yield* fs.readFileString(manifestPath).pipe(Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.fail(missing(`cannot be found: ${consumer.carrier} is not installed at ${root}`)) : Effect.fail(failure("Io", `could not read ${manifestPath}`, {
+				manager,
+				cause: error
+			}))));
+			const manifest = readPackedManifest(text);
+			if (Result.isFailure(manifest)) return yield* failure("Io", `${manifestPath} is not a JSON object`, {
+				manager,
+				cause: manifest.failure
+			});
+			const target = binTargetOf(text, name);
+			if (target === void 0) return yield* missing(`is not declared by ${consumer.carrier}`);
+			const file = path.join(root, target);
+			if (!(yield* fs.exists(file).pipe(Effect.mapError((cause) => failure("Io", `could not inspect ${file}`, {
+				manager,
+				cause
+			}))))) return yield* missing(`points at ${file}, which does not exist`);
+			return ChildProcess.make("node", [file, ...args], {
+				cwd: options.cwd ?? consumer.directory,
+				env: layeredEnv(consumer, options),
+				extendEnv: false
+			});
+		});
+	}
+	/**
+	* Run the carrier's own bin `name` to completion, whichever package won
+	* the `node_modules/.bin` slot.
+	*
+	* @remarks
+	* Spawns {@link InstalledConsumer.carrierCommand} with stdin ignored, and
+	* reports as {@link InstalledConsumer.runBin} does: a non-zero exit is a
+	* result, and a bin that cannot spawn or outlives `options.timeout` (one
+	* minute by default) fails `BinFailed`. Use it beside `runBin` under
+	* `allowSharedBins`: `runBin` proves what a user typing the bin name gets,
+	* this proves the carrier's shim itself works, within `carrierCommand`'s
+	* limits (a Node script, shebang flags dropped, executable bit not
+	* checked).
+	*
+	* @param name - The bin, as the carrier's `bin` map names it.
+	* @param args - Its arguments.
+	* @param options - Extra environment, working directory and ceiling.
+	*/
+	runCarrierBin(name, args = [], options = {}) {
+		const manager = this.manager;
+		return this.carrierCommand(name, args, options).pipe(Effect.flatMap((command) => collectBin(command, manager, name, options.timeout)));
+	}
+};
+/** The install's scrubbed environment with the caller's entries layered on after the scrub: a deliberate CI=true must survive it. */
+const layeredEnv = (consumer, options) => {
+	const env = scrubEnv(consumer.env === void 0 ? {} : Redacted.value(consumer.env));
+	for (const [key, value] of Object.entries(options.env ?? {})) if (value === void 0) delete env[key];
+	else env[key] = value;
+	return env;
+};
+/** Run a bin's command to completion, stdin ignored, mapping a failed spawn or an expired ceiling to `BinFailed`. */
+const collectBin = (command, manager, name, timeout = DEFAULT_BIN_TIMEOUT) => Run.collect(ChildProcess.make(command.command, command.args, {
+	...command.options,
+	stdin: "ignore"
+}), { timeout }).pipe(Effect.mapError((cause) => failure("BinFailed", cause._tag === "CommandFailedError" && cause.kind === "timeout" ? `${manager}: ${name} timed out after ${describeDuration(timeout)}` : `${manager}: ${name} could not run`, {
+	manager,
+	cause
+})));
+/**
+* What a packed install produced.
+*
+* @public
+*/
+var PackedInstallResult = class extends Schema.Class("PackedInstallResult")({
+	/** One consumer per available manager, in the order requested. */
+	consumers: Schema.Array(InstalledConsumer),
+	/** The requested managers that did not answer `--version`. */
+	unavailable: Schema.Array(PackageManagerName),
+	/** Every packed package: name to absolute tarball path. */
+	tarballs: Schema.Record(Schema.String, Schema.String),
+	/**
+	* The scratch root (realpath'd) holding the tarballs and every consumer.
+	* It is removed when the scope that ran `PackedInstall.run` closes, so a
+	* directory made under it, such as an `XDG_DATA_HOME` for the bins, is
+	* cleaned up with it.
+	*/
+	scratch: Schema.String
+}) {};
+const DEFAULT_PACK_FROM = { directory: "dist/prod/npm/pkg" };
+const WORKSPACE_PROTOCOL_NOT_INSTALLED = "ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL";
+const TAIL = 2e3;
+const tail = (text) => text.length <= TAIL ? text : text.slice(-2e3);
+const DEFAULT_INSTALL_TIMEOUT = "4 minutes";
+const PROBE_TIMEOUT = "30 seconds";
+const DEFAULT_PACK_TIMEOUT = "2 minutes";
+const MANIFEST_TIMEOUT = "30 seconds";
+/** The untimed steps a budget allows for: discovery, the consumer files and the bin checks. */
+const UNTIMED_SLACK = "30 seconds";
+/**
+* Cleanup a budget allows for: removing the scratch root, every consumer's
+* `node_modules` included, when the scope closes, and killing and reaping a
+* child after its ceiling interrupts it.
+*/
+const CLEANUP_ALLOWANCE = "1 minute";
+/** A ceiling as a person reads it: `"4m"` for `"4 minutes"`, the raw input if it does not decode. */
+const describeDuration = (input) => Option.match(Duration.fromInput(input), {
+	onNone: () => String(input),
+	onSome: Duration.format
+});
+const failure = (reason, message, extra = {}) => new PackedInstallError({
+	reason,
+	message,
+	...extra
+});
+const namesOf = (plan) => [...plan.closure.map((pkg) => pkg.name), ...plan.replacements.map((replacement) => replacement.name)];
+/**
+* The one implementation of "what does this run pack", behind both
+* `PackedInstall.closure` and `PackedInstall.run`, so the two cannot drift.
+*/
+const planClosure = (carrier, options) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const discovery = yield* WorkspaceDiscovery;
+	const discoveryFailed = (cause) => failure("Discovery", "workspace discovery failed", { cause });
+	const packages = yield* discovery.listPackages().pipe(Effect.mapError(discoveryFailed));
+	const closure = closureOf(packages, carrier, options.closure ?? "auto");
+	if (Result.isFailure(closure)) return yield* failure("UnknownPackage", `${closure.failure} is not a package of this workspace`, { package: closure.failure });
+	const requested = Object.entries(options.overrides ?? {}).map(([name, spec]) => [name, overridePath(spec)]);
+	const root = options.workspaceOverrides === true || requested.some(([, spec]) => !path.isAbsolute(spec)) ? (yield* discovery.info().pipe(Effect.mapError(discoveryFailed))).root : "/";
+	const wanted = /* @__PURE__ */ new Map();
+	if (options.workspaceOverrides === true) {
+		const file = path.join(root, "pnpm-workspace.yaml");
+		const text = yield* fs.readFileString(file).pipe(Effect.mapError((cause) => failure("InvalidOverride", `workspaceOverrides reads ${file}, which could not be read`, { cause })));
+		const document = yield* Yaml.parse(text).pipe(Effect.mapError((cause) => failure("InvalidOverride", `${file} is not valid YAML`, { cause })));
+		for (const [name, spec] of Object.entries(fileOverridesOf(document))) wanted.set(name, spec);
+	}
+	for (const [name, spec] of requested) wanted.set(name, spec);
+	const packed = new Set(closure.success.map((pkg) => pkg.name));
+	const replacements = [];
+	for (const name of [...wanted.keys()].sort()) {
+		const invalid = (message, cause) => failure("InvalidOverride", `override ${name}: ${message}`, {
+			package: name,
+			...cause === void 0 ? {} : { cause }
+		});
+		if (packed.has(name)) return yield* invalid(`${name === carrier ? "the carrier" : "a closure member"} is always packed from the workspace; overrides replace only packages outside it`);
+		const spec = wanted.get(name) ?? "";
+		const absolute = path.isAbsolute(spec) ? spec : path.resolve(root, spec);
+		const source = yield* fs.realPath(absolute).pipe(Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.fail(invalid(`${absolute} does not exist`)) : Effect.fail(failure("Io", `could not resolve ${absolute}`, {
+			package: name,
+			cause: error
+		}))));
+		const info = yield* fs.stat(source).pipe(Effect.mapError((cause) => failure("Io", `could not inspect ${source}`, {
+			package: name,
+			cause
+		})));
+		if (info.type === "Directory") {
+			const manifest = path.join(source, "package.json");
+			if (!(yield* fs.exists(manifest).pipe(Effect.mapError((cause) => failure("Io", `could not inspect ${manifest}`, {
+				package: name,
+				cause
+			}))))) return yield* invalid(`${source} has no package.json to pack`);
+			replacements.push({
+				name,
+				source,
+				kind: "directory"
+			});
+		} else if (info.type === "File" && source.endsWith(".tgz")) replacements.push({
+			name,
+			source,
+			kind: "tarball"
+		});
+		else return yield* invalid(`${source} is neither a package directory nor a .tgz`);
+	}
+	return {
+		closure: closure.success,
+		replacements
+	};
+});
+/**
+* Prove a carrier's bins reach a consumer that is not part of the workspace,
+* once per available package manager.
+*
+* @remarks
+* Packs the carrier and its closure into a scoped, realpath'd scratch
+* directory (so `file:` specs and the install cwd agree on macOS). Then, for
+* each manager that answers `--version` from that directory (so a corepack
+* pin in the repo cannot refuse it), it writes a consumer whose only direct
+* dependency is the carrier tarball, steers the closure to its tarballs
+* through the manager's own override field, pins the probed version (as
+* `packageManager`, or for pnpm as `devEngines.packageManager` with
+* `onFail: "ignore"`, since pnpm resolves a `packageManager` pin from the registry even
+* when it names the running version), installs with lifecycle scripts skipped,
+* and checks every
+* expected bin is present and executable. A packed manifest that still
+* carries `workspace:`, `catalog:`, `link:` or a relative `file:` specifier
+* fails `UnresolvedProtocol` before any install.
+*
+* It asserts nothing about what the bins DO: run them from the test through
+* `InstalledConsumer.runBin`, or for an MCP bin through `McpProbe` from
+* `@effected/mcp/testing` at `InstalledConsumer.binPath`, inside the same
+* scope, because the scratch directory (`PackedInstallResult.scratch`) is
+* removed when the scope closes. Size the test's outer timeout with
+* {@link PackedInstall.timeoutBudget}. POSIX only.
+*
+* @example
+* ```ts
+* import { NodeServices } from "@effect/platform-node";
+* import { Workspaces } from "@effected/workspaces";
+* import { PackedInstall } from "@effected/workspaces/testing";
+* import { Effect, Layer } from "effect";
+*
+* const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+*
+* // Use the consumers INSIDE the scope: closing it removes the scratch
+* // directory, so a binPath returned out of Effect.scoped points at nothing.
+* const program = Effect.gen(function* () {
+*   const result = yield* PackedInstall.run({
+*     carrier: "my-tool",
+*     closure: "auto",
+*     managers: ["npm", "pnpm"],
+*     bins: ["my-tool"],
+*     env: process.env,
+*   });
+*   // Keep the tool's data inside the scratch root, removed with it.
+*   const env = { XDG_DATA_HOME: `${result.scratch}/xdg` };
+*   for (const consumer of result.consumers) {
+*     const { stdout, exitCode } = yield* consumer.runBin("my-tool", ["--version"], { env });
+*     console.log(consumer.manager, exitCode, stdout.trim());
+*   }
+* }).pipe(Effect.scoped, Effect.provide(Live));
+* ```
+*
+* @public
+*/
+var PackedInstall = class PackedInstall {
+	constructor() {}
+	/** `env` without undefined values or the parent manager's context: the environment the installs run under. Reuse it to run the installed bins. */
+	static scrubEnv = scrubEnv;
+	/**
+	* The ceiling a test's outer timeout should cover so that every one of the
+	* run's own ceilings fires first, as a named `PackedInstallError`, rather
+	* than the outer guard's `TimeoutError` that names nothing.
+	*
+	* @remarks
+	* The worst case of the run's own ceilings, taken in sequence as the run
+	* takes them: each manager's `--version` probe (30 seconds), install
+	* (`installTimeout`) and `perConsumer` (one minute by default, one `runBin`
+	* at its default ceiling), plus each package's pack
+	* (`packTimeout`, two minutes by default) and manifest read (30 seconds),
+	* plus 30 seconds for the untimed steps and one minute for cleanup:
+	* removing the scratch root when the scope closes, and killing a child
+	* whose ceiling interrupted it. It reads the same defaults the run does.
+	* Pass `packages` as the names {@link PackedInstall.closure} returns to
+	* size it before the run. A vitest test timeout must sit above it, since
+	* vitest's own guard should not pre-empt the Effect's.
+	*
+	* @example
+	* ```ts
+	* import { PackedInstall } from "@effected/workspaces/testing";
+	* import { Duration } from "effect";
+	*
+	* const budget = PackedInstall.timeoutBudget({
+	*   managers: ["npm", "pnpm", "yarn", "bun"],
+	*   installTimeout: "3 minutes",
+	*   packTimeout: "30 seconds",
+	*   packages: ["my-tool", "my-tool-cli", "my-tool-core"],
+	*   perConsumer: "2 minutes",
+	* });
+	* console.log(Duration.format(budget));
+	* // => 26m 30s
+	* ```
+	*/
+	static timeoutBudget = (budget) => {
+		const perManager = [
+			PROBE_TIMEOUT,
+			budget.installTimeout ?? DEFAULT_INSTALL_TIMEOUT,
+			budget.perConsumer ?? DEFAULT_BIN_TIMEOUT
+		].map(Duration.fromInputUnsafe).reduce((total, step) => Duration.sum(total, step), Duration.zero);
+		const perPackage = Duration.sum(Duration.fromInputUnsafe(budget.packTimeout ?? DEFAULT_PACK_TIMEOUT), Duration.fromInputUnsafe(MANIFEST_TIMEOUT));
+		const packages = typeof budget.packages === "number" ? budget.packages : budget.packages.length;
+		return Duration.sum(Duration.sum(Duration.times(perManager, new Set(budget.managers).size), Duration.times(perPackage, Math.max(1, packages))), Duration.sum(Duration.fromInputUnsafe(UNTIMED_SLACK), Duration.fromInputUnsafe(CLEANUP_ALLOWANCE)));
+	};
+	/**
+	* The packages a run packs, in the order it packs them, without packing
+	* anything: the carrier, the rest of the closure, then the `overrides`
+	* packages by name.
+	*
+	* @remarks
+	* The same implementation {@link PackedInstall.run} plans with, so for the
+	* same workspace and options the result equals the keys of
+	* `PackedInstallResult.tarballs`, in order. `options.closure` defaults to
+	* `"auto"`, and the run's own options object is accepted as it is. It
+	* fails as the run would before packing: `UnknownPackage`, `Discovery`,
+	* `InvalidOverride` or `Io`. Use it to size
+	* {@link PackedInstall.timeoutBudget} before the test is declared.
+	*
+	* @example
+	* ```ts
+	* import { NodeServices } from "@effect/platform-node";
+	* import { Workspaces } from "@effected/workspaces";
+	* import { PackedInstall } from "@effected/workspaces/testing";
+	* import { Effect, Layer } from "effect";
+	*
+	* const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+	* const packages = await Effect.runPromise(PackedInstall.closure("my-tool").pipe(Effect.provide(Live)));
+	* const budget = PackedInstall.timeoutBudget({ managers: ["npm", "pnpm"], packages });
+	* ```
+	*
+	* @param carrier - The carrier, as the run's `carrier`.
+	* @param options - The closure and override options, as the run takes them.
+	*/
+	static closure = (carrier, options = {}) => planClosure(carrier, options).pipe(Effect.map(namesOf), Effect.withSpan("PackedInstall.closure"));
+	/**
+	* {@link PackedInstall.timeoutBudget} for exactly the run `options`
+	* describes, planned from the options themselves.
+	*
+	* @remarks
+	* Plans the closure with {@link PackedInstall.closure} (the run's own
+	* planner, `overrides` and `workspaceOverrides` included) and takes
+	* `managers`, `installTimeout` and `packTimeout` from the same object, so
+	* nothing is written twice. `perConsumer` is the one input a run's options
+	* do not carry. It is an Effect because planning reads the workspace; in a
+	* vitest file, await it at module evaluation, since a test's timeout is
+	* fixed when the test is declared. Fails as `closure` does.
+	*
+	* @example
+	* ```ts
+	* import { NodeServices } from "@effect/platform-node";
+	* import { Workspaces } from "@effected/workspaces";
+	* import type { PackedInstallOptions } from "@effected/workspaces/testing";
+	* import { PackedInstall } from "@effected/workspaces/testing";
+	* import { Duration, Effect, Layer } from "effect";
+	*
+	* const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
+	* const RUN: PackedInstallOptions = {
+	*   carrier: "my-tool",
+	*   closure: "auto",
+	*   managers: ["npm", "pnpm"],
+	*   bins: ["my-tool"],
+	*   env: process.env,
+	*   packTimeout: "30 seconds",
+	* };
+	* const budget = await Effect.runPromise(
+	*   PackedInstall.timeoutBudgetFor(RUN, { perConsumer: "1 minute" }).pipe(Effect.provide(Live)),
+	* );
+	* const TEST_TIMEOUT_MS = Duration.toMillis(budget) + 60_000;
+	* ```
+	*
+	* @param options - The run's options, the same object passed to `run`.
+	* @param extra - What the test does with each consumer afterwards.
+	*/
+	static timeoutBudgetFor = (options, extra = {}) => PackedInstall.closure(options.carrier, options).pipe(Effect.map((packages) => PackedInstall.timeoutBudget({
+		managers: options.managers,
+		packages,
+		...options.installTimeout === void 0 ? {} : { installTimeout: options.installTimeout },
+		...options.packTimeout === void 0 ? {} : { packTimeout: options.packTimeout },
+		...extra.perConsumer === void 0 ? {} : { perConsumer: extra.perConsumer }
+	})));
+	/** Pack, then install under every available manager. */
+	static run = Effect.fn("PackedInstall.run")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		if (path.sep !== "/") return yield* failure("UnsupportedPlatform", "PackedInstall drives POSIX .bin shims and tar; run it on macOS or Linux");
+		const managers = [...new Set(options.managers)];
+		if (managers.length === 0) return yield* failure("NoManagerAvailable", "managers is empty: name at least one package manager to install with");
+		const env = scrubEnv(options.env);
+		const io = (message) => (cause) => failure("Io", message, { cause });
+		const command = (executable, args, cwd) => ChildProcess.make(executable, args, {
+			cwd,
+			env,
+			extendEnv: false,
+			stdin: "ignore"
+		});
+		const scratch = yield* fs.makeTempDirectoryScoped({ prefix: "effected-packed-install-" }).pipe(Effect.flatMap((directory) => fs.realPath(directory)), Effect.mapError(io("could not create the scratch directory")));
+		const probes = yield* Effect.forEach(managers, (manager) => Run.collect(command(manager, ["--version"], scratch), { timeout: PROBE_TIMEOUT }).pipe(Effect.map((output) => output.succeeded ? versionOf(output.stdout) : void 0), Effect.catch(() => Effect.succeed(void 0)), Effect.map((version) => ({
+			manager,
+			version
+		}))));
+		const available = probes.flatMap(({ manager, version }) => version === void 0 ? [] : [{
+			manager,
+			version
+		}]);
+		const unavailable = probes.flatMap(({ manager, version }) => version === void 0 ? [manager] : []);
+		if (available.length === 0) return yield* failure("NoManagerAvailable", `none of ${managers.join(", ")} answered --version from ${scratch}`);
+		const missing = unavailable[0];
+		if (options.require === "all" && missing !== void 0) return yield* failure("ManagerUnavailable", `${missing} is required but did not answer --version`, { manager: missing });
+		const plan = yield* planClosure(options.carrier, options);
+		const source = options.packFrom ?? DEFAULT_PACK_FROM;
+		const packTimeout = options.packTimeout ?? DEFAULT_PACK_TIMEOUT;
+		/** `npm pack` or `pnpm pack` in `cwd` into an empty `destination`; the one tarball it wrote. */
+		const pack = (name, cwd, packer, destination) => Effect.gen(function* () {
+			yield* fs.makeDirectory(destination, { recursive: true }).pipe(Effect.mapError(io(`could not create ${destination}`)));
+			const args = packer === "pnpm" ? [
+				"pack",
+				"--pack-destination",
+				destination,
+				"--config.ignore-scripts=true"
+			] : [
+				"pack",
+				"--ignore-scripts",
+				"--pack-destination",
+				destination
+			];
+			const output = yield* Run.collect(command(packer, args, cwd), { timeout: packTimeout }).pipe(Effect.mapError((cause) => failure("PackFailed", cause._tag === "CommandFailedError" && cause.kind === "timeout" ? `${packer} pack timed out after ${describeDuration(packTimeout)} for ${name}` : `${packer} pack could not run for ${name}`, {
+				package: name,
+				cause
+			})));
+			if (!output.succeeded) {
+				const notInstalled = packer === "pnpm" && `${output.stdout}${output.stderr}`.includes(WORKSPACE_PROTOCOL_NOT_INSTALLED);
+				return yield* failure("PackFailed", notInstalled ? `pnpm pack could not rewrite the workspace: specifiers of ${name} because the workspace is not installed; run pnpm install in the workspace first` : `${packer} pack exited ${output.exitCode} for ${name}`, {
+					package: name,
+					output: tail(`${output.stdout}\n${output.stderr}`)
+				});
+			}
+			const found = (yield* fs.readDirectory(destination).pipe(Effect.mapError(io(`could not list ${destination}`)))).filter((file) => file.endsWith(".tgz"));
+			const [only] = found;
+			if (only === void 0 || found.length !== 1) return yield* failure("PackFailed", `expected exactly one tarball for ${name} in ${destination}, found ${found.length}`, { package: name });
+			return path.join(destination, only);
+		});
+		/** The packed manifest, read with `tar` from `cwd`, refused if only a workspace could resolve it. */
+		const inspect = (name, tarball, cwd) => Effect.gen(function* () {
+			const text = yield* Run.text(command("tar", [
+				"-xzOf",
+				tarball,
+				"package/package.json"
+			], cwd), { timeout: MANIFEST_TIMEOUT }).pipe(Effect.mapError((cause) => failure("PackFailed", `could not read package/package.json out of ${tarball}`, {
+				package: name,
+				cause
+			})));
+			const manifest = readPackedManifest(text);
+			if (Result.isFailure(manifest)) return yield* failure("PackFailed", `the packed package.json of ${name} is not a JSON object`, {
+				package: name,
+				cause: manifest.failure
+			});
+			if (manifest.success.unresolved.length > 0) return yield* failure("UnresolvedProtocol", `${name}'s packed manifest still carries ${manifest.success.unresolved.join(", ")}, which no consumer outside the workspace can resolve; pack from "source" so pnpm rewrites workspace: and catalog:, or fix the build`, { package: name });
+			return manifest.success;
+		});
+		const packed = [];
+		for (const [index, pkg] of plan.closure.entries()) {
+			const destination = path.join(scratch, "tarballs", String(index));
+			const cwd = source === "source" ? pkg.path : path.join(pkg.path, source.directory);
+			if (source !== "source") {
+				if (!(yield* fs.exists(path.join(cwd, "package.json")).pipe(Effect.mapError(io(`could not inspect ${cwd}`))))) return yield* failure("PackSourceMissing", `${cwd} has no package.json; build ${pkg.name} before packing it`, { package: pkg.name });
+			}
+			const tarball = yield* pack(pkg.name, cwd, source === "source" ? "pnpm" : "npm", destination);
+			packed.push({
+				name: pkg.name,
+				tarball,
+				manifest: yield* inspect(pkg.name, tarball, destination)
+			});
+		}
+		for (const [offset, replacement] of plan.replacements.entries()) {
+			const destination = path.join(scratch, "tarballs", String(plan.closure.length + offset));
+			const tarball = replacement.kind === "tarball" ? replacement.source : yield* pack(replacement.name, replacement.source, "npm", destination);
+			const manifest = yield* inspect(replacement.name, tarball, scratch);
+			if (manifest.name !== replacement.name) return yield* failure("InvalidOverride", `override ${replacement.name}: ${replacement.source} packs ${manifest.name ?? "a package with no name"}, not ${replacement.name}`, { package: replacement.name });
+			packed.push({
+				name: replacement.name,
+				tarball,
+				manifest
+			});
+		}
+		const [carrier, ...rest] = packed;
+		if (carrier === void 0) return yield* failure("UnknownPackage", `${options.carrier} was not packed`, { package: options.carrier });
+		const conflict = options.allowSharedBins === true ? void 0 : binConflict({
+			name: carrier.name,
+			bins: carrier.manifest.bins
+		}, rest.map(({ name, manifest }) => ({
+			name,
+			bins: manifest.bins
+		})));
+		if (conflict !== void 0) return yield* failure("BinConflict", `${conflict.package} declares the bin ${conflict.bin}, which the carrier ${carrier.name} declares; under a flat layout (npm, bun, Yarn's node-modules linker) either can take node_modules/.bin/${conflict.bin} and the carrier's provenance is lost there; drop the bin from ${conflict.package}, or pass allowSharedBins: true to share it deliberately`, { package: conflict.package });
+		const overrides = Object.fromEntries(rest.map(({ name, tarball }) => [name, tarball]));
+		const consumers = yield* Effect.forEach(available, ({ manager, version }) => Effect.gen(function* () {
+			const directory = path.join(scratch, `consumer-${manager}`);
+			yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError(io(`could not create ${directory}`)));
+			for (const { file, content } of consumerFiles({
+				manager,
+				version,
+				carrier,
+				overrides,
+				dependencies: options.consumerDependencies ?? {}
+			})) yield* fs.writeFileString(path.join(directory, file), content).pipe(Effect.mapError(io(`could not write ${file}`)));
+			const installTimeout = options.installTimeout ?? DEFAULT_INSTALL_TIMEOUT;
+			const output = yield* Run.collect(command(manager, installArgs(manager, version), directory), { timeout: installTimeout }).pipe(Effect.mapError((cause) => failure("InstallFailed", cause._tag === "CommandFailedError" && cause.kind === "timeout" ? `${manager} install timed out after ${describeDuration(installTimeout)}` : `${manager} install could not run`, {
+				manager,
+				cause
+			})));
+			if (!output.succeeded) return yield* failure("InstallFailed", `${manager} install exited ${output.exitCode}`, {
+				manager,
+				output: tail(`${output.stdout}\n${output.stderr}`)
+			});
+			const consumer = InstalledConsumer.make({
+				manager,
+				managerVersion: version,
+				directory,
+				env: Redacted.make(env),
+				carrier: carrier.name
+			});
+			for (const bin of options.bins) {
+				const info = yield* Effect.option(fs.stat(consumer.binPath(bin)));
+				if (Option.isNone(info) || (info.value.mode & 73) === 0) {
+					const listing = yield* fs.readDirectory(path.join(directory, "node_modules", ".bin")).pipe(Effect.map((names) => names.length === 0 ? "node_modules/.bin is empty" : `node_modules/.bin holds: ${[...names].sort().join(", ")}`), Effect.catch(() => Effect.succeed("node_modules/.bin does not exist or cannot be listed")));
+					return yield* failure("MissingBin", `${manager} installed ${options.carrier} but node_modules/.bin/${bin} is missing or not executable; ${listing}`, {
+						manager,
+						package: options.carrier,
+						output: listing
+					});
+				}
+			}
+			return consumer;
+		}));
+		return PackedInstallResult.make({
+			consumers,
+			unavailable,
+			tarballs: Object.fromEntries(packed.map(({ name, tarball }) => [name, tarball])),
+			scratch
+		});
+	});
+};
+
+//#endregion
+export { InstalledConsumer, PackedInstall, PackedInstallError, PackedInstallResult };