@effected/workspaces 0.17.1 → 0.18.0

package/WorkspaceDiscovery.js

@@ -199,8 +199,17 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				cause
 			})));
 		});
-		const discover = Effect.gen(function* () {
-			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+		/**
+		* Discovery for ONE already-resolved root — the whole read, with the root
+		* as a parameter rather than a closed-over constant.
+		*
+		* Everything derived here (patterns, member manifests, names, versions) is
+		* read beneath `root`, which is what makes the per-call-root methods
+		* honest: re-rooting an already-discovered package list onto a different
+		* directory rewrites paths but keeps the ORIGINAL root's manifests, so a
+		* branch that adds or removes a package stays invisible. This re-reads.
+		*/
+		const discoverAt = (root) => Effect.gen(function* () {
 			const patterns = yield* readPatterns(root).pipe(Effect.mapError((failure) => new WorkspaceDiscoveryError({
 				root,
 				path: failure.path,
@@ -233,8 +242,43 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				packages
 			};
 		}).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+		const discover = Effect.gen(function* () {
+			const root = yield* Effect.suspend(() => roots.find(options?.cwd ?? process.cwd()));
+			return yield* discoverAt(root);
+		});
 		const [resolveOnce, invalidate] = yield* Effect.cachedInvalidateWithTTL(discover, Duration.infinity);
 		const memo = Effect.onExit(resolveOnce, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidate);
+		/**
+		* Per-resolved-root memos for the `…In` methods, each success-only on the
+		* same discipline as the layer-bound one above.
+		*
+		* Deliberately SEPARATE from that memo rather than replacing it: the
+		* layer-bound path resolves its root once, at first use, and folding it
+		* into this map would make every call re-run the root ascent. A caller
+		* that asks for the layer's own root through `listPackagesIn` pays one
+		* extra discovery — the honest price for not changing what the existing
+		* methods do.
+		*
+		* The map grows one entry per distinct root, which is the point for a
+		* long-lived host serving many worktrees, and is why `refresh()` clears
+		* it wholesale rather than invalidating one cell.
+		*/
+		const rootMemos = /* @__PURE__ */ new Map();
+		/** The memoized discovery for the workspace root containing `directory`. */
+		const memoIn = Effect.fn("WorkspaceDiscovery.memoIn")(function* (directory) {
+			const root = yield* roots.find(directory);
+			const existing = rootMemos.get(root);
+			if (existing !== void 0) return yield* existing.memo;
+			const [resolveOnce, invalidateOne] = yield* Effect.cachedInvalidateWithTTL(discoverAt(root), Duration.infinity);
+			const built = Effect.onExit(resolveOnce, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidateOne);
+			const raced = rootMemos.get(root);
+			if (raced !== void 0) return yield* raced.memo;
+			rootMemos.set(root, {
+				memo: built,
+				invalidate: invalidateOne
+			});
+			return yield* built;
+		});
 		const packages = memo.pipe(Effect.map((state) => state.packages));
 		/**
 		* The longest-prefix index, built once per package list.
@@ -292,6 +336,12 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				const all = yield* packages;
 				return ownerOf(filePath, owners(all));
 			}),
+			infoIn: Effect.fn("WorkspaceDiscovery.infoIn")(function* (directory) {
+				return (yield* memoIn(directory)).info;
+			}),
+			listPackagesIn: Effect.fn("WorkspaceDiscovery.listPackagesIn")(function* (directory) {
+				return (yield* memoIn(directory)).packages;
+			}),
 			resolveFiles: Effect.fn("WorkspaceDiscovery.resolveFiles")(function* (filePaths) {
 				const all = yield* packages;
 				const index = owners(all);
@@ -302,7 +352,17 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				}
 				return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
 			}),
-			refresh: () => invalidate
+			refreshIn: Effect.fn("WorkspaceDiscovery.refreshIn")(function* (directory) {
+				const root = yield* roots.find(directory);
+				const cell = rootMemos.get(root);
+				if (cell === void 0) return;
+				yield* cell.invalidate;
+				rootMemos.delete(root);
+			}),
+			refresh: () => Effect.flatMap(Effect.forEach([...rootMemos.values()], (cell) => cell.invalidate, { discard: true }), () => {
+				rootMemos.clear();
+				return invalidate;
+			})
 		};
 	});
 	/**
@@ -396,7 +456,10 @@ var WorkspaceDiscovery = class WorkspaceDiscovery extends Context.Service()("@ef
 				}
 				return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
 			}),
+			infoIn: () => Effect.die(/* @__PURE__ */ new Error("WorkspaceDiscovery.makeTest: infoIn() was called but not stubbed — a double cannot know what another root's workspace looks like; pass an `infoIn` override.")),
+			listPackagesIn: () => Effect.die(/* @__PURE__ */ new Error("WorkspaceDiscovery.makeTest: listPackagesIn() was called but not stubbed — deriving it from `listPackages` would model every root as identical, which is the bug this method exists to prevent; pass a `listPackagesIn` override.")),
 			refresh: () => Effect.void,
+			refreshIn: () => Effect.void,
 			...overrides
 		};
 	};

package/WorkspaceSnapshots.js

@@ -104,6 +104,7 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 		const roots = yield* WorkspaceRoot;
 		const discovery = yield* WorkspaceDiscovery;
 		const catalogsService = yield* WorkspaceCatalogs;
+		const seeded = (snapshot) => options?.seedCatalogs === void 0 ? snapshot : snapshot.withSeededCatalogs(options.seedCatalogs);
 		/**
 		* What a manager's lockfile records at the ref: its catalog set and its
 		* importer versions, from ONE parse. Empty on both counts when the
@@ -166,11 +167,11 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 			const packages = [];
 			if (Option.isSome(rootPackage)) packages.push(rootPackage.value);
 			for (const member of members) if (Option.isSome(member)) packages.push(member.value);
-			return WorkspaceStateSnapshot.make({
+			return seeded(WorkspaceStateSnapshot.make({
 				packages,
 				catalogs,
 				importerVersions: recorded.importerVersions
-			});
+			}));
 		});
 		const atCaches = /* @__PURE__ */ new Map();
 		return {
@@ -203,11 +204,11 @@ var WorkspaceSnapshots = class WorkspaceSnapshots extends Context.Service()("@ef
 					peerDependencies: pkg.peerDependencies,
 					optionalDependencies: pkg.optionalDependencies
 				}));
-				return WorkspaceStateSnapshot.make({
+				return seeded(WorkspaceStateSnapshot.make({
 					packages: snapshotPackages,
 					catalogs,
 					importerVersions
-				});
+				}));
 			})
 		};
 	});

package/WorkspaceStateSnapshot.js

@@ -83,7 +83,7 @@ var PackageStateSnapshot = class extends Schema.Class("PackageStateSnapshot")({
 *
 * @public
 */
-var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot")({
+var WorkspaceStateSnapshot = class WorkspaceStateSnapshot extends Schema.Class("WorkspaceStateSnapshot")({
 	/** Every workspace package captured at this moment. */
 	packages: Schema.Array(PackageStateSnapshot),
 	/** The catalog set assembled at this moment. */
@@ -99,7 +99,30 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 	* the behavior those older values were captured under. Only pnpm records
 	* importer versions; bun and npm yield an empty index.
 	*/
-	importerVersions: Schema.optionalKey(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.String)))
+	importerVersions: Schema.optionalKey(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.String))),
+	/**
+	* Catalogs supplied from OUTSIDE this moment, consulted only when
+	* `catalogs` cannot answer.
+	*
+	* @remarks
+	* **This is deliberately not merged into `catalogs`.** That field means "the
+	* catalog set assembled at this moment" and a snapshot is a serializable
+	* value someone stores and diffs; blending an external set into it would
+	* quietly make the field mean something else, and nothing downstream could
+	* tell the two apart afterwards. Kept separate, the ref's own declaration
+	* always wins and both halves stay readable.
+	*
+	* The motivating case is a catalog injected by a config-dependency
+	* `pnpmfile` hook. It is recorded in no committed catalog source, so
+	* `WorkspaceSnapshots.at(ref)` — which never replays hooks, by design — cannot
+	* see it, and a `catalog:` specifier against it resolves to nothing on BOTH
+	* sides of a diff. Seeding the live hook-injected set, or the other side's
+	* set, restores a declared RANGE without executing any historical code.
+	*
+	* Defaults to absent, which makes the seed inert — exactly the behavior of
+	* every snapshot captured before this field existed.
+	*/
+	seededCatalogs: Schema.optionalKey(CatalogSet)
 }) {
 	#versionIndex;
 	#packageIndex;
@@ -134,7 +157,16 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 	* unparseable string — is `Option.none()`, because there is no indirection to
 	* resolve. Total.
 	*
-	* A `catalog:` specifier the catalog set cannot resolve falls back to this
+	* A `catalog:` specifier resolves in three steps, and the order is the
+	* contract: this moment's own `catalogs` first,
+	* then `seededCatalogs` if one was supplied,
+	* then the `importerVersions` fallback below. The first two answer with a
+	* declared RANGE and the third with a concrete version, so a seeded snapshot
+	* reports a range change where an unseeded one could only report a version —
+	* which is the difference between a diff row and no row when both refs
+	* recorded the same installed version.
+	*
+	* A `catalog:` specifier neither catalog set can resolve falls back to this
 	* snapshot's `importerVersions` — but only to a version
 	* **every** importer recording that dependency agrees on. A catalog injected
 	* by a config-dependency pnpmfile hook appears in no committed catalog source,
@@ -187,7 +219,7 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 		const classified = exit.value;
 		switch (classified._tag) {
 			case "catalog": {
-				const fromCatalogs = this.catalogs.rangeOf(dependency, classified.name);
+				const fromCatalogs = this.#catalogRange(dependency, classified.name);
 				return Option.isSome(fromCatalogs) ? fromCatalogs : onUnresolvedCatalog();
 			}
 			case "workspace": return Option.fromUndefinedOr(this.#versions().get(dependency));
@@ -195,6 +227,126 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 		}
 	}
 	/**
+	* The catalog half of resolution, in precedence order: this moment's own
+	* catalogs first, the external seed second.
+	*
+	* @remarks
+	* The ordering is the whole contract. What the ref itself declared can never
+	* be overridden by something handed in from outside, so a seed can only ever
+	* ADD an answer where there was none — which is why seeding is safe to do
+	* unconditionally and why an over-broad seed cannot corrupt a diff.
+	*/
+	#catalogRange(dependency, catalog) {
+		const own = this.catalogs.rangeOf(dependency, catalog);
+		if (Option.isSome(own)) return own;
+		return this.seededCatalogs === void 0 ? Option.none() : this.seededCatalogs.rangeOf(dependency, catalog);
+	}
+	/**
+	* This snapshot with `seed` as its `seededCatalogs`
+	* — catalogs consulted only where this moment's own catalogs cannot answer.
+	*
+	* @remarks
+	* Returns a NEW snapshot; the receiver is untouched, and the seed REPLACES
+	* any seed already present rather than merging with it (a snapshot is a
+	* value, and an accumulating seed would make precedence depend on call
+	* order). {@link WorkspaceStateSnapshot.crossSeed} is the deliberate
+	* exception: it composes the two seeds explicitly, precisely because a bare
+	* replace would discard a layer-level seed. `catalogs`, `packages` and `importerVersions` are carried through
+	* unchanged, so what the ref declared is still exactly what it declared.
+	*
+	* The two seeds worth reaching for: the LIVE hook-injected catalog set (from
+	* a `WorkspaceCatalogs` built by one of the config-dependency layers), or the
+	* other side of a two-ref diff — see
+	* {@link WorkspaceStateSnapshot.crossSeed}.
+	*
+	* @param seed - The catalogs to consult as a fallback.
+	*
+	* @example
+	* ```ts
+	* import { WorkspaceCatalogs, WorkspaceSnapshots } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const program = Effect.gen(function* () {
+	*   const snapshots = yield* WorkspaceSnapshots;
+	*   const catalogs = yield* WorkspaceCatalogs;
+	*   // The live set includes hook-injected catalogs under a config-dependency
+	*   // layer; the ref's own set never can.
+	*   const live = yield* catalogs.set();
+	*   const before = (yield* snapshots.at("origin/main")).withSeededCatalogs(live);
+	*   return before.resolve("effect", "catalog:");
+	* });
+	* ```
+	*/
+	withSeededCatalogs(seed) {
+		return WorkspaceStateSnapshot.make({
+			packages: this.packages,
+			catalogs: this.catalogs,
+			...this.importerVersions === void 0 ? {} : { importerVersions: this.importerVersions },
+			seededCatalogs: seed
+		});
+	}
+	/**
+	* Both sides of a diff, each seeded with the other's catalogs.
+	*
+	* @remarks
+	* The two-ref symmetry the hook-catalog gap actually needs. A catalog
+	* injected by a config-dependency hook is declared in no committed source,
+	* so neither ref's snapshot can see it and a `catalog:` specifier against it
+	* resolves to nothing on both sides — a real version movement then produces
+	* no row. Cross-seeding restores a declared RANGE on whichever side is
+	* missing it, at strictly lower precedence than that side's own catalogs, so
+	* a genuine change between the refs still reads as a change.
+	*
+	* **The limitation is inherent and is not a defect to work around.** A range
+	* change made purely by bumping the config dependency BETWEEN the two refs is
+	* suppressed: neither committed source declares the catalog, so each side
+	* falls back to the other's value and the two agree by construction. Seeding
+	* the live hook-injected set via
+	* {@link WorkspaceStateSnapshot.withSeededCatalogs} has the same blind spot
+	* against history — recovering it would mean replaying each ref's pinned
+	* config-dependency code, which `at(ref)` will not do. If that case must be
+	* detected, diff `configDependencies` in `pnpm-workspace.yaml` directly; it
+	* is the only committed evidence that the injection changed.
+	*
+	* **The seeding relationship is symmetric; the RETURN ORDER is not.** Each
+	* snapshot is seeded with the other's catalogs, so neither argument is
+	* privileged and swapping them produces the same two values — but they come
+	* back mirroring the order they went in, so destructure in the order you
+	* passed. The `before`/`after` names describe the intended calling
+	* convention for a two-ref diff, not a constraint on what may be passed.
+	*
+	* **A seed already present on either snapshot is preserved**, beneath the
+	* other side's catalogs — which matters because
+	* `WorkspaceSnapshotsOptions.seedCatalogs` puts one there on every snapshot
+	* the service returns. Composing the two surfaces is therefore safe: the
+	* layer-level seed keeps answering what neither ref declared, while the
+	* other ref's committed declaration wins where it has one.
+	*
+	* @param before - One snapshot, conventionally the earlier one.
+	* @param after - The other snapshot, conventionally the later one.
+	* @returns Both snapshots in the order given, each carrying the other's
+	*   catalogs as its seed.
+	*
+	* @example
+	* ```ts
+	* import { WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+	* import { Effect } from "effect";
+	*
+	* const program = Effect.gen(function* () {
+	*   const snapshots = yield* WorkspaceSnapshots;
+	*   const [before, after] = WorkspaceStateSnapshot.crossSeed(
+	*     yield* snapshots.at("origin/main"),
+	*     yield* snapshots.worktree(),
+	*   );
+	*   return { before: before.resolve("effect", "catalog:"), after: after.resolve("effect", "catalog:") };
+	* });
+	* ```
+	*/
+	static crossSeed(before, after) {
+		const seedFor = (self, other) => self.seededCatalogs === void 0 ? other.catalogs : CatalogSet.merge(self.seededCatalogs, other.catalogs);
+		return [before.withSeededCatalogs(seedFor(before, after)), after.withSeededCatalogs(seedFor(after, before))];
+	}
+	/**
 	* A `CatalogResolver` layer implementing `@effected/npm`'s contract against
 	* THIS snapshot's catalog set — so code written to the contract resolves
 	* `catalog:` specifiers as of this ref. Built once per instance and cached, so
@@ -207,7 +359,7 @@ var WorkspaceStateSnapshot = class extends Schema.Class("WorkspaceStateSnapshot"
 	* `rangeOf` never fails.
 	*/
 	get catalogResolver() {
-		if (this.#catalogResolver === void 0) this.#catalogResolver = Layer.succeed(CatalogResolver, { rangeOf: (packageName, catalog) => Effect.succeed(this.catalogs.rangeOf(packageName, catalog)) });
+		if (this.#catalogResolver === void 0) this.#catalogResolver = Layer.succeed(CatalogResolver, { rangeOf: (packageName, catalog) => Effect.succeed(this.#catalogRange(packageName, catalog)) });
 		return this.#catalogResolver;
 	}
 	/**

package/Workspaces.js

@@ -19,14 +19,30 @@ const compose = (options, catalogsFactory) => {
 	return Layer.mergeAll(roots, detector, discovery, lockfiles, catalogs);
 };
 const layer = (options) => compose(options, WorkspaceCatalogs.layer);
-const layerWithGit = (options) => {
-	const core = layer(options);
+/**
+* The git half, over an ALREADY-BUILT core composite.
+*
+* @remarks
+* Taking the core as a parameter rather than building it is what lets the
+* config-dependency composites exist at all: the git services are identical
+* across all three, and only the catalogs layer underneath differs. Copying
+* this graph per variant is exactly what a consumer had to do downstream
+* before `layerWithGitAndConfigDependencies` existed.
+*
+* `core` is threaded in as a value, so the caller's single `layer(options)`
+* reference is shared by `ChangeDetector`, `WorkspaceSnapshots` and the merge —
+* building it twice here would defeat layer memoization inside one composite.
+*/
+const withGit = (core, options) => {
 	const git = Git.layer;
 	return Layer.mergeAll(core, git, ChangeDetector.layer.pipe(Layer.provide(git), Layer.provide(core)), WorkspaceSnapshots.layer(options).pipe(Layer.provide(git), Layer.provide(core)));
 };
+const layerWithGit = (options) => withGit(layer(options), options);
 const resolvers = Layer.mergeAll(WorkspaceCatalogs.catalogResolver, WorkspaceDiscovery.workspaceResolver);
 const layerWithConfigDependencies = (options) => compose(options, WorkspaceCatalogs.layerWithConfigDependencies);
 const layerWithConfigDependenciesSubprocess = (options) => compose(options, WorkspaceCatalogs.layerWithConfigDependenciesSubprocess);
+const layerWithGitAndConfigDependencies = (options) => withGit(layerWithConfigDependencies(options), options);
+const layerWithGitAndConfigDependenciesSubprocess = (options) => withGit(layerWithConfigDependenciesSubprocess(options), options);
 const resolverLayer = (options) => resolvers.pipe(Layer.provide(layerWithConfigDependencies(options)));
 const resolveManifest = Effect.fn("Workspaces.resolveManifest")(function* (manifest, options) {
 	return yield* manifest.resolve().pipe(Effect.provide(resolverLayer(options)));
@@ -148,6 +164,68 @@ var Workspaces = class {
 	*/
 	static layerWithGit = layerWithGit;
 	/**
+	* {@link Workspaces.layerWithGit} over
+	* {@link Workspaces.layerWithConfigDependencies} — snapshots, change
+	* detection and git, with catalog assembly that **replays config dependency
+	* `pnpmfile.cjs` hooks**.
+	*
+	* @remarks
+	* The composite that did not exist. `layerWithGit` hard-wires the no-op
+	* catalogs layer, so a consumer wanting snapshots + git + hook replay had to
+	* rebuild the entire service graph by hand — which is exactly what
+	* `@savvy-web/silk-effects` did, and the copy this static deletes.
+	*
+	* Requirements are unchanged from {@link Workspaces.layerWithGit}: a
+	* filesystem, a path service, and core's `ChildProcessSpawner` (behind
+	* `Git`). The in-process replay adds no requirement of its own — it is a
+	* dynamic `import()`, not a subprocess. **If the consumer is bundled, reach
+	* for {@link Workspaces.layerWithGitAndConfigDependenciesSubprocess}
+	* instead**; the computed import does not survive a bundler, and the
+	* `ChildProcessSpawner` the subprocess variant needs is already required
+	* here for git, so on this composite the subprocess form costs nothing extra.
+	*
+	* Opt in deliberately: this executes config-dependency code in process, and
+	* {@link Workspaces.layerWithGit} never does.
+	*
+	* **Bind the result to a `const`.** A parameterized factory mints a fresh
+	* reference per call and layers memoize by reference.
+	*
+	* @example
+	* ```ts
+	* import { Workspaces } from "@effected/workspaces";
+	*
+	* const KitLayer = Workspaces.layerWithGitAndConfigDependencies();
+	* ```
+	*/
+	static layerWithGitAndConfigDependencies = layerWithGitAndConfigDependencies;
+	/**
+	* {@link Workspaces.layerWithGitAndConfigDependencies}, with the hook replay
+	* in a `node` **child process** rather than in process.
+	*
+	* @remarks
+	* Same typed semantics; the difference is mechanism, and it decides whether
+	* catalog assembly works at all in a **bundled** consumer — see
+	* {@link Workspaces.layerWithConfigDependenciesSubprocess} for why the
+	* in-process computed `import()` dies under a bundler.
+	*
+	* **This composite's requirement set is identical to the in-process one.**
+	* The subprocess replay needs core's `ChildProcessSpawner`, which this
+	* composite already requires for `Git` — so unlike the git-free pair, there
+	* is no R-widening to weigh here and a bundled consumer pays nothing to be
+	* correct. Prefer this variant whenever the program ships as a bundle.
+	*
+	* **Bind the result to a `const`.**
+	*
+	* @example
+	* ```ts
+	* import { Workspaces } from "@effected/workspaces";
+	*
+	* // A bundled CLI or MCP server: the computed import never enters the graph.
+	* const KitLayer = Workspaces.layerWithGitAndConfigDependenciesSubprocess();
+	* ```
+	*/
+	static layerWithGitAndConfigDependenciesSubprocess = layerWithGitAndConfigDependenciesSubprocess;
+	/**
 	* This package's implementation of `@effected/commands`' `LocalExec`
 	* contract: how to run a project-local binary here.
 	*

package/index.d.ts

@@ -537,8 +537,65 @@ interface WorkspaceDiscoveryShape {
   readonly resolveFile: (filePath: string) => Effect.Effect<Option.Option<WorkspacePackage>, WorkspaceDiscoveryFailure>;
   /** The distinct packages owning any of `filePaths`. */
   readonly resolveFiles: (filePaths: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
-  /** Drop the memoized discovery so the next call re-reads the filesystem. */
+  /**
+   * Facts about the workspace containing `directory`, discovered against THAT
+   * root rather than the layer-bound one.
+   */
+  readonly infoIn: (directory: string) => Effect.Effect<WorkspaceInfo, WorkspaceDiscoveryFailure>;
+  /**
+   * Every package of the workspace containing `directory`, discovered against
+   * THAT root rather than the layer-bound one.
+   *
+   * @remarks
+   * For a **long-lived host serving many roots** — an MCP server or a language
+   * server that resolves one workspace at startup and then answers calls
+   * scoped to a git worktree, a nested repository, or another project
+   * entirely. The layer-bound {@link WorkspaceDiscoveryShape.listPackages}
+   * answers about the root discovered from `options.cwd`, which such a host
+   * has no way to vary per call without building a fresh layer.
+   *
+   * **This re-reads; it does not re-root.** The tempting cheap fix — take the
+   * layer's package list and rewrite each `path` onto the caller's directory —
+   * produces correct-looking paths over the ORIGINAL root's manifests, so a
+   * worktree whose branch adds, removes or renames a package reports the other
+   * branch's membership with no error. Patterns, member manifests, names and
+   * versions all come from beneath `directory`'s own root here.
+   *
+   * `directory` may be the workspace root or anything inside it: the root is
+   * resolved by the same upward walk the layer-bound path uses, and results are
+   * memoized per RESOLVED root, so many directories in one workspace share one
+   * discovery. The memo holds one entry per distinct root for the layer's
+   * lifetime; {@link WorkspaceDiscoveryShape.refresh} drops all of them.
+   *
+   * @param directory - Absolute path to the workspace root, or to any
+   *   directory inside it.
+   */
+  readonly listPackagesIn: (directory: string) => Effect.Effect<ReadonlyArray<WorkspacePackage>, WorkspaceDiscoveryFailure>;
+  /**
+   * Drop every memoized discovery — the layer-bound one and each per-root memo
+   * — so the next call re-reads the filesystem.
+   */
   readonly refresh: () => Effect.Effect<void>;
+  /**
+   * Drop only the memo for the workspace containing `directory`, leaving the
+   * layer-bound memo and every other root's untouched.
+   *
+   * @remarks
+   * The precise counterpart to {@link WorkspaceDiscoveryShape.refresh} for a
+   * host serving several roots: refreshing one worktree because it changed
+   * should not discard sibling worktrees that did not, which is all `refresh`
+   * can do.
+   *
+   * **Fails typed on a directory in no workspace**, exactly as
+   * {@link WorkspaceDiscoveryShape.listPackagesIn} does for the same input —
+   * the three per-root methods answer a bad path the same way, and a caller
+   * that would rather treat it as a no-op writes `Effect.ignore`. Refreshing a
+   * root that HAS no memo is an ordinary no-op and not an error.
+   *
+   * @param directory - Absolute path to the workspace root, or to any
+   *   directory inside it.
+   */
+  readonly refreshIn: (directory: string) => Effect.Effect<void, WorkspaceRootNotFoundError>;
 }
 declare const WorkspaceDiscovery_base: Context.ServiceClass<WorkspaceDiscovery, "@effected/workspaces/WorkspaceDiscovery", WorkspaceDiscoveryShape>;
 /**
@@ -2687,6 +2744,29 @@ declare const WorkspaceStateSnapshot_base: Schema.Class<WorkspaceStateSnapshot,
    * importer versions; bun and npm yield an empty index.
    */
   readonly importerVersions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
+  /**
+   * Catalogs supplied from OUTSIDE this moment, consulted only when
+   * `catalogs` cannot answer.
+   *
+   * @remarks
+   * **This is deliberately not merged into `catalogs`.** That field means "the
+   * catalog set assembled at this moment" and a snapshot is a serializable
+   * value someone stores and diffs; blending an external set into it would
+   * quietly make the field mean something else, and nothing downstream could
+   * tell the two apart afterwards. Kept separate, the ref's own declaration
+   * always wins and both halves stay readable.
+   *
+   * The motivating case is a catalog injected by a config-dependency
+   * `pnpmfile` hook. It is recorded in no committed catalog source, so
+   * `WorkspaceSnapshots.at(ref)` — which never replays hooks, by design — cannot
+   * see it, and a `catalog:` specifier against it resolves to nothing on BOTH
+   * sides of a diff. Seeding the live hook-injected set, or the other side's
+   * set, restores a declared RANGE without executing any historical code.
+   *
+   * Defaults to absent, which makes the seed inert — exactly the behavior of
+   * every snapshot captured before this field existed.
+   */
+  readonly seededCatalogs: Schema.optionalKey<typeof CatalogSet>;
 }>, {}>;
 /**
  * The state of a whole workspace at one moment — its packages and its assembled
@@ -2736,7 +2816,16 @@ declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base {
    * unparseable string — is `Option.none()`, because there is no indirection to
    * resolve. Total.
    *
-   * A `catalog:` specifier the catalog set cannot resolve falls back to this
+   * A `catalog:` specifier resolves in three steps, and the order is the
+   * contract: this moment's own `catalogs` first,
+   * then `seededCatalogs` if one was supplied,
+   * then the `importerVersions` fallback below. The first two answer with a
+   * declared RANGE and the third with a concrete version, so a seeded snapshot
+   * reports a range change where an unseeded one could only report a version —
+   * which is the difference between a diff row and no row when both refs
+   * recorded the same installed version.
+   *
+   * A `catalog:` specifier neither catalog set can resolve falls back to this
    * snapshot's `importerVersions` — but only to a version
    * **every** importer recording that dependency agrees on. A catalog injected
    * by a config-dependency pnpmfile hook appears in no committed catalog source,
@@ -2773,6 +2862,101 @@ declare class WorkspaceStateSnapshot extends WorkspaceStateSnapshot_base {
    * @param specifier - The raw specifier string.
    */
   resolveIn(importerPath: string, dependency: string, specifier: string): Option.Option<string>;
+  /**
+   * This snapshot with `seed` as its `seededCatalogs`
+   * — catalogs consulted only where this moment's own catalogs cannot answer.
+   *
+   * @remarks
+   * Returns a NEW snapshot; the receiver is untouched, and the seed REPLACES
+   * any seed already present rather than merging with it (a snapshot is a
+   * value, and an accumulating seed would make precedence depend on call
+   * order). {@link WorkspaceStateSnapshot.crossSeed} is the deliberate
+   * exception: it composes the two seeds explicitly, precisely because a bare
+   * replace would discard a layer-level seed. `catalogs`, `packages` and `importerVersions` are carried through
+   * unchanged, so what the ref declared is still exactly what it declared.
+   *
+   * The two seeds worth reaching for: the LIVE hook-injected catalog set (from
+   * a `WorkspaceCatalogs` built by one of the config-dependency layers), or the
+   * other side of a two-ref diff — see
+   * {@link WorkspaceStateSnapshot.crossSeed}.
+   *
+   * @param seed - The catalogs to consult as a fallback.
+   *
+   * @example
+   * ```ts
+   * import { WorkspaceCatalogs, WorkspaceSnapshots } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const snapshots = yield* WorkspaceSnapshots;
+   *   const catalogs = yield* WorkspaceCatalogs;
+   *   // The live set includes hook-injected catalogs under a config-dependency
+   *   // layer; the ref's own set never can.
+   *   const live = yield* catalogs.set();
+   *   const before = (yield* snapshots.at("origin/main")).withSeededCatalogs(live);
+   *   return before.resolve("effect", "catalog:");
+   * });
+   * ```
+   */
+  withSeededCatalogs(seed: CatalogSet): WorkspaceStateSnapshot;
+  /**
+   * Both sides of a diff, each seeded with the other's catalogs.
+   *
+   * @remarks
+   * The two-ref symmetry the hook-catalog gap actually needs. A catalog
+   * injected by a config-dependency hook is declared in no committed source,
+   * so neither ref's snapshot can see it and a `catalog:` specifier against it
+   * resolves to nothing on both sides — a real version movement then produces
+   * no row. Cross-seeding restores a declared RANGE on whichever side is
+   * missing it, at strictly lower precedence than that side's own catalogs, so
+   * a genuine change between the refs still reads as a change.
+   *
+   * **The limitation is inherent and is not a defect to work around.** A range
+   * change made purely by bumping the config dependency BETWEEN the two refs is
+   * suppressed: neither committed source declares the catalog, so each side
+   * falls back to the other's value and the two agree by construction. Seeding
+   * the live hook-injected set via
+   * {@link WorkspaceStateSnapshot.withSeededCatalogs} has the same blind spot
+   * against history — recovering it would mean replaying each ref's pinned
+   * config-dependency code, which `at(ref)` will not do. If that case must be
+   * detected, diff `configDependencies` in `pnpm-workspace.yaml` directly; it
+   * is the only committed evidence that the injection changed.
+   *
+   * **The seeding relationship is symmetric; the RETURN ORDER is not.** Each
+   * snapshot is seeded with the other's catalogs, so neither argument is
+   * privileged and swapping them produces the same two values — but they come
+   * back mirroring the order they went in, so destructure in the order you
+   * passed. The `before`/`after` names describe the intended calling
+   * convention for a two-ref diff, not a constraint on what may be passed.
+   *
+   * **A seed already present on either snapshot is preserved**, beneath the
+   * other side's catalogs — which matters because
+   * `WorkspaceSnapshotsOptions.seedCatalogs` puts one there on every snapshot
+   * the service returns. Composing the two surfaces is therefore safe: the
+   * layer-level seed keeps answering what neither ref declared, while the
+   * other ref's committed declaration wins where it has one.
+   *
+   * @param before - One snapshot, conventionally the earlier one.
+   * @param after - The other snapshot, conventionally the later one.
+   * @returns Both snapshots in the order given, each carrying the other's
+   *   catalogs as its seed.
+   *
+   * @example
+   * ```ts
+   * import { WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const snapshots = yield* WorkspaceSnapshots;
+   *   const [before, after] = WorkspaceStateSnapshot.crossSeed(
+   *     yield* snapshots.at("origin/main"),
+   *     yield* snapshots.worktree(),
+   *   );
+   *   return { before: before.resolve("effect", "catalog:"), after: after.resolve("effect", "catalog:") };
+   * });
+   * ```
+   */
+  static crossSeed(before: WorkspaceStateSnapshot, after: WorkspaceStateSnapshot): readonly [WorkspaceStateSnapshot, WorkspaceStateSnapshot];
   /**
    * A `CatalogResolver` layer implementing `@effected/npm`'s contract against
    * THIS snapshot's catalog set — so code written to the contract resolves
@@ -2838,6 +3022,32 @@ interface WorkspaceSnapshotsOptions {
    *   first call is honoured.
    */
   readonly cwd?: string;
+  /**
+   * Catalogs every snapshot this service produces carries as its
+   * `seededCatalogs` — consulted only where the snapshot's own catalogs cannot
+   * answer.
+   *
+   * @remarks
+   * The layer-level spelling of `WorkspaceStateSnapshot.withSeededCatalogs`,
+   * for the common case where the seed is the same for every read: a consumer
+   * diffing many refs against one live workspace seeds once here instead of
+   * remembering to call `withSeededCatalogs` at each site — and a forgotten
+   * call is a silently missing diff row, not a type error.
+   *
+   * **This executes nothing.** The caller supplies the set; `at(ref)` still
+   * never replays config-dependency hooks and still never fetches. The
+   * deliberate at/worktree asymmetry is unchanged — this only lets a consumer
+   * who has already paid for the live set share it with the ref side.
+   *
+   * Applied to `worktree()` too, for symmetry. There it is usually inert: a
+   * live set assembled under a config-dependency layer already contains the
+   * hook-injected catalogs at full precedence, so the seed answers nothing the
+   * snapshot could not answer itself.
+   *
+   * @defaultValue absent — no seed, and resolution behaves exactly as before
+   *   this option existed.
+   */
+  readonly seedCatalogs?: CatalogSet;
 }
 /**
  * The {@link WorkspaceSnapshots} service shape.
@@ -2969,6 +3179,20 @@ interface WorkspacesOptions {
   /** Descent cap for segment-crossing `packages:` patterns. Defaults to 32. */
   readonly maxDepth?: number;
 }
+/**
+ * Options for the composites that additionally provide {@link WorkspaceSnapshots}
+ * — {@link Workspaces.layerWithGit} and the two config-dependency variants.
+ *
+ * @remarks
+ * {@link WorkspacesOptions} plus whatever {@link WorkspaceSnapshotsOptions}
+ * adds, so `seedCatalogs` reaches `at(ref)` through the composite instead of
+ * forcing a consumer to hand-compose the graph just to pass one option. The
+ * two interfaces agree on `cwd`, which stays one explicit concern applied
+ * uniformly.
+ *
+ * @public
+ */
+interface WorkspacesGitOptions extends WorkspacesOptions, WorkspaceSnapshotsOptions {}
 /**
  * Every service the git-free composite layer provides.
  *
@@ -3068,7 +3292,69 @@ declare class Workspaces {
    * provides `Git.layerTest({ … })` — git's own shipped double, whose
    * unstubbed members die named — and needs no repository on disk.
    */
-  static readonly layerWithGit: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  static readonly layerWithGit: (options?: WorkspacesGitOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * {@link Workspaces.layerWithGit} over
+   * {@link Workspaces.layerWithConfigDependencies} — snapshots, change
+   * detection and git, with catalog assembly that **replays config dependency
+   * `pnpmfile.cjs` hooks**.
+   *
+   * @remarks
+   * The composite that did not exist. `layerWithGit` hard-wires the no-op
+   * catalogs layer, so a consumer wanting snapshots + git + hook replay had to
+   * rebuild the entire service graph by hand — which is exactly what
+   * `@savvy-web/silk-effects` did, and the copy this static deletes.
+   *
+   * Requirements are unchanged from {@link Workspaces.layerWithGit}: a
+   * filesystem, a path service, and core's `ChildProcessSpawner` (behind
+   * `Git`). The in-process replay adds no requirement of its own — it is a
+   * dynamic `import()`, not a subprocess. **If the consumer is bundled, reach
+   * for {@link Workspaces.layerWithGitAndConfigDependenciesSubprocess}
+   * instead**; the computed import does not survive a bundler, and the
+   * `ChildProcessSpawner` the subprocess variant needs is already required
+   * here for git, so on this composite the subprocess form costs nothing extra.
+   *
+   * Opt in deliberately: this executes config-dependency code in process, and
+   * {@link Workspaces.layerWithGit} never does.
+   *
+   * **Bind the result to a `const`.** A parameterized factory mints a fresh
+   * reference per call and layers memoize by reference.
+   *
+   * @example
+   * ```ts
+   * import { Workspaces } from "@effected/workspaces";
+   *
+   * const KitLayer = Workspaces.layerWithGitAndConfigDependencies();
+   * ```
+   */
+  static readonly layerWithGitAndConfigDependencies: (options?: WorkspacesGitOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * {@link Workspaces.layerWithGitAndConfigDependencies}, with the hook replay
+   * in a `node` **child process** rather than in process.
+   *
+   * @remarks
+   * Same typed semantics; the difference is mechanism, and it decides whether
+   * catalog assembly works at all in a **bundled** consumer — see
+   * {@link Workspaces.layerWithConfigDependenciesSubprocess} for why the
+   * in-process computed `import()` dies under a bundler.
+   *
+   * **This composite's requirement set is identical to the in-process one.**
+   * The subprocess replay needs core's `ChildProcessSpawner`, which this
+   * composite already requires for `Git` — so unlike the git-free pair, there
+   * is no R-widening to weigh here and a bundled consumer pays nothing to be
+   * correct. Prefer this variant whenever the program ships as a bundle.
+   *
+   * **Bind the result to a `const`.**
+   *
+   * @example
+   * ```ts
+   * import { Workspaces } from "@effected/workspaces";
+   *
+   * // A bundled CLI or MCP server: the computed import never enters the graph.
+   * const KitLayer = Workspaces.layerWithGitAndConfigDependenciesSubprocess();
+   * ```
+   */
+  static readonly layerWithGitAndConfigDependenciesSubprocess: (options?: WorkspacesGitOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
   /**
    * This package's implementation of `@effected/commands`' `LocalExec`
    * contract: how to run a project-local binary here.
@@ -3454,5 +3740,5 @@ interface GetWorkspacePackagesSyncOptions extends WorkspacesSyncOptions {
  */
 declare const getWorkspacePackagesSync: (root: string, options: GetWorkspacePackagesSyncOptions) => ReadonlyArray<WorkspacePackage>;
 //#endregion
-export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncDirectoryEntry, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
+export { type CatalogAssemblyFailure, CatalogSet, ChangeDetectionError, type ChangeDetectionFailure, ChangeDetectionOptions, ChangeDetector, type ChangeDetectorShape, type ClassifyOptions, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, NoPeerDependencyRules, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerEvidence, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PeerCheck, type PeerCheckOptions, type PeerDependencyRules, PeerParent, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncDirectoryEntry, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, UnsatisfiedPeer, type UnverifiedReason, type VersioningDetectOptions, VersioningStrategy, VersioningStrategyType, WORKSPACE_MARKERS, WorkspaceCatalogs, type WorkspaceCatalogsOptions, type WorkspaceCatalogsShape, WorkspaceDiscovery, WorkspaceDiscoveryError, type WorkspaceDiscoveryFailure, type WorkspaceDiscoveryOptions, type WorkspaceDiscoveryShape, WorkspaceInfo, type WorkspaceLookupFailure, WorkspaceManifestError, WorkspacePackage, WorkspacePatternError, WorkspaceRoot, WorkspaceRootNotFoundError, type WorkspaceRootShape, type WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesGitOptions, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, classifyTag, findWorkspaceRootSync, getWorkspacePackagesSync };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.17.1",
+	"version": "0.18.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": [
@@ -49,12 +49,12 @@
 		"@effected/commands": "^0.5.0",
 		"@effected/git": "^0.9.0",
 		"@effected/glob": "^0.4.0",
-		"@effected/lockfiles": "^0.6.2",
+		"@effected/lockfiles": "^0.6.3",
 		"@effected/npm": "^0.11.1",
 		"@effected/package-json": "^0.10.2",
 		"@effected/semver": "^0.5.0",
 		"@effected/walker": "^0.5.0",
-		"@effected/yaml": "^0.10.0",
+		"@effected/yaml": "^0.11.0",
 		"@pnpm/catalogs.config": "^1100.0.5",
 		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
 		"@pnpm/catalogs.resolver": "^1100.0.0",

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.13"
+      "packageVersion": "7.59.0"
     }
   ]
 }