rolldown-pnpm-config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# rolldown-pnpm-config
+
+[![npm](https://img.shields.io/npm/v/rolldown-pnpm-config?label=npm&color=cb3837)](https://www.npmjs.com/package/rolldown-pnpm-config)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+
+A rolldown plugin whose output is a pnpm config-dependency `pnpmfile`. You author your catalogs and pnpm settings as one declarative config. Run a build and you get a self-contained `pnpmfile.mjs`. pnpm 11 loads it and calls its `updateConfig` hook to merge your settings into a consuming repo.
+
+## Install
+
+```bash
+npm install -D rolldown-pnpm-config rolldown
+# or
+pnpm add -D rolldown-pnpm-config rolldown
+```
+
+The build runs on Node.js. The emitted `pnpmfile.mjs` targets pnpm 11 in the consuming repo — the pnpm version that loads `.mjs` pnpmfiles.
+
+## Quick start
+
+A vanilla rolldown setup is three files: the config you author, a build entry that re-exports the runtime hooks and a rolldown config that runs the plugin.
+
+Author your catalogs and pnpm settings as a plain `PluginConfig` object. The `name` field is required — use the npm name of the config package itself; it tags runtime warnings as `[<name>]` so consuming repos know which config dependency is speaking:
+
+```ts
+import type { PluginConfig } from "rolldown-pnpm-config";
+
+export const plugin = {
+  name: "@acme/pnpm-config",
+  catalogs: {
+    default: { packages: { typescript: "^5.9.0", vitest: "^4.0.0" } },
+  },
+  overrides: { "tar@<6.2.1": ">=6.2.1" },
+  publicHoistPattern: ["@types/*"],
+  allowBuilds: { esbuild: true },
+  strictDepBuilds: true,
+  minimumReleaseAge: { value: 1440, enforcement: "warn" },
+  confirmModulesPurge: false,
+} satisfies PluginConfig;
+```
+
+Add a build entry that re-exports the runtime `hooks` from the plugin's virtual pnpmfile module. The reference directive pulls in the package's shipped virtual-module types, so the import type-checks with no hand-written declaration. Save it as `src/pnpmfile.ts`:
+
+```ts
+/// <reference types="rolldown-pnpm-config/virtual" />
+export { hooks } from "rolldown-pnpm-config/virtual/pnpmfile";
+```
+
+Run `PnpmConfigPlugin` over your authored config and point rolldown at the build entry:
+
+```ts
+import { defineConfig } from "rolldown";
+import { PnpmConfigPlugin } from "rolldown-pnpm-config";
+import { plugin } from "./pnpm-config.js"; // the config above, saved as pnpm-config.ts
+
+export default defineConfig({
+  input: "src/pnpmfile.ts",
+  // the emitted pnpmfile runs under Node, so target node — externalizes node: builtins
+  platform: "node",
+  output: { file: "pnpmfile.mjs", format: "esm" },
+  plugins: [PnpmConfigPlugin(plugin)],
+});
+```
+
+Build it:
+
+```bash
+npx rolldown -c
+# writes a self-contained pnpmfile.mjs to the project root
+```
+
+The output pulls in only Node's own builtins, so pnpm can load it without any `node_modules` present. Ship it as a pnpm config dependency and pnpm 11 calls its `updateConfig` hook to merge your settings into the consuming repo.
+
+## Keeping catalogs current
+
+The bundled `rolldown-pnpm-config upgrade` command rewrites the version ranges in your config file in place. Run it with no arguments and it autodetects the config — the single top-level `.ts` file in the current directory that calls `PnpmConfigPlugin(...)`:
+
+```bash
+npx rolldown-pnpm-config upgrade
+# walks each catalog package, then:
+# Applied <n> change(s).
+```
+
+The walk is interactive by default. `--yes` takes the latest in-range version without prompting, `--dry-run` prints the planned changes without writing and `--catalog <name>` restricts the walk to one catalog. Pass `--preview` for a non-interactive projection of what the walk would do, with `--full` to show the full tree without context collapsing. The output is colorized in a supporting terminal. For packages that declare a `strategy`, the command also resyncs their materialized peer range. See [upgrading catalogs](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/05-upgrading-catalogs.md) for the full surface.
+
+## Exporting to pnpm-workspace.yaml
+
+For repos that develop the plugin itself and cannot consume it as a config dependency, `rolldown-pnpm-config export` materializes the managed config directly into `pnpm-workspace.yaml`. Pass `--dry-run` to print a colored canonical diff without writing; add `--full` to emit the entire tree rather than changed lines with context. `file:`, `link:`, `workspace:` and `portal:` overrides already present in the file are preserved by default on every run.
+
+The `rolldown-pnpm-config preview` command opens an interactive tabbed view — Changes, Full and Simulated — without writing anything. In a non-interactive terminal it falls back to printing the Changes diff, so it is safe to run in CI.
+
+The optional `local` field on `PluginConfig` adjusts managed settings for this repo's export only — the built pnpmfile and its runtime behavior are unaffected. A bare value overwrites the managed value; the directive form merges it:
+
+```ts
+local: {
+  // union: add local patterns on top of the managed list
+  publicHoistPattern: { strategy: "union", value: ["@acme/*"] },
+  // difference: drop one managed override entry
+  overrides: { strategy: "difference", value: { "lodash@<4.17.21": ">=4.17.21" } },
+  // bare value: overwrite the managed field entirely
+  strictDepBuilds: false,
+},
+```
+
+`publicHoistPattern` also accepts `excludeByRepo` — a map keyed by consuming repo name — to drop specific patterns when the config runs in a named repo:
+
+```ts
+publicHoistPattern: {
+  value: ["@types/*", "@acme/cli"],
+  excludeByRepo: { "consumer-a": ["@acme/cli"] },
+}
+```
+
+See [exporting to pnpm-workspace.yaml](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/06-exporting.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.
+- [Using @savvy-web/bundler](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/02-savvy-bundler.md) — The same plugin with the build wiring done for you, emitting both `.mjs` and `.cjs`.
+- [Concepts](https://github.com/spencerbeggs/rolldown-pnpm-config/blob/main/docs/03-concepts.md) — What the emitted pnpmfile does: config dependencies, catalogs and the enforcement model.
+- [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.
+
+## License
+
+[MIT](LICENSE)

package/bin/rolldown-pnpm-config.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { exportCommand } from "../cli/commands/export.js";
+import { previewCommand } from "../cli/commands/preview.js";
+import { upgradeCommand } from "../cli/commands/upgrade.js";
+import { Effect } from "effect";
+import { Command } from "@effect/cli";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+
+//#region src/cli/bin.ts
+const root = Command.make("rolldown-pnpm-config").pipe(Command.withSubcommands([
+	upgradeCommand,
+	exportCommand,
+	previewCommand
+]));
+Command.run(root, {
+	name: "rolldown-pnpm-config",
+	version: "0.1.0"
+})(process.argv).pipe(Effect.provide(NodeContext.layer), NodeRuntime.runMain);
+
+//#endregion
+export {  };

package/catalogs.js

@@ -0,0 +1,27 @@
+//#region src/catalogs.ts
+/**
+* Normalize declarative catalog input into the resolved `{ catalog → pkg → range }`
+* map consumed by the runtime. Pure: the base catalog uses each package's
+* `range` (or bare string); a `<name>Peers` catalog is emitted only for packages
+* carrying a materialized `peer`, using that value verbatim. `strategy` is
+* CLI-only and ignored here.
+*
+* @internal
+*/
+function normalizeCatalogs(input) {
+	const out = {};
+	for (const [name, decl] of Object.entries(input)) {
+		const base = {};
+		const peers = {};
+		for (const [pkg, spec] of Object.entries(decl.packages)) {
+			base[pkg] = typeof spec === "string" ? spec : spec.range;
+			if (typeof spec === "object" && spec.peer !== void 0) peers[pkg] = spec.peer;
+		}
+		out[name] = base;
+		if (Object.keys(peers).length > 0) out[`${name}Peers`] = peers;
+	}
+	return out;
+}
+
+//#endregion
+export { normalizeCatalogs };

package/cli/commands/export.js

@@ -0,0 +1,118 @@
+import { DESCRIPTORS } from "../../descriptors/index.js";
+import { freeze } from "../../plugin/freeze.js";
+import { resolveRootName } from "../../runtime/ctx.js";
+import { buildDiff } from "../diff/build.js";
+import { renderExportDiff } from "../diff/render.js";
+import { effectiveManaged } from "../effective.js";
+import { evaluatePluginConfig } from "../evaluate.js";
+import { findConfigFiles, pickConfigCandidate } from "../select-file.js";
+import { toAnsi } from "../ui/ansi.js";
+import { detectCapabilities } from "../ui/env.js";
+import { canonicalize, findWorkspaceFile, parseWorkspace, renderWorkspace } from "../workspace-file.js";
+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 { Args, Command, Options } from "@effect/cli";
+
+//#region src/cli/commands/export.ts
+/**
+* Typed failure raised when the export run cannot complete.
+*
+* @internal
+*/
+var ExportError = class extends Data.TaggedError("ExportError") {};
+/**
+* The set of pnpm config keys that belong in pnpm-workspace.yaml
+* (i.e. descriptors with `workspaceYaml: true`).
+*
+* @internal
+*/
+const WORKSPACE_FIELDS = new Set(Object.entries(DESCRIPTORS).filter(([, d]) => d.workspaceYaml).map(([k]) => k));
+/**
+* Export core: freeze the plugin config first, then apply excludeByRepo and
+* local directives via the effective pipeline, overlay onto the existing
+* pnpm-workspace.yaml (or create fresh), and write the result. In preview
+* mode nothing is written.
+*
+* @internal
+*/
+function runExport(opts) {
+	return Effect.gen(function* () {
+		const { config, errors } = evaluatePluginConfig(yield* Effect.try({
+			try: () => readFileSync(opts.configFile, "utf8"),
+			catch: () => new ExportError({ message: `Cannot read ${opts.configFile}` })
+		}), 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 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");
+		const parsed = existsSync(path) ? yield* Effect.try({
+			try: () => parseWorkspace(readFileSync(path, "utf8")),
+			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 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), {
+			localKeys,
+			managedKeys: WORKSPACE_FIELDS
+		}), { full: opts.full ?? false });
+		if (opts.preview) return {
+			path,
+			rendered,
+			written: false,
+			diff
+		};
+		yield* Effect.try({
+			try: () => writeFileSync(path, rendered, "utf8"),
+			catch: () => new ExportError({ message: `Cannot write ${path}` })
+		});
+		return {
+			path,
+			rendered,
+			written: true,
+			diff
+		};
+	});
+}
+const pathArg = Args.file({ name: "path" }).pipe(Args.optional);
+const dryRunFlag = Options.boolean("dry-run").pipe(Options.withDefault(false));
+const fullFlag = Options.boolean("full").pipe(Options.withDefault(false));
+/**
+* The "export" command. Materializes the plugin config into pnpm-workspace.yaml.
+* An optional path argument overrides the auto-detected workspace file. --dry-run
+* prints the colored diff to stdout without writing. --full disables context
+* collapsing in the diff output.
+*
+* @internal
+*/
+const exportCommand = Command.make("export", {
+	path: pathArg,
+	dryRun: dryRunFlag,
+	full: fullFlag
+}, ({ path, dryRun, full }) => Effect.gen(function* () {
+	const picked = pickConfigCandidate(yield* findConfigFiles(process.cwd()));
+	if (!picked.ok) return yield* Effect.fail(new ExportError({ message: picked.message }));
+	const workspacePath = Option.getOrUndefined(path);
+	const result = yield* runExport({
+		configFile: picked.file,
+		...workspacePath !== void 0 ? { workspacePath } : {},
+		preview: dryRun,
+		full
+	});
+	yield* Effect.sync(() => {
+		if (dryRun) {
+			const caps = detectCapabilities();
+			process.stdout.write(`${result.path} (dry run — not written)\n\n`);
+			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`);
+	});
+})).pipe(Command.withDescription("Materialize the plugin config into pnpm-workspace.yaml (--dry-run to preview)"));
+
+//#endregion
+export { ExportError, WORKSPACE_FIELDS, exportCommand, runExport };

package/cli/commands/preview.js

@@ -0,0 +1,73 @@
+import { freeze } from "../../plugin/freeze.js";
+import { resolveRootName } from "../../runtime/ctx.js";
+import { evaluatePluginConfig } from "../evaluate.js";
+import { findConfigFiles, pickConfigCandidate } from "../select-file.js";
+import { toAnsi } from "../ui/ansi.js";
+import { detectCapabilities } from "../ui/env.js";
+import { findWorkspaceFile, parseWorkspace } from "../workspace-file.js";
+import { WORKSPACE_FIELDS } from "./export.js";
+import { buildPreviewViews } from "../preview-views.js";
+import { runPreview } from "../ui/run-preview.js";
+import { Data, Effect, Option } from "effect";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Args, Command } from "@effect/cli";
+
+//#region src/cli/commands/preview.ts
+/** Typed failure for the preview run. @internal */
+var PreviewError = class extends Data.TaggedError("PreviewError") {};
+/**
+* Build the three preview views from a config + workspace file. Pure of any
+* terminal interaction; the command wraps this with interactive/non-TTY output.
+*
+* @internal
+*/
+function runPreviewViews(opts) {
+	return Effect.gen(function* () {
+		const { config, errors } = evaluatePluginConfig(yield* Effect.try({
+			try: () => readFileSync(opts.configFile, "utf8"),
+			catch: () => new PreviewError({ message: `Cannot read ${opts.configFile}` })
+		}), opts.configFile);
+		if (config === null) return yield* Effect.fail(new PreviewError({ message: `No PnpmConfigPlugin call found in ${opts.configFile}` }));
+		if (errors.length > 0) return yield* Effect.fail(new PreviewError({ message: `Non-literal config values: ${errors.join("; ")}` }));
+		const { base, manifest } = yield* freeze(config).pipe(Effect.mapError((e) => new PreviewError({ 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");
+		const parsed = existsSync(path) ? yield* Effect.try({
+			try: () => parseWorkspace(readFileSync(path, "utf8")),
+			catch: (e) => new PreviewError({ message: `Cannot read or parse ${path}: ${String(e)}` })
+		}) : {};
+		const localCfg = config.local && typeof config.local === "object" ? config.local : void 0;
+		return buildPreviewViews({
+			managed,
+			...localCfg ? { local: localCfg } : {},
+			parsed,
+			manifest,
+			rootName: resolveRootName({ dir: dirname(path) })
+		});
+	});
+}
+const pathArg = Args.file({ name: "path" }).pipe(Args.optional);
+/**
+* The "preview" command: interactive ink-tab explorer of the export diff
+* (Changes / Full / Simulated). Falls back to printing the Changes view when
+* the terminal is non-interactive.
+*
+* @internal
+*/
+const previewCommand = Command.make("preview", { path: pathArg }, ({ path }) => Effect.gen(function* () {
+	const picked = pickConfigCandidate(yield* findConfigFiles(process.cwd()));
+	if (!picked.ok) return yield* Effect.fail(new PreviewError({ message: picked.message }));
+	const workspacePath = Option.getOrUndefined(path);
+	const views = yield* runPreviewViews({
+		configFile: picked.file,
+		...workspacePath !== void 0 ? { workspacePath } : {}
+	});
+	const caps = detectCapabilities();
+	if (caps.interactive) yield* runPreview(views);
+	else yield* Effect.sync(() => process.stdout.write(`${toAnsi(views.changes, { color: caps.color })}\n`));
+})).pipe(Command.withDescription("Interactively preview how pnpm-workspace.yaml would change"));
+
+//#endregion
+export { PreviewError, previewCommand, runPreviewViews };