rolldown-pnpm-config 0.1.0 → 0.2.1

package/README.md

@@ -113,6 +113,20 @@ publicHoistPattern: {
 
 See [exporting to pnpm-workspace.yaml](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/06-exporting.md) for the full surface.
 
+## Distributing dependency patches
+
+A plugin author can ship pnpm dependency patches through the plugin. Author a `.patch` with stock pnpm into `public/patches/` — the bundler copies `public/` into the published package, so the file travels with the plugin. At build the plugin discovers each patch, rewrites its path to the consumer-resolved `node_modules/.pnpm-config/<name>/patches/<file>.patch` and bakes it into the emitted pnpmfile. Every consumer then applies it automatically through `updateConfig`, with no hand-written `patchedDependencies` entry:
+
+```ts
+export const plugin = {
+  name: "@acme/pnpm-config",
+  // default once public/patches/ has files; a bare map is the manual escape hatch
+  patchedDependencies: { strategy: "rewrite" },
+} satisfies PluginConfig;
+```
+
+A sibling `patches/` folder stays local to your repo and never ships. On `rolldown-pnpm-config export` your own `pnpm-workspace.yaml` gets the patches with their local on-disk paths, merged by key so sibling and hand-written entries survive. See [distributing dependency patches](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/07-distributing-patches.md) for the full surface.
+
 ## Documentation
 
 - [Getting started](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/01-getting-started.md) — Wire the plugin into a vanilla rolldown build and emit a pnpmfile.
@@ -121,6 +135,7 @@ See [exporting to pnpm-workspace.yaml](https://github.com/spencerbeggs/rolldown-
 - [pnpm settings coverage](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/04-pnpm-settings-coverage.md) — Every pnpm-workspace.yaml setting the plugin manages and the ones it leaves to each consumer.
 - [Upgrading catalogs](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/05-upgrading-catalogs.md) — The `upgrade` CLI that rewrites catalog version ranges in place.
 - [Exporting to pnpm-workspace.yaml](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/06-exporting.md) — The `export` and `preview` CLI, the `local` merge directive and per-repo `excludeByRepo` filtering.
+- [Distributing dependency patches](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/07-distributing-patches.md) — Ship pnpm patches through the plugin so every consumer applies them automatically.
 
 ## License
 

package/bin/rolldown-pnpm-config.js

@@ -14,7 +14,7 @@ const root = Command.make("rolldown-pnpm-config").pipe(Command.withSubcommands([
 ]));
 Command.run(root, {
 	name: "rolldown-pnpm-config",
-	version: "0.1.0"
+	version: "0.2.1"
 })(process.argv).pipe(Effect.provide(NodeContext.layer), NodeRuntime.runMain);
 
 //#endregion

package/cli/commands/export.js

@@ -1,6 +1,9 @@
+import { discoverPatches } from "../../patches/discover.js";
+import { isRewriteDirective, readLocalPatchesDir, withResolvedBuildPatches } from "../../patches/build.js";
 import { DESCRIPTORS } from "../../descriptors/index.js";
 import { freeze } from "../../plugin/freeze.js";
 import { resolveRootName } from "../../runtime/ctx.js";
+import { reconcilePatches } from "../../patches/reconcile.js";
 import { buildDiff } from "../diff/build.js";
 import { renderExportDiff } from "../diff/render.js";
 import { effectiveManaged } from "../effective.js";
@@ -12,7 +15,7 @@ import { canonicalize, findWorkspaceFile, parseWorkspace, renderWorkspace } from
 import { overlayWorkspace } from "../workspace-overlay.js";
 import { Data, Effect, Option } from "effect";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { Args, Command, Options } from "@effect/cli";
 
 //#region src/cli/commands/export.ts
@@ -45,7 +48,7 @@ function runExport(opts) {
 		}), opts.configFile);
 		if (config === null) return yield* Effect.fail(new ExportError({ message: `No PnpmConfigPlugin call found in ${opts.configFile}` }));
 		if (errors.length > 0) return yield* Effect.fail(new ExportError({ message: `Non-literal config values: ${errors.join("; ")}` }));
-		const { base, manifest } = yield* freeze(config).pipe(Effect.mapError((e) => new ExportError({ message: e.message })));
+		const { base, manifest } = yield* freeze(withResolvedBuildPatches(config, dirname(opts.configFile))).pipe(Effect.mapError((e) => new ExportError({ message: e.message })));
 		const managed = {};
 		for (const [k, v] of Object.entries(base)) if (WORKSPACE_FIELDS.has(k)) managed[k] = v;
 		const path = opts.workspacePath ?? findWorkspaceFile(process.cwd()) ?? join(process.cwd(), "pnpm-workspace.yaml");
@@ -54,7 +57,33 @@ function runExport(opts) {
 			catch: (e) => new ExportError({ message: `Cannot read or parse ${path}: ${String(e)}` })
 		}) : {};
 		const rootName = resolveRootName({ dir: dirname(path) });
-		const merged = overlayWorkspace(effectiveManaged(managed, config.local && typeof config.local === "object" ? config.local : void 0, parsed, manifest, rootName), parsed);
+		const effective = effectiveManaged(managed, config.local && typeof config.local === "object" ? config.local : void 0, parsed, manifest, rootName);
+		const rawPatched = config.patchedDependencies;
+		const explicitPatchMap = rawPatched !== void 0 && !isRewriteDirective(rawPatched);
+		const contributed = {};
+		if (explicitPatchMap) {
+			const explicit = effective.patchedDependencies;
+			if (explicit !== null && typeof explicit === "object" && !Array.isArray(explicit)) Object.assign(contributed, explicit);
+		} else {
+			const localPatchesDir = readLocalPatchesDir(config);
+			const owned = discoverPatches({
+				baseDir: dirname(opts.configFile),
+				name: typeof config.name === "string" ? config.name : "",
+				...localPatchesDir !== void 0 ? { localPatchesDir } : {}
+			});
+			const workspaceRoot = dirname(path);
+			for (const p of owned) contributed[p.key] = relative(workspaceRoot, p.absPath).split(/[\\/]/).join("/");
+		}
+		if (Object.keys(contributed).length > 0) effective.patchedDependencies = {
+			...(parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.patchedDependencies : void 0) ?? {},
+			...contributed
+		};
+		const report = reconcilePatches({
+			parsedPatched: effective.patchedDependencies ?? {},
+			root: dirname(path),
+			exists: existsSync
+		});
+		const merged = overlayWorkspace(effective, parsed);
 		const rendered = renderWorkspace(merged);
 		const localKeys = new Set(config.local && typeof config.local === "object" ? Object.keys(config.local) : []);
 		const diff = renderExportDiff(buildDiff(canonicalize(parsed), canonicalize(merged), {
@@ -65,7 +94,8 @@ function runExport(opts) {
 			path,
 			rendered,
 			written: false,
-			diff
+			diff,
+			report
 		};
 		yield* Effect.try({
 			try: () => writeFileSync(path, rendered, "utf8"),
@@ -75,7 +105,8 @@ function runExport(opts) {
 			path,
 			rendered,
 			written: true,
-			diff
+			diff,
+			report
 		};
 	});
 }
@@ -111,6 +142,8 @@ const exportCommand = Command.make("export", {
 			process.stdout.write(`${toAnsi(result.diff, { color: caps.color })}\n`);
 			process.stdout.write("\n+ added  ~ changed  - removed   (local) local override  (unmanaged) not managed\n");
 		} else process.stdout.write(`Exported to ${result.path}\n`);
+		for (const k of result.report.staleEntries) process.stderr.write(`warning: patch entry "${k}" has no file on disk\n`);
+		for (const k of result.report.keyMismatches) process.stderr.write(`warning: patch entry "${k}" does not match its filename\n`);
 	});
 })).pipe(Command.withDescription("Materialize the plugin config into pnpm-workspace.yaml (--dry-run to preview)"));
 

package/cli/local-merge.js

@@ -56,8 +56,9 @@ function combine(managed, value, strategy) {
 function applyLocalDirective(managed, raw, parsed, field) {
 	const directive = isLocalDirective(raw) ? raw : { value: raw };
 	let result;
-	if (directive.strategy && directive.value !== void 0) result = combine(managed, directive.value, directive.strategy);
-	else if (directive.value !== void 0) result = directive.value;
+	const strat = directive.strategy === "merge" ? "union" : directive.strategy;
+	if (strat && strat !== "rewrite" && directive.value !== void 0) result = combine(managed, directive.value, strat);
+	else if (directive.value !== void 0 && directive.strategy !== "rewrite") result = directive.value;
 	else result = managed;
 	if (field === "overrides") {
 		const protocols = directive.preserve ?? DEFAULT_PRESERVE;

package/cli/plan.js

@@ -24,7 +24,8 @@ function planEntry(entry, versions) {
 		}
 		parsed.sort((a, b) => a.compare(b));
 		const maxOf = (list) => list.length ? list[list.length - 1] : null;
-		const current = yield* parseOrNull(entry.currentRange.replace(/^[\^~]/, ""));
+		const currentStripped = entry.currentRange.replace(/^[\^~]/, "");
+		const current = yield* parseOrNull(currentStripped);
 		const currentMajor = current?.major ?? 0;
 		const inRangeMax = range ? maxOf(parsed.filter((v) => range.test(v))) : null;
 		const overallMax = maxOf(parsed);

package/index.d.ts

@@ -60,7 +60,7 @@ type FieldInput<T> = T | {
 interface LocalDirective<T> {
   readonly preserve?: readonly string[];
   readonly value?: T;
-  readonly strategy?: "union" | "difference";
+  readonly strategy?: "union" | "difference" | "merge" | "rewrite";
 }
 /**
  * The declarative plugin configuration.
@@ -83,7 +83,14 @@ interface PluginConfig {
    * generated field when running `rolldown-pnpm-config export`. Ignored by the
    * build and the shipped pnpmfile.
    */
-  readonly local?: { readonly [K in keyof PluginConfig]?: PluginConfig[K] | LocalDirective<PluginConfig[K]> };
+  readonly local?: {
+    /**
+     * Override the local discovery root for distributed patches (default
+     * `public/patches/` adjacent to the build file). The local-only `patches/`
+     * folder detection is independent and unaffected.
+     */
+    readonly localPatchesDir?: string;
+  } & { readonly [K in keyof PluginConfig]?: PluginConfig[K] | LocalDirective<PluginConfig[K]> };
   /** Whether pnpm prompts before purging `node_modules`. */
   readonly confirmModulesPurge?: FieldInput<boolean>;
   /** Per-package manifest overrides merged into the dependency graph. */
@@ -242,8 +249,15 @@ interface PluginConfig {
   readonly shellEmulator?: FieldInput<boolean>;
   /** Scripts that must exist in every project matching the current filter. */
   readonly requiredScripts?: FieldInput<string[]>;
-  /** Patches applied to dependencies, keyed by package identifier. */
-  readonly patchedDependencies?: FieldInput<Record<string, string>>;
+  /**
+   * Patches applied to dependencies, keyed by package identifier. Pass a plain
+   * map for explicit control, or `{ strategy: "rewrite" }` (the default when
+   * `public/patches/` contains files) to auto-discover and rewrite patch paths
+   * to their distributed `node_modules/.pnpm-config/<name>/` location.
+   */
+  readonly patchedDependencies?: FieldInput<Record<string, string>> | {
+    readonly strategy: "rewrite";
+  };
   /** Whether unused patches (patches that apply to no installed package) are allowed. */
   readonly allowUnusedPatches?: FieldInput<boolean>;
   /** Whether non-applied patches (patches that fail to apply) are allowed. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rolldown-pnpm-config",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"private": false,
 	"description": "A dogfooding example of our plugin",
 	"repository": {
@@ -34,16 +34,24 @@
 	},
 	"dependencies": {
 		"@effect/cli": "^0.75.2",
+		"@effect/cluster": "^0.59.0",
+		"@effect/experimental": "^0.60.0",
 		"@effect/platform": "^0.96.2",
 		"@effect/platform-node": "^0.107.0",
+		"@effect/printer": "^0.49.0",
+		"@effect/printer-ansi": "^0.49.0",
+		"@effect/rpc": "^0.75.1",
+		"@effect/sql": "^0.51.1",
+		"@effect/typeclass": "^0.40.0",
+		"@effect/workflow": "^0.18.2",
 		"effect": "^3.21.4",
 		"ink": "^7.1.0",
 		"ink-tab": "^5.2.0",
-		"oxc-parser": "^0.137.0",
+		"oxc-parser": "^0.138.0",
 		"react": "^19.2.7",
-		"semver-effect": "^0.2.1",
+		"semver-effect": "^0.3.1",
 		"std-env": "^4.1.0",
-		"std-osc8": "^0.1.0",
+		"std-osc8": "^0.2.0",
 		"yaml": "^2.9.0"
 	},
 	"peerDependencies": {

package/patches/build.js

@@ -0,0 +1,44 @@
+import { discoverPatches } from "./discover.js";
+
+//#region src/patches/build.ts
+/** True only for the `{ strategy: "rewrite" }` directive. @internal */
+function isRewriteDirective(v) {
+	return v !== null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 1 && v.strategy === "rewrite";
+}
+/** Read `local.localPatchesDir` when it is a string. @internal */
+function readLocalPatchesDir(config) {
+	const local = config.local;
+	return typeof local?.localPatchesDir === "string" ? local.localPatchesDir : void 0;
+}
+/**
+* Resolve build-time `patchedDependencies`. When the field is absent or the
+* `{ strategy: "rewrite" }` directive, run discovery and inject the distributed
+* map (`name`-scoped `.pnpm-config` paths) so `freeze` sees a plain map. An
+* explicit map / wrapped value passes through untouched.
+*
+* @internal
+*/
+function withResolvedBuildPatches(config, baseDir) {
+	const raw = config.patchedDependencies;
+	if (raw !== void 0 && !isRewriteDirective(raw)) return config;
+	const localPatchesDir = readLocalPatchesDir(config);
+	const distributed = discoverPatches({
+		baseDir,
+		name: config.name,
+		...localPatchesDir !== void 0 ? { localPatchesDir } : {}
+	}).filter((p) => p.distributed);
+	if (distributed.length === 0) {
+		if (raw === void 0) return config;
+		const { patchedDependencies: _drop, ...rest } = config;
+		return rest;
+	}
+	const map = {};
+	for (const p of distributed) map[p.key] = p.distributedPath;
+	return {
+		...config,
+		patchedDependencies: map
+	};
+}
+
+//#endregion
+export { isRewriteDirective, readLocalPatchesDir, withResolvedBuildPatches };

package/patches/discover.js

@@ -0,0 +1,39 @@
+import { patchKeyFromFileName } from "./keys.js";
+import { distributedPatchPath, distributedRel } from "./paths.js";
+import { existsSync, readdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+//#region src/patches/discover.ts
+/**
+* Discover owned patches in the two convention folders adjacent to the build
+* file: `public/patches/` (distributed, rewritten) and `patches/` (local-only).
+* `localPatchesDir` overrides the distributed source root only. Read-only.
+*
+* @internal
+*/
+function discoverPatches(opts) {
+	const distRoot = opts.localPatchesDir ? isAbsolute(opts.localPatchesDir) ? opts.localPatchesDir : join(opts.baseDir, opts.localPatchesDir) : join(opts.baseDir, "public", "patches");
+	const localOnlyRoot = join(opts.baseDir, "patches");
+	const out = [];
+	collect(distRoot, true);
+	collect(localOnlyRoot, false);
+	return out;
+	function collect(dir, distributed) {
+		if (!existsSync(dir)) return;
+		for (const fileName of readdirSync(dir).sort()) {
+			const key = patchKeyFromFileName(fileName);
+			if (key === null) continue;
+			const absPath = join(dir, fileName);
+			out.push({
+				key,
+				fileName,
+				distributed,
+				absPath,
+				...distributed ? { distributedPath: distributedPatchPath(opts.name, distributedRel(opts.baseDir, distRoot, fileName)) } : {}
+			});
+		}
+	}
+}
+
+//#endregion
+export { discoverPatches };

package/patches/keys.js

@@ -0,0 +1,17 @@
+//#region src/patches/keys.ts
+/**
+* Derive the `patchedDependencies` key from a `.patch` filename, reversing pnpm's
+* `/`→`__` mangling (`@scope__pkg@1.0.0.patch` → `@scope/pkg@1.0.0`). Returns
+* `null` when the name does not end in `.patch` or has an empty stem.
+*
+* @internal
+*/
+function patchKeyFromFileName(fileName) {
+	if (!fileName.endsWith(".patch")) return null;
+	const stem = fileName.slice(0, -6);
+	if (stem.length === 0) return null;
+	return stem.replace(/__/g, "/");
+}
+
+//#endregion
+export { patchKeyFromFileName };

package/patches/paths.js

@@ -0,0 +1,29 @@
+import { basename, join, posix, relative } from "node:path";
+
+//#region src/patches/paths.ts
+/**
+* Consumer-resolved distributed patch path for a config dependency:
+* `node_modules/.pnpm-config/<name>/<rel>`, POSIX separators. `<name>` is used
+* verbatim (a scoped name keeps its `/`). Verify the prefix against a real
+* install — see plan Task 1.
+*
+* @internal
+*/
+function distributedPatchPath(name, rel) {
+	const segments = rel.split(/[\\/]/).filter(Boolean);
+	return posix.join("node_modules", ".pnpm-config", name, ...segments);
+}
+/**
+* The patch's path relative to the bundler's `public/` directory — the subpath
+* the bundler preserves when copying `public/` into `dist/`. Falls back to
+* `<basename(distRoot)>/<fileName>` when `distRoot` is not under `public/`.
+*
+* @internal
+*/
+function distributedRel(baseDir, distRoot, fileName) {
+	const rel = relative(join(baseDir, "public"), distRoot);
+	return `${(rel === "" || rel.startsWith("..") ? basename(distRoot) : rel).split(/[\\/]/).filter(Boolean).join("/")}/${fileName}`;
+}
+
+//#endregion
+export { distributedPatchPath, distributedRel };

package/patches/reconcile.js

@@ -0,0 +1,27 @@
+import { patchKeyFromFileName } from "./keys.js";
+import { basename, join } from "node:path";
+
+//#region src/patches/reconcile.ts
+/**
+* Report `patchedDependencies` entries whose file is missing (`staleEntries`) or
+* whose key does not derive from its filename (`keyMismatches`). `exists` is
+* injected so the function stays pure and testable.
+*
+* @internal
+*/
+function reconcilePatches(args) {
+	const staleEntries = [];
+	const keyMismatches = [];
+	for (const [key, rel] of Object.entries(args.parsedPatched)) {
+		if (!args.exists(join(args.root, rel))) staleEntries.push(key);
+		const derived = patchKeyFromFileName(basename(rel));
+		if (derived !== null && derived !== key) keyMismatches.push(key);
+	}
+	return {
+		staleEntries,
+		keyMismatches
+	};
+}
+
+//#endregion
+export { reconcilePatches };

package/plugin/index.js

@@ -1,3 +1,4 @@
+import { withResolvedBuildPatches } from "../patches/build.js";
 import { freeze } from "./freeze.js";
 import { emitCatalogsModule, emitPnpmfileModule } from "./serialize.js";
 import { Effect } from "effect";
@@ -14,7 +15,7 @@ const CATALOGS_SPEC = "rolldown-pnpm-config/virtual/catalogs";
 */
 function createPnpmConfigPlugin(config, deps = { freeze }) {
 	let frozen;
-	const getFrozen = () => frozen ??= Effect.runPromise(deps.freeze(config));
+	const getFrozen = () => frozen ??= Effect.runPromise(deps.freeze(withResolvedBuildPatches(config, process.cwd())));
 	return {
 		name: "rolldown-pnpm-config",
 		resolveId(source) {