@effected/workspaces 0.25.0 → 0.26.0

package/LayerPolicy.js

@@ -0,0 +1,133 @@
+import { ALL_DEPENDENCY_FIELDS } from "./internal/dependencyFields.js";
+import { Effect, FileSystem, Result, Schema } from "effect";
+import { GlobSet } from "@effected/glob";
+import { DependencyField } from "@effected/npm";
+
+//#region src/LayerPolicy.ts
+const REQUIRED_EDGE = /^\S+ -> \S+$/;
+/** `input` without `keys`, when it is a plain object; anything else passes through for the schema to reject. */
+const withoutKeys = (input, keys) => {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) return input;
+	return Object.fromEntries(Object.entries(input).filter(([key]) => !keys.includes(key)));
+};
+/**
+* Raised when a layer policy cannot be read, parsed or decoded.
+*
+* @public
+*/
+var LayerPolicyError = class extends Schema.TaggedError()("LayerPolicyError", {
+	/** `read`: the file could not be read. `json`: it is not JSON. `decode`: it is not a `LayerPolicy`. */
+	reason: Schema.Literals([
+		"read",
+		"json",
+		"decode"
+	]),
+	/** The file, when the policy came from one. */
+	path: Schema.optionalKey(Schema.String),
+	/** The originating failure. */
+	cause: Schema.Defect()
+}) {
+	/** Renders the failure kind and the file into one line. */
+	get message() {
+		const at = this.path === void 0 ? "" : ` at ${this.path}`;
+		switch (this.reason) {
+			case "read": return `Could not read the layer policy${at}`;
+			case "json": return `The layer policy${at} is not valid JSON`;
+			default: return `The layer policy${at} does not match the LayerPolicy shape${this.cause instanceof Error && this.cause.message !== "" ? `: ${this.cause.message}` : ""}`;
+		}
+	}
+};
+/**
+* A committed dependency-layering policy (`layers.json`).
+*
+* @remarks
+* `layers` is top-down: an edge may only point from a layer to one BELOW it
+* (a higher index), or into `tooling`. `tooling` packages may depend on each
+* other but never reach a layer. `unconstrained` holds globs (through
+* `@effected/glob`) for packages whose own edges are not checked (a test
+* harness, the private root). `fields` narrows which dependency maps count,
+* defaulting to all four. `requiredEdges` (`"a -> b"`) are edges that must
+* exist in a checked field: the non-vacuity guard against a discovery that
+* quietly drops real edges.
+*
+* Every entry matches a package's `name`, never its `relativePath`: `layers`
+* and `tooling` list exact names, and `unconstrained` globs match names. A
+* private root named `my-monorepo` at `relativePath` `"."` is classified as
+* `"my-monorepo"`; an entry of `"."` or `"packages/*"` classifies nothing.
+*
+* Decoding is strict: a key the policy does not model fails `decode`, and the
+* message names every such key. A typo on an optional key would otherwise be
+* silently dropped: `requiredEdge` would remove the non-vacuity guard and
+* leave the report green. `$schema` is always accepted. A file that carries
+* keys of its own, such as systems' `harness`, passes them in `allowKeys`.
+*
+* @example
+* ```ts
+* import { NodeServices } from "@effect/platform-node";
+* import { LayerPolicy } from "@effected/workspaces/testing";
+* import { Effect } from "effect";
+*
+* const policy = LayerPolicy.load("/repo/layers.json").pipe(Effect.provide(NodeServices.layer));
+* ```
+*
+* @public
+*/
+var LayerPolicy = class LayerPolicy extends Schema.Class("LayerPolicy")({
+	/** Exact package names (never relative paths) per layer, top layer first. */
+	layers: Schema.Array(Schema.Array(Schema.String)),
+	/** Exact package names (never relative paths) any layer may depend on that never depend on a layer. */
+	tooling: Schema.Array(Schema.String),
+	/** Globs matched against package names (never relative paths) for packages whose own edges are not checked. */
+	unconstrained: Schema.Array(Schema.String).check(Schema.makeFilter((patterns) => Result.isSuccess(GlobSet.compileResult(patterns)), { title: "compilable glob patterns" })),
+	/** The dependency maps to check. Absent means all four. */
+	fields: Schema.optionalKey(Schema.Array(DependencyField)),
+	/** Edges that must exist, written `"a -> b"`. */
+	requiredEdges: Schema.optionalKey(Schema.Array(Schema.String.check(Schema.isPattern(REQUIRED_EDGE))))
+}) {
+	/** The dependency maps a check reads: `fields`, or all four. */
+	get effectiveFields() {
+		return this.fields ?? ALL_DEPENDENCY_FIELDS;
+	}
+	/**
+	* Decode a policy from a parsed JSON value.
+	*
+	* @remarks
+	* Every key the policy does not model fails, except `$schema` and the
+	* keys named in `options.allowKeys`, which are dropped before decoding.
+	* `options.path` names the file in the error.
+	*/
+	static decode = Effect.fn("LayerPolicy.decode")((input, options) => {
+		const path = options?.path;
+		return Schema.decodeUnknownEffect(LayerPolicy)(withoutKeys(input, ["$schema", ...options?.allowKeys ?? []]), {
+			onExcessProperty: "error",
+			errors: "all"
+		}).pipe(Effect.mapError((cause) => new LayerPolicyError({
+			reason: "decode",
+			cause,
+			...path === void 0 ? {} : { path }
+		})));
+	});
+	/** Read, parse and decode the policy file at `path`; `options.allowKeys` is passed to `decode`. */
+	static load = Effect.fn("LayerPolicy.load")(function* (path, options) {
+		const text = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new LayerPolicyError({
+			reason: "read",
+			path,
+			cause
+		})));
+		const json = yield* Effect.try({
+			try: () => JSON.parse(text),
+			catch: (cause) => new LayerPolicyError({
+				reason: "json",
+				path,
+				cause
+			})
+		});
+		return yield* LayerPolicy.decode(json, {
+			path,
+			allowKeys: options?.allowKeys
+		});
+	});
+};
+
+//#endregion
+export { LayerPolicy, LayerPolicyError };

package/PackedInstall.js

@@ -0,0 +1,282 @@
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { PackageManagerName } from "./PackageManagerName.js";
+import { closureOf, consumerFiles, installArgs, scrubEnv, unresolvedSpecifiers, versionOf } from "./internal/packedInstallPlan.js";
+import { Duration, Effect, FileSystem, Option, Path, Result, Schema } from "effect";
+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",
+		"InstallFailed",
+		"MissingBin",
+		"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())
+}) {};
+/**
+* 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 installed bin `name`, in `node_modules/.bin`. POSIX: `PackedInstall` runs only there. */
+	binPath(name) {
+		return `${this.directory}/node_modules/.bin/${name}`;
+	}
+};
+/**
+* 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)
+}) {};
+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";
+/** 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
+});
+/**
+* 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.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.
+*
+* @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));
+*
+* // 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,
+*   });
+*   const env = PackedInstall.scrubEnv(process.env);
+*   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());
+*   }
+* }).pipe(Effect.scoped, Effect.provide(Live));
+* ```
+*
+* @public
+*/
+var PackedInstall = class {
+	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;
+	/** 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: "30 seconds" }).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 packages = yield* (yield* WorkspaceDiscovery).listPackages().pipe(Effect.mapError((cause) => failure("Discovery", "workspace discovery failed", { cause })));
+		const closure = closureOf(packages, options.carrier, options.closure);
+		if (Result.isFailure(closure)) return yield* failure("UnknownPackage", `${closure.failure} is not a package of this workspace`, { package: closure.failure });
+		const source = options.packFrom ?? DEFAULT_PACK_FROM;
+		const pack = (pkg, destination) => Effect.gen(function* () {
+			yield* fs.makeDirectory(destination, { recursive: true }).pipe(Effect.mapError(io(`could not create ${destination}`)));
+			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 packer = source === "source" ? "pnpm" : "npm";
+			const args = source === "source" ? [
+				"pack",
+				"--pack-destination",
+				destination,
+				"--config.ignore-scripts=true"
+			] : [
+				"pack",
+				"--ignore-scripts",
+				"--pack-destination",
+				destination
+			];
+			const output = yield* Run.collect(command(packer, args, cwd), { timeout: "2 minutes" }).pipe(Effect.mapError((cause) => failure("PackFailed", `${packer} pack could not run for ${pkg.name}`, {
+				package: pkg.name,
+				cause
+			})));
+			if (!output.succeeded) {
+				const notInstalled = source === "source" && `${output.stdout}${output.stderr}`.includes(WORKSPACE_PROTOCOL_NOT_INSTALLED);
+				return yield* failure("PackFailed", notInstalled ? `pnpm pack could not rewrite the workspace: specifiers of ${pkg.name} because the workspace is not installed; run pnpm install in the workspace first` : `${packer} pack exited ${output.exitCode} for ${pkg.name}`, {
+					package: pkg.name,
+					output: tail(`${output.stdout}\n${output.stderr}`)
+				});
+			}
+			const found = (yield* fs.readDirectory(destination).pipe(Effect.mapError(io(`could not list ${destination}`)))).filter((name) => name.endsWith(".tgz"));
+			const [only] = found;
+			if (only === void 0 || found.length !== 1) return yield* failure("PackFailed", `expected exactly one tarball for ${pkg.name} in ${destination}, found ${found.length}`, { package: pkg.name });
+			const tarball = path.join(destination, only);
+			const manifest = yield* Run.text(command("tar", [
+				"-xzOf",
+				tarball,
+				"package/package.json"
+			], destination), { timeout: "30 seconds" }).pipe(Effect.mapError((cause) => failure("PackFailed", `could not read package/package.json out of ${tarball}`, {
+				package: pkg.name,
+				cause
+			})));
+			const unresolved = unresolvedSpecifiers(manifest);
+			if (Result.isFailure(unresolved)) return yield* failure("PackFailed", `the packed package.json of ${pkg.name} is not a JSON object`, {
+				package: pkg.name,
+				cause: unresolved.failure
+			});
+			if (unresolved.success.length > 0) return yield* failure("UnresolvedProtocol", `${pkg.name}'s packed manifest still carries ${unresolved.success.join(", ")}, which no consumer outside the workspace can resolve; pack from "source" so pnpm rewrites workspace: and catalog:, or fix the build`, { package: pkg.name });
+			return tarball;
+		});
+		const packed = [];
+		for (const [index, pkg] of closure.success.entries()) packed.push({
+			name: pkg.name,
+			tarball: yield* pack(pkg, path.join(scratch, "tarballs", String(index)))
+		});
+		const [carrier, ...rest] = packed;
+		if (carrier === void 0) return yield* failure("UnknownPackage", `${options.carrier} was not packed`, { package: options.carrier });
+		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
+			});
+			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]))
+		});
+	});
+};
+
+//#endregion
+export { InstalledConsumer, PackedInstall, PackedInstallError, PackedInstallResult };

package/README.md

@@ -75,6 +75,22 @@ Effect.runPromise(program.pipe(Effect.provide(WorkspacesLayer))).then(console.lo
 `toMermaid()` renders the same graph for a job summary, an issue or a design doc. It is total, deterministic (nodes and edges both in sorted order) and safe for scoped names, which appear only inside quoted labels:
 
 ```ts
+import { DependencyGraph, WorkspacePackage } from "@effected/workspaces";
+
+const member = (name: string, dependencies: Record<string, string> = {}) =>
+  WorkspacePackage.make({
+    name,
+    version: "1.0.0",
+    path: `/repo/packages/${name.slice(6)}`,
+    packageJsonPath: `/repo/packages/${name.slice(6)}/package.json`,
+    relativePath: `packages/${name.slice(6)}`,
+    workspaceRoot: "/repo",
+    dependencies,
+  });
+
+const graph = DependencyGraph.make({
+  packages: [member("@acme/app", { "@acme/utils": "workspace:^" }), member("@acme/utils")],
+});
 console.log(graph.toMermaid());
 // flowchart TD
 //   0["@acme/app"]
@@ -239,6 +255,183 @@ For a test fake, `@effected/memfs`' `MemoryFileSystem.syncFileSystem(volume)` sa
 
 Windows correctness is therefore the operations you pass, and nothing else. Both entry points drive one traversal state machine (the same dequeue order, depth rule, visit budget and `node_modules` prune), so the sync and Effect surfaces can never disagree about what a pattern means. The one deliberate difference is at a bound: the Effect enumerator fails typed, the sync one truncates. Prefer the Effect API everywhere you can run one.
 
+## Repo-shape checks (`@effected/workspaces/testing`)
+
+A monorepo's shape drifts in ways no unit test sees: a package that should stay platform-free starts reading `process`, a low-level package grows an edge up into an application, or a bin resolves fine inside the workspace and is missing once installed from its tarball. The `@effected/workspaces/testing` subpath holds three checks you run from your own test suite to catch each one. The main entry never re-exports it, so a consumer of `.` never loads a scanner or package-manager orchestration it does not use.
+
+Every check refuses to pass vacuously, so every example below pairs "nothing wrong" with "something was checked".
+
+### Layering
+
+`WorkspaceLayering` holds the discovered package graph to a committed `layers.json`. `layers` is top-down: a package may depend only on a layer below its own, or on `tooling`. `unconstrained` globs name packages whose own edges are not checked, such as the private root, which must be classified like any other package. Every entry matches a package's `name`, never its `relativePath`: `layers` and `tooling` list exact names, and `unconstrained` globs match names. So a private root named `my-monorepo` at `relativePath` `.` is classified as `"my-monorepo"`, and an entry of `"."` or `"packages/*"` classifies nothing. `fields` picks the dependency maps that count, and `requiredEdges` lists edges that must exist, so a discovery that silently drops edges fails. Decoding is strict: any other key fails `LayerPolicyError` naming the key, so a typo such as `requiredEdge` cannot silently drop that guard. `$schema` is always accepted, and keys a policy file carries for its own use go in `LayerPolicy.load(path, { allowKeys: [...] })`.
+
+```json
+{
+  "layers": [["my-tool"], ["my-tool-cli", "my-tool-mcp"], ["my-tool-engine"]],
+  "tooling": [],
+  "unconstrained": ["my-monorepo"],
+  "fields": ["dependencies", "peerDependencies", "optionalDependencies"],
+  "requiredEdges": ["my-tool-mcp -> my-tool-engine"]
+}
+```
+
+```ts
+// __test__/layering.test.ts, one level below the workspace root
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NodeServices } from "@effect/platform-node";
+import { assert, describe, layer } from "@effect/vitest";
+import { Workspaces } from "@effected/workspaces";
+import { LayerPolicy, WorkspaceLayering } from "@effected/workspaces/testing";
+import { Effect, Layer } from "effect";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const Live = Workspaces.layer({ cwd: ROOT }).pipe(Layer.provideMerge(NodeServices.layer));
+
+describe("package layering", () => {
+  layer(Live)((it) => {
+    it.effect("the workspace honours layers.json, over real edges", () =>
+      Effect.gen(function* () {
+        const policy = yield* LayerPolicy.load(join(ROOT, "layers.json"));
+        const report = yield* WorkspaceLayering.checkWorkspace(policy);
+        assert.deepStrictEqual(report.violations, []);
+        assert.isAbove(report.edgeCount, 0, "the check read real edges");
+      }),
+    );
+  });
+});
+```
+
+An edge is drawn wherever a dependency's name is a workspace package, whatever its specifier, and once per declaring field. A cycle closed only by a devDependency is therefore invisible to a policy that checks runtime fields only: pin acyclicity across every field separately, with `DependencyGraph.make({ packages }).hasCycle`.
+
+### Source boundaries
+
+`SourceBoundary.scan` walks a source tree and reports every read of the global `process`, forbidden import, `stdout.write` or console write. It lexes each file first, so the word `process` in a comment, a string, template text or a regex is never a read, and a `/*` inside a string never hides the code after it. Assert `verifyFixtures()` beside your scan: it proves the scanner still flags and spares what its shipped fixtures say.
+
+```ts
+// __test__/boundary.test.ts, one level below the package root
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NodeServices } from "@effect/platform-node";
+import { assert, describe, layer } from "@effect/vitest";
+import { SourceBoundary } from "@effected/workspaces/testing";
+import { Effect } from "effect";
+
+const SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "src");
+
+describe("source boundary", () => {
+  layer(NodeServices.layer)((it) => {
+    it.effect("the scanner still flags and spares what its fixtures say", () =>
+      Effect.sync(() => assert.deepStrictEqual(SourceBoundary.verifyFixtures(), [])),
+    );
+
+    it.effect("no module reads process, writes to the console, or imports node: or a platform package", () =>
+      Effect.gen(function* () {
+        const scan = yield* SourceBoundary.scan({
+          root: SRC,
+          rules: ["process", "node:process", "console", { forbidImports: ["node:*", "@effect/platform*"] }],
+        });
+        assert.isNotEmpty(scan.files, "the scan read the tree");
+        assert.deepStrictEqual(scan.violations, []);
+      }),
+    );
+  });
+});
+```
+
+| Rule | Flags |
+| --- | --- |
+| `"process"` | a read of the global `process`; `process.env.__PACKAGE_VERSION__` is exempt |
+| `"node:process"` | an import of `node:process` or `process` |
+| `"stdout-write"` | a `stdout.write`, or a `stdout.end` passing a final chunk, on anything named `stdout`; a renamed receiver is left to `"process"` |
+| `"console"` | any reference to the global `console` |
+| `"console-stdout"` | a reference to the global `console`, except a member access to a method Node writes to stderr: `error`, `warn`, `trace`, `assert`. A bare or aliased reference (`const c = console`, `f(console)`, `console[m]`) is flagged, since it can reach `log` |
+| `{ forbidImports }` | an import equal to an entry, a subpath of one, or starting with an entry's text before a trailing `*` |
+
+Neither console rule flags core's `Console` service. `"console-stdout"` suits a stdio server that must keep stdout for its protocol but may log to stderr.
+
+`allow` globs exempt a file from every rule, and the file is listed in `scan.allowed`. To exempt a file from one rule only, use `allowRules`, keyed by the rule (`"forbidImports"` covers every `{ forbidImports }` rule). The file is still checked against every other rule, and each offence a per-rule glob waives lands in `scan.waived` rather than disappearing, so a stale or over-broad waiver fails an assertion:
+
+```ts
+const scan = yield* SourceBoundary.scan({
+  root: SRC,
+  rules: ["process", "stdout-write"],
+  // main.ts hands process.stdout to a transport, but must never write to it itself.
+  allowRules: { process: ["main.ts"] },
+});
+assert.deepStrictEqual(scan.violations, []);
+assert.deepStrictEqual([...new Set(scan.waived.map((offence) => offence.file))], ["main.ts"]);
+```
+
+Both kinds of glob compile with `@effected/glob` and match the scan's relative, `/`-separated path; an uncompilable one fails the scan with `GlobPatternError`.
+
+The scanner is a lexer, not a type checker. Its known limits:
+
+- There is no scope analysis, so any local binding named `process` or `console` is flagged like the global: a parameter (`(process: Handle) => process.kill()`), a variable, a label, or an unannotated class field (`process = 1`). An annotated class field (`process: T`) reads as a type member and is spared. Prefer renaming the binding; failing that, waive that one rule for the file with `allowRules` and assert `scan.waived` names exactly it.
+- `globalThis["process"]` and `const { process: p } = globalThis` are not seen.
+- A regex literal directly after a block-closing `}` reads as a division.
+- JSX text reads as code, which is why `.tsx` and `.jsx` are not scanned by default.
+- `forbidImports: ["node:*"]` matches only the `node:` spelling, not a bare `"fs"`. To forbid both, spread Node's list in the test file: `{ forbidImports: ["node:*", ...builtinModules] }`, with `builtinModules` from `node:module`. That also forbids npm packages named like a built-in (`events`, `buffer`).
+
+### Packed install
+
+`PackedInstall.run` packs a carrier and every workspace package it needs, then installs the carrier into a fresh project outside the workspace under each package manager that answers `--version`, and checks every expected bin is linked and executable. It carries the traps each manager sets: the parent run's `npm_*` and `pnpm_config_*` context is scrubbed, pnpm's overrides go in `pnpm-workspace.yaml`, Yarn Berry gets the `node-modules` linker, `packageManager` is pinned to the probed version, and lifecycle scripts are skipped. By default it packs each package's built `dist/prod/npm/pkg`, the artifact a release publishes; build first.
+
+It does not run the bins; the test does, inside the same scope, because the scratch directory is removed when the scope closes. For an MCP server bin, `McpProbe` from `@effected/mcp/testing` is the proof:
+
+```ts
+// __test__/e2e/packed-install.e2e.test.ts, two levels below the workspace root
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NodeServices } from "@effect/platform-node";
+import { assert, describe, layer } from "@effect/vitest";
+import { McpProbe } from "@effected/mcp/testing";
+import { Workspaces } from "@effected/workspaces";
+import { PackedInstall } from "@effected/workspaces/testing";
+import { Effect, Layer } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const Live = Workspaces.layer({ cwd: ROOT }).pipe(Layer.provideMerge(NodeServices.layer));
+
+describe("packed install", () => {
+  // The real clock: installs and the probe are real processes.
+  layer(Live, { excludeTestServices: true })((it) => {
+    it.effect(
+      "my-tool's MCP bin boots from a packed install under every available manager",
+      () =>
+        Effect.gen(function* () {
+          const result = yield* PackedInstall.run({
+            carrier: "my-tool",
+            closure: "auto",
+            managers: ["npm", "pnpm", "yarn", "bun"],
+            bins: ["my-tool-mcp"],
+            env: process.env,
+            installTimeout: "2 minutes",
+          });
+          assert.isAbove(result.consumers.length, 0, `nothing installed; unavailable: ${result.unavailable.join(", ")}`);
+          const env = PackedInstall.scrubEnv(process.env);
+          for (const consumer of result.consumers) {
+            const bin = ChildProcess.make(consumer.binPath("my-tool-mcp"), [], {
+              cwd: consumer.directory,
+              env,
+              extendEnv: false,
+            });
+            const { response, stderr, exitCode } = yield* McpProbe.initialize(bin).pipe(Effect.timeout("30 seconds"));
+            assert.isUndefined(response.error, `${consumer.manager}: initialize was refused`);
+            assert.strictEqual(stderr, "", `${consumer.manager}: stderr`);
+            assert.strictEqual(exitCode, 0, `${consumer.manager}: exit code`);
+          }
+          // The installs run one after another: the guard covers 4 managers x installTimeout, plus pack and probes.
+        }).pipe(Effect.timeout("12 minutes")),
+      780_000,
+    );
+  });
+});
+```
+
+Pass `process.env` in: nothing in the subpath reads `process` itself. Run the bins under `PackedInstall.scrubEnv(process.env)`, the same environment the installs ran under. A requested manager that is not installed lands in `result.unavailable`; pass `require: "all"` to make that a failure instead. Declare in `consumerDependencies` every package the consumer's own code imports besides the carrier: pnpm links only declared dependencies at a project's top level. An entry that names a packed package is written as its `file:` tarball whatever spec you pass, so any range will do; npm fails `EOVERRIDE` when a direct spec differs from its override. The installs run one after another, so an outer `Effect.timeout` must be at least the number of managers times `installTimeout` (four minutes by default), plus the pack and the probes; a tighter guard fires first, as a `TimeoutError` that names no manager. `PackedInstall` is POSIX-only and fails `UnsupportedPlatform` elsewhere.
+
 ## Error handling
 
 Every failure is a `Schema.TaggedError` with structured fields you can branch on, not a prose string:
@@ -278,6 +471,7 @@ const TestDiscovery = WorkspaceDiscovery.layerTest({
         path: "/repo/packages/utils",
         packageJsonPath: "/repo/packages/utils/package.json",
         relativePath: "packages/utils",
+        workspaceRoot: "/repo",
       }),
     ]),
 });
@@ -305,6 +499,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `ReleaseTag` / `TrackingTag` — release-tag formatting (`ReleaseTag.single` / `.scoped`, strict SemVer by default with no `v` prefix) and the floating major/minor alias derivation GitHub Actions-style consumers expect (`v1`, `v1.2`), plus `classifyTag` to tell a release tag from a tracking alias.
 - `VersioningStrategy` — classify a workspace as `single`, `fixed-group` or `independent` from package names and fixed groups, or detect it live against `PublishabilityDetector`, and produce the release tags for a batch with `tagsFor`.
 - `findWorkspaceRootSync` / `getWorkspacePackagesSync` — the synchronous escape hatch for config-time callers that cannot await, over file and path operations you supply.
+- `@effected/workspaces/testing` — a third entry point holding the repo-shape checks: `WorkspaceLayering` and `LayerPolicy` (the package graph against a committed `layers.json`), `SourceBoundary` (a lexer-backed scanner for `process` reads, forbidden imports and console writes, with shipped positive controls) and `PackedInstall` (the carrier's bins installed from packed tarballs under every available package manager).
 - `@effected/workspaces/node-sync` — a second entry point holding the Node bindings for those operations (`nodeFileSystem`, `nodePath` and the `nodeSyncOps` bag), kept off the main entry so `node:*` never reaches a consumer that supplies its own. `nodeFileSystem` implements the optional `readDirectoryWithTypes` fast path, so the bindings enumerate a workspace in one `readdirSync` per directory.
 
 ## License