@effected/workspaces 0.31.0 → 0.32.0

package/PackedInstall.js

@@ -1,7 +1,7 @@
 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 { Config, Duration, Effect, FileSystem, Option, Path, Redacted, Result, Schema, Stream } from "effect";
 import { Yaml } from "@effected/yaml";
 import { Run } from "@effected/commands";
 import { ChildProcess } from "effect/process";
@@ -182,7 +182,9 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	* Run the installed bin `name` to completion and collect what it wrote.
 	*
 	* @remarks
-	* Spawns {@link InstalledConsumer.command} with stdin ignored: the bin
+	* Spawns {@link InstalledConsumer.command} with `options.stdin` as its
+	* input (the null device when omitted, so a bin never waits on an open
+	* pipe): 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
@@ -194,10 +196,10 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	*
 	* @param name - The bin, as named in `node_modules/.bin`.
 	* @param args - Its arguments.
-	* @param options - Extra environment, working directory and ceiling.
+	* @param options - Extra environment, working directory, ceiling and stdin.
 	*/
 	runBin(name, args = [], options = {}) {
-		return collectBin(this.command(name, args, options), this.manager, name, options.timeout);
+		return collectBin(this.command(name, args, options), this.manager, name, options);
 	}
 	/**
 	* The command that runs the CARRIER's own bin `name`, whichever package
@@ -271,7 +273,8 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	* the `node_modules/.bin` slot.
 	*
 	* @remarks
-	* Spawns {@link InstalledConsumer.carrierCommand} with stdin ignored, and
+	* Spawns {@link InstalledConsumer.carrierCommand} with `options.stdin` as
+	* its input (the null device when omitted), 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
@@ -282,11 +285,11 @@ var InstalledConsumer = class extends Schema.Class("InstalledConsumer")({
 	*
 	* @param name - The bin, as the carrier's `bin` map names it.
 	* @param args - Its arguments.
-	* @param options - Extra environment, working directory and ceiling.
+	* @param options - Extra environment, working directory, ceiling and stdin.
 	*/
 	runCarrierBin(name, args = [], options = {}) {
 		const manager = this.manager;
-		return this.carrierCommand(name, args, options).pipe(Effect.flatMap((command) => collectBin(command, manager, name, options.timeout)));
+		return this.carrierCommand(name, args, options).pipe(Effect.flatMap((command) => collectBin(command, manager, name, options)));
 	}
 };
 /** The install's scrubbed environment with the caller's entries layered on after the scrub: a deliberate CI=true must survive it. */
@@ -296,14 +299,24 @@ const layeredEnv = (consumer, options) => {
 	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
-})));
+/** A bin's stdin as `ChildProcess` takes it: absent or `""` is the null device (immediate end of input), anything else is written and closed. */
+const stdinOf = (stdin) => {
+	if (stdin === void 0 || stdin === "") return "ignore";
+	if (typeof stdin === "string") return Stream.make(new TextEncoder().encode(stdin));
+	if (stdin instanceof Uint8Array) return Stream.make(stdin);
+	return stdin;
+};
+/** Run a bin's command to completion with `options.stdin` as its input (the null device when omitted), mapping a failed spawn or an expired ceiling to `BinFailed`. */
+const collectBin = (command, manager, name, options) => {
+	const timeout = options.timeout ?? DEFAULT_BIN_TIMEOUT;
+	return Run.collect(ChildProcess.make(command.command, command.args, {
+		...command.options,
+		stdin: stdinOf(options.stdin)
+	}), { 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.
 *
@@ -594,6 +607,113 @@ var PackedInstall = class PackedInstall {
 		...options.packTimeout === void 0 ? {} : { packTimeout: options.packTimeout },
 		...extra.perConsumer === void 0 ? {} : { perConsumer: extra.perConsumer }
 	})));
+	/**
+	* Whether the pack source {@link PackedInstall.run} would read is on disk,
+	* before any package manager is spawned.
+	*
+	* @remarks
+	* Plans the closure as the run does (`PackedInstall.closure`'s planner) and
+	* checks the `package.json` of each closure package under `packFrom`
+	* (default `{ directory: "dist/prod/npm/pkg" }`), the same file whose
+	* absence makes the run fail `PackSourceMissing`. Under `packFrom: "source"`
+	* the packer builds nothing of its own, so nothing is checked and the
+	* result is ready. A package a bundler's dev build produced is no
+	* substitute: the prod output exists only after the prod build, which a
+	* test job's usual `build:dev` pre-step does not run. Pair it with
+	* {@link PackedInstall.gate} to skip locally and fail under CI.
+	*
+	* Fails as `closure` does, plus `Io` when a path cannot be inspected.
+	*
+	* @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 preflight = await Effect.runPromise(
+	*   PackedInstall.preflight({ carrier: "my-tool", closure: "auto" }).pipe(Effect.provide(Live)),
+	* );
+	* console.log(preflight.ready, preflight.missing);
+	* ```
+	*
+	* @param options - The run's carrier, closure, overrides and pack source.
+	*/
+	static preflight = Effect.fn("PackedInstall.preflight")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const plan = yield* planClosure(options.carrier, options);
+		const source = options.packFrom ?? DEFAULT_PACK_FROM;
+		if (source === "source") return {
+			ready: true,
+			missing: []
+		};
+		const missing = [];
+		for (const pkg of plan.closure) {
+			const manifest = path.join(pkg.path, source.directory, "package.json");
+			if (!(yield* fs.exists(manifest).pipe(Effect.mapError((cause) => failure("Io", `could not inspect ${manifest}`, { cause }))))) missing.push(manifest);
+		}
+		return {
+			ready: missing.length === 0,
+			missing
+		};
+	});
+	/**
+	* Turns a {@link PackedInstallPreflight} into the suite's decision: run,
+	* skip locally, or fail under CI.
+	*
+	* @remarks
+	* `CI` is read through `Config`, so the ambient `ConfigProvider` decides —
+	* the process environment at a test file's top level, and whatever a test
+	* provides in a test; nothing here reads `process`. `CI` counts as set when
+	* it is present and not `""`, `"0"` or `"false"` (case-insensitive), and an
+	* unreadable `CI` counts as unset. Ready is always `"run"`;
+	* missing is `"skip"` off CI and `"fail"` on it, so a CI job that never ran
+	* the prod build cannot pass by silently skipping the proof. The message
+	* names every missing path. The test job must run the prod build
+	* (`build:prod` for a `@savvy-web/bundler` package) before the packed-install
+	* tests: a dev build leaves `dist/prod` absent.
+	*
+	* @example
+	* ```ts
+	* import { assert, describe, it } from "@effect/vitest";
+	* import { PackedInstall } from "@effected/workspaces/testing";
+	* import { Effect } from "effect";
+	*
+	* declare const preflight: { readonly ready: boolean; readonly missing: ReadonlyArray<string> };
+	* const gate = Effect.runSync(PackedInstall.gate(preflight));
+	*
+	* describe.runIf(gate.action === "run")("packed install", () => {
+	*   it("installs", () => {});
+	* });
+	* describe.runIf(gate.action === "fail")("packed install prod build", () => {
+	*   it("exists", () => assert.fail(gate.message));
+	* });
+	* ```
+	*
+	* @param preflight - What {@link PackedInstall.preflight} answered.
+	*/
+	static gate = (preflight) => Effect.gen(function* () {
+		if (preflight.ready) return {
+			action: "run",
+			message: ""
+		};
+		const ci = yield* Config.option(Config.String("CI")).pipe(Effect.orElseSucceed(() => Option.none()));
+		const underCi = Option.isSome(ci) && ![
+			"",
+			"0",
+			"false"
+		].includes(ci.value.toLowerCase());
+		const message = `the pack source is missing: ${preflight.missing.join(", ")}; run the prod build (build:prod) before the packed-install tests`;
+		return underCi ? {
+			action: "fail",
+			message: `${message}; it must not be skipped under CI`
+		} : {
+			action: "skip",
+			message
+		};
+	});
 	/** Pack, then install under every available manager. */
 	static run = Effect.fn("PackedInstall.run")(function* (options) {
 		const fs = yield* FileSystem.FileSystem;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.31.0",
+	"version": "0.32.0",
 	"private": false,
 	"description": "Monorepo workspace tooling as Effect services — root discovery, package enumeration, the dependency graph, package-manager detection, pnpm catalog resolution, lockfile IO and git-based change detection.",
 	"keywords": [
@@ -54,13 +54,13 @@
 		"@effected/commands": "^0.11.0",
 		"@effected/git": "^0.20.0",
 		"@effected/glob": "^0.10.0",
-		"@effected/jsonc": "^0.15.0",
+		"@effected/jsonc": "^0.15.1",
 		"@effected/lockfiles": "^0.15.0",
 		"@effected/npm": "^0.20.0",
 		"@effected/package-json": "^0.20.0",
 		"@effected/semver": "^0.11.0",
 		"@effected/walker": "^0.15.0",
-		"@effected/yaml": "^0.19.0",
+		"@effected/yaml": "^0.19.1",
 		"@pnpm/catalogs.config": "^1100.0.5",
 		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
 		"@pnpm/catalogs.resolver": "^1100.0.0",

package/testing.d.ts

@@ -1,5 +1,5 @@
 import { DependencyField, WorkspaceResolver } from "@effected/npm";
-import { Context, Duration, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Context, Duration, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema, Stream } from "effect";
 import { GlobPattern } from "@effected/glob";
 import { WorkspaceManifest } from "@effected/lockfiles";
 import { Package } from "@effected/package-json";
@@ -1030,7 +1030,12 @@ interface PackedInstallOptions extends PackedInstallClosureOptions {
    * `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. */
+  /**
+   * The environment for every spawn: pass `process.env` from the test file, the edge that supplies the host
+   * environment. It is taken whole because the parent manager's context is stripped by prefix (`npm_*`,
+   * `pnpm_config_*`, `yarn_*`), which `Config`, reading keys by name, cannot enumerate; read single keys such as
+   * `CI` through `Config`.
+   */
   readonly env: Readonly<Record<string, string | undefined>>;
   /**
    * Extra consumer dependencies, name to range or `file:` tarball spec.
@@ -1107,6 +1112,22 @@ interface BinCommandOptions {
 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;
+  /**
+   * What to write to the bin's stdin, which is then closed: a string (UTF-8
+   * encoded), bytes, or a byte stream for input that must arrive in pieces,
+   * such as a framed LSP session.
+   *
+   * @remarks
+   * Omitted or `""`, the bin's stdin is the null device: it reads end of
+   * input immediately, never an open pipe, so a bin that reads stdin exits
+   * instead of hanging until the ceiling. Empty bytes and an empty stream
+   * are sent as given: the bin sees an ended, empty input. A bin that answers
+   * only after the input is complete is driven by this option; one that must
+   * be interleaved with its output is driven through
+   * {@link InstalledConsumer.command} or {@link InstalledConsumer.carrierCommand},
+   * which leave stdin open.
+   */
+  readonly stdin?: string | Uint8Array | Stream.Stream<Uint8Array, PlatformError.PlatformError> | undefined;
 }
 /**
  * Which installed package a `node_modules/.bin` symlink resolves into.
@@ -1209,7 +1230,9 @@ export declare class InstalledConsumer extends InstalledConsumer_base {
    * Run the installed bin `name` to completion and collect what it wrote.
    *
    * @remarks
-   * Spawns {@link InstalledConsumer.command} with stdin ignored: the bin
+   * Spawns {@link InstalledConsumer.command} with `options.stdin` as its
+   * input (the null device when omitted, so a bin never waits on an open
+   * pipe): 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
@@ -1221,7 +1244,7 @@ export declare class InstalledConsumer extends InstalledConsumer_base {
    *
    * @param name - The bin, as named in `node_modules/.bin`.
    * @param args - Its arguments.
-   * @param options - Extra environment, working directory and ceiling.
+   * @param options - Extra environment, working directory, ceiling and stdin.
    */
   runBin(name: string, args?: ReadonlyArray<string>, options?: RunBinOptions): Effect.Effect<CommandOutput, PackedInstallError, ChildProcessSpawner.ChildProcessSpawner>;
   /**
@@ -1261,7 +1284,8 @@ export declare class InstalledConsumer extends InstalledConsumer_base {
    * the `node_modules/.bin` slot.
    *
    * @remarks
-   * Spawns {@link InstalledConsumer.carrierCommand} with stdin ignored, and
+   * Spawns {@link InstalledConsumer.carrierCommand} with `options.stdin` as
+   * its input (the null device when omitted), 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
@@ -1272,7 +1296,7 @@ export declare class InstalledConsumer extends InstalledConsumer_base {
    *
    * @param name - The bin, as the carrier's `bin` map names it.
    * @param args - Its arguments.
-   * @param options - Extra environment, working directory and ceiling.
+   * @param options - Extra environment, working directory, ceiling and stdin.
    */
   runCarrierBin(name: string, args?: ReadonlyArray<string>, options?: RunBinOptions): Effect.Effect<CommandOutput, PackedInstallError, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
 }
@@ -1323,6 +1347,43 @@ interface PackedInstallBudget {
    */
   readonly perConsumer?: Duration.Input | undefined;
 }
+/**
+ * Options for {@link PackedInstall.preflight}: the run's closure and pack
+ * source, so the check answers for exactly the run those options describe.
+ *
+ * @public
+ */
+interface PackedInstallPreflightOptions extends PackedInstallClosureOptions {
+  /** The carrier, as the run's `carrier`. */
+  readonly carrier: string;
+  /** Where the run packs from; defaults as the run's does, to `{ directory: "dist/prod/npm/pkg" }`. */
+  readonly packFrom?: PackSource | undefined;
+}
+/**
+ * Whether the pack source a run needs is on disk.
+ *
+ * @public
+ */
+interface PackedInstallPreflight {
+  /** `true` when every package the run packs has its pack source in place. */
+  readonly ready: boolean;
+  /** The absolute `package.json` paths that do not exist, in pack order; empty exactly when `ready`. */
+  readonly missing: ReadonlyArray<string>;
+}
+/**
+ * What a test suite should do about a {@link PackedInstallPreflight}.
+ *
+ * @public
+ */
+interface PackedInstallGate {
+  /**
+   * `"run"` when the pack source is there; `"skip"` when it is missing and
+   * the run is not under CI; `"fail"` when it is missing under CI.
+   */
+  readonly action: "run" | "skip" | "fail";
+  /** Why, naming the missing paths and the build to run. Empty when `action` is `"run"`. */
+  readonly message: string;
+}
 /**
  * Prove a carrier's bins reach a consumer that is not part of the workspace,
  * once per available package manager.
@@ -1490,6 +1551,76 @@ export declare class PackedInstall {
   static readonly timeoutBudgetFor: (options: PackedInstallOptions, extra?: {
     readonly perConsumer?: Duration.Input | undefined;
   }) => Effect.Effect<Duration.Duration, PackedInstallError, WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * Whether the pack source {@link PackedInstall.run} would read is on disk,
+   * before any package manager is spawned.
+   *
+   * @remarks
+   * Plans the closure as the run does (`PackedInstall.closure`'s planner) and
+   * checks the `package.json` of each closure package under `packFrom`
+   * (default `{ directory: "dist/prod/npm/pkg" }`), the same file whose
+   * absence makes the run fail `PackSourceMissing`. Under `packFrom: "source"`
+   * the packer builds nothing of its own, so nothing is checked and the
+   * result is ready. A package a bundler's dev build produced is no
+   * substitute: the prod output exists only after the prod build, which a
+   * test job's usual `build:dev` pre-step does not run. Pair it with
+   * {@link PackedInstall.gate} to skip locally and fail under CI.
+   *
+   * Fails as `closure` does, plus `Io` when a path cannot be inspected.
+   *
+   * @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 preflight = await Effect.runPromise(
+   *   PackedInstall.preflight({ carrier: "my-tool", closure: "auto" }).pipe(Effect.provide(Live)),
+   * );
+   * console.log(preflight.ready, preflight.missing);
+   * ```
+   *
+   * @param options - The run's carrier, closure, overrides and pack source.
+   */
+  static readonly preflight: (options: PackedInstallPreflightOptions) => Effect.Effect<PackedInstallPreflight, PackedInstallError, WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * Turns a {@link PackedInstallPreflight} into the suite's decision: run,
+   * skip locally, or fail under CI.
+   *
+   * @remarks
+   * `CI` is read through `Config`, so the ambient `ConfigProvider` decides —
+   * the process environment at a test file's top level, and whatever a test
+   * provides in a test; nothing here reads `process`. `CI` counts as set when
+   * it is present and not `""`, `"0"` or `"false"` (case-insensitive), and an
+   * unreadable `CI` counts as unset. Ready is always `"run"`;
+   * missing is `"skip"` off CI and `"fail"` on it, so a CI job that never ran
+   * the prod build cannot pass by silently skipping the proof. The message
+   * names every missing path. The test job must run the prod build
+   * (`build:prod` for a `@savvy-web/bundler` package) before the packed-install
+   * tests: a dev build leaves `dist/prod` absent.
+   *
+   * @example
+   * ```ts
+   * import { assert, describe, it } from "@effect/vitest";
+   * import { PackedInstall } from "@effected/workspaces/testing";
+   * import { Effect } from "effect";
+   *
+   * declare const preflight: { readonly ready: boolean; readonly missing: ReadonlyArray<string> };
+   * const gate = Effect.runSync(PackedInstall.gate(preflight));
+   *
+   * describe.runIf(gate.action === "run")("packed install", () => {
+   *   it("installs", () => {});
+   * });
+   * describe.runIf(gate.action === "fail")("packed install prod build", () => {
+   *   it("exists", () => assert.fail(gate.message));
+   * });
+   * ```
+   *
+   * @param preflight - What {@link PackedInstall.preflight} answered.
+   */
+  static readonly gate: (preflight: PackedInstallPreflight) => Effect.Effect<PackedInstallGate>;
   /** Pack, then install under every available manager. */
   static readonly run: (options: PackedInstallOptions) => Effect.Effect<PackedInstallResult, PackedInstallError, ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path | import("effect/Scope").Scope | WorkspaceDiscovery>;
 }
@@ -1861,5 +1992,5 @@ export declare class WorkspaceLayering {
   static readonly checkWorkspace: (policy: LayerPolicy) => Effect.Effect<LayeringReport, WorkspaceDiscoveryFailure, WorkspaceDiscovery>;
 }
 //#endregion
-export type { BinCommandOptions, BinProvenance, BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallBudget, PackedInstallClosureOptions, PackedInstallOptions, ReferenceOptions, RunBinOptions, ScanOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
+export type { BinCommandOptions, BinProvenance, BoundaryFixture, BoundaryRule, DependencyDiff, FindWorkspaceRootOptions, LayeringGraph, OffenceRule, PackSource, PackedInstallBudget, PackedInstallClosureOptions, PackedInstallGate, PackedInstallOptions, PackedInstallPreflight, PackedInstallPreflightOptions, ReferenceOptions, RunBinOptions, ScanOptions, WorkspaceDiscoveryFailure, WorkspaceDiscoveryOptions, WorkspaceDiscoveryShape, WorkspaceLookupFailure, WorkspaceRootShape };
 //# sourceMappingURL=testing.d.ts.map