@effected/workspaces 0.26.0 → 0.28.0-next-20260927062352

package/testing.d.ts

@@ -3,6 +3,8 @@ import { Context, Duration, Effect, FileSystem, Layer, Option, Path, Schema } fr
 import { GlobPattern } from "@effected/glob";
 import { WorkspaceManifest } from "@effected/lockfiles";
 import { Package } from "@effected/package-json";
+import { CommandOutput } from "@effected/commands";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 //#region src/LayerPolicy.d.ts
 declare const LayerPolicyError_base: Schema.Class<LayerPolicyError, Schema.TaggedStruct<"LayerPolicyError", {
   /** `read`: the file could not be read. `json`: it is not JSON. `decode`: it is not a `LayerPolicy`. */
@@ -883,12 +885,66 @@ export declare class WorkspaceDiscovery extends WorkspaceDiscovery_base {
 type PackSource = "source" | {
   readonly directory: string;
 };
+/**
+ * What decides the set of packages a packed install packs: the options
+ * {@link PackedInstall.closure} and {@link PackedInstall.run} share.
+ *
+ * @remarks
+ * The run's options satisfy this interface, so
+ * `PackedInstall.closure(options.carrier, options)` answers for exactly the
+ * run those options describe.
+ *
+ * @public
+ */
+interface PackedInstallClosureOptions {
+  /**
+   * The other workspace packages to pack and override; `"auto"` is the
+   * carrier's transitive runtime workspace dependencies (`dependencies`,
+   * `optionalDependencies`, `peerDependencies`). `PackedInstall.closure`
+   * defaults it to `"auto"`.
+   */
+  readonly closure?: ReadonlyArray<string> | "auto" | undefined;
+  /**
+   * Packages from outside the workspace that replace registry resolution in
+   * every scratch consumer: package name to a local package directory or a
+   * `.tgz`, with or without a `file:` prefix.
+   *
+   * @remarks
+   * The dogfood case: a closure member imports a surface of a dependency
+   * that exists only in a sibling checkout's unreleased build, and the
+   * registry's copy lacks it. A directory is `npm pack`ed, so it must be
+   * publish-ready (for an effected-bundled package, its
+   * `dist/prod/npm/pkg`); a `.tgz` is used as it is. Either way the packed
+   * manifest must be named as its key, carry no specifier only a workspace
+   * could resolve, and it joins `PackedInstallResult.tarballs`. Each
+   * consumer steers the package to that tarball through the same override
+   * field as the closure (npm's and bun's `overrides`, Yarn's `resolutions`,
+   * pnpm's `overrides` in `pnpm-workspace.yaml`), so the carrier's
+   * transitive references resolve to it too, whatever range they ask for.
+   *
+   * A relative path resolves against the workspace root. A key naming the
+   * carrier or a closure member, a path that is neither a directory with a
+   * `package.json` nor a `.tgz` file, or a manifest named otherwise fails
+   * `InvalidOverride`. Entries here win over `workspaceOverrides` ones.
+   */
+  readonly overrides?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Also read the workspace root's `pnpm-workspace.yaml` and take every
+   * `overrides:` entry of the dogfood link shape,
+   * `"@scope/name": "file:<dir>"`, as if passed through `overrides`: the
+   * linked sibling builds the workspace itself installs. Entries that are not `file:`, or
+   * whose key carries a selector (`a>b`, `a@1`), are left out. A root with
+   * no readable `pnpm-workspace.yaml`, or one that is not YAML, fails
+   * `InvalidOverride`.
+   */
+  readonly workspaceOverrides?: boolean | undefined;
+}
 /**
  * Options for {@link PackedInstall.run}.
  *
  * @public
  */
-interface PackedInstallOptions {
+interface PackedInstallOptions extends PackedInstallClosureOptions {
   /** The carrier: a direct dependency of each scratch consumer, beside only `consumerDependencies`. */
   readonly carrier: string;
   /** The other workspace packages to pack and override; `"auto"` is the carrier's transitive runtime workspace dependencies. */
@@ -906,8 +962,46 @@ interface PackedInstallOptions {
    * published artifact; see {@link PackSource} for what `"source"` costs.
    */
   readonly packFrom?: PackSource | undefined;
-  /** Bin names every consumer must expose, executable, in `node_modules/.bin`. */
+  /**
+   * Bin names every consumer must expose, executable, in `node_modules/.bin`.
+   *
+   * @remarks
+   * By default only the carrier may declare them. Whatever this lists, a
+   * packed package other than the carrier that declares one of the
+   * carrier's own bin names fails `BinConflict` before any install, unless
+   * `allowSharedBins` is set: under a flat layout (npm, bun,
+   * Yarn's `node-modules` linker) either package can take the `.bin` slot,
+   * so the bin check and every bin run could pass on the wrong package.
+   *
+   * The check compares packed packages only (the carrier, the closure and
+   * `overrides`), reading each manifest's `bin` field; it does not read
+   * `directories.bin`, and a dependency installed from the registry that
+   * declares the same bin name goes undetected.
+   */
   readonly bins: ReadonlyArray<string>;
+  /**
+   * Skip the `BinConflict` check: the front ends declare the carrier's bin
+   * names too, deliberately.
+   *
+   * @remarks
+   * A supported, permanent choice for a carrier whose front ends are also
+   * installed and run on their own, and a stopgap for one migrating to
+   * carrier-only bins. Its cost is provenance: under npm, bun and Yarn's
+   * `node-modules` linker, either package can take the `.bin` slot (npm and
+   * bun were observed to link the package whose name sorts first, which for
+   * a `cli` front end and a `plugin` carrier is the front end; Yarn 1 and 4
+   * were observed to keep the carrier's, the consumer's direct dependency),
+   * and the bin that runs then carries no distribution identity: no
+   * `--version` suffix.
+   * When every shared bin calls the same `main()`, nothing else changes.
+   *
+   * Every expected bin in `bins` is still verified present and executable,
+   * but that check, and `runBin`, can pass on the front end's bin. Prove the
+   * carrier's own shim with `InstalledConsumer.runCarrierBin`, and read who
+   * owns the slot with `InstalledConsumer.binProvenance`. Defaults to
+   * `false`, so sharing is an explicit choice.
+   */
+  readonly allowSharedBins?: boolean | undefined;
   /** The environment for every spawn: pass `process.env` from the test file. The parent manager's context is stripped. */
   readonly env: Readonly<Record<string, string | undefined>>;
   /**
@@ -922,19 +1016,26 @@ interface PackedInstallOptions {
    * while npm and bun hoist it and pass. That is a property of the consumer,
    * not of the pack.
    *
-   * An entry naming a packed package (the carrier or a closure member) is
-   * written as that package's `file:` tarball, whatever spec you pass, so
-   * any range will do: the packed tarball always wins. npm fails an install
-   * whose direct spec differs from its override (`EOVERRIDE`), so a range
-   * written through unchanged would break every npm consumer.
+   * An entry naming a packed package (the carrier, a closure member or an
+   * `overrides` package) is written as that package's `file:` tarball,
+   * whatever spec you pass, so any range will do: the packed tarball always
+   * wins. npm fails an install whose direct spec differs from its override
+   * (`EOVERRIDE`), so a range written through unchanged would break every
+   * npm consumer.
    */
   readonly consumerDependencies?: Readonly<Record<string, string>> | undefined;
   /** Ceiling on each install. Defaults to four minutes. Expiry fails `InstallFailed` with a message naming the manager and this duration. */
   readonly installTimeout?: Duration.Input | undefined;
+  /**
+   * Ceiling on each package's pack. Defaults to two minutes. Expiry fails
+   * `PackFailed` with a message naming the package and this duration. Pass
+   * the same value to {@link PackedInstall.timeoutBudget}.
+   */
+  readonly packTimeout?: Duration.Input | undefined;
 }
 declare const PackedInstallError_base: Schema.Class<PackedInstallError, Schema.TaggedStruct<"PackedInstallError", {
   /** What failed. */
-  readonly reason: Schema.Literals<readonly ["UnsupportedPlatform", "NoManagerAvailable", "ManagerUnavailable", "UnknownPackage", "PackSourceMissing", "PackFailed", "UnresolvedProtocol", "InstallFailed", "MissingBin", "Discovery", "Io"]>;
+  readonly reason: Schema.Literals<readonly ["UnsupportedPlatform", "NoManagerAvailable", "ManagerUnavailable", "UnknownPackage", "PackSourceMissing", "PackFailed", "UnresolvedProtocol", "InvalidOverride", "BinConflict", "InstallFailed", "MissingBin", "BinFailed", "UnownedBin", "Discovery", "Io"]>;
   /** One line, naming the package or manager involved. */
   readonly message: Schema.String;
   /** The package manager involved. */
@@ -952,6 +1053,44 @@ declare const PackedInstallError_base: Schema.Class<PackedInstallError, Schema.T
  * @public
  */
 export declare class PackedInstallError extends PackedInstallError_base {}
+/**
+ * Options for {@link InstalledConsumer.command}: how the bin's environment
+ * and working directory are built.
+ *
+ * @public
+ */
+interface BinCommandOptions {
+  /**
+   * Variables layered over the environment the install ran under, such as an
+   * `XDG_DATA_HOME` inside `PackedInstallResult.scratch`. A key set to
+   * `undefined` removes that variable. They are applied after the parent
+   * manager's context is stripped, so an explicit entry always wins: pass
+   * `CI: "true"` to run a bin as if under CI.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** The working directory. Defaults to the consumer's `directory`. */
+  readonly cwd?: string | undefined;
+}
+/**
+ * Options for {@link InstalledConsumer.runBin}.
+ *
+ * @public
+ */
+interface RunBinOptions extends BinCommandOptions {
+  /** Ceiling on the run. Defaults to one minute. Expiry fails `BinFailed` with a message naming the bin and this duration. */
+  readonly timeout?: Duration.Input | undefined;
+}
+/**
+ * Which installed package a `node_modules/.bin` symlink resolves into.
+ *
+ * @public
+ */
+interface BinProvenance {
+  /** The `name` from the nearest `package.json` above the link's target. */
+  readonly package: string;
+  /** The link's target, realpath'd. */
+  readonly target: string;
+}
 declare const InstalledConsumer_base: Schema.Class<InstalledConsumer, Schema.Struct<{
   /** The package manager that installed it. */
   readonly manager: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
@@ -959,6 +1098,18 @@ declare const InstalledConsumer_base: Schema.Class<InstalledConsumer, Schema.Str
   readonly managerVersion: Schema.String;
   /** The consumer project directory (realpath'd). */
   readonly 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`.
+   */
+  readonly 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.
+   */
+  readonly carrier: Schema.optionalKey<Schema.String>;
 }>, {}>;
 /**
  * One scratch project, outside the workspace, with the carrier installed.
@@ -968,6 +1119,134 @@ declare const InstalledConsumer_base: Schema.Class<InstalledConsumer, Schema.Str
 export declare class InstalledConsumer extends InstalledConsumer_base {
   /** The installed bin `name`, in `node_modules/.bin`. POSIX: `PackedInstall` runs only there. */
   binPath(name: string): string;
+  /**
+   * 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: string): Effect.Effect<BinProvenance | undefined, PackedInstallError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * 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: string, args?: ReadonlyArray<string>, options?: BinCommandOptions): ChildProcess.StandardCommand;
+  /**
+   * 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: string, args?: ReadonlyArray<string>, options?: RunBinOptions): Effect.Effect<CommandOutput, PackedInstallError, ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * 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: string, args?: ReadonlyArray<string>, options?: BinCommandOptions): Effect.Effect<ChildProcess.StandardCommand, PackedInstallError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * 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: string, args?: ReadonlyArray<string>, options?: RunBinOptions): Effect.Effect<CommandOutput, PackedInstallError, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
 }
 declare const PackedInstallResult_base: Schema.Class<PackedInstallResult, Schema.Struct<{
   /** One consumer per available manager, in the order requested. */
@@ -976,6 +1255,13 @@ declare const PackedInstallResult_base: Schema.Class<PackedInstallResult, Schema
   readonly unavailable: Schema.$Array<Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>>;
   /** Every packed package: name to absolute tarball path. */
   readonly 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.
+   */
+  readonly scratch: Schema.String;
 }>, {}>;
 /**
  * What a packed install produced.
@@ -983,6 +1269,32 @@ declare const PackedInstallResult_base: Schema.Class<PackedInstallResult, Schema
  * @public
  */
 export declare class PackedInstallResult extends PackedInstallResult_base {}
+/**
+ * What {@link PackedInstall.timeoutBudget} adds up.
+ *
+ * @public
+ */
+interface PackedInstallBudget {
+  /** The managers the run requests; one listed twice counts once. */
+  readonly managers: ReadonlyArray<PackageManagerName>;
+  /** The run's `installTimeout`. Defaults to four minutes, as the run does. */
+  readonly installTimeout?: Duration.Input | undefined;
+  /** The run's `packTimeout`. Defaults to two minutes, as the run does. */
+  readonly packTimeout?: Duration.Input | undefined;
+  /**
+   * What the run packs: a count, or the names {@link PackedInstall.closure}
+   * returns for the run's options, which are exactly the keys of
+   * `PackedInstallResult.tarballs`.
+   */
+  readonly packages: number | ReadonlyArray<string>;
+  /**
+   * What the test does with each consumer afterwards, such as its bin runs'
+   * ceilings. Defaults to one minute: one {@link InstalledConsumer.runBin}
+   * at its default ceiling. Add a minute per further `runBin`, and pass
+   * `"0 seconds"` for a test that only installs.
+   */
+  readonly perConsumer?: Duration.Input | undefined;
+}
 /**
  * Prove a carrier's bins reach a consumer that is not part of the workspace,
  * once per available package manager.
@@ -994,8 +1306,8 @@ export declare class PackedInstallResult extends PackedInstallResult_base {}
  * 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
+ * `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
@@ -1003,18 +1315,18 @@ export declare class PackedInstallResult extends PackedInstallResult_base {}
  * fails `UnresolvedProtocol` before any install.
  *
  * It asserts nothing about what the bins DO: run them from the test through
- * `InstalledConsumer.binPath`, for an MCP bin with `McpProbe` from
- * `@effected/mcp/testing`, inside the same scope, because the scratch
- * directory is removed when the scope closes. POSIX only.
+ * `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 { Run } from "@effected/commands";
  * import { Workspaces } from "@effected/workspaces";
  * import { PackedInstall } from "@effected/workspaces/testing";
  * import { Effect, Layer } from "effect";
- * import { ChildProcess } from "effect/unstable/process";
  *
  * const Live = Workspaces.layer({ cwd: "/repo" }).pipe(Layer.provideMerge(NodeServices.layer));
  *
@@ -1028,12 +1340,11 @@ export declare class PackedInstallResult extends PackedInstallResult_base {}
  *     bins: ["my-tool"],
  *     env: process.env,
  *   });
- *   const env = PackedInstall.scrubEnv(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 version = yield* Run.text(
- *       ChildProcess.make(consumer.binPath("my-tool"), ["--version"], { env, extendEnv: false }),
- *     );
- *     console.log(consumer.manager, version.trim());
+ *     const { stdout, exitCode } = yield* consumer.runBin("my-tool", ["--version"], { env });
+ *     console.log(consumer.manager, exitCode, stdout.trim());
  *   }
  * }).pipe(Effect.scoped, Effect.provide(Live));
  * ```
@@ -1044,8 +1355,115 @@ export declare class PackedInstall {
   private 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 readonly scrubEnv: (env: Readonly<Record<string, string | undefined>>) => Record<string, string>;
+  /**
+   * 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 readonly timeoutBudget: (budget: PackedInstallBudget) => Duration.Duration;
+  /**
+   * 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 readonly closure: (carrier: string, options?: PackedInstallClosureOptions) => Effect.Effect<ReadonlyArray<string>, PackedInstallError, WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * {@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 readonly timeoutBudgetFor: (options: PackedInstallOptions, extra?: {
+    readonly perConsumer?: Duration.Input | undefined;
+  }) => Effect.Effect<Duration.Duration, PackedInstallError, WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
   /** Pack, then install under every available manager. */
-  static readonly run: (options: PackedInstallOptions) => Effect.Effect<PackedInstallResult, PackedInstallError, import("effect/unstable/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | Path.Path | import("effect/Scope").Scope | WorkspaceDiscovery>;
+  static readonly run: (options: PackedInstallOptions) => Effect.Effect<PackedInstallResult, PackedInstallError, ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path | import("effect/Scope").Scope | WorkspaceDiscovery>;
 }
 //#endregion
 //#region src/SourceBoundary.d.ts
@@ -1068,6 +1486,17 @@ export declare class PackedInstall {
  * core's `Console` service. `{ forbidImports }` forbids an import whose specifier
  * equals an entry, is a subpath of one, or starts with an entry's text before a
  * trailing `*` (so `"node:*"` and `"@effect/platform*"` are prefixes).
+ * `{ forbidTokens }` forbids each entry's exact text wherever it appears in
+ * code (see {@link SourceBoundary.check} for how a token is matched).
+ *
+ * To confine a token to named files rather than forbid it everywhere, forbid
+ * it and waive the rule for those files through
+ * {@link ScanOptions.allowRules}: the `"forbidTokens"` key names the files, and
+ * `SourceScan.waived` then reports every use inside them, so a
+ * confinement that no longer matches anything shows up there. The house rule
+ * "`process.env.__PACKAGE_VERSION__` only in `version.ts`" is
+ * `rules: [{ forbidTokens: ["process.env.__PACKAGE_VERSION__"] }]` with
+ * `allowRules: { forbidTokens: ["version.ts"] }`.
  *
  * `"node:*"` matches only the `node:` spelling: a bare built-in such as `"fs"`
  * is not caught. To forbid both, spread Node's own list from the test file,
@@ -1080,6 +1509,8 @@ export declare class PackedInstall {
  */
 type BoundaryRule = "process" | "node:process" | "stdout-write" | "console" | "console-stdout" | {
   readonly forbidImports: ReadonlyArray<string>;
+} | {
+  readonly forbidTokens: ReadonlyArray<string>;
 };
 /**
  * Options for the `process` rule.
@@ -1090,7 +1521,9 @@ interface ReferenceOptions {
   /**
    * Exact tokens exempt from the `process` rule, each starting at the
    * reference (`"process.env.MY_CONSTANT"`). `process.env.__PACKAGE_VERSION__`
-   * is always exempt: the bundler substitutes it at build time.
+   * is always exempt: the bundler substitutes it at build time. To hold such a
+   * token to named files, forbid it with a `{ forbidTokens }` rule as well (see
+   * {@link BoundaryRule}).
    */
   readonly ignoreTokens?: ReadonlyArray<string> | undefined;
 }
@@ -1117,8 +1550,8 @@ declare const Offence_base: Schema.Class<Offence, Schema.Struct<{
   /** The 1-based column, in UTF-16 code units. */
   readonly column: Schema.Number;
   /** The rule broken. */
-  readonly rule: Schema.Literals<readonly ["process", "node:process", "stdout-write", "console", "console-stdout", "forbidImports"]>;
-  /** What matched: the identifier, the call, or the import specifier. */
+  readonly rule: Schema.Literals<readonly ["process", "node:process", "stdout-write", "console", "console-stdout", "forbidImports", "forbidTokens"]>;
+  /** What matched: the identifier, the call, the import specifier, or the token. */
   readonly detail: Schema.String;
 }>, {}>;
 /**
@@ -1132,7 +1565,8 @@ export declare class Offence extends Offence_base {
 }
 /**
  * The rule an {@link Offence} names: every string {@link BoundaryRule}, plus
- * `"forbidImports"` for any `{ forbidImports }` rule. These are the keys of
+ * `"forbidImports"` for any `{ forbidImports }` rule and `"forbidTokens"` for
+ * any `{ forbidTokens }` rule. These are the keys of
  * {@link ScanOptions.allowRules}.
  *
  * @public
@@ -1178,8 +1612,10 @@ interface ScanOptions extends ReferenceOptions {
    * rule. A matching file is still checked against every other rule, and
    * each offence a glob waives is reported in `SourceScan.waived`
    * rather than dropped. The `"forbidImports"` key covers every
-   * `{ forbidImports }` rule. A file `allow` matches is exempt from every
-   * rule, so nothing in it is waived.
+   * `{ forbidImports }` rule, and the `"forbidTokens"` key every
+   * `{ forbidTokens }` rule, which is how a token is confined to named files.
+   * A file `allow` matches is exempt from every rule, so nothing in it is
+   * waived.
    */
   readonly allowRules?: { readonly [R in OffenceRule]?: ReadonlyArray<string> | undefined; } | undefined;
   /**
@@ -1221,6 +1657,10 @@ interface ScanOptions extends ReferenceOptions {
  *
  * - JSX text reads as code;
  *
+ * - a variable named `yield` or `await` in a sloppy-mode script reads as the
+ *   keyword, so a `/` after it opens a regex (module and strict code reserve
+ *   both words);
+ *
  * - `forbidImports: ["node:*"]` does not catch a bare built-in such as
  *   `"fs"` (see {@link BoundaryRule}).
  *
@@ -1250,7 +1690,22 @@ export declare class SourceBoundary {
   static readonly importSpecifiers: (text: string) => ReadonlyArray<string>;
   /** Whether `text` imports the Node built-in `module`, in either its `node:` or bare form. */
   static readonly importsNode: (text: string, module: string) => boolean;
-  /** Every place `text` breaks one of `rules`, in source order, attributed to `file`. */
+  /**
+   * Every place `text` breaks one of `rules`, in source order, attributed to `file`.
+   *
+   * @remarks
+   * A `{ forbidTokens }` entry matches its exact text in code only: comments,
+   * strings, template text and regex bodies are blanked first, so a token that
+   * itself contains a string literal never matches, and whitespace inside a
+   * token must match byte for byte. A token that starts with an identifier
+   * character does not match inside a longer identifier or after `#`, and one
+   * that ends with one does not match when an identifier character follows.
+   * A member access is still a match: `globalThis.process.env.X` contains the
+   * token `process.env.X`. A token listed twice is reported once. A token with
+   * no identifier character at either end (`"=>"`, `"?."`) has no edge guard,
+   * so it matches inside longer punctuation, and consecutive matches of it can
+   * overlap.
+   */
   static readonly check: (file: string, text: string, rules: ReadonlyArray<BoundaryRule>, options?: ReferenceOptions) => ReadonlyArray<Offence>;
   /**
    * Check every source file under `root` against `rules`.
@@ -1378,5 +1833,5 @@ export declare class WorkspaceLayering {
   static readonly checkWorkspace: (policy: LayerPolicy) => Effect.Effect<LayeringReport, WorkspaceDiscoveryFailure, WorkspaceDiscovery>;
 }
 //#endregion
-export type { BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallOptions, ReferenceOptions, ScanOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
+export type { BinCommandOptions, BinProvenance, BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallBudget, PackedInstallClosureOptions, PackedInstallOptions, ReferenceOptions, RunBinOptions, ScanOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
 //# sourceMappingURL=testing.d.ts.map