@effected/workspaces 0.7.0 → 0.9.0

package/index.d.ts

@@ -4,6 +4,7 @@ import { CatalogAssemblyError, CatalogResolver, DependencyResolutionError, Manif
 import { GlobPattern } from "@effected/glob";
 import { Lockfile, LockfileFramingError, LockfileIntegrity, LockfileParseError, ResolvedPackage, WorkspaceManifest } from "@effected/lockfiles";
 import { Package } from "@effected/package-json";
+import { LocalExec } from "@effected/commands";
 import { ChildProcessSpawner } from "effect/unstable/process";
 //#region src/WorkspacePackage.d.ts
 declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
@@ -1046,10 +1047,21 @@ declare class PackageManagerDetectionError extends PackageManagerDetectionError_
  * @public
  */
 type PackageManagerDetectionFailure = PackageManagerDetectionError | WorkspaceManifestError;
-declare const PackageManagerDetector_base: Context.ServiceClass<PackageManagerDetector, "@effected/workspaces/PackageManagerDetector", {
+/**
+ * The {@link PackageManagerDetector} service shape.
+ *
+ * @remarks
+ * Exported so a consumer can type a bespoke double against the contract without
+ * reaching into the class — the `WorkspaceDiscoveryShape` /
+ * `PublishabilityDetectorShape` convention.
+ *
+ * @public
+ */
+interface PackageManagerDetectorShape {
   /** Detect the package manager at a workspace root. */
   readonly detect: (root: string) => Effect.Effect<DetectedPackageManager, PackageManagerDetectionFailure>;
-}>;
+}
+declare const PackageManagerDetector_base: Context.ServiceClass<PackageManagerDetector, "@effected/workspaces/PackageManagerDetector", PackageManagerDetectorShape>;
 /**
  * Detects which package manager owns a workspace root.
  *
@@ -1098,6 +1110,50 @@ declare class PackageManagerDetector extends PackageManagerDetector_base {
   }, never, FileSystem.FileSystem | Path.Path>;
   /** The live layer. */
   static readonly layer: Layer.Layer<PackageManagerDetector, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The sanctioned in-memory double.
+   *
+   * @remarks
+   * **`detect` has no honest default, so an unstubbed call dies** — the
+   * `WorkspaceDiscovery.info` posture, for the same reason. A stand-in that
+   * answered `"pnpm"` would hand a consumer a fact nothing established, and it
+   * would contradict the very service it stands in for: the live detector's
+   * defining property is that it [refuses to
+   * guess](https://github.com/spencerbeggs/effected) when no evidence matches.
+   * A double that guesses is worse than no double.
+   *
+   * Failing typed would be the subtler mistake: `PackageManagerDetectionError`
+   * reads as a legitimate "no manager here" answer, so a consumer would branch
+   * on it and proceed, never learning that the test simply forgot to stub.
+   *
+   * @param overrides - Members to supply; anything omitted dies on use.
+   *
+   * @example
+   * ```ts
+   * import { DetectedPackageManager, PackageManagerDetector } from "@effected/workspaces";
+   * import { Effect, Option } from "effect";
+   *
+   * const TestDetector = PackageManagerDetector.layerTest({
+   *   detect: () =>
+   *     Effect.succeed(
+   *       DetectedPackageManager.make({ name: "pnpm", version: Option.none(), runtime: "node" }),
+   *     ),
+   * });
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<PackageManagerDetectorShape>) => PackageManagerDetectorShape;
+  /**
+   * {@link PackageManagerDetector.makeTest} behind `Layer.succeed`.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * Pairs with `WorkspaceRoot.layerTest` and `WorkspaceDiscovery.layerTest` to
+   * stand up the whole discovery path with no filesystem at all.
+   */
+  static readonly layerTest: (overrides?: Partial<PackageManagerDetectorShape>) => Layer.Layer<PackageManagerDetector>;
 }
 //#endregion
 //#region src/LockfileReader.d.ts
@@ -1212,6 +1268,65 @@ declare class LockfileReader extends LockfileReader_base {
    * `const` and reuse it.
    */
   static readonly layer: (options?: LockfileReaderOptions) => Layer.Layer<LockfileReader, never, WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double satisfying the full {@link LockfileReaderShape} with no
+   * filesystem, root walk, or package-manager detection.
+   *
+   * @remarks
+   * There is **no honest default lockfile**: an empty one that looks like a
+   * legitimate answer is indistinguishable from "this workspace resolves
+   * nothing" — the silent-empty failure class this package documents on the
+   * live paths — so `read` **dies** with an instructive defect until stubbed.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `read` override is supplied,
+   * `resolvedVersion` answers as the live service does — the **first** entry
+   * of `lockfile.packagesNamed(name)` in lockfile order, `Option.none()` on a
+   * miss — so the two stay consistent by construction. `integrity` is **not**
+   * derivable: the live method compares the lockfile against the workspace
+   * manifests discovery enumerates, and the double has no discovery to ask, so
+   * it dies unless stubbed.
+   *
+   * `refresh` defaults to `Effect.void` honestly: the live contract is "drop
+   * the memoized read so the next call re-reads", and this double memoizes
+   * nothing — every `read()` call re-invokes the override — so there is
+   * nothing to drop and the no-op is truthful, the same reasoning as
+   * `WorkspaceDiscovery.makeTest`'s `refresh`.
+   *
+   * @example
+   * ```ts
+   * import { Lockfile } from "@effected/lockfiles";
+   * import { LockfileReader } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = LockfileReader.makeTest({
+   *   read: () =>
+   *     Effect.succeed(
+   *       Lockfile.make({ format: "pnpm", lockfileVersion: "9.0", packages: [], workspaceDependencies: [] }),
+   *     ),
+   * });
+   * // `resolvedVersion` now answers consistently from that lockfile.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<LockfileReaderShape>) => LockfileReaderShape;
+  /**
+   * The test layer: {@link LockfileReader.makeTest} behind `Layer.succeed`, so
+   * a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { LockfileReader } from "@effected/workspaces";
+   *
+   * const TestLockfiles = LockfileReader.layerTest();
+   * // program.pipe(Effect.provide(TestLockfiles)) — dies loudly if touched.
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<LockfileReaderShape>) => Layer.Layer<LockfileReader>;
 }
 //#endregion
 //#region src/Publishability.d.ts
@@ -1318,8 +1433,422 @@ declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDe
  * @public
  */
 declare class PublishabilityDetector extends PublishabilityDetector_base {
-  /** Standard npm publishing semantics. Pure — no filesystem, no platform services. */
-  static readonly layer: Layer.Layer<PublishabilityDetector>;
+  /**
+   * Standard npm publishing semantics, **as a value**. Pure — no filesystem,
+   * no platform services.
+   *
+   * @remarks
+   * Exposed as a shape and not only as a layer, because a consumer composing
+   * *around* these rules cannot reach them through a layer without re-entering
+   * the very tag it is replacing. `@savvy-web/silk-effects` had to write
+   * `Effect.provide(PublishabilityDetector, PublishabilityDetector.layer)`
+   * **inside its own implementation of that tag** to get at this function for
+   * its pass-through branch; with the value exposed that becomes
+   * `PublishabilityDetector.npm.detect(pkg)`.
+   *
+   * @example
+   * ```ts
+   * import { PublishabilityDetector } from "@effected/workspaces";
+   * import { Effect, Layer } from "effect";
+   *
+   * // A policy that defers to npm semantics for everything it does not veto.
+   * const withVeto = Layer.succeed(PublishabilityDetector, {
+   *   detect: (pkg) =>
+   *     pkg.name.endsWith("-private")
+   *       ? Effect.succeed([])
+   *       : PublishabilityDetector.npm.detect(pkg),
+   * });
+   * ```
+   */
+  static readonly npm: PublishabilityDetectorShape;
+  /** Nothing publishes. */
+  static readonly none: PublishabilityDetectorShape;
+  /**
+   * {@link PublishabilityDetector.npm} as a layer.
+   *
+   * @remarks
+   * Named for its policy rather than called `layer`, deliberately. **No
+   * composite in this package provides a publishability detector**: a
+   * `Workspaces.layer()` that quietly supplied npm semantics made the choice
+   * invisible, and worse, made a naively-ordered override lose to it in
+   * silence — `Layer.mergeAll(myDetector, Workspaces.layer())` resolved to the
+   * default, because `mergeAll` is last-wins. For a service that decides
+   * whether a package publishes and to which registry, that silent revert was
+   * the worst available failure. The requirement now sits in `R`, so the
+   * choice is made once, explicitly, and unmade wiring does not compile.
+   */
+  static readonly layerNpm: Layer.Layer<PublishabilityDetector>;
+  /**
+   * {@link PublishabilityDetector.none} as a layer: a workspace where nothing
+   * publishes.
+   *
+   * @remarks
+   * For dry runs, and for a release tool whose configuration disables
+   * publishing wholesale — silk's changeset `mode: "none"` is exactly this.
+   */
+  static readonly layerNone: Layer.Layer<PublishabilityDetector>;
+}
+//#endregion
+//#region src/ReleaseTag.d.ts
+/**
+ * Whether one shared tag names a whole release, or one tag names each package.
+ *
+ * @remarks
+ * `single` is the shape of a single-package repo and of a monorepo whose
+ * publishable packages all version in lockstep; `scoped` is the shape of
+ * independent versioning, where a shared tag would be ambiguous.
+ *
+ * @public
+ */
+declare const TagStyle: Schema.Literals<readonly ["single", "scoped"]>;
+/**
+ * The decoded type of {@link (TagStyle:variable)}: `"single" | "scoped"`.
+ *
+ * @public
+ */
+type TagStyle = typeof TagStyle.Type;
+/**
+ * Formatting knobs for {@link ReleaseTag.single} and {@link ReleaseTag.scoped}.
+ *
+ * @public
+ */
+interface TagFormatOptions {
+  /**
+   * The prefix on the version segment.
+   *
+   * @remarks
+   * Defaults to `""` uniformly, for both {@link ReleaseTag.single} and
+   * {@link ReleaseTag.scoped} — strict SemVer, deliberately chosen. Pass
+   * `"v"` for the GitHub release-tag convention (`v1.2.3`), which tools such
+   * as `actions/checkout`'s ref resolution and third-party changelog
+   * generators expect.
+   */
+  readonly versionPrefix?: string;
+}
+/**
+ * Options for {@link TrackingTag.forVersion}.
+ *
+ * @public
+ */
+interface TrackingTagOptions {
+  /**
+   * Prefix the alias with a package name, for a monorepo that namespaces its
+   * tags: `@scope/pkg@v1`. Omit it for a single-package repo's bare `v1`.
+   */
+  readonly packageName?: string;
+  /**
+   * Which aliases to derive. `"both"` (the default) gives `v1` and `v1.2`;
+   * `"major"` gives only the broad `v1`.
+   */
+  readonly precision?: "major" | "both";
+  /**
+   * Derive aliases for a prerelease version too. **Off by default, and you
+   * almost certainly want it off** — see {@link TrackingTag.forVersion}.
+   */
+  readonly includePrerelease?: boolean;
+}
+declare const TrackingTag_base: Schema.Class<TrackingTag, Schema.Struct<{
+  /** The tag string exactly as it appears in git. */
+  readonly value: Schema.NonEmptyString;
+  /** The package the alias namespaces; absent on a bare `v1`. */
+  readonly packageName: Schema.optionalKey<Schema.NonEmptyString>;
+  /** The major version the alias tracks. */
+  readonly major: Schema.Int;
+  /** The minor version, on a `v1.2`-precision alias; absent on `v1`. */
+  readonly minor: Schema.optionalKey<Schema.Int>;
+}>, {}>;
+/**
+ * A floating alias tag — `v1`, `v1.2` — that a repo re-points at its newest
+ * matching release.
+ *
+ * @remarks
+ * This is the GitHub Actions distribution convention: a consumer writes
+ * `uses: owner/repo@v1` and receives whatever 1.x the repo last pointed `v1` at.
+ *
+ * **Deliberately not SemVer, and deliberately not a {@link (TagStyle:variable)}.**
+ * A release tag names one immutable version; a tracking tag is an alias derived
+ * *from* a version, carrying a truncated number that is not a version at all.
+ * Folding it into `ReleaseTag` as a third style would put a mutable pointer and
+ * an immutable name behind one type.
+ *
+ * Everything here is derivation, formatting and parsing. **Actually moving a
+ * git tag is not this package's business** — a consumer does that through git,
+ * and the deliberate omission is what keeps this module a pure leaf.
+ *
+ * @example
+ * ```ts
+ * import { TrackingTag } from "@effected/workspaces";
+ *
+ * TrackingTag.forVersion("1.2.3").map((t) => t.value);        // ["v1", "v1.2"]
+ * TrackingTag.forVersion("1.0.0-beta.3");                     // [] — never float onto a beta
+ * TrackingTag.forVersion("1.2.3", { packageName: "@acme/cli" });
+ * // ["@acme/cli@v1", "@acme/cli@v1.2"]
+ * ```
+ *
+ * @public
+ */
+declare class TrackingTag extends TrackingTag_base {
+  /** Whether this alias tracks a whole major line, or one minor line inside it. */
+  get precision(): "major" | "minor";
+  /**
+   * The tracking tags a release of `version` should be pointed at.
+   *
+   * @remarks
+   * **A prerelease derives nothing.** Anyone depending on `owner/repo@v1` is
+   * asking for the newest *stable* 1.x, so re-pointing that alias at
+   * `1.0.0-beta.3` would ship a prerelease to every such consumer with no
+   * signal at all. `includePrerelease` exists for callers who genuinely mean
+   * it — a prerelease-only distribution channel — and should be rare.
+   *
+   * **Total, never throwing.** A version that is not `X.Y.Z` derives nothing
+   * rather than failing: this is a query about a version, not a validation of
+   * one, and `WorkspacePackage.version` is deliberately tolerant, so odd
+   * versions reach here routinely.
+   *
+   * 0.x versions DO derive aliases. Floating `v0` across 0.x minors is a real
+   * hazard, but which aliases to publish is the caller's policy, decided where
+   * the tags are moved — not something a derivation should quietly withhold.
+   *
+   * @param version - The version being released.
+   * @param options - Package prefix, precision and the prerelease override.
+   * @returns The aliases, broadest first; empty when none apply.
+   */
+  static forVersion(version: string, options?: TrackingTagOptions): ReadonlyArray<TrackingTag>;
+}
+/**
+ * What an arbitrary tag string denotes.
+ *
+ * @remarks
+ * `unrecognized` is a real answer, not a failure: a repository's tags include
+ * branches-turned-tags, `latest`, and whatever else humans wrote, and forcing
+ * those into a bucket is exactly what a classifier must not do.
+ *
+ * @public
+ */
+type TagClassification = {
+  readonly kind: "release";
+  readonly tag: ReleaseTag;
+} | {
+  readonly kind: "tracking";
+  readonly tag: TrackingTag;
+} | {
+  readonly kind: "unrecognized";
+};
+/**
+ * Decide whether a tag string is a release tag, a tracking alias, or neither.
+ *
+ * @remarks
+ * The two families are told apart by **segment count**, not by the `v` prefix:
+ * three numeric segments is a version (so `1.0.0` and `v1.0.0` are both release
+ * tags), while one or two segments is a truncated alias. The `v` *is* required
+ * on an alias — a bare `1` is neither valid SemVer nor the tracking convention,
+ * and accepting it would make this function guess.
+ *
+ * The package prefix splits at the **last** `@`, so a leading npm scope
+ * survives: `@scope/pkg@1.0.0` is package `@scope/pkg` at version `1.0.0`.
+ *
+ * Round-tripping is a tested property: every tag {@link ReleaseTag} and
+ * {@link TrackingTag} format classifies back to the family that produced it,
+ * with its fields intact.
+ *
+ * @param tag - Any tag string.
+ * @returns The classification.
+ *
+ * @public
+ */
+declare const classifyTag: (tag: string) => TagClassification;
+declare const ReleaseTag_base: Schema.Class<ReleaseTag, Schema.Struct<{
+  /** The tag string exactly as it appears in git. */
+  readonly value: Schema.NonEmptyString;
+  /** The package the tag names; absent on a workspace-wide single tag. */
+  readonly packageName: Schema.optionalKey<Schema.NonEmptyString>;
+  /** The version the tag names, without any prefix. */
+  readonly version: Schema.NonEmptyString;
+  /** Which style produced it. */
+  readonly style: Schema.Literals<readonly ["single", "scoped"]>;
+}>, {}>;
+/**
+ * A git tag naming a release, and the parts it was built from.
+ *
+ * @remarks
+ * `value` is the tag exactly as it appears in git; `version` stays **bare**
+ * even when `value` carries a prefix, so a consumer comparing versions never
+ * has to strip one back off.
+ *
+ * Formatting is **total**: there is no error channel, because the only failure
+ * v3 modelled — an empty version — is caught by `Schema.NonEmptyString` when
+ * the value is constructed. A bad version reaching these statics is developer
+ * wiring rather than untrusted input, so it dies as a defect, the same posture
+ * as an uncompilable glob literal in `WorkspacePackage.matchesDependency`.
+ *
+ * @example
+ * ```ts
+ * import { ReleaseTag } from "@effected/workspaces";
+ *
+ * ReleaseTag.single("1.2.3").value;               // "1.2.3"
+ * ReleaseTag.scoped("@acme/cli", "1.2.3").value;  // "@acme/cli@1.2.3"
+ * ReleaseTag.scoped("cli", "1.2.3").value;        // "cli@1.2.3"
+ * ReleaseTag.scoped("cli", "1.2.3", { versionPrefix: "v" }).value; // "cli@v1.2.3"
+ * ```
+ *
+ * @public
+ */
+declare class ReleaseTag extends ReleaseTag_base {
+  /**
+   * One shared tag for a whole release: `1.2.3`.
+   *
+   * @param version - The version being released. Must not be empty.
+   * @param options - Formatting overrides.
+   */
+  static single(version: string, options?: TagFormatOptions): ReleaseTag;
+  /**
+   * A per-package tag: `<packageName>@<version>` — `@scope/pkg@1.2.3` for a
+   * scoped name, `pkg@1.2.3` for an unscoped one, uniformly, unless
+   * `options.versionPrefix` says otherwise.
+   *
+   * @param packageName - The package being released. Must not be empty.
+   * @param version - The version being released. Must not be empty.
+   * @param options - Formatting overrides.
+   */
+  static scoped(packageName: string, version: string, options?: TagFormatOptions): ReleaseTag;
+}
+//#endregion
+//#region src/VersioningStrategy.d.ts
+/**
+ * How a workspace assigns versions across its publishable packages.
+ *
+ * @remarks
+ * - `single` — zero or one publishable package, so one tag names the release.
+ * - `fixed-group` — every publishable package sits inside one group that
+ *   versions in lockstep, so one tag still names the release.
+ * - `independent` — publishable packages version separately, so a shared tag
+ *   would be ambiguous and each package needs its own.
+ *
+ * @public
+ */
+declare const VersioningStrategyType: Schema.Literals<readonly ["single", "fixed-group", "independent"]>;
+/**
+ * The decoded type of {@link (VersioningStrategyType:variable)}.
+ *
+ * @public
+ */
+type VersioningStrategyType = typeof VersioningStrategyType.Type;
+/**
+ * Arguments to {@link VersioningStrategy.classify}.
+ *
+ * @public
+ */
+interface ClassifyOptions {
+  /** Publishable package names, in any order. Duplicates are collapsed. */
+  readonly packages: ReadonlyArray<string>;
+  /**
+   * Groups of packages that version in lockstep.
+   *
+   * @remarks
+   * A **plain argument, deliberately.** Fixed groups are a release tool's
+   * concept — changesets writes them to `.changeset/config.json` — and a
+   * workspace-model package that read that file would be taking on one tool's
+   * schema and one tool's release policy. The caller reads its own tool's
+   * config and hands the groups in. Groups may name packages that are not
+   * publishable, or do not exist; only whether some single group covers the
+   * whole publishable set matters.
+   */
+  readonly fixedGroups?: ReadonlyArray<ReadonlyArray<string>>;
+}
+/**
+ * Arguments to {@link VersioningStrategy.detect}.
+ *
+ * @public
+ */
+interface VersioningDetectOptions {
+  /** See {@link ClassifyOptions.fixedGroups}. Defaults to none. */
+  readonly fixedGroups?: ReadonlyArray<ReadonlyArray<string>>;
+}
+/**
+ * One entry in a release batch: which package went out, at which version.
+ *
+ * @remarks
+ * Deliberately structural and minimal — a caller passes whatever it already
+ * has (a publish result, a changeset plan row) without projecting it into a
+ * package-specific type first.
+ *
+ * @public
+ */
+interface PackageRelease {
+  /** The package that was released. */
+  readonly name: string;
+  /** The version it was released at. */
+  readonly version: string;
+}
+declare const VersioningStrategy_base: Schema.Class<VersioningStrategy, Schema.Struct<{
+  /** The classification. */
+  readonly type: Schema.Literals<readonly ["single", "fixed-group", "independent"]>;
+  /** The groups classification was performed against, as supplied. */
+  readonly fixedGroups: Schema.$Array<Schema.$Array<Schema.String>>;
+  /** The publishable package names, sorted and de-duplicated. */
+  readonly publishablePackages: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * How a workspace versions, and the tagging that follows from it.
+ *
+ * @remarks
+ * Built either purely with {@link VersioningStrategy.classify}, or from a live
+ * workspace with {@link VersioningStrategy.detect}.
+ *
+ * @example
+ * ```ts
+ * import { VersioningStrategy } from "@effected/workspaces";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const strategy = yield* VersioningStrategy.detect({ fixedGroups });
+ *   return strategy.tagsFor(released).map((tag) => tag.value);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class VersioningStrategy extends VersioningStrategy_base {
+  /**
+   * Whether a release needs one tag per package rather than one shared tag.
+   */
+  get perPackageTags(): boolean;
+  /** The tag style this strategy implies. */
+  get tagStyle(): TagStyle;
+  /**
+   * Classify a workspace from its publishable package names and fixed groups.
+   *
+   * @remarks
+   * Pure and total — no IO, no error channel. `packages` is sorted and
+   * de-duplicated first, so a name listed twice cannot inflate a one-package
+   * repo into an independent one.
+   */
+  static classify(options: ClassifyOptions): VersioningStrategy;
+  /**
+   * Classify the ambient workspace: enumerate its packages, keep the ones the
+   * {@link PublishabilityDetector} says publish somewhere, and classify those.
+   *
+   * @remarks
+   * The publishability question is asked through the service precisely so a
+   * consumer with its own rules — honouring a release tool's ignore list, say —
+   * swaps the layer instead of filtering afterwards.
+   */
+  static readonly detect: (options?: VersioningDetectOptions | undefined) => Effect.Effect<VersioningStrategy, WorkspaceDiscoveryFailure, PublishabilityDetector | WorkspaceDiscovery>;
+  /**
+   * The tags a release of `releases` produces under this strategy.
+   *
+   * @remarks
+   * Under `independent` this is one {@link ReleaseTag} per release, in the
+   * order given. Under `single` and `fixed-group` it is exactly one shared tag
+   * carrying the **first** release's version — every release in a lockstep
+   * batch shares a version by construction, so the choice is only visible on a
+   * batch that should not exist. Whether a batch actually agreed is a property
+   * of that batch rather than of the workspace, so it stays the caller's
+   * one-line check rather than a field here.
+   *
+   * An empty batch produces no tags under either style.
+   */
+  tagsFor(releases: ReadonlyArray<PackageRelease>, options?: TagFormatOptions): ReadonlyArray<ReleaseTag>;
 }
 //#endregion
 //#region src/WorkspaceCatalogs.d.ts
@@ -1553,6 +2082,61 @@ declare class WorkspaceCatalogs extends WorkspaceCatalogs_base {
    * Parameterized, so bind it to a `const` and reuse it.
    */
   static readonly layerWithConfigDependencies: (options?: WorkspaceCatalogsOptions) => Layer.Layer<WorkspaceCatalogs, never, WorkspaceRoot | LockfileReader | FileSystem.FileSystem | Path.Path>;
+  /**
+   * A test double satisfying the full {@link WorkspaceCatalogsShape} with no
+   * filesystem, lockfile read, or hook replay.
+   *
+   * @remarks
+   * There is **no honest default catalog set**: an empty `CatalogSet` that
+   * looks like a legitimate answer is the "every dependency looks newly added"
+   * failure class the live assembler hard-fails to prevent, so every method
+   * **dies** with an instructive defect until stubbed — a test-wiring mistake
+   * fails loudly as a defect rather than succeeding with a lie or failing with
+   * a dishonest typed error.
+   *
+   * The one derivation mirrors `WorkspaceDiscovery.makeTest`'s
+   * derived-from-the-primary rule: when a `set` override is supplied,
+   * `resolveSpecifier` answers from that `CatalogSet`'s own
+   * {@link CatalogSet.resolveSpecifier} — exactly what the live service runs
+   * over its assembled set — so the two stay consistent by construction.
+   * `releaseAgeGate` and `importerVersions` are **not** derivable from a
+   * catalog set (the gate comes from release-age keys and hook contributions,
+   * the importer index from the lockfile's importer blocks — neither is in a
+   * `CatalogSet`) and always die unless stubbed.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const double = WorkspaceCatalogs.makeTest({
+   *   set: () => Effect.succeed(CatalogSet.fromCatalogs({ default: { effect: "4.0.0" } })),
+   * });
+   * // `resolveSpecifier` now answers consistently from that set.
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceCatalogsShape>) => WorkspaceCatalogsShape;
+  /**
+   * The test layer: {@link WorkspaceCatalogs.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceCatalogs } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestCatalogs = WorkspaceCatalogs.layerTest({
+   *   set: () => Effect.succeed(CatalogSet.empty()),
+   * });
+   * // program.pipe(Effect.provide(TestCatalogs))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceCatalogsShape>) => Layer.Layer<WorkspaceCatalogs>;
   /**
    * The real implementation of `@effected/npm`'s `CatalogResolver` contract —
    * the one `@effected/package-json` declares but cannot fill.
@@ -1828,6 +2412,62 @@ declare class WorkspaceSnapshots extends WorkspaceSnapshots_base {
    * `const` and reuse it, or layer memoization does not apply.
    */
   static readonly layer: (options?: WorkspaceSnapshotsOptions) => Layer.Layer<WorkspaceSnapshots, never, Git | WorkspaceRoot | WorkspaceDiscovery | WorkspaceCatalogs>;
+  /**
+   * A test double satisfying the full {@link WorkspaceSnapshotsShape} with no
+   * git, filesystem, discovery, or catalog assembly.
+   *
+   * @remarks
+   * There are **no honest defaults and no derivations** here: `at(ref)` and
+   * `worktree()` are two independent reads of two different sources (a git ref
+   * vs. the live tree), so neither can be honestly derived from the other, and
+   * a fabricated empty {@link WorkspaceStateSnapshot} on either side of a
+   * before/after diff reads as every dependency newly added or removed — the
+   * exact silent-empty failure class this package documents on the live paths.
+   * Both methods therefore **die** with an instructive defect until stubbed; a
+   * test-wiring mistake fails loudly as a defect rather than succeeding with a
+   * lie.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const empty = WorkspaceStateSnapshot.make({
+   *   packages: [],
+   *   catalogs: CatalogSet.empty(),
+   *   importerVersions: {},
+   * });
+   * const double = WorkspaceSnapshots.makeTest({
+   *   at: () => Effect.succeed(empty),
+   *   worktree: () => Effect.succeed(empty),
+   * });
+   * ```
+   */
+  static readonly makeTest: (overrides?: Partial<WorkspaceSnapshotsShape>) => WorkspaceSnapshotsShape;
+  /**
+   * The test layer: {@link WorkspaceSnapshots.makeTest} behind `Layer.succeed`,
+   * so a suite provides only the methods it exercises.
+   *
+   * @remarks
+   * A parameterized layer factory mints a **fresh reference per call**, and
+   * layers memoize by reference — bind the result to a `const` and reuse it
+   * rather than calling `layerTest(...)` at each composition site.
+   *
+   * @example
+   * ```ts
+   * import { CatalogSet, WorkspaceSnapshots, WorkspaceStateSnapshot } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const TestSnapshots = WorkspaceSnapshots.layerTest({
+   *   worktree: () =>
+   *     Effect.succeed(
+   *       WorkspaceStateSnapshot.make({ packages: [], catalogs: CatalogSet.empty(), importerVersions: {} }),
+   *     ),
+   * });
+   * // program.pipe(Effect.provide(TestSnapshots))
+   * ```
+   */
+  static readonly layerTest: (overrides?: Partial<WorkspaceSnapshotsShape>) => Layer.Layer<WorkspaceSnapshots>;
 }
 //#endregion
 //#region src/Workspaces.d.ts
@@ -1852,20 +2492,206 @@ interface WorkspacesOptions {
  *
  * @public
  */
-type WorkspacesServices = WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | LockfileReader | WorkspaceCatalogs | PublishabilityDetector;
+type WorkspacesServices = WorkspaceRoot | PackageManagerDetector | WorkspaceDiscovery | LockfileReader | WorkspaceCatalogs;
 /**
  * The composite layers.
  *
  * @public
  */
-declare const Workspaces: {
-  readonly layer: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices, never, FileSystem.FileSystem | Path.Path>;
-  readonly layerWithConfigDependencies: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices, never, FileSystem.FileSystem | Path.Path>;
-  readonly layerWithGit: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices | ChangeDetector | WorkspaceSnapshots | Git, never, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
-  readonly resolveManifest: (manifest: Manifest, options?: WorkspacesOptions) => Effect.Effect<Manifest, CatalogAssemblyError | DependencyResolutionError | UnresolvedDependencyError, FileSystem.FileSystem | Path.Path>;
-  readonly resolverLayer: (options?: WorkspacesOptions) => Layer.Layer<CatalogResolver | WorkspaceResolver, never, FileSystem.FileSystem | Path.Path>;
-  readonly resolvers: Layer.Layer<CatalogResolver | WorkspaceResolver, never, WorkspaceCatalogs | WorkspaceDiscovery>;
-};
+declare class Workspaces {
+  private constructor();
+  /**
+   * Every service that needs only a filesystem: root, package-manager
+   * detection, discovery, lockfile reading, catalogs and publishability.
+   *
+   * @remarks
+   * Requires core `FileSystem` and `Path`, which the consumer provides at the
+   * edge (`@effect/platform-node`, `@effect/platform-bun`, or a test's
+   * `FileSystem.layerNoop`).
+   *
+   * **Bind the result to a `const`.** This is a parameterized factory and
+   * layers memoize by reference, so calling it twice builds everything twice.
+   *
+   * @example
+   * ```ts
+   * import { Workspaces } from "@effected/workspaces";
+   * import { Layer } from "effect";
+   *
+   * const WorkspacesLayer = Workspaces.layer();
+   * const AppLayer = Layer.provide(WorkspacesLayer, PlatformLayer);
+   * ```
+   */
+  static readonly layer: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The git-free composite, but with catalog assembly that **replays config
+   * dependency `pnpmfile.cjs` hooks** —
+   * {@link WorkspaceCatalogs.layerWithConfigDependencies} in place of the
+   * default no-op catalogs layer.
+   *
+   * @remarks
+   * Identical requirement set to {@link Workspaces.layer}; the only
+   * difference is that config-dependency code is executed in process. Opt in
+   * deliberately — the default {@link Workspaces.layer} never executes
+   * config-dependency code.
+   *
+   * **Bind the result to a `const`.**
+   */
+  static readonly layerWithConfigDependencies: (options?: WorkspacesOptions) => Layer.Layer<WorkspacesServices, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The git-free composite plus {@link ChangeDetector} and
+   * {@link WorkspaceSnapshots}, over `@effected/git`'s `Git` service.
+   *
+   * @remarks
+   * The extra requirement is core's `ChildProcessSpawner` (behind `Git`),
+   * which is why it is a separate layer rather than a flag: a consumer that
+   * never detects changes or reads at a ref should not have to be able to
+   * spawn a subprocess. The consumer provides `ChildProcessSpawner` once at
+   * the edge (`@effect/platform-node`'s `NodeServices.layer`); a test
+   * provides `Layer.succeed(Git, …)` and needs no repository on disk.
+   */
+  static readonly layerWithGit: (options?: WorkspacesOptions) => 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.
+   *
+   * @remarks
+   * **An inverted contract, the `@effected/npm` `CatalogResolver`
+   * precedent.** Tool discovery needs package-manager detection and
+   * workspace-root resolution, both of which live here — but a direct edge
+   * from `@effected/commands` to this package would make that boundary-tier
+   * package integrated, and through the planned `npm` → `commands` edge
+   * would drag `npm`, `lockfiles` (pure!) and `package-json` up a tier with
+   * it. So `commands` declares the narrow contract and we ship the layer.
+   *
+   * **The argv knowledge is not duplicated.** `LocalExec.prefixes(name)` is
+   * the one home of the four managers' `exec`/`dlx` prefixes; this layer
+   * detects *which* manager owns the directory and asks `commands` what that
+   * manager's argv looks like. Neither package reimplements the other's
+   * half.
+   *
+   * **`None` is success.** Outside any workspace — and inside one whose
+   * manager cannot be identified — the answer is `Option.none()`: "there is
+   * no project-local way to run tools here" is an ordinary fact, not an
+   * exceptional one, and a consumer running in a bare directory should not
+   * have to catch an error to learn it. The contract's typed
+   * `LocalExecError` is reserved for **mechanism** failure — a manifest that
+   * exists but cannot be read or parsed, which means something is broken
+   * rather than absent. That is npm's resolver convention, adopted
+   * verbatim.
+   *
+   * `directory` is the resolved **workspace root**, not the caller's cwd: a
+   * project-local launcher has to run where the workspace is.
+   *
+   * A consumer with no monorepo never needs this layer, and therefore never
+   * installs this package — `LocalExec.layerNone` and `LocalExec.layerFor`
+   * are one-liners in `@effected/commands`.
+   *
+   * **Bind the result to a `const`** — a parameterized layer factory mints a
+   * fresh reference per call and layers memoize by reference.
+   *
+   * @example
+   * ```ts
+   * import { ToolDiscovery } from "@effected/commands";
+   * import { Workspaces } from "@effected/workspaces";
+   * import { Layer } from "effect";
+   *
+   * const AppLayer = ToolDiscovery.layer.pipe(
+   *   Layer.provide(Workspaces.localExecLayer()),
+   *   Layer.provide(Workspaces.layer()),
+   *   Layer.provide(NodeServices.layer),
+   * );
+   * ```
+   */
+  static readonly localExecLayer: (options?: {
+    readonly cwd?: string;
+  }) => Layer.Layer<LocalExec, never, PackageManagerDetector | WorkspaceRoot>;
+  /**
+   * Resolve every `catalog:` and `workspace:` specifier in one `Manifest`
+   * against the real workspace, in one call — the 90% path. Decode stays at
+   * the consumer's edge: build the `Manifest` with `Manifest.decode` (from
+   * `@effected/npm`), hand it here, and get a new `Manifest` back with
+   * concrete ranges; `toRecord()` returns to the wire shape.
+   *
+   * @remarks
+   * Composes `manifest.resolve()` with a fresh {@link Workspaces.resolverLayer}
+   * per call, so the workspace root is re-discovered from `options.cwd` (or
+   * the current `process.cwd()`) on every invocation. Consumers processing
+   * many manifests should check `manifest.needsResolution` first and skip
+   * the call entirely when no dependency field carries a
+   * `catalog:`/`workspace:` specifier — that predicate is pure and avoids
+   * catalog assembly altogether.
+   *
+   * A specifier the workspace cannot answer fails typed as
+   * `UnresolvedDependencyError`; assembly and mechanism failures surface as
+   * `CatalogAssemblyError` / `DependencyResolutionError`.
+   *
+   * @example
+   * ```ts
+   * import { Manifest } from "@effected/npm";
+   * import { Workspaces } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const manifest = yield* Manifest.decode({ dependencies: { effect: "catalog:" } });
+   *   const resolved = manifest.needsResolution ? yield* Workspaces.resolveManifest(manifest) : manifest;
+   *   return resolved.toRecord();
+   * });
+   * ```
+   */
+  static readonly resolveManifest: (manifest: Manifest, options?: WorkspacesOptions) => Effect.Effect<Manifest, CatalogAssemblyError | DependencyResolutionError | UnresolvedDependencyError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The one-call resolver factory: {@link Workspaces.resolvers} pre-wired
+   * over {@link Workspaces.layerWithConfigDependencies}, so the two
+   * `@effected/npm` contracts (`CatalogResolver`, `WorkspaceResolver`) need
+   * only a platform (`FileSystem` + `Path`) from the consumer.
+   *
+   * @remarks
+   * This is deliberately a **parameterized layer function, and the fresh
+   * layer per call is the feature**: layers memoize by reference, so each
+   * call mints an unmemoized layer whose root discovery re-runs — including
+   * a per-call `process.cwd()` read when `options.cwd` is omitted. A build
+   * tool that changes directory between manifests gets a correct
+   * re-discovery each time precisely because nothing is shared across
+   * calls. When you *want* sharing, bind one call's result to a `const` and
+   * provide that; the memoization rule is unchanged, this factory just
+   * refuses to hide it.
+   *
+   * Catalog assembly replays config-dependency `pnpmfile` hooks (the
+   * `layerWithConfigDependencies` path) — the semantics a real pnpm install
+   * has. Compose {@link Workspaces.resolvers} with {@link Workspaces.layer}
+   * yourself if config-dependency code must not run in process.
+   *
+   * @example
+   * ```ts
+   * import { Workspaces } from "@effected/workspaces";
+   * import { Effect } from "effect";
+   *
+   * const program = doSomethingWithResolvers.pipe(
+   *   Effect.provide(Workspaces.resolverLayer()),
+   * );
+   * ```
+   */
+  static readonly resolverLayer: (options?: WorkspacesOptions) => Layer.Layer<CatalogResolver | WorkspaceResolver, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The two `@effected/npm` resolver contracts, implemented for real.
+   *
+   * @remarks
+   * Provide this alongside `@effected/package-json`'s `Package.resolve` and
+   * a manifest's `catalog:` and `workspace:` specifiers resolve against the
+   * actual workspace instead of the no-op layers' `Option.none()`.
+   *
+   * @example
+   * ```ts
+   * import { Package } from "@effected/package-json";
+   * import { Workspaces } from "@effected/workspaces";
+   * import { Layer } from "effect";
+   *
+   * const WorkspacesLayer = Workspaces.layer();
+   * const Resolvers = Workspaces.resolvers.pipe(Layer.provide(WorkspacesLayer));
+   * ```
+   */
+  static readonly resolvers: Layer.Layer<CatalogResolver | WorkspaceResolver, never, WorkspaceCatalogs | WorkspaceDiscovery>;
+}
 //#endregion
 //#region src/WorkspacesSync.d.ts
 /**
@@ -2056,5 +2882,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, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootOptions, type GetWorkspacePackagesSyncOptions, type HookInjection, type ImporterVersions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, type SyncFileSystem, type SyncPath, 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, 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, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, type PackageManagerDetectorShape, PackageManagerName, PackageNotFoundError, type PackageRelease, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, type PublishabilityDetectorShape, ReleaseTag, type SyncFileSystem, type SyncPath, type TagClassification, type TagFormatOptions, TagStyle, TrackingTag, type TrackingTagOptions, 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 };
 //# sourceMappingURL=index.d.ts.map