@effected/workspaces 0.1.0

package/LockfileReader.js

@@ -0,0 +1,118 @@
+import { WorkspaceRoot } from "./WorkspaceRoot.js";
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { PackageManagerDetector } from "./PackageManagerName.js";
+import { Context, Duration, Effect, Exit, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Lockfile, LockfileFormat, LockfileIntegrity, filenameFor } from "@effected/lockfiles";
+
+//#region src/LockfileReader.ts
+/**
+* Raised when the workspace's lockfile cannot be read off disk.
+*
+* @remarks
+* Parse failures are `@effected/lockfiles`' `LockfileParseError`, not this —
+* this is strictly the IO half.
+*
+* @public
+*/
+var LockfileReadError = class extends Schema.TaggedErrorClass()("LockfileReadError", {
+	/** Absolute path to the lockfile that could not be read. */
+	lockfilePath: Schema.String,
+	/** The format the detected package manager implies. */
+	format: LockfileFormat,
+	/** The originating failure. */
+	cause: Schema.Defect()
+}) {
+	/** Renders the unreadable path into a one-line message. */
+	get message() {
+		return `Cannot read ${this.format} lockfile at ${this.lockfilePath}`;
+	}
+};
+/**
+* Reads and parses the workspace's lockfile.
+*
+* @remarks
+* Layer construction is O(1). The root walk, package-manager detection, file
+* read, parse and pnpm name resolution all happen on the first method call and
+* are memoized success-only for the lifetime of the layer.
+*
+* @example
+* ```ts
+* import { LockfileReader } from "@effected/workspaces";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const reader = yield* LockfileReader;
+*   const lockfile = yield* reader.read();
+*   return lockfile.packages.length;
+* });
+* ```
+*
+* @public
+*/
+var LockfileReader = class LockfileReader extends Context.Service()("@effected/workspaces/LockfileReader") {
+	/** Builds the service. */
+	static make = (options) => Effect.gen(function* () {
+		const roots = yield* WorkspaceRoot;
+		const detector = yield* PackageManagerDetector;
+		const discovery = yield* WorkspaceDiscovery;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const init = Effect.gen(function* () {
+			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+			const format = (yield* detector.detect(root)).name;
+			const lockfilePath = path.join(root, filenameFor(format));
+			const content = yield* fs.readFileString(lockfilePath).pipe(Effect.mapError((cause) => new LockfileReadError({
+				lockfilePath,
+				format,
+				cause
+			})));
+			const lockfile = yield* Lockfile.parse(content, { format });
+			if (format !== "pnpm") return lockfile;
+			const importers = lockfile.packages.filter((pkg) => pkg.isWorkspace && pkg.relativePath !== void 0);
+			const resolved = yield* Effect.forEach(importers, (pkg) => readName(path.join(root, pkg.relativePath, "package.json")).pipe(Effect.map((name) => [pkg.relativePath, name])), { concurrency: 10 });
+			const names = /* @__PURE__ */ new Map();
+			for (const [relativePath, name] of resolved) if (Option.isSome(name)) names.set(relativePath, name.value);
+			return lockfile.withImporterNames(names);
+		});
+		/** A workspace member's name, or none — an unreadable manifest is a miss, not a failure. */
+		const readName = (manifestPath) => Effect.gen(function* () {
+			const content = yield* fs.readFileString(manifestPath).pipe(Effect.orElseSucceed(() => ""));
+			if (content === "") return Option.none();
+			const parsed = yield* Effect.try({
+				try: () => JSON.parse(content),
+				catch: () => void 0
+			}).pipe(Effect.orElseSucceed(() => void 0));
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return Option.none();
+			const name = parsed.name;
+			return typeof name === "string" && name.length > 0 ? Option.some(name) : Option.none();
+		});
+		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(init, Duration.infinity);
+		const memo = Effect.onExit(resolveOnce, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidate);
+		return {
+			read: Effect.fn("LockfileReader.read")(function* () {
+				return yield* memo;
+			}),
+			resolvedVersion: Effect.fn("LockfileReader.resolvedVersion")(function* (packageName) {
+				const matches = (yield* memo).packagesNamed(packageName);
+				return Option.fromUndefinedOr(matches[0]);
+			}),
+			integrity: Effect.fn("LockfileReader.integrity")(function* () {
+				const lockfile = yield* memo;
+				const packages = yield* discovery.listPackages();
+				return LockfileIntegrity.compare(lockfile, packages.map((pkg) => pkg.toWorkspaceManifest()));
+			}),
+			refresh: () => invalidate
+		};
+	});
+	/**
+	* The live layer.
+	*
+	* @remarks
+	* Parameterized, so it mints a fresh reference per call — bind it to a
+	* `const` and reuse it.
+	*/
+	static layer = (options) => Layer.effect(LockfileReader, LockfileReader.make(options));
+};
+
+//#endregion
+export { LockfileReadError, LockfileReader };

package/PackageManagerName.js

@@ -0,0 +1,248 @@
+import { WorkspaceManifestError } from "./WorkspacePackage.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { PackageManager } from "@effected/package-json";
+
+//#region src/PackageManagerName.ts
+/**
+* The four package managers this package understands.
+*
+* @public
+*/
+const PackageManagerName = Schema.Literals([
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+]);
+/**
+* The outcome of package-manager detection at a workspace root.
+*
+* @remarks
+* `version` is `Option.none()` unless a manifest field naming the *same* manager
+* that was detected also carries a version — a `packageManager: "yarn@4"` in a
+* pnpm workspace tells us nothing about pnpm's version, so it is not reported as
+* one. The two fields consulted are the corepack top-level `packageManager` and
+* `devEngines.packageManager`; see {@link PackageManagerDetector} for the
+* precedence between them.
+*
+* @public
+*/
+var DetectedPackageManager = class extends Schema.Class("DetectedPackageManager")({
+	/** The detected manager. */
+	name: PackageManagerName,
+	/** Its version, when a manifest field agrees on the manager and carries one. */
+	version: Schema.Option(Schema.String),
+	/** The JavaScript runtime the manager implies. */
+	runtime: Schema.Literals(["node", "bun"])
+}) {};
+/** Whether `value` is a non-null, non-array object — corepack's own shape test. */
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The exact version a `name` + `version` pair denotes, or none when the version
+* is not an exact version.
+*
+* Reuses the corepack `name@version+integrity` grammar rather than a second
+* parser, so a `devEngines` version carrying a hash (`11.11.0+sha512.…`, which
+* this repo's own root manifest does) normalizes to the same `11.11.0` the
+* top-level field reports — and a *range* (`^11`, `11.x`) yields none, because a
+* range is not a version and corepack will not run one either.
+*/
+const exactVersionOf = (name, version) => Schema.decodeUnknownOption(PackageManager.FromString)(`${name}@${version}`).pipe(Option.map((pm) => pm.version));
+/**
+* The `devEngines.packageManager` hint, or none.
+*
+* Every malformed shape corepack itself tolerates is tolerated here by *ignoring
+* the field*, never by failing detection: a non-object `devEngines`, a
+* non-object `packageManager`, an **array** of them (corepack does not support
+* arrays in this slot and falls back), a missing or non-string `name`, and a
+* `name` containing `@`. A version that is not an exact version is dropped on its
+* own, keeping the name — the name is still a valid disambiguator.
+*/
+const devEnginesHint = (manifest) => {
+	const devEngines = manifest.devEngines;
+	if (!isPlainObject(devEngines)) return Option.none();
+	const slot = devEngines.packageManager;
+	if (!isPlainObject(slot)) return Option.none();
+	const name = slot.name;
+	if (typeof name !== "string" || name === "" || name.includes("@")) return Option.none();
+	const version = slot.version;
+	return Option.some({
+		name,
+		version: typeof version === "string" && version !== "" ? exactVersionOf(name, version) : Option.none()
+	});
+};
+/** The corepack top-level `packageManager` hint, or none when absent or malformed. */
+const corepackHint = (manifest) => {
+	const raw = manifest.packageManager;
+	if (typeof raw !== "string") return Option.none();
+	return Schema.decodeUnknownOption(PackageManager.FromString)(raw).pipe(Option.map((pm) => ({
+		name: pm.name,
+		version: Option.some(pm.version)
+	})));
+};
+/**
+* Raised when a directory carries no lockfile and no workspace configuration,
+* so no package manager can be attributed to it.
+*
+* @public
+*/
+var PackageManagerDetectionError = class extends Schema.TaggedErrorClass()("PackageManagerDetectionError", {
+	/** The workspace root that was probed. */
+	root: Schema.String,
+	/** The marker files probed, in the order they were probed. */
+	checked: Schema.Array(Schema.String)
+}) {
+	/** Renders the root and probed markers into a one-line message. */
+	get message() {
+		return `No package manager detected at ${this.root} (checked ${this.checked.join(", ")})`;
+	}
+};
+/** The markers probed, in priority order. Exposed on the error so the contract is not prose-only. */
+const CHECKED = [
+	"pnpm-workspace.yaml",
+	"bun.lock",
+	"bun.lockb",
+	"yarn.lock",
+	"package.json#workspaces"
+];
+/**
+* Detects which package manager owns a workspace root.
+*
+* @remarks
+* **Lockfile evidence is the primary signal** — it is what says which manager
+* actually ran. Priority, first match wins: a `pnpm-workspace.yaml` means pnpm;
+* a bun lockfile *plus* a manifest field naming bun means bun; a `yarn.lock`
+* *plus* a manifest field naming yarn means yarn; a root `package.json` with a
+* `workspaces` field falls back to npm.
+*
+* The manifest conjunction is deliberate: a stray `yarn.lock` in an npm repo is
+* common, and only a declared manager name disambiguates it.
+*
+* **Two manifest fields declare a manager, and they are not interchangeable.**
+* Corepack reads both, and this is the rule that falls out of how it treats
+* them:
+*
+* - `devEngines.packageManager.name` is authoritative for the **name**.
+*   Corepack *errors* when a top-level `packageManager` disagrees with it (per
+*   `devEngines.packageManager.onFail`), so where both are present and disagree,
+*   `devEngines` is the one to believe. When `devEngines` names a manager, the
+*   top-level field's name is not consulted as a disambiguator at all.
+* - The top-level `packageManager` is authoritative for the exact **version**:
+*   it is the field that carries the integrity hash. Where both name the same
+*   manager, its version wins; where it is absent, `devEngines.packageManager.version`
+*   supplies the version instead.
+*
+* A version is reported **only when the field it came from names the manager
+* that was actually detected**. A `packageManager: "yarn@4"` in a pnpm workspace
+* says nothing about pnpm's version, so no version is reported — and the same
+* discipline applies to `devEngines`.
+*
+* Malformed manifest *hints* are ignored rather than fatal, matching corepack: a
+* non-object or array `devEngines.packageManager`, a `name` containing `@`, or a
+* version that is not an exact version cannot turn a detectable workspace into a
+* detection failure. A manifest that exists but cannot be **read or parsed** is a
+* different thing entirely and fails with a `WorkspaceManifestError` — a corrupt
+* root manifest is a real problem, not a missing hint.
+*
+* @public
+*/
+var PackageManagerDetector = class PackageManagerDetector extends Context.Service()("@effected/workspaces/PackageManagerDetector") {
+	/** Builds the service over core `FileSystem` and `Path`. */
+	static make = Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const has = (root, file) => fs.exists(path.join(root, file)).pipe(Effect.orElseSucceed(() => false));
+		/**
+		* The root manifest, read and parsed **once** per detection.
+		*
+		* An absent manifest is `Option.none()` — a bun or yarn repo with no root
+		* `package.json` is unusual but not an error. A manifest that is present but
+		* unreadable, unparseable, or not a JSON object fails typed: those are
+		* corrupt-manifest conditions, and swallowing them would report "no manager
+		* declared" for a repo whose manifest is simply broken.
+		*/
+		const manifestOf = (root) => Effect.gen(function* () {
+			const packageJsonPath = path.join(root, "package.json");
+			if (!(yield* fs.exists(packageJsonPath).pipe(Effect.orElseSucceed(() => false)))) return Option.none();
+			const content = yield* fs.readFileString(packageJsonPath).pipe(Effect.mapError((cause) => new WorkspaceManifestError({
+				packageJsonPath,
+				kind: "read",
+				cause
+			})));
+			const parsed = yield* Effect.try({
+				try: () => JSON.parse(content),
+				catch: (cause) => new WorkspaceManifestError({
+					packageJsonPath,
+					kind: "decode",
+					cause
+				})
+			});
+			if (!isPlainObject(parsed)) return yield* Effect.fail(new WorkspaceManifestError({
+				packageJsonPath,
+				kind: "decode",
+				cause: /* @__PURE__ */ new Error("package.json is not a JSON object")
+			}));
+			return Option.some(parsed);
+		});
+		/**
+		* The manager name the manifest declares, if any.
+		*
+		* `devEngines` first — it is authoritative for the name, and corepack errors
+		* when the top-level field contradicts it.
+		*/
+		const declaredName = (hints) => Option.map(Option.orElse(hints.devEngines, () => hints.corepack), (hint) => hint.name);
+		/** Whether the manifest declares `name` as its manager. */
+		const namesManager = (hints, name) => Option.contains(declaredName(hints), name);
+		/**
+		* The version to report for the manager that was detected — none unless a
+		* field naming *that* manager carries one.
+		*
+		* The top-level `packageManager` wins when it names the manager, because it
+		* is the field carrying the integrity hash; `devEngines` supplies the version
+		* when it does not.
+		*/
+		const versionFor = (hints, name) => {
+			if (!namesManager(hints, name)) return Option.none();
+			const fromCorepack = Option.flatMap(hints.corepack, (hint) => hint.name === name ? hint.version : Option.none());
+			return Option.orElse(fromCorepack, () => Option.flatMap(hints.devEngines, (hint) => hint.name === name ? hint.version : Option.none()));
+		};
+		const detect = Effect.fn("PackageManagerDetector.detect")(function* (root) {
+			const manifest = yield* manifestOf(root);
+			const hints = {
+				devEngines: Option.flatMap(manifest, devEnginesHint),
+				corepack: Option.flatMap(manifest, corepackHint)
+			};
+			if (yield* has(root, "pnpm-workspace.yaml")) return DetectedPackageManager.make({
+				name: "pnpm",
+				version: versionFor(hints, "pnpm"),
+				runtime: "node"
+			});
+			if (((yield* has(root, "bun.lock")) || (yield* has(root, "bun.lockb"))) && namesManager(hints, "bun")) return DetectedPackageManager.make({
+				name: "bun",
+				version: versionFor(hints, "bun"),
+				runtime: "bun"
+			});
+			if ((yield* has(root, "yarn.lock")) && namesManager(hints, "yarn")) return DetectedPackageManager.make({
+				name: "yarn",
+				version: versionFor(hints, "yarn"),
+				runtime: "node"
+			});
+			const workspaces = Option.map(manifest, (fields) => fields.workspaces);
+			if (Option.isSome(workspaces) && workspaces.value !== void 0 && workspaces.value !== null) return DetectedPackageManager.make({
+				name: "npm",
+				version: versionFor(hints, "npm"),
+				runtime: "node"
+			});
+			return yield* Effect.fail(new PackageManagerDetectionError({
+				root,
+				checked: CHECKED
+			}));
+		});
+		return { detect: (root) => detect(root).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path)) };
+	});
+	/** The live layer. */
+	static layer = Layer.effect(PackageManagerDetector, PackageManagerDetector.make);
+};
+
+//#endregion
+export { DetectedPackageManager, PackageManagerDetectionError, PackageManagerDetector, PackageManagerName };

package/Publishability.js

@@ -0,0 +1,73 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+//#region src/Publishability.ts
+/** The public npm registry, used when `publishConfig.registry` says nothing. */
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+/**
+* A resolved publish destination for a workspace package.
+*
+* @public
+*/
+var PublishTarget = class extends Schema.Class("PublishTarget")({
+	/** The package name being published. */
+	name: Schema.NonEmptyString,
+	/** The registry URL. */
+	registry: Schema.NonEmptyString,
+	/** The directory to publish, relative to the package root; `"."` for the root itself. */
+	directory: Schema.String,
+	/** Scoped-package visibility. */
+	access: Schema.Literals(["public", "restricted"]),
+	/** Whether to publish with a provenance attestation. */
+	provenance: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false)), Schema.withConstructorDefault(Effect.succeed(false)))
+}) {};
+/**
+* Decides whether a workspace package publishes, and to where.
+*
+* @remarks
+* The default layer implements standard npm semantics: a `private` package with
+* no `publishConfig.access` publishes nowhere; an explicit
+* `publishConfig.access` overrides `private`; anything else publishes to the
+* public registry with defaults.
+*
+* Those are *npm's* semantics, not necessarily yours. Swap the layer:
+*
+* @example
+* ```ts
+* import { PublishabilityDetector, PublishTarget } from "@effected/workspaces";
+* import { Effect, Layer } from "effect";
+*
+* const internalOnly = Layer.succeed(PublishabilityDetector, {
+*   detect: (pkg) =>
+*     Effect.succeed(
+*       pkg.name.startsWith("@acme/")
+*         ? [PublishTarget.make({
+*             name: pkg.name,
+*             registry: "https://npm.acme.internal/",
+*             directory: ".",
+*             access: "restricted",
+*           })]
+*         : [],
+*     ),
+* });
+* ```
+*
+* @public
+*/
+var PublishabilityDetector = class PublishabilityDetector extends Context.Service()("@effected/workspaces/PublishabilityDetector") {
+	/** Standard npm publishing semantics. Pure — no filesystem, no platform services. */
+	static layer = Layer.succeed(PublishabilityDetector, { detect: (pkg) => Effect.sync(() => {
+		const config = pkg.publishConfig;
+		const access = config?.access;
+		if (pkg.private && access === void 0) return [];
+		return [PublishTarget.make({
+			name: pkg.name,
+			registry: config?.registry ?? DEFAULT_REGISTRY,
+			directory: config?.directory ?? ".",
+			access: access ?? "public",
+			provenance: false
+		})];
+	}) });
+};
+
+//#endregion
+export { PublishTarget, PublishabilityDetector };

package/README.md

@@ -0,0 +1,165 @@
+# @effected/workspaces
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fworkspaces?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/workspaces)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Monorepo workspace tooling for [Effect](https://effect.website) v4: find the workspace root, enumerate its packages, walk the dependency graph, detect the package manager, resolve pnpm catalogs, read the lockfile and work out which packages a git range touches. Every capability is a service you provide at the edge and swap in tests. Works with npm, pnpm, yarn Berry and bun.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/workspaces
+
+Monorepo tooling keeps re-deriving the same facts: where the root is, which directories are packages, what depends on what, what a `catalog:` specifier means and which packages a change affects. Each tool re-derives them slightly differently, and the differences show up as bugs. This package answers those questions once.
+
+Discovery is honest about what a glob means. A `packages/**` pattern finds packages nested more than one level deep, because the enumerator does a bounded descent rather than the one-level approximation that a trailing-`**` rewrite quietly turns it into — and a package that goes undiscovered with no diagnostic is the worst kind of wrong, because an empty result is indistinguishable from a legitimately empty workspace. The same discipline runs through the error model: a malformed `package.json`, an unenumerable pattern, a missing lockfile and a failed git command all fail through the typed channel with structured fields, while a developer wiring mistake (an uncompilable glob literal, a fractional `maxDepth`) stays a defect. The typed channel is exactly the set of things a caller can branch on.
+
+Git runs through `@effected/git`'s `Git` service rather than a hard-coded subprocess call, so change detection is testable with no repository on disk and portable to a runtime that spawns processes differently. And where `@effected/npm` declares the `CatalogResolver` and `WorkspaceResolver` seams — contracts that `@effected/package-json` consumes but no pure package can fill — this is the package that fills them.
+
+## Install
+
+```bash
+npm install @effected/workspaces effect
+```
+
+```bash
+pnpm add @effected/workspaces effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is a peer dependency. You provide a `FileSystem` and `Path` implementation at the edge — `@effect/platform-node` or `@effect/platform-bun`.
+
+pnpm's catalog semantics come from pnpm's own `@pnpm/catalogs.*` packages, which install as regular dependencies. Reimplementing them would mean owning a moving spec with no oracle, so they are used directly and confined to a single internal module.
+
+## Quick start
+
+```ts
+import { NodeFileSystem, NodePath } from "@effect/platform-node";
+import { DependencyGraph, WorkspaceDiscovery, Workspaces } from "@effected/workspaces";
+import { Effect, Layer } from "effect";
+
+// Bind the layer to a const: layers memoize by reference, so calling
+// Workspaces.layer() twice builds the whole stack twice.
+const Platform = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);
+const WorkspacesLayer = Workspaces.layer().pipe(Layer.provide(Platform));
+
+const program = Effect.gen(function* () {
+  const discovery = yield* WorkspaceDiscovery;
+
+  const packages = yield* discovery.listPackages();
+  const graph = DependencyGraph.make({ packages });
+
+  // Parallel build tiers: level 0 depends on nothing in the workspace,
+  // level n depends only on the levels below it.
+  return yield* graph.levels();
+});
+
+Effect.runPromise(program.pipe(Effect.provide(WorkspacesLayer))).then(console.log);
+// [ [ ...names with no workspace dependencies ], [ ...names that depend only on level 0 ], ... ]
+```
+
+`DependencyGraph` is a value class, not a service: build it from packages you already have. A cycle fails with `CyclicDependencyError` naming the packages that could not be ordered.
+
+## Change detection
+
+`ChangeDetector` offers three depths of analysis on one service — `changedFiles` (raw paths from a git range), `changedPackages` (the packages owning them) and `affectedPackages` (the transitive blast radius through the dependency graph).
+
+```ts
+import { NodeServices } from "@effect/platform-node";
+import { ChangeDetectionOptions, ChangeDetector, Workspaces } from "@effected/workspaces";
+import { Effect, Layer } from "effect";
+
+// layerWithGit runs ChangeDetector over @effected/git's Git service; NodeServices
+// provides the ChildProcessSpawner it needs, alongside FileSystem and Path.
+const WorkspacesLayer = Workspaces.layerWithGit().pipe(Layer.provide(NodeServices.layer));
+
+const program = Effect.gen(function* () {
+  const detector = yield* ChangeDetector;
+  const affected = yield* detector.affectedPackages(ChangeDetectionOptions.make({ base: "origin/main" }));
+  return affected.map((pkg) => pkg.name);
+});
+
+Effect.runPromise(program.pipe(Effect.provide(WorkspacesLayer))).then(console.log);
+// [ ...names of packages the range touched, plus everything downstream of them ]
+```
+
+Git is a separate layer rather than a flag, because the extra requirement is a subprocess: a consumer that never detects changes should not have to be able to spawn one. A test provides the `Git` service with a `Layer.succeed` stub and needs no repository at all.
+
+## pnpm catalogs
+
+`WorkspaceCatalogs` assembles a workspace's catalogs with pnpm's precedence (the lockfile's record first, the inline `pnpm-workspace.yaml` declaration wins) and resolves `catalog:` specifiers against the result.
+
+It also supplies the real implementations of `@effected/npm`'s `CatalogResolver` and `WorkspaceResolver` contracts — the seams `@effected/package-json` reads through, which without a workspace under them can only answer `Option.none()`. Provide `Workspaces.resolvers` and `Package.resolve` rewrites `catalog:` and `workspace:` specifiers to concrete ranges:
+
+```ts
+import { Workspaces } from "@effected/workspaces";
+import { Layer } from "effect";
+
+const WorkspacesLayer = Workspaces.layer();
+const Resolvers = Workspaces.resolvers.pipe(Layer.provide(WorkspacesLayer));
+// Layer<CatalogResolver | WorkspaceResolver, never, FileSystem | Path>
+```
+
+## The synchronous escape hatch
+
+Vitest's config-time project discovery cannot await. Two functions exist for exactly that case, and they are **Node-only and synchronous**:
+
+```ts
+import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+
+const root = findWorkspaceRootSync();
+const packages = root === null ? [] : getWorkspacePackagesSync(root);
+// root: the workspace root path, or null when none is found above the cwd
+// packages: the discovered workspace packages, empty when there is no root
+```
+
+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.
+
+## Error handling
+
+Every failure is a `Schema.TaggedErrorClass` with structured fields you can branch on, not a prose string:
+
+```ts
+import { WorkspaceDiscovery, WorkspacePatternError } from "@effected/workspaces";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const discovery = yield* WorkspaceDiscovery;
+  return yield* discovery.listPackages();
+}).pipe(
+  Effect.catchTag("WorkspacePatternError", (error: WorkspacePatternError) =>
+    // kind: "missingBaseDir" | "uncompilable" | "depthExceeded" | "budgetExceeded"
+    Effect.logError(`pattern ${error.pattern} failed: ${error.kind}`).pipe(Effect.as([])),
+  ),
+);
+```
+
+`WorkspaceRootNotFoundError`, `WorkspaceDiscoveryError`, `WorkspacePatternError`, `PackageNotFoundError`, `WorkspaceManifestError`, `PackageManagerDetectionError`, `CatalogAssemblyError`, `LockfileReadError`, `CyclicDependencyError` and `ChangeDetectionError` each name one thing that can actually go wrong, and each method's error channel is narrowed to the ones it can produce. Change detection additionally surfaces `@effected/git`'s typed git errors, such as `NotARepositoryError`.
+
+## Features
+
+- `Workspaces.layer` / `Workspaces.layerWithGit` / `Workspaces.resolvers` — the composite layers, split on requirements rather than feature flags: a filesystem, a filesystem plus a subprocess, and the two `@effected/npm` resolver contracts.
+- `WorkspaceRoot` — root discovery from a `cwd`, over `WORKSPACE_MARKERS`.
+- `WorkspaceDiscovery` — package enumeration with a bounded descent for segment-crossing `packages/**` patterns, plus per-package lookup.
+- `WorkspacePackage` — a deliberately tolerant manifest model, so one member with an odd version cannot fail discovery for the whole repo. `WorkspacePackage.manifest(pkg)` is the opt-in bridge to `@effected/package-json`'s strict `Package`.
+- `DependencyGraph` — a value class over discovered packages: `levels()` for parallel build tiers, the flattened topological order, and `CyclicDependencyError` when there isn't one.
+- `PackageManagerDetector` — npm, pnpm, yarn or bun from lockfiles and the `packageManager` field.
+- `WorkspaceCatalogs` — pnpm catalog assembly and `catalog:` resolution, on pnpm's own catalog packages.
+- `LockfileReader` — locate and parse the workspace's lockfile through `@effected/lockfiles`.
+- `ChangeDetector` — git-range change detection over `@effected/git`'s `Git` service; swap the layer to mock it with no repository.
+- `PublishabilityDetector` — whether a package publishes and to where, as a `PublishTarget` (registry, directory, access, provenance). The default layer implements npm's semantics; swap the layer if yours differ.
+- `findWorkspaceRootSync` / `getWorkspacePackagesSync` — the Node-only synchronous escape hatch for config-time callers that cannot await.
+
+## License
+
+[MIT](LICENSE)