@savvy-web/tsdown-plugins 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @savvy-web/tsdown-plugins
+
+[![npm](https://img.shields.io/npm/v/@savvy-web%2Ftsdown-plugins?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/tsdown-plugins)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+
+The plugin pack behind [`@savvy-web/bundler`](https://www.npmjs.com/package/@savvy-web/bundler). It holds every build behavior the bundler drives — entry detection, manifest emission and catalog resolution, the dts tsconfig port, the per-target build loop and the build-output reporter — as composable helpers and one [rolldown](https://rolldown.rs/) plugin. It is authored against rolldown's plugin _type_ only, so it imports no `tsdown` runtime and declares no `tsdown` peer dependency: bring your own `tsdown`.
+
+Most packages should use `@savvy-web/bundler` directly. Reach for this package when you have outgrown the bundler's front door and want to compose the same building blocks in a hand-written `tsdown.config.ts`.
+
+## Install
+
+```bash
+npm install --save-dev @savvy-web/tsdown-plugins tsdown
+# or
+pnpm add -D @savvy-web/tsdown-plugins tsdown
+```
+
+`tsdown` is a peer of your own choosing — the plugin pack never pins it.
+
+## Quick start
+
+Compose the helpers in a `tsdown.config.ts` to reproduce the bundler's front door yourself:
+
+```ts
+// tsdown.config.ts
+import { packageJsonEntries, emitManifest } from "@savvy-web/tsdown-plugins";
+import { defineConfig } from "tsdown";
+
+const sourceDir = process.cwd();
+
+export default defineConfig({
+  entry: packageJsonEntries({ cwd: sourceDir }),
+  // emitManifest writes a transformed, catalog-resolved package.json into the output pkg/
+  plugins: [emitManifest({ sourceDir, targetGroup: { id: "npm", isProd: true } })],
+});
+```
+
+`packageJsonEntries` reads a package's `exports` and `bin` and returns the `Record<name, path>` that `tsdown` accepts as `entry`. `emitManifest` reads the `package.json` under `sourceDir`, writes the transformed manifest and copies `LICENSE`/`README.md` into the output folder.
+
+## Features
+
+- **Entry detection** — `packageJsonEntries` and `extractEntries` derive build entries from a package's `exports` and `bin`, matching the rules used across the Silk Suite builders.
+- **Manifest transforms** — `transformManifest`, `transformExports`, `transformBin` and `normalizeBinPaths` rewrite a source `package.json` into a publishable one; `emitManifest` is the rolldown plugin that writes it. A dual-format build emits both `import` and `require` export conditions.
+- **Catalog resolution** — `resolveManifest` resolves `catalog:` and `workspace:` specifiers against the workspace, delegating to `workspaces-effect`'s `CatalogResolver`.
+- **Multi-target resolution** — `resolveTargets` turns a `publishConfig.targets` map into the distinct byte-variant groups to build and the registry bindings for each; `writeTargetsBinding` persists that resolution as `dist/prod/targets.json` for the release step.
+- **JSX resolution** — `resolveJsxConfig` and `readTsconfigJsx` derive the effective JSX transform from a package's tsconfig, with an explicit override winning.
+- **Executable binaries** — `normalizeExeOptions` fills the SEA defaults and infers targets from the package's `os`/`cpu`; `runExeBuild` drives `@tsdown/exe` to compile the binaries.
+- **Config validation** — the `ConfigValidator` Effect service (with `ConfigValidatorLive`) fast-fails on a bad `publishConfig.targets`, `exe` or `meta` config, raising the typed `ConfigValidationError`.
+- **dts tsconfig port** — `buildResolvedTsconfig` and `writeResolvedTsconfig` write a temp tsconfig with absolute paths so type declarations emit cleanly under pnpm symlinks.
+- **Per-target build loop** — `deriveTargetGroupOptions` and `buildTargetGroups` map a target to its `tsdown` options and run the build once per target, exposed as a helper so the escape hatch gets multi-target builds too. A `format` of `["esm", "cjs"]` (the `BuildFormat` type) derives a dual-format build — a require-able CJS output with default-export interop and `.d.cts` declarations alongside the ESM one. The `bundleNodeModules`, `bundledPackages` and `dtsExternals` options thread the dependency-bundling posture into both the JS and declaration passes.
+- **Bundled declarations** — each target runs two `tsdown` passes: a JavaScript pass that preserves per-module output, then a declaration-only pass that rolls every re-exported type into a single `.d.ts` per public entry (`deriveDtsPassOptions`). Per-module JavaScript stays intact while consumers keep reaching re-exported types through your published subpaths.
+- **API Extractor meta** — `generateMeta` runs [API Extractor](https://api-extractor.com/) over a package's emitted `.d.ts` to write an api-model bundle (`.api.json`, `tsdoc-metadata.json`, resolved `tsconfig.json`); `normalizeMetaOptions` fills the `MetaOptions` defaults that drive it.
+- **Output reporter** — `renderReport` plus the `BuildReport` schema and a set of formatters (terminal, JSON, markdown, CI annotations, silent) render a build report for humans, agents or CI.
+
+## Effect
+
+The package is implemented in [Effect](https://effect.website/), but Effect runs behind the plugin boundary: the catalog wrapper returns a `Promise` and the reporter is rendered with `Effect.runPromise` at the call site. The plugin and helper values you compose are plain rolldown-conformant objects. `effect` is a peer dependency.
+
+## License
+
+[MIT](LICENSE)

package/build/build-target-groups.js

@@ -0,0 +1,133 @@
+import { emitManifest } from "../manifest/emit-manifest.js";
+import { cjsDefaultInterop } from "./cjs-default-interop.js";
+import { nodeBuiltinDefaultInterop } from "./node-builtin-default-interop.js";
+import { syncPublicDir } from "./sync-public.js";
+import { deriveDtsPassOptions, deriveTargetGroupOptions } from "./target-groups.js";
+import { join } from "node:path";
+
+//#region src/build/build-target-groups.ts
+/**
+* Run tsdown.build() per TargetGroup. Composable so the escape hatch gets multi-group too.
+*
+* Each group runs TWO passes to the SAME outDir:
+*  1. JS pass — per-module JS (`unbundle: true`, `dts: false`), with the `emitManifest` plugin
+*     and the `public/` copy. Default `clean: true` gives it a fresh outDir.
+*  2. dts pass — bundled declarations only (`unbundle: false`, `dts: { emitDtsOnly: true }`,
+*     `clean: false`). No manifest plugin, no copy, no sourcemaps. `clean: false` is load-bearing:
+*     it must NOT wipe the JS the first pass just wrote.
+*
+* Why two passes: tsdown's `unbundle` maps to rolldown `output.preserveModules` for the whole
+* build (JS and the dts plugin share it), so a single pass cannot give per-module JS + bundled
+* dts. Per-module dts breaks type portability (TS2883); bundling the JS re-bundles workspace
+* consumers. The split keeps per-module JS AND rolled-up, self-contained declarations.
+*/
+async function buildTargetGroups(options) {
+	const build = options.build ?? (await import("tsdown")).build;
+	const publicDir = join(options.cwd, "public");
+	for (const group of options.groups) {
+		const partitions = [{
+			entry: options.entry,
+			...options.format !== void 0 ? { format: options.format } : {},
+			...options.externals !== void 0 ? { externals: options.externals } : {},
+			...options.bundle !== void 0 ? { bundle: options.bundle } : {},
+			...options.bundleNodeModules !== void 0 ? { bundleNodeModules: options.bundleNodeModules } : {},
+			...options.bundledPackages !== void 0 ? { bundledPackages: options.bundledPackages } : {},
+			...options.dtsExternals !== void 0 ? { dtsExternals: options.dtsExternals } : {}
+		}, ...options.overrides ?? []];
+		for (let p = 0; p < partitions.length; p++) {
+			const part = partitions[p];
+			if (part === void 0) continue;
+			const isBase = p === 0;
+			const partExternals = part.externals;
+			const partBundle = part.bundle;
+			const partBundleNodeModules = part.bundleNodeModules;
+			const partBundledPackages = part.bundledPackages;
+			const partDtsExternals = part.dtsExternals;
+			const deriveInput = {
+				group: group.id,
+				cwd: options.cwd,
+				version: options.version,
+				entry: part.entry,
+				tsconfigPath: options.tsconfigPath,
+				devManifest: options.devManifest,
+				...partExternals !== void 0 ? { externals: partExternals } : {},
+				...partBundledPackages !== void 0 ? { bundledPackages: partBundledPackages } : {},
+				...part.format !== void 0 ? { format: part.format } : {},
+				...options.minify !== void 0 ? { minify: options.minify } : {},
+				...options.jsx !== void 0 ? { jsx: options.jsx } : {}
+			};
+			const js = deriveTargetGroupOptions(deriveInput);
+			const dts = deriveDtsPassOptions(deriveInput);
+			const targetGroup = {
+				id: group.id,
+				name: group.name,
+				isProd: js.isProd
+			};
+			const manifestPlugin = isBase ? emitManifest({
+				targetGroup,
+				devManifest: options.devManifest,
+				transform: options.transform,
+				sourceDir: options.cwd,
+				dual: options.dualExports ?? js.format.includes("cjs")
+			}) : void 0;
+			await build({
+				config: false,
+				cwd: options.cwd,
+				entry: js.entry,
+				outDir: js.outDir,
+				format: js.format,
+				platform: js.platform,
+				sourcemap: js.sourcemap,
+				minify: js.minify,
+				unbundle: js.unbundle,
+				clean: isBase ? js.clean : false,
+				fixedExtension: js.fixedExtension,
+				dts: js.dts,
+				define: js.define,
+				...partExternals?.length || partBundleNodeModules || partBundle?.length ? { deps: {
+					...partExternals?.length ? { neverBundle: partExternals } : {},
+					...partBundle?.length ? { alwaysBundle: partBundle } : {},
+					...partBundleNodeModules ? { skipNodeModulesBundle: false } : {}
+				} } : {},
+				...js.cjsDefault !== void 0 ? { cjsDefault: js.cjsDefault } : {},
+				...js.jsx !== void 0 ? { inputOptions: { jsx: js.jsx } } : {},
+				plugins: [
+					...manifestPlugin ? [manifestPlugin] : [],
+					...js.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [],
+					...options.extraPlugins ?? []
+				]
+			});
+			if (isBase) syncPublicDir(publicDir, join(js.outDir, "public"));
+			const dtsNeverBundle = [...partExternals ?? [], ...partDtsExternals ?? []];
+			await build({
+				config: false,
+				cwd: options.cwd,
+				entry: dts.entry,
+				outDir: dts.outDir,
+				format: dts.format,
+				platform: dts.platform,
+				sourcemap: dts.sourcemap,
+				unbundle: dts.unbundle,
+				clean: false,
+				fixedExtension: dts.fixedExtension,
+				dts: dts.dts,
+				define: dts.define,
+				...dtsNeverBundle.length > 0 || partBundleNodeModules || dts.bundledPackages ? { deps: {
+					...dtsNeverBundle.length > 0 ? { neverBundle: dtsNeverBundle } : {},
+					...partBundleNodeModules ? {
+						skipNodeModulesBundle: false,
+						...dts.bundledPackages ? { dts: { alwaysBundle: dts.bundledPackages } } : {}
+					} : dts.bundledPackages ? {
+						skipNodeModulesBundle: true,
+						dts: { alwaysBundle: dts.bundledPackages }
+					} : {}
+				} } : {},
+				...dts.jsx !== void 0 ? { inputOptions: { jsx: dts.jsx } } : {},
+				plugins: [...dts.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [], ...options.extraPlugins ?? []]
+			});
+		}
+	}
+}
+
+//#endregion
+export { buildTargetGroups };

package/build/cjs-default-interop.js

@@ -0,0 +1,98 @@
+//#region src/build/cjs-default-interop.ts
+/**
+* The interop footer appended to a CJS ENTRY chunk that has a default export
+* alongside named exports. It reassigns `module.exports` to the default value
+* and re-attaches every named export as an own property of it.
+*
+* This is the rslib `cjsInterop: true` equivalent. rolldown's `output.exports`
+* cannot natively produce `module.exports = <default>` while ALSO keeping named
+* exports: for a default+named module both `"auto"` and `"named"` emit
+* `exports.default = <default>` (verified against rolldown 1.1.0), so an
+* ESM consumer doing `import(x).default` receives the `{ default, ...named }`
+* wrapper object rather than the default value. The footer restores the rslib
+* behavior so `import(x).default === <default>` and `require(x) === <default>`
+* (with named exports attached as properties of it).
+*
+* Why this matters concretely: markdownlint-cli2 resolves a `customRules`
+* specifier to a file path, `await import(fileURL)`, and reads `module.default`,
+* expecting it to be the rules ARRAY (it then `.flat()`s it). silk's
+* `./changesets/markdownlint` subpath default-exports the rules array plus five
+* named rule objects; without this footer `import(...).default` is the wrapper
+* object, whose `.names` is undefined, and markdownlint-cli2 aborts with
+* "Property 'names' of custom rule at index 0 is incorrect: 'undefined'".
+*
+* Limitation — PRIMITIVE defaults: promotion only happens when the default value
+* is an object or function, because named exports are re-attached to it as own
+* properties (a primitive cannot carry properties). When a cjs entry chunk has a
+* primitive default (`export default "x"` / `42` / `true`) ALONGSIDE named exports,
+* `module.exports` is left as the `{ default, ...named }` wrapper and the footer
+* emits a one-line `console.warn` so the no-op is observable rather than silent.
+* This case does not occur in the suite today (every promoted default — the
+* markdownlint rules array, the commitlint config objects — is an object), and a
+* default-ONLY primitive is unaffected: rolldown already emits `module.exports =
+* <primitive>` for it (no named exports, so this plugin never fires).
+*/
+const INTEROP_FOOTER = [
+	"",
+	"// __cjs_default_interop__ (rslib cjsInterop parity): make module.exports the",
+	"// default export with named exports attached, so import(x).default is the value.",
+	"if (typeof module !== \"undefined\" && module.exports && module.exports.default !== void 0) {",
+	"	const __cjsDefault = module.exports.default;",
+	"	if (__cjsDefault !== null && (typeof __cjsDefault === \"object\" || typeof __cjsDefault === \"function\")) {",
+	"		for (const __cjsKey of Object.keys(module.exports)) {",
+	"			if (__cjsKey === \"default\" || __cjsKey === \"__esModule\") continue;",
+	"			try {",
+	"				Object.defineProperty(__cjsDefault, __cjsKey, {",
+	"					value: module.exports[__cjsKey],",
+	"					enumerable: true,",
+	"					configurable: true,",
+	"					writable: true",
+	"				});",
+	"			} catch {}",
+	"		}",
+	"		module.exports = __cjsDefault;",
+	"	} else {",
+	"		// Primitive default + named exports: cannot attach named props to a primitive,",
+	"		// so module.exports stays the wrapper. Surface the no-op instead of hiding it.",
+	"		if (typeof console !== \"undefined\")",
+	"			console.warn(\"[savvy:cjs-default-interop] primitive default export left as a {default,...named} wrapper; import().default is NOT the primitive value\");",
+	"	}",
+	"}"
+].join("\n");
+/**
+* Rolldown plugin: append the CJS default-interop footer to ENTRY chunks of the
+* `cjs` format that export a default alongside named exports.
+*
+* Gated tightly so it never touches the wrong chunk:
+*  - format must be `cjs` (ESM is untouched; `import().default` on ESM is already correct);
+*  - the chunk must be an ENTRY chunk — never a SHARED chunk. Shared chunks are required by
+*    entry chunks via their named bindings (e.g. `require_changesets.changesets_exports.X`);
+*    reassigning a shared chunk's `module.exports` to its own default would break those reads
+*    (many bundled vendor chunks carry an `exports.default`);
+*  - the chunk must export a `default` AND at least one named export. A default-only chunk
+*    already gets `module.exports = <default>` from rolldown, and a named-only chunk has no
+*    default to promote.
+*
+* The emitted footer is also self-guarded (`module.exports.default !== void 0`), so it is a
+* runtime no-op whenever the static gate is ever too generous.
+*/
+function cjsDefaultInterop() {
+	return {
+		name: "savvy:cjs-default-interop",
+		renderChunk(code, chunk, outputOptions) {
+			if (outputOptions.format !== "cjs") return null;
+			if (!chunk.isEntry) return null;
+			const exportsList = chunk.exports;
+			if (!Array.isArray(exportsList)) return null;
+			if (!exportsList.includes("default")) return null;
+			if (!exportsList.some((name) => name !== "default")) return null;
+			return {
+				code: `${code}\n${INTEROP_FOOTER}\n`,
+				map: null
+			};
+		}
+	};
+}
+
+//#endregion
+export { cjsDefaultInterop };

package/build/node-builtin-default-interop.js

@@ -0,0 +1,74 @@
+import { builtinModules } from "node:module";
+
+//#region src/build/node-builtin-default-interop.ts
+/**
+* The set of Node built-in module names (without the `node:` prefix), e.g. `path`,
+* `process`, `fs`. Used to decide whether a BARE import specifier names a builtin.
+*/
+const BUILTIN_NAMES = new Set(builtinModules);
+/** True when `spec` resolves to a Node built-in module (either `node:x` or a bare builtin name). */
+function isNodeBuiltin(spec) {
+	if (spec.startsWith("node:")) return true;
+	return BUILTIN_NAMES.has(spec);
+}
+/**
+* Rewrite a default import / default re-export of a Node built-in into the
+* equivalent NAMESPACE form, so rolldown's CJS codegen produces correct interop.
+*
+* Why this exists — a rolldown 1.1.0 codegen defect (verified against the latest
+* published rolldown 1.1.0 / tsdown 0.22.2, with no newer release to upgrade to):
+*
+*   // SOURCE (e.g. vfile's lib/minproc.js)
+*   export {default as minproc} from 'node:process'
+*   // ...consumed as minproc.cwd()
+*
+*   // rolldown CJS OUTPUT (BROKEN)
+*   let node_process = require("node:process");
+*   node_process.default.cwd()           // <- require("node:process").default is undefined
+*
+* For a default import of an EXTERNAL Node builtin, rolldown emits a bare
+* `require("node:x")` WITHOUT its `__toESM` interop wrapper, yet still accesses
+* `.default` — which is `undefined` on a builtin's CJS export object, so the call
+* throws `Cannot read properties of undefined (reading 'cwd')` at runtime. NAMED
+* imports are unaffected (`(0, node_process.cwd)()` reads a real property), and a
+* NAMESPACE import is handled correctly: rolldown wraps it as
+* `node_process = __toESM(require("node:process"), 1)`, which synthesizes `.default`
+* and copies every own property, so member access works. This transform converts the
+* broken default form into the working namespace form BEFORE codegen, so it is immune
+* to minification and applies identically to per-module and bundled output.
+*
+* rolldown exposes no Rollup-style `output.interop` knob to fix this at the output
+* layer, which is why the correction happens here on the source.
+*
+* Rewrites (the two static forms that occur in practice, anchored to statement start):
+*  - `import NAME from "node:x"`            -> `import * as NAME from "node:x"`
+*  - `export { default as NAME } from "node:x"` -> `export * as NAME from "node:x"`
+*  - `import NAME, { a, b } from "node:x"`  -> `import * as NAME from "node:x"; import { a, b } from "node:x"`
+*
+* The namespace binding NAME carries the builtin's named exports (`NAME.cwd`,
+* `NAME.join`, ...), which is exactly how a default import of a builtin is consumed
+* in practice. ESM output is unaffected at runtime (a namespace import of a builtin
+* resolves to the same members), so the plugin is safe to attach to dual builds.
+*/
+function nodeBuiltinDefaultInterop() {
+	const DEFAULT_REEXPORT = /(^|\n)([ \t]*)export\s*\{\s*default\s+as\s+([A-Za-z_$][\w$]*)\s*\}\s*from\s*(["'])([^"']+)\4/g;
+	const DEFAULT_WITH_NAMED = /(^|\n)([ \t]*)import\s+([A-Za-z_$][\w$]*)\s*,\s*(\{[^}]*\})\s*from\s*(["'])([^"']+)\5/g;
+	const DEFAULT_IMPORT = /(^|\n)([ \t]*)import\s+([A-Za-z_$][\w$]*)\s+from\s*(["'])([^"']+)\4/g;
+	return {
+		name: "savvy:node-builtin-default-interop",
+		transform(code) {
+			if (!code.includes("node:") && !code.includes("from")) return null;
+			let out = code;
+			out = out.replace(DEFAULT_REEXPORT, (match, lead, indent, name, quote, spec) => isNodeBuiltin(spec) ? `${lead}${indent}export * as ${name} from ${quote}${spec}${quote}` : match);
+			out = out.replace(DEFAULT_WITH_NAMED, (match, lead, indent, name, named, quote, spec) => isNodeBuiltin(spec) ? `${lead}${indent}import * as ${name} from ${quote}${spec}${quote};\n${indent}import ${named} from ${quote}${spec}${quote}` : match);
+			out = out.replace(DEFAULT_IMPORT, (match, lead, indent, name, quote, spec) => isNodeBuiltin(spec) ? `${lead}${indent}import * as ${name} from ${quote}${spec}${quote}` : match);
+			return out === code ? null : {
+				code: out,
+				map: null
+			};
+		}
+	};
+}
+
+//#endregion
+export { nodeBuiltinDefaultInterop };

package/build/strip-maps.js

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+import { readdirSync, rmSync } from "node:fs";
+
+//#region src/build/strip-maps.ts
+/**
+* Remove declaration source-map files (`.d.ts.map` / `.d.cts.map`) from a built `pkg`
+* directory, returning the removed paths.
+*
+* The dts pass emits these next to each `.d.ts` (the resolved dts tsconfig sets
+* `declarationMap: true`) because API Extractor reads them during meta generation to
+* resolve original-source positions. But they are dead weight in a PUBLISHED package —
+* they reference `.ts` sources the tarball does not ship — and they leak local source
+* paths, so the prod build strips them AFTER meta generation has consumed them. The dev
+* build keeps them (it is never published, and `savvy build --target meta` reads them).
+*
+* Recurses, but skips `node_modules` so it does not traverse a self-contained bundle's
+* vendored tree — only the package's own emitted declarations carry maps worth stripping.
+*/
+function removeDeclarationMaps(pkgDir) {
+	const removed = [];
+	let entries;
+	try {
+		entries = readdirSync(pkgDir, { withFileTypes: true });
+	} catch {
+		return removed;
+	}
+	for (const entry of entries) {
+		if (entry.name === "node_modules") continue;
+		const full = join(pkgDir, entry.name);
+		if (entry.isDirectory()) removed.push(...removeDeclarationMaps(full));
+		else if (entry.name.endsWith(".d.ts.map") || entry.name.endsWith(".d.cts.map")) {
+			rmSync(full, { force: true });
+			removed.push(full);
+		}
+	}
+	return removed;
+}
+
+//#endregion
+export { removeDeclarationMaps };

package/build/sync-public.js

@@ -0,0 +1,67 @@
+import { dirname, join, relative } from "node:path";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+
+//#region src/build/sync-public.ts
+/** Recursively collect every file path under `dir`, relative to `base`. */
+function listFilesRel(dir, base = dir) {
+	const out = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const abs = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...listFilesRel(abs, base));
+		else out.push(relative(base, abs));
+	}
+	return out;
+}
+/** True when both files exist with identical size and bytes. Size is checked first so the byte read is skipped for the common changed case. */
+function sameBytes(a, b) {
+	if (statSync(a).size !== statSync(b).size) return false;
+	return readFileSync(a).equals(readFileSync(b));
+}
+/** Remove empty directories under `dir` (deepest-first); `dir` itself is left in place. */
+function pruneEmptyDirs(dir) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const sub = join(dir, entry.name);
+		pruneEmptyDirs(sub);
+		if (readdirSync(sub).length === 0) rmSync(sub, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Mirror `sourceDir` into `targetDir`, idempotently.
+*
+* Replaces tsdown's built-in `copy`, whose non-recursive mkdir throws `EEXIST` when the target
+* already exists (re-builds, `prepare`-on-install, concurrent turbo invocations). Behavior:
+*
+* - source absent: no-op.
+* - target absent: copy `sourceDir` wholesale.
+* - target present: copy only files that are new or whose bytes differ, then delete target files
+*   that no longer exist in the source and prune the directories left empty.
+*
+* The byte-diff keeps unchanged files (and their timestamps) untouched, so a large copied asset
+* tree — e.g. the mcp markdown corpus — is not rewritten on every build.
+*/
+function syncPublicDir(sourceDir, targetDir) {
+	if (!existsSync(sourceDir)) return;
+	if (!existsSync(targetDir)) {
+		cpSync(sourceDir, targetDir, { recursive: true });
+		return;
+	}
+	const sourceFiles = listFilesRel(sourceDir);
+	const sourceSet = new Set(sourceFiles);
+	for (const rel of sourceFiles) {
+		const src = join(sourceDir, rel);
+		const dst = join(targetDir, rel);
+		if (!existsSync(dst) || !sameBytes(src, dst)) {
+			mkdirSync(dirname(dst), { recursive: true });
+			copyFileSync(src, dst);
+		}
+	}
+	for (const rel of listFilesRel(targetDir)) if (!sourceSet.has(rel)) rmSync(join(targetDir, rel), { force: true });
+	pruneEmptyDirs(targetDir);
+}
+
+//#endregion
+export { syncPublicDir };

package/build/target-groups.js

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+
+//#region src/build/target-groups.ts
+const outDirFor = (cwd, group) => group === "dev" ? join(cwd, "dist/dev/pkg") : join(cwd, "dist/prod", group, "pkg");
+/** Derive the JS-pass tsdown options for one TargetGroup (per-module JS, no dts). */
+function deriveTargetGroupOptions(options) {
+	const isProd = options.group !== "dev";
+	const format = options.format ?? ["esm"];
+	const hasCjs = format.includes("cjs");
+	return {
+		outDir: outDirFor(options.cwd, options.group),
+		sourcemap: !isProd,
+		minify: isProd && (options.minify ?? false),
+		format,
+		unbundle: true,
+		clean: true,
+		platform: "node",
+		fixedExtension: false,
+		entry: options.entry,
+		dts: false,
+		define: { __PACKAGE_VERSION__: JSON.stringify(options.version) },
+		isProd,
+		...hasCjs ? { cjsDefault: true } : {},
+		...options.jsx !== void 0 ? { jsx: options.jsx } : {}
+	};
+}
+/** Derive the dts-pass tsdown options for one TargetGroup (bundled declarations only). */
+function deriveDtsPassOptions(options) {
+	const isProd = options.group !== "dev";
+	const format = options.format ?? ["esm"];
+	return {
+		outDir: outDirFor(options.cwd, options.group),
+		sourcemap: false,
+		format,
+		unbundle: false,
+		clean: false,
+		platform: "node",
+		fixedExtension: false,
+		entry: options.entry,
+		dts: {
+			tsconfig: options.tsconfigPath,
+			emitDtsOnly: true
+		},
+		define: { __PACKAGE_VERSION__: JSON.stringify(options.version) },
+		isProd,
+		...options.jsx !== void 0 ? { jsx: options.jsx } : {},
+		...options.bundledPackages !== void 0 ? { bundledPackages: options.bundledPackages } : {}
+	};
+}
+
+//#endregion
+export { deriveDtsPassOptions, deriveTargetGroupOptions };

package/catalog/resolve-catalogs.js

@@ -0,0 +1,24 @@
+import { CatalogResolver, WorkspacesLive } from "workspaces-effect";
+import { NodeContext } from "@effect/platform-node";
+import { Effect } from "effect";
+
+//#region src/catalog/resolve-catalogs.ts
+/**
+* Resolve every `catalog:`/`workspace:` specifier in a manifest to a concrete spec,
+* delegating to workspaces-effect's CatalogResolver. The resolver discovers the
+* workspace root from `process.cwd()` (run this from inside the target workspace)
+* and assembles catalogs durably (inline + config-dependency hook-replay + lockfile),
+* so no transient `.pnpm-workspace-state-v1.json` is required.
+*
+* Rejects with `CatalogResolutionError` on an unresolvable reference, or
+* `CatalogAssemblyError` if the workspace catalog set cannot be assembled.
+*/
+function resolveManifest(pkg) {
+	const program = Effect.gen(function* () {
+		return yield* (yield* CatalogResolver).resolve(pkg);
+	});
+	return Effect.runPromise(program.pipe(Effect.provide(WorkspacesLive), Effect.provide(NodeContext.layer)));
+}
+
+//#endregion
+export { resolveManifest };

package/config-validation/ConfigValidator.js

@@ -0,0 +1,8 @@
+import { Context } from "effect";
+
+//#region src/config-validation/ConfigValidator.ts
+/** Fast-fail config validator; runs first in the bundler over the resolved config. */
+var ConfigValidator = class extends Context.Tag("@savvy-web/tsdown-plugins/ConfigValidator")() {};
+
+//#endregion
+export { ConfigValidator };

package/config-validation/ConfigValidatorLive.js

@@ -0,0 +1,61 @@
+import { ConfigValidator } from "./ConfigValidator.js";
+import { ConfigValidationError } from "../errors.js";
+import { normalizeExeOptions } from "../exe/config.js";
+import { resolveTargets } from "../targets/resolve-targets.js";
+import { Effect, Layer } from "effect";
+import { existsSync, statSync } from "node:fs";
+
+//#region src/config-validation/ConfigValidatorLive.ts
+const VALID_SYNTAX_KINDS = new Set([
+	"block",
+	"inline",
+	"modifier"
+]);
+/** Synchronous rule set; throws ConfigValidationError on the first violation. */
+function check(input) {
+	if (input.targets !== void 0 && Object.keys(input.targets).length > 0) resolveTargets({
+		targets: input.targets,
+		baseName: input.baseName
+	});
+	if (input.exe !== void 0) {
+		const specs = normalizeExeOptions(input.exe, input.osCpu ?? {
+			os: [],
+			cpu: []
+		});
+		for (const spec of specs) {
+			if (spec.fileName.trim() === "") throw new ConfigValidationError({
+				path: "exe.fileName",
+				reason: "an exe binary needs a non-empty fileName"
+			});
+			if (spec.targets.length === 0) throw new ConfigValidationError({
+				path: `exe.${spec.fileName}.targets`,
+				reason: "no targets: the package declares no os/cpu and the exe config states none"
+			});
+		}
+	}
+	if (input.meta !== void 0) {
+		if (!input.hasExports) throw new ConfigValidationError({
+			path: "meta",
+			reason: "meta requires an exports map to extract an api-model from"
+		});
+		for (const tag of input.meta.tsdoc?.tagDefinitions ?? []) if (!VALID_SYNTAX_KINDS.has(tag.syntaxKind)) throw new ConfigValidationError({
+			path: "meta.tsdoc.tagDefinitions",
+			reason: `tag "${tag.tagName}" has an invalid syntaxKind "${tag.syntaxKind}"`
+		});
+		for (const p of input.meta.localPaths ?? []) if (existsSync(p) && !statSync(p).isDirectory()) throw new ConfigValidationError({
+			path: "meta.localPaths",
+			reason: `"${p}" exists but is not a directory`
+		});
+	}
+}
+/** Live ConfigValidator: wraps the synchronous rule set, surfacing ConfigValidationError as a typed Effect failure. */
+const ConfigValidatorLive = Layer.succeed(ConfigValidator, { validate: (input) => Effect.try({
+	try: () => check(input),
+	catch: (e) => e instanceof ConfigValidationError ? e : new ConfigValidationError({
+		path: "config",
+		reason: String(e)
+	})
+}) });
+
+//#endregion
+export { ConfigValidatorLive };