@effected/workspaces 0.2.1 → 0.3.0

package/Publishability.js

@@ -51,6 +51,37 @@ var PublishTarget = class extends Schema.Class("PublishTarget")({
 * });
 * ```
 *
+* @example
+* The shape's error channel is `never` — **degrade or die**. An override
+* backed by something fallible (a policy service, a registry probe) folds its
+* failure structurally over `{ readonly message: string }` — matching every
+* `Error`, every Effect schema error class, and anything else carrying a
+* message — and either degrades to a safe answer or dies:
+*
+* ```ts
+* import { PublishabilityDetector, PublishTarget } from "@effected/workspaces";
+* import { Effect, Layer } from "effect";
+*
+* declare const lookupPolicy: (
+*   name: string,
+* ) => Effect.Effect<ReadonlyArray<PublishTarget>, { readonly message: string }>;
+*
+* const fromPolicyService = Layer.succeed(PublishabilityDetector, {
+*   detect: (pkg) =>
+*     lookupPolicy(pkg.name).pipe(
+*       Effect.catch((error) =>
+*         Effect.die(new Error(`publishability policy lookup failed for ${pkg.name}: ${error.message}`)),
+*       ),
+*     ),
+* });
+* ```
+*
+* A lookup failure that should *not* abort the run degrades instead —
+* `Effect.catch(() => Effect.succeed([]))` reads as "unknown means
+* unpublishable" — but pick one deliberately; silently swallowing the failure
+* into a wrong "publishes to npm" answer is the one option the contract
+* forbids.
+*
 * @public
 */
 var PublishabilityDetector = class PublishabilityDetector extends Context.Service()("@effected/workspaces/PublishabilityDetector") {

package/README.md

@@ -39,6 +39,8 @@ 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`.
 
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
 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

package/WorkspacePackage.js

@@ -12,9 +12,9 @@ const EMPTY_MANIFEST = Object.freeze(Object.create(null));
 * @remarks
 * Deliberately narrow. `@effected/package-json` models `publishConfig` as an
 * open `Record<string, unknown>` for round-trip fidelity, which preserves every
-* key but types none of them; this is the typed projection of the four that
-* decide *where and whether* a package publishes. Unknown keys are ignored, not
-* rejected.
+* key but types none of them; this is the typed projection of the handful that
+* decide *where, whether and as what* a package publishes. Unknown keys are
+* ignored, not rejected.
 *
 * @public
 */
@@ -25,6 +25,13 @@ var PublishConfig = class extends Schema.Class("PublishConfig")({
 	registry: Schema.optionalKey(Schema.String),
 	/** A subdirectory to publish instead of the package root. */
 	directory: Schema.optionalKey(Schema.String),
+	/**
+	* Whether workspace links point into `directory` during local development —
+	* pnpm symlinks the publish directory instead of the package root, so
+	* siblings resolve the built artifact they would install from the registry.
+	* Meaningful only alongside `directory`.
+	*/
+	linkDirectory: Schema.optionalKey(Schema.Boolean),
 	/** The dist-tag to publish under. */
 	tag: Schema.optionalKey(Schema.String)
 }) {};

package/index.d.ts

@@ -13,6 +13,13 @@ declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
   readonly registry: Schema.optionalKey<Schema.String>;
   /** A subdirectory to publish instead of the package root. */
   readonly directory: Schema.optionalKey<Schema.String>;
+  /**
+   * Whether workspace links point into `directory` during local development —
+   * pnpm symlinks the publish directory instead of the package root, so
+   * siblings resolve the built artifact they would install from the registry.
+   * Meaningful only alongside `directory`.
+   */
+  readonly linkDirectory: Schema.optionalKey<Schema.Boolean>;
   /** The dist-tag to publish under. */
   readonly tag: Schema.optionalKey<Schema.String>;
 }>, {}>;
@@ -22,9 +29,9 @@ declare const PublishConfig_base: Schema.Class<PublishConfig, Schema.Struct<{
  * @remarks
  * Deliberately narrow. `@effected/package-json` models `publishConfig` as an
  * open `Record<string, unknown>` for round-trip fidelity, which preserves every
- * key but types none of them; this is the typed projection of the four that
- * decide *where and whether* a package publishes. Unknown keys are ignored, not
- * rejected.
+ * key but types none of them; this is the typed projection of the handful that
+ * decide *where, whether and as what* a package publishes. Unknown keys are
+ * ignored, not rejected.
  *
  * @public
  */
@@ -977,10 +984,26 @@ declare const PublishTarget_base: Schema.Class<PublishTarget, Schema.Struct<{
  * @public
  */
 declare class PublishTarget extends PublishTarget_base {}
-declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDetector, "@effected/workspaces/PublishabilityDetector", {
+/**
+ * The {@link PublishabilityDetector} service shape.
+ *
+ * @remarks
+ * The error channel is deliberately `never`: every consumer of the service —
+ * a release planner iterating a whole workspace — treats "does this publish"
+ * as a total question, so an overriding layer whose lookup can fail must
+ * **degrade or die**. Fold a recoverable failure into a safe answer (usually
+ * the empty target list), or `Effect.orDie` it into the defect channel; it
+ * cannot widen the channel the contract declares. See
+ * {@link PublishabilityDetector} for the adapter an overriding consumer
+ * writes.
+ *
+ * @public
+ */
+interface PublishabilityDetectorShape {
   /** The publish targets for a package; empty means it does not publish. */
   readonly detect: (pkg: WorkspacePackage) => Effect.Effect<ReadonlyArray<PublishTarget>>;
-}>;
+}
+declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDetector, "@effected/workspaces/PublishabilityDetector", PublishabilityDetectorShape>;
 /**
  * Decides whether a workspace package publishes, and to where.
  *
@@ -1012,6 +1035,37 @@ declare const PublishabilityDetector_base: Context.ServiceClass<PublishabilityDe
  * });
  * ```
  *
+ * @example
+ * The shape's error channel is `never` — **degrade or die**. An override
+ * backed by something fallible (a policy service, a registry probe) folds its
+ * failure structurally over `{ readonly message: string }` — matching every
+ * `Error`, every Effect schema error class, and anything else carrying a
+ * message — and either degrades to a safe answer or dies:
+ *
+ * ```ts
+ * import { PublishabilityDetector, PublishTarget } from "@effected/workspaces";
+ * import { Effect, Layer } from "effect";
+ *
+ * declare const lookupPolicy: (
+ *   name: string,
+ * ) => Effect.Effect<ReadonlyArray<PublishTarget>, { readonly message: string }>;
+ *
+ * const fromPolicyService = Layer.succeed(PublishabilityDetector, {
+ *   detect: (pkg) =>
+ *     lookupPolicy(pkg.name).pipe(
+ *       Effect.catch((error) =>
+ *         Effect.die(new Error(`publishability policy lookup failed for ${pkg.name}: ${error.message}`)),
+ *       ),
+ *     ),
+ * });
+ * ```
+ *
+ * A lookup failure that should *not* abort the run degrades instead —
+ * `Effect.catch(() => Effect.succeed([]))` reads as "unknown means
+ * unpublishable" — but pick one deliberately; silently swallowing the failure
+ * into a wrong "publishes to npm" answer is the one option the contract
+ * forbids.
+ *
  * @public
  */
 declare class PublishabilityDetector extends PublishabilityDetector_base {
@@ -1668,5 +1722,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 FindWorkspaceRootSyncOptions, type GetWorkspacePackagesSyncOptions, LockfileReadError, type LockfileReadFailure, LockfileReader, type LockfileReaderOptions, type LockfileReaderShape, PackageManagerDetectionError, type PackageManagerDetectionFailure, PackageManagerDetector, PackageManagerName, PackageNotFoundError, PackageStateSnapshot, PublishConfig, PublishTarget, PublishabilityDetector, 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 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, ConfigDependencyHooks, type ConfigDependencyHooksShape, CyclicDependencyError, type DependencyDiff, DependencyGraph, DetectedPackageManager, type FindWorkspaceRootSyncOptions, type GetWorkspacePackagesSyncOptions, 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 WorkspaceSnapshotAtFailure, type WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, type WorkspaceSnapshotsOptions, type WorkspaceSnapshotsShape, WorkspaceStateSnapshot, Workspaces, type WorkspacesOptions, type WorkspacesServices, type WorkspacesSyncOptions, findWorkspaceRootSync, getWorkspacePackagesSync };
 //# sourceMappingURL=index.d.ts.map

package/node-sync.d.ts

@@ -0,0 +1,116 @@
+import "@effected/glob";
+import "@effected/lockfiles";
+import "@effected/package-json";
+import "effect";
+//#region src/WorkspacesSync.d.ts
+/**
+ * The synchronous file operations the sync entry points need, supplied by the
+ * consumer. Node's built-ins satisfy it directly:
+ *
+ * ```ts
+ * import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+ *
+ * const fileSystem: SyncFileSystem = {
+ * 	exists: existsSync,
+ * 	readFile: (p) => readFileSync(p, "utf8"),
+ * 	readDirectory: (p) => readdirSync(p),
+ * 	isDirectory: (p) => statSync(p).isDirectory(),
+ * };
+ * ```
+ *
+ * `exists` must return a boolean and not throw (Node's `existsSync` never
+ * does). The other three may throw — `statSync` on a missing path, a
+ * permission error mid-read — and every throw is absorbed into the documented
+ * degraded-skip semantics: a throwing `readFile` reads as an unusable
+ * manifest, a throwing `readDirectory` as an unreadable directory, a throwing
+ * `isDirectory` as "not a directory". Nothing propagates.
+ *
+ * @public
+ */
+interface SyncFileSystem {
+  /** Whether a file or directory exists at `path`. Must not throw. */
+  readonly exists: (path: string) => boolean;
+  /** Read the file at `path` as text. May throw; a throw degrades to a skip. */
+  readonly readFile: (path: string) => string;
+  /** The entry names inside the directory at `path`. May throw; a throw skips the directory. */
+  readonly readDirectory: (path: string) => ReadonlyArray<string>;
+  /** Whether `path` is a directory. May throw; a throw reads as `false`. */
+  readonly isDirectory: (path: string) => boolean;
+}
+/**
+ * The synchronous path operations the sync entry points need, supplied by the
+ * consumer. Deliberately a structural subset of `node:path`, so the built-in
+ * module (and its `win32` / `posix` variants, or a Bun / Deno equivalent)
+ * satisfies it verbatim:
+ *
+ * ```ts
+ * import * as path from "node:path";
+ *
+ * const options: WorkspacesSyncOptions = {
+ * 	fileSystem: { exists: existsSync, readFile: (p) => readFileSync(p, "utf8"), readDirectory: (p) => readdirSync(p), isDirectory: (p) => statSync(p).isDirectory() },
+ * 	path, // node:path IS a SyncPath
+ * };
+ * ```
+ *
+ * These operations shape only the ABSOLUTE paths handed back to the consumer
+ * (and to its own `fileSystem`); workspace-relative pattern matching is POSIX
+ * by the `packages:` contract and never routes through here. Windows
+ * correctness comes from supplying a win32-appropriate implementation, not
+ * from anything in this module.
+ *
+ * @public
+ */
+interface SyncPath {
+  /** Join segments with the implementation's separator (like `path.join`). */
+  readonly join: (...segments: ReadonlyArray<string>) => string;
+  /** The directory portion of `p` (like `path.dirname`). */
+  readonly dirname: (p: string) => string;
+  /** Resolve segments to an absolute path (rightmost-wins, like `path.resolve`). */
+  readonly resolve: (...segments: ReadonlyArray<string>) => string;
+}
+/**
+ * The consumer-supplied operations backing one sync call: the file operations
+ * and the path implementation. Both are required — this package never imports
+ * `node:*` and never assumes posix, so the platform binding is entirely the
+ * caller's.
+ *
+ * @public
+ */
+interface WorkspacesSyncOptions {
+  /** The synchronous file operations (Node: `existsSync` / `readFileSync` / `readdirSync` / `statSync`). */
+  readonly fileSystem: SyncFileSystem;
+  /** The synchronous path implementation (Node: the `node:path` module itself). */
+  readonly path: SyncPath;
+}
+//#endregion
+//#region src/node-sync.d.ts
+/**
+ * `SyncFileSystem` over `node:fs`.
+ *
+ * @remarks
+ * `existsSync` never throws, satisfying `exists`'s must-not-throw contract;
+ * the other three may throw and every throw lands in the sync entry points'
+ * documented degraded-skip semantics.
+ *
+ * @public
+ */
+declare const nodeFileSystem: SyncFileSystem;
+/**
+ * `SyncPath` as the running platform's `node:path` — win32 semantics on
+ * Windows, posix elsewhere. Pass `node:path/win32` or `node:path/posix`
+ * yourself to pin a dialect.
+ *
+ * @public
+ */
+declare const nodePath: SyncPath;
+/**
+ * The complete Node-bound options bag for `findWorkspaceRootSync` and
+ * `getWorkspacePackagesSync` — {@link nodeFileSystem} plus {@link nodePath}.
+ * Spread it to add the per-call extras: `{ ...nodeSyncOps, cwd }`.
+ *
+ * @public
+ */
+declare const nodeSyncOps: WorkspacesSyncOptions;
+//#endregion
+export { type SyncFileSystem, type SyncPath, type WorkspacesSyncOptions, nodeFileSystem, nodePath, nodeSyncOps };
+//# sourceMappingURL=node-sync.d.ts.map

package/node-sync.js

@@ -0,0 +1,67 @@
+import * as path from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+
+//#region src/node-sync.ts
+/**
+* The Node.js binding for the sync entry points — ready-made `SyncFileSystem`
+* and `SyncPath` operations over `node:fs` / `node:path`, so adopting
+* `findWorkspaceRootSync` / `getWorkspacePackagesSync` is one import instead
+* of four hand-wired one-liners.
+*
+* Deliberately a **separate subpath** (`@effected/workspaces/node-sync`), not
+* part of the main entry: the main entry imports nothing platform-shaped, and
+* re-exporting these from it would drag `node:*` imports into every consumer —
+* including the ones supplying their own operations (a win32-explicit `path`,
+* a Bun or Deno binding, a test fake). Import this module only where Node's
+* built-ins are the platform you mean; `nodePath` is the running platform's
+* `node:path`, so on Windows the paths handed back are win32 paths.
+*
+* @example
+* ```ts
+* import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+* import { nodeSyncOps } from "@effected/workspaces/node-sync";
+*
+* const root = findWorkspaceRootSync(nodeSyncOps);
+* const packages = root === null ? [] : getWorkspacePackagesSync(root, nodeSyncOps);
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* `SyncFileSystem` over `node:fs`.
+*
+* @remarks
+* `existsSync` never throws, satisfying `exists`'s must-not-throw contract;
+* the other three may throw and every throw lands in the sync entry points'
+* documented degraded-skip semantics.
+*
+* @public
+*/
+const nodeFileSystem = {
+	exists: existsSync,
+	readFile: (p) => readFileSync(p, "utf8"),
+	readDirectory: (p) => readdirSync(p),
+	isDirectory: (p) => statSync(p).isDirectory()
+};
+/**
+* `SyncPath` as the running platform's `node:path` — win32 semantics on
+* Windows, posix elsewhere. Pass `node:path/win32` or `node:path/posix`
+* yourself to pin a dialect.
+*
+* @public
+*/
+const nodePath = path;
+/**
+* The complete Node-bound options bag for `findWorkspaceRootSync` and
+* `getWorkspacePackagesSync` — {@link nodeFileSystem} plus {@link nodePath}.
+* Spread it to add the per-call extras: `{ ...nodeSyncOps, cwd }`.
+*
+* @public
+*/
+const nodeSyncOps = {
+	fileSystem: nodeFileSystem,
+	path: nodePath
+};
+
+//#endregion
+export { nodeFileSystem, nodePath, nodeSyncOps };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.2.1",
+	"version": "0.3.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": [
@@ -37,16 +37,20 @@
 			"types": "./index.d.ts",
 			"import": "./index.js"
 		},
+		"./node-sync": {
+			"types": "./node-sync.d.ts",
+			"import": "./node-sync.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/git": "0.2.0",
+		"@effected/git": "0.3.0",
 		"@effected/glob": "0.1.0",
-		"@effected/lockfiles": "0.1.1",
+		"@effected/lockfiles": "0.1.2",
 		"@effected/npm": "0.2.0",
-		"@effected/package-json": "0.2.0",
-		"@effected/walker": "0.1.0",
-		"@effected/yaml": "0.1.0",
+		"@effected/package-json": "0.3.0",
+		"@effected/walker": "0.2.0",
+		"@effected/yaml": "0.2.0",
 		"@pnpm/catalogs.config": "^1100.0.0",
 		"@pnpm/catalogs.protocol-parser": "^1100.0.0",
 		"@pnpm/catalogs.resolver": "^1100.0.0",