@savvy-web/bundler 0.1.0

package/README.md

@@ -0,0 +1,257 @@
+# @savvy-web/bundler
+
+[![npm](https://img.shields.io/npm/v/@savvy-web%2Fbundler?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/bundler)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+
+The zero-config bundler for [Silk Suite](https://github.com/savvy-web/systems) TypeScript packages. Configure a package with a single self-executing `savvy.build.ts`, run it against the `dev` or `npm` target and get a clean, publishable `dist/<target>/pkg`. Install one devDependency; `tsdown` is pinned and tested transitively, so a toolchain upgrade is a bundler release rather than a peer bump across your repos.
+
+## Install
+
+```bash
+npm install --save-dev @savvy-web/bundler
+# or
+pnpm add -D @savvy-web/bundler
+```
+
+## Quick start
+
+Add a `savvy.build.ts` to the package root. It both exports a config object and runs the build when invoked directly:
+
+```ts
+// savvy.build.ts
+import { defineBuild, runBuild } from "@savvy-web/bundler";
+
+const config = defineBuild({
+  format: ["esm"],
+  devManifest: "preserve",
+});
+
+export default config;
+
+if (import.meta.main) {
+  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
+}
+```
+
+Wire the two targets into `package.json` scripts and run them with Node's native TypeScript support (Node 24.11+):
+
+```json
+{
+  "scripts": {
+    "build:dev": "node savvy.build.ts --target dev",
+    "build:prod": "node savvy.build.ts --target prod"
+  }
+}
+```
+
+```bash
+npm run build:prod
+# writes dist/prod/npm/pkg — the tarball root, with a resolved manifest and built code
+```
+
+`--target dev` writes `dist/dev/pkg`, the local-link target with `catalog:`/`workspace:` specifiers preserved. `--target prod` writes `dist/prod/npm/pkg` with those specifiers resolved to concrete ranges, ready to publish. Two further targets, `--target meta` and `--target exe`, are covered below.
+
+Every build emits per-module JavaScript alongside a single rolled-up, self-contained `.d.ts` per public entry. Each entry's declaration file pulls in every re-exported type, so a consumer that infers a type from your public API never has to reach into a deep sibling module that no export subpath addresses.
+
+## TypeScript config
+
+The bundler ships its shared TypeScript base as a subpath export. Extend it from your package's `tsconfig.json` so source and declaration emit line up with what the bundler expects:
+
+```json
+{
+  "extends": ["@savvy-web/bundler/ecma.json"]
+}
+```
+
+`ecma.json` sets ESNext libs, NodeNext resolution, strict mode and `composite` declaration output. Override any of it in your own `tsconfig.json`.
+
+## Multi-target publishing
+
+By default `--target prod` builds a single group named after the package and writes it to `dist/prod/npm/pkg`. To publish the same package to more than one registry, or under more than one name, declare a `publishConfig.targets` map in `package.json`:
+
+```json
+{
+  "publishConfig": {
+    "targets": {
+      "npm": true,
+      "github": "@scope/internal-name",
+      "mirror": { "registry": "https://registry.example.com", "from": "npm" }
+    }
+  }
+}
+```
+
+Each key is a target. `true` publishes under the package's own name to a well-known registry (`npm`, `github`); a string renames the group for that target; an object form takes `{ registry }` plus either `name` (a rename) or `from` (reuse another target's built bytes). `--target prod` then builds one byte-variant group per distinct name, applies the rename to each group's manifest and writes `dist/prod/<group>/pkg`. It also writes `dist/prod/targets.json`, the group-to-registry binding the release step consumes to know what to publish where.
+
+With no `targets` map the build falls back to the single-`npm` group above.
+
+## API Extractor meta
+
+Set the optional `meta` field on `defineBuild` to generate an [API Extractor](https://api-extractor.com/) api-model from a package's type declarations:
+
+```ts
+const config = defineBuild({
+  format: ["esm"],
+  meta: {
+    // directories the generated api-model is copied into on `--target meta`
+    localPaths: ["../mcp/models/@savvy-web/bundler"],
+    tsdoc: {
+      suppressWarnings: [{ messageId: "ae-undocumented" }],
+      tagDefinitions: [{ tagName: "@internal", syntaxKind: "modifier" }],
+    },
+  },
+});
+```
+
+With `meta` set, two behaviors come online:
+
+- `savvy build --target meta` runs API Extractor over the dev build's `.d.ts` — no tsdown build, so it depends only on a prior `--target dev`. It writes the api-model (`<unscoped>.api.json`, `tsdoc-metadata.json` and a resolved `tsconfig.json`) into each `localPaths` directory.
+- `savvy build --target prod` additionally emits the same bundle into `dist/prod/npm/meta` as a release asset alongside `pkg/`.
+
+`meta` is optional; omit it and neither behavior runs. `--target meta` errors if the config has no `meta` field.
+
+## Executable binaries
+
+Set the optional `exe` field to compile a single-executable application (SEA) from a bin entry, via [`@tsdown/exe`](https://www.npmjs.com/package/@tsdown/exe):
+
+```ts
+const config = defineBuild({
+  format: ["esm"],
+  exe: {
+    fileName: "savvy",
+    entry: "./src/bin.ts",
+    // targets default to the package's own os/cpu when omitted
+    targets: [{ platform: "linux", arch: "x64" }],
+  },
+});
+```
+
+`savvy build --target exe` compiles each declared binary into `dist/dev/pkg/bin`. Pass an array to `exe` to compile several. When `targets` is omitted the platform is inferred from the package's `os`/`cpu` fields. `--target exe` errors if the config has no `exe` field.
+
+## JSX
+
+Packages that emit JSX inherit their transform from `tsconfig.json` (`compilerOptions.jsx`/`jsxImportSource`) with no extra config. Set the optional `jsx` field on `defineBuild` to override it:
+
+```ts
+const config = defineBuild({
+  format: ["esm"],
+  jsx: { runtime: "automatic", importSource: "preact" },
+});
+```
+
+The resolved JSX settings feed both the dts tsconfig and the tsdown transform. Omit `jsx` to inherit the tsconfig value.
+
+## Dual-format output
+
+Builds are esm-only by default. Set the `format` field to add a CommonJS output alongside the ESM one:
+
+```ts
+const config = defineBuild({
+  format: ["esm", "cjs"],
+});
+```
+
+A dual-format build emits an ESM `.js` and a require-able CJS `.cjs` plus matching `.d.ts` and `.d.cts` declarations, and writes a manifest carrying both `import` and `require` export conditions. The CJS output uses default-export interop — `module.exports` is the module's default export, so a `require()` of the package yields that value directly. Omit `format`, or pass `["esm"]`, for an ESM-only build.
+
+## Bundling dependencies
+
+Dependencies you declare in `package.json` are externalized automatically — they stay `import`ed from the published `.js` and referenced from the `.d.ts`, and the consumer resolves them from their own `node_modules`. You don't list declared deps anywhere; `externals` exists only to externalize a package tsdown would otherwise bundle (a transitive dep you reference but don't declare). Four fields change the bundling posture, for the cases where a dependency cannot be left external:
+
+```ts
+const config = defineBuild({
+  // force-inline these specific packages into the .js, even ones declared in package.json
+  bundle: ["some-declared-dep"],
+  // force-bundle every non-externalized node_modules and workspace dep into the output
+  bundleNodeModules: true,
+  // inline only these packages' types into the bundled .d.ts; the rest stay external
+  bundledPackages: ["some-types-only-dep"],
+  // externalize these in the declaration pass only — referenced via import in the .d.ts,
+  // still bundled in the .js
+  dtsExternals: ["effect"],
+});
+```
+
+- `bundle` inlines the listed packages into the JavaScript output, the inverse of `externals`, even for packages declared in `package.json` that would otherwise be auto-externalized. Declarations are not inlined by this option — pair it with `bundledPackages` to roll a package's types into the `.d.ts` too.
+- `bundleNodeModules` inlines node_modules and workspace JavaScript into the output so the published package is self-contained, and inlines their types into the bundled `.d.ts` to match.
+- `bundledPackages` inlines only the listed packages' declarations into the `.d.ts` while every other dependency stays external. Use it for a types-only dependency you don't want consumers to install.
+- `dtsExternals` keeps a package out of the declaration bundle when its types cannot be safely inlined — effect's cross-module `declare module` augmentations, for one, inline into conflicting interface extensions in consumers. The package is referenced by `import` in the `.d.ts` and still bundled in the JavaScript, so declare it as a package dependency.
+
+## Per-entry overrides
+
+The format and bundling fields above apply to every export entry. Use `overrides` to pin a subset of entries to their own format and bundling, layered onto the base config. The base build stays as configured; only the listed `entries` (by export subpath) get the override:
+
+```ts
+const config = defineBuild({
+  format: ["esm"], // base entries are ESM-only
+  overrides: [
+    {
+      // this one entry is also require-able, and inlines its node_modules so a
+      // CommonJS caller never has to resolve an ESM-only dependency
+      entries: ["./changesets/markdownlint"],
+      format: ["esm", "cjs"],
+      bundleNodeModules: true,
+    },
+  ],
+});
+```
+
+Each override carries the same `format`, `bundle`, `externals`, `bundleNodeModules`, `bundledPackages` and `dtsExternals` fields as the base config. An override does not inherit the base `externals` — list what that partition needs. The build errors if an override names an export path the package does not declare.
+
+## Minified output
+
+Prod output is not minified by default. This builder targets Node libraries, where readable output matters more than bundle size — minified code degrades stack traces and trips some security scanners. Set `minify` to opt back in:
+
+```ts
+const config = defineBuild({
+  minify: true, // applies to prod target groups only; dev is never minified
+});
+```
+
+## Manifest transform
+
+Every build runs a manifest transform after resolving `publishConfig.targets`, to produce the published `package.json`. By default it strips build- and dev-only fields (`devDependencies`, `scripts`, `publishConfig` and the like). Supplying your own `transform` replaces that default — import `defaultManifestTransform` and call it from yours if you still want the stripping:
+
+```ts
+import { defaultManifestTransform, defineBuild } from "@savvy-web/bundler";
+
+const config = defineBuild({
+  transform: ({ pkg }) => {
+    // custom manifest work here
+    return defaultManifestTransform({ pkg });
+  },
+});
+```
+
+## Features
+
+- **One self-executing config** — `savvy.build.ts` exports a `defineBuild` object for tooling to introspect and runs the build when invoked directly. No factory-notation config file.
+- **Four build targets** — `dev` for local linking, `npm` for a resolved publishable manifest, `meta` for an API Extractor api-model and `exe` for SEA binaries, on disjoint `dist/dev` and `dist/prod` output paths for clean caching.
+- **Bundled declarations** — per-module JavaScript with a single rolled-up `.d.ts` per public entry, so re-exported types stay reachable through your published export subpaths.
+- **Shared tsconfig base** — extend `@savvy-web/bundler/ecma.json` for the ESNext/NodeNext/strict settings the build expects.
+- **Manifest resolution** — `catalog:` and `workspace:` specifiers are resolved against the workspace for the published target, and preserved for the linked dev target.
+- **Multi-target publishing** — a `publishConfig.targets` map publishes one package to several registries or under several names; `--target prod` builds the distinct byte variants and writes a `targets.json` binding for the release step.
+- **Executable binaries** — an `exe` config compiles SEA binaries from a bin entry via `@tsdown/exe`, inferring the platform from the package's `os`/`cpu` when targets are omitted.
+- **JSX, config-first** — JSX transform is inherited from `tsconfig.json` and overridable via the `jsx` field, feeding both the dts tsconfig and the tsdown transform.
+- **Dual-format output** — esm-only by default; set `format` to `["esm", "cjs"]` for a require-able CJS output with default-export interop, `.d.cts` declarations and dual `import`/`require` export conditions.
+- **Dependency bundling** — declared dependencies stay external by default; `bundle`, `bundleNodeModules`, `bundledPackages` and `dtsExternals` force-inline specific packages or all node_modules into the output, inline select declarations into the `.d.ts` or hold a package out of the declaration bundle when its types cannot be inlined.
+- **Per-entry overrides** — `overrides` pins a subset of export entries to their own format and bundling, so one entry can ship dual-format CJS in an otherwise ESM-only package without changing the rest.
+- **Readable prod output** — prod output is unminified by default to keep stack traces legible and pass security scanners; `minify` opts back in.
+- **Default manifest stripping** — the published `package.json` drops build- and dev-only fields automatically; a custom `transform` replaces the default and can re-apply it via `defaultManifestTransform`.
+- **Fast-fail config validation** — `runBuild` validates the config (`publishConfig.targets`, `exe`, `meta`) before any build work, raising a typed `ConfigValidationError` on the first violation.
+- **One devDependency** — `tsdown` is a regular dependency, pinned and tested transitively, so you never carry it or its plugin peers in your own tree.
+- **Injectable orchestration** — `runBuild` takes its IO dependencies as options, so the build is testable without spawning a real bundle.
+- **Escape hatch** — every build behavior lives in [`@savvy-web/tsdown-plugins`](https://www.npmjs.com/package/@savvy-web/tsdown-plugins); compose the same helpers in a hand-written `tsdown.config.ts` when you outgrow the front door.
+
+## API
+
+- `defineBuild(input)` — normalizes a build config (`externals`, `bundle`, `bundleNodeModules`, `bundledPackages`, `dtsExternals`, `minify`, `devManifest`, `transform`, `output`, `meta`, `jsx`, `exe`, `format`, `overrides`), applying defaults. The `format` field controls the output module formats forwarded to tsdown (esm-only by default; add `"cjs"` for a dual-format esm+cjs build). `minify` defaults to false, `transform` defaults to a manifest stripper, and `overrides` pins a subset of entries to their own format and bundling. Pure; it does not run the build.
+- `runBuild(config, options)` — the orchestrator. Parses `--target`/`--watch` from `options.argv`, reads `package.json` at `options.cwd`, derives entries, drives the build for the selected target and renders a report. Every IO dependency on `options` is injectable for tests.
+- `parseArgs(argv)` — the argument parser behind `runBuild`, exported for embedding.
+
+## Turbo tasks
+
+`pnpm turbo run build:meta` regenerates api-models into the `localPaths` configured in each package's `savvy.build.ts`, reading the dev build's `dist/dev/pkg` dts; it depends on `build:dev` and is intentionally uncached because it writes outside the package's own cache scope.
+
+## License
+
+[MIT](LICENSE)

package/config.js

@@ -0,0 +1,39 @@
+import { defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+
+//#region src/config.ts
+/** Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts). */
+function defineBuild(input = {}) {
+	return {
+		formats: input.formats ?? ["esm"],
+		externals: input.externals ?? [],
+		bundledPackages: input.bundledPackages,
+		dtsExternals: input.dtsExternals,
+		bundleNodeModules: input.bundleNodeModules,
+		bundle: input.bundle,
+		minify: input.minify ?? false,
+		devManifest: input.devManifest ?? "preserve",
+		transform: input.transform ?? defaultManifestTransform,
+		output: input.output,
+		meta: input.meta,
+		jsx: input.jsx,
+		exe: input.exe,
+		format: input.format,
+		overrides: input.overrides
+	};
+}
+function parseArgs(argv) {
+	let target = "dev";
+	let watch = false;
+	for (let i = 0; i < argv.length; i++) if (argv[i] === "--target") {
+		const v = argv[i + 1];
+		if (v === "dev" || v === "prod" || v === "meta" || v === "exe") target = v;
+		i++;
+	} else if (argv[i] === "--watch") watch = true;
+	return {
+		target,
+		watch
+	};
+}
+
+//#endregion
+export { defineBuild, parseArgs };

package/index.d.ts

@@ -0,0 +1,180 @@
+import { BuildFormat, BuildTargetGroupsOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, MetaOptions, MetaResult, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+
+//#region src/config.d.ts
+interface BuildEntryOverride {
+  /** Export paths to pin to this partition, e.g. "./changesets/markdownlint" (or "." for root). */
+  readonly entries: ReadonlyArray<string>;
+  readonly format?: ReadonlyArray<BuildFormat> | undefined;
+  readonly bundle?: ReadonlyArray<string> | undefined;
+  readonly externals?: ReadonlyArray<string> | undefined;
+  readonly bundleNodeModules?: boolean | undefined;
+  readonly bundledPackages?: ReadonlyArray<string> | undefined;
+  readonly dtsExternals?: ReadonlyArray<string> | undefined;
+}
+interface OutputConfig {
+  readonly console?: {
+    readonly human?: boolean;
+    readonly agent?: boolean;
+    readonly ci?: boolean;
+  };
+  readonly format?: "terminal" | "json" | "markdown" | "ci-annotations" | "silent";
+}
+interface BuildConfigInput {
+  readonly formats?: ReadonlyArray<"esm">;
+  readonly externals?: ReadonlyArray<string>;
+  /**
+   * External packages whose type declarations are inlined into the bundled dts
+   * (the rslib `dtsBundledPackages` equivalent). Only these node_modules
+   * packages are rolled into the emitted `.d.ts`; all other deps stay external.
+   */
+  readonly bundledPackages?: ReadonlyArray<string> | undefined;
+  /**
+   * Packages externalized in the dts pass ONLY — referenced via `import` in the
+   * emitted `.d.ts` rather than inlined — while the JS pass still bundles them per
+   * `bundleNodeModules`. Use when a dependency's types cannot be safely inlined,
+   * for example effect's cross-module `declare module` augmentations, which inline
+   * into conflicting interface-extension errors in consumers. Declare these as
+   * package dependencies so consumers can resolve the emitted type imports.
+   */
+  readonly dtsExternals?: ReadonlyArray<string> | undefined;
+  /**
+   * Force-bundle node_modules (and workspace) JS dependencies that are not
+   * externalized into the package output, restoring the self-contained bundle
+   * the rslib builder produced. Threads tsdown `deps.skipNodeModulesBundle:
+   * false` into BOTH the JS output and the bundled declarations: the dts posture
+   * tracks the JS posture, so node_modules types are inlined into the `.d.ts`
+   * and the published package needs no extra declared deps for them. Defaults to false.
+   */
+  readonly bundleNodeModules?: boolean | undefined;
+  /**
+   * Force-bundle (inline) these packages into the JS output, even ones declared in
+   * package.json that would otherwise be auto-externalized. The inverse of `externals`;
+   * maps to tsdown `deps.alwaysBundle`. Accepts package names. Use when you declare a
+   * dependency for metadata/types but want its code inlined. Declarations are NOT
+   * inlined by this option — use `bundledPackages` to also roll a package's types into
+   * the emitted `.d.ts`.
+   */
+  readonly bundle?: ReadonlyArray<string> | undefined;
+  /**
+   * Minify the prod build output. Applies ONLY to prod target groups (dev is never
+   * minified) and defaults to false: this builder targets Node libraries, where
+   * readable output matters more than bundle size — minified/obfuscated code trips
+   * security/SCA scanners and degrades stack traces. Set true to opt back in.
+   */
+  readonly minify?: boolean | undefined;
+  readonly devManifest?: "preserve" | "resolve";
+  /**
+   * Final mutation of the emitted package.json, run after the declarative
+   * `publishConfig.targets` rename. Defaults to {@link defaultManifestTransform},
+   * which strips build/dev-only fields (devDependencies, scripts, publishConfig,
+   * etc.). Supplying your own REPLACES that default — import and call
+   * `defaultManifestTransform` from it if you still want the stripping.
+   */
+  readonly transform?: (args: {
+    pkg: Json;
+    targetGroup: TargetGroupRef;
+  }) => Json;
+  readonly output?: OutputConfig;
+  readonly meta?: MetaOptions;
+  readonly jsx?: JsxConfig | undefined;
+  readonly exe?: ExeConfig | ReadonlyArray<ExeConfig> | undefined;
+  /**
+   * Output module formats forwarded to the tsdown build. Defaults to esm-only;
+   * add "cjs" for a dual-format esm plus cjs build. This is the live field;
+   * the legacy "formats" field above is not consumed by the build.
+   */
+  readonly format?: ReadonlyArray<BuildFormat> | undefined;
+  /**
+   * Per-entry format/bundling overrides. Each group pins its `entries` (export paths) to
+   * its own format and bundling, layered onto the base build. Use to keep one entry CJS in
+   * an otherwise ESM-only package (e.g. silk's `./changesets/markdownlint`).
+   */
+  readonly overrides?: ReadonlyArray<BuildEntryOverride> | undefined;
+}
+interface BuildConfig {
+  readonly formats: ReadonlyArray<"esm">;
+  readonly externals: ReadonlyArray<string>;
+  /**
+   * External packages whose type declarations are inlined into the bundled dts
+   * (the rslib `dtsBundledPackages` equivalent). Only these node_modules
+   * packages are rolled into the emitted `.d.ts`; all other deps stay external.
+   */
+  readonly bundledPackages?: ReadonlyArray<string> | undefined;
+  /**
+   * Packages externalized in the dts pass ONLY — referenced via `import` in the
+   * emitted `.d.ts` rather than inlined — while the JS pass still bundles them per
+   * `bundleNodeModules`. Use when a dependency's types cannot be safely inlined
+   * (e.g. effect's cross-module `declare module` augmentations). Declare these as
+   * package dependencies so consumers can resolve the emitted type imports.
+   */
+  readonly dtsExternals?: ReadonlyArray<string> | undefined;
+  /**
+   * Force-bundle node_modules (and workspace) JS dependencies that are not
+   * externalized into the package output (rslib parity). Threads tsdown
+   * `deps.skipNodeModulesBundle: false` into BOTH the JS output and the bundled
+   * declarations — the dts posture tracks the JS posture, inlining node_modules
+   * types into the `.d.ts`. Defaults to false.
+   */
+  readonly bundleNodeModules?: boolean | undefined;
+  /** Force-bundle (inline) these packages into the JS output (tsdown `deps.alwaysBundle`). Inverse of `externals`. */
+  readonly bundle?: ReadonlyArray<string> | undefined;
+  /** Minify prod output (prod groups only; dev is never minified). defineBuild defaults this to false. */
+  readonly minify?: boolean | undefined;
+  readonly devManifest: "preserve" | "resolve";
+  readonly transform?: ((args: {
+    pkg: Json;
+    targetGroup: TargetGroupRef;
+  }) => Json) | undefined;
+  readonly output?: OutputConfig | undefined;
+  readonly meta?: MetaOptions | undefined;
+  readonly jsx?: JsxConfig | undefined;
+  readonly exe?: ExeConfig | ReadonlyArray<ExeConfig> | undefined;
+  /** Output module formats forwarded to the tsdown build (esm-only by default; add "cjs" for dual-format). */
+  readonly format?: ReadonlyArray<BuildFormat> | undefined;
+  readonly overrides?: ReadonlyArray<BuildEntryOverride> | undefined;
+}
+/** Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts). */
+declare function defineBuild(input?: BuildConfigInput): BuildConfig;
+interface ParsedArgs {
+  readonly target: "dev" | "prod" | "meta" | "exe";
+  readonly watch: boolean;
+}
+declare function parseArgs(argv: ReadonlyArray<string>): ParsedArgs;
+//#endregion
+//#region src/run.d.ts
+interface RunOptions {
+  readonly cwd: string;
+  readonly argv: ReadonlyArray<string>;
+  /** Injectable for tests. */
+  readonly buildTargetGroups?: (o: BuildTargetGroupsOptions) => Promise<void>;
+  /** Injectable for tests: consumes rendered output (defaults to process.stdout.write). */
+  readonly writeOutput?: (output: RenderedOutput) => void;
+  /** Injectable for tests: returns the package version string. */
+  readonly readVersion?: () => string;
+  /** Injectable for tests: returns the package name. */
+  readonly readPackageName?: () => string;
+  /** Injectable for tests: writes the resolved tsconfig and returns its path (defaults to writeResolvedTsconfig, which writes to the OS temp dir). */
+  readonly writeTsconfig?: (cwd: string) => string;
+  /** Injectable for tests. */
+  readonly generateMeta?: (o: GenerateMetaOptions) => Promise<MetaResult>;
+  /** Injectable for tests: returns the package.json `exports` map. */
+  readonly readExports?: () => Record<string, string> | undefined;
+  /** Injectable for tests: returns package.json publishConfig.targets, or undefined. */
+  readonly readPublishTargets?: (() => PublishTargets | undefined) | undefined;
+  /** Injectable for tests: writes the target binding artifact. */
+  readonly writeTargetsBinding?: ((cwd: string, resolution: TargetResolution) => string) | undefined;
+  /** Injectable for tests: reads the jsx-relevant tsconfig compilerOptions slice. */
+  readonly readTsconfigJsx?: (() => TsconfigJsx) | undefined;
+  /** Injectable for tests. */
+  readonly runExeBuild?: ((o: RunExeBuildOptions) => Promise<void>) | undefined;
+  /** Injectable for tests: returns the package os/cpu arrays. */
+  readonly readOsCpu?: (() => {
+    os: ReadonlyArray<string>;
+    cpu: ReadonlyArray<string>;
+  }) | undefined;
+}
+/** Run a build from a normalized config. Pure orchestration; all IO injectable. */
+declare function runBuild(config: BuildConfig, options: RunOptions): Promise<void>;
+//#endregion
+export { type BuildConfig, type BuildConfigInput, type BuildEntryOverride, type OutputConfig, type ParsedArgs, type RunOptions, defaultManifestTransform, defineBuild, parseArgs, runBuild };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,5 @@
+import { defineBuild, parseArgs } from "./config.js";
+import { runBuild } from "./run.js";
+import { defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+
+export { defaultManifestTransform, defineBuild, parseArgs, runBuild };

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@savvy-web/bundler",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Zero-config tsdown-based bundler for Silk Suite TypeScript packages",
+	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/bundler",
+	"bugs": {
+		"url": "https://github.com/savvy-web/systems/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/savvy-web/systems.git",
+		"directory": "packages/bundler"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@savvyweb.systems",
+		"url": "https://savvyweb.systems"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./ecma.json": "./public/ecma.json"
+	},
+	"dependencies": {
+		"@savvy-web/tsdown-plugins": "0.1.0",
+		"@tsdown/exe": "^0.22.1",
+		"tsdown": "^0.22.2"
+	},
+	"peerDependencies": {
+		"effect": ">=3.21.0"
+	}
+}

package/public/ecma.json

@@ -0,0 +1,55 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"compilerOptions": {
+		"allowSyntheticDefaultImports": true,
+		"composite": true,
+		"declaration": true,
+		"declarationDir": "${configDir}/dist",
+		"declarationMap": false,
+		"emitDeclarationOnly": false,
+		"esModuleInterop": true,
+		"explainFiles": false,
+		"forceConsistentCasingInFileNames": true,
+		"incremental": true,
+		"isolatedDeclarations": false,
+		"isolatedModules": true,
+		"exactOptionalPropertyTypes": true,
+		"jsx": "preserve",
+		"lib": ["esnext"],
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"outDir": "${configDir}/dist",
+		"resolveJsonModule": true,
+		"rootDir": "${configDir}",
+		"skipLibCheck": true,
+		"sourceMap": false,
+		"strict": true,
+		"strictNullChecks": true,
+		"target": "es2023",
+		"tsBuildInfoFile": "${configDir}/dist/.tsbuildinfo.lib",
+		"typeRoots": ["${configDir}/node_modules/@types", "${configDir}/types"],
+		"verbatimModuleSyntax": true,
+		"types": ["node"]
+	},
+	"exclude": ["${configDir}/node_modules", "${configDir}/dist/**/*"],
+	"include": [
+		"${configDir}/types/*.ts",
+		"${configDir}/package.json",
+		"${configDir}/*.ts",
+		"${configDir}/*.cts",
+		"${configDir}/*.mts",
+		"${configDir}/src/**/*.ts",
+		"${configDir}/src/**/*.tsx",
+		"${configDir}/src/**/*.cts",
+		"${configDir}/src/**/*.mts",
+		"${configDir}/lib/**/*.ts",
+		"${configDir}/lib/**/*.tsx",
+		"${configDir}/lib/**/*.cts",
+		"${configDir}/lib/**/*.mts",
+		"${configDir}/__test__/**/*.ts",
+		"${configDir}/__test__/**/*.tsx",
+		"${configDir}/__test__/**/*.cts",
+		"${configDir}/__test__/**/*.mts",
+		"${configDir}/public/**/*.json"
+	]
+}

package/run.js

@@ -0,0 +1,225 @@
+import { parseArgs } from "./config.js";
+import { ConfigValidator, ConfigValidatorLive, ReportPipelineLive, buildTargetGroups, createEntryName, generateMeta, normalizeExeOptions, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveTargets, runExeBuild, writeResolvedTsconfig, writeTargetsBinding } from "@savvy-web/tsdown-plugins";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Effect } from "effect";
+
+//#region src/run.ts
+/** Read and parse package.json at cwd, returning an empty object on any error. */
+function readPackageJson(cwd) {
+	try {
+		return JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
+	} catch {
+		return {};
+	}
+}
+/** Resolve the prod build groups and the target binding from publishConfig.targets (or the single-npm default). */
+function deriveProdGroups(targets, baseName) {
+	const resolution = resolveTargets({
+		targets: targets !== void 0 && Object.keys(targets).length > 0 ? targets : { npm: true },
+		baseName
+	});
+	return {
+		groups: resolution.groups.map((g) => ({
+			id: g.id,
+			name: g.name
+		})),
+		resolution
+	};
+}
+/** Map entry names to export paths using the package exports map. index maps to ".". */
+function deriveExportPaths(entries, exportsMap) {
+	const out = {};
+	const sourceToKey = /* @__PURE__ */ new Map();
+	if (exportsMap) for (const [key, src] of Object.entries(exportsMap)) sourceToKey.set(src, key);
+	for (const [entryName, src] of Object.entries(entries)) out[entryName] = sourceToKey.get(src) ?? (entryName === "index" ? "." : `./${entryName}`);
+	return out;
+}
+/** Run a build from a normalized config. Pure orchestration; all IO injectable. */
+async function runBuild(config, options) {
+	const { target } = parseArgs(options.argv);
+	const build = options.buildTargetGroups ?? buildTargetGroups;
+	const cwd = options.cwd;
+	const pkg = readPackageJson(cwd);
+	const version = options.readVersion ? options.readVersion() : pkg.version ?? "0.0.0";
+	const packageName = options.readPackageName ? options.readPackageName() : pkg.name ?? "unknown";
+	const jsx = resolveJsxConfig((options.readTsconfigJsx ?? (() => readTsconfigJsx(cwd)))(), config.jsx);
+	const tsconfigPath = (options.writeTsconfig ?? ((c) => writeResolvedTsconfig({
+		cwd: c,
+		...jsx?.runtime === "automatic" ? {
+			jsx: "react-jsx",
+			jsxImportSource: jsx.importSource
+		} : {},
+		...jsx?.runtime === "classic" ? { jsx: "react" } : {}
+	})))(cwd);
+	const entries = packageJsonEntries({
+		pkg,
+		cwd
+	});
+	const exportsMap = options.readExports ? options.readExports() : pkg.exports;
+	const runGenerateMeta = options.generateMeta ?? generateMeta;
+	const publishTargets = (options.readPublishTargets ?? (() => {
+		const declared = pkg.publishConfig?.targets;
+		return declared !== void 0 && !Array.isArray(declared) && typeof declared === "object" ? declared : void 0;
+	}))();
+	const writeBinding = options.writeTargetsBinding ?? writeTargetsBinding;
+	const osCpuForValidate = options.readOsCpu ? options.readOsCpu() : {
+		os: pkg.os ?? [],
+		cpu: pkg.cpu ?? []
+	};
+	await Effect.runPromise(Effect.flatMap(ConfigValidator, (v) => v.validate({
+		baseName: packageName,
+		hasExports: exportsMap !== void 0 && Object.keys(exportsMap).length > 0,
+		...publishTargets !== void 0 ? { targets: publishTargets } : {},
+		...config.exe !== void 0 ? { exe: config.exe } : {},
+		osCpu: osCpuForValidate,
+		...config.meta !== void 0 ? { meta: config.meta } : {}
+	})).pipe(Effect.provide(ConfigValidatorLive)));
+	if (target === "meta") {
+		if (config.meta === void 0) throw new Error("`savvy build --target meta` requires a `meta` option in the build config");
+		const norm = normalizeMetaOptions(config.meta);
+		const dtsBasenames = {};
+		for (const name of Object.keys(entries)) dtsBasenames[name] = name;
+		await runGenerateMeta({
+			cwd,
+			packageName,
+			tsconfigPath,
+			dtsDir: join(cwd, "dist", "dev", "pkg"),
+			entries: dtsBasenames,
+			exportPaths: deriveExportPaths(entries, exportsMap),
+			outMetaDir: join(cwd, "dist", "dev", "meta"),
+			localPaths: norm.localPaths,
+			tsdoc: norm.tsdoc
+		});
+		(options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`)))({
+			target: "stdout",
+			contentType: "text/plain",
+			content: `meta: wrote api-model for ${packageName} to ${norm.localPaths.length} localPath(s)`
+		});
+		return;
+	}
+	if (target === "exe") {
+		if (config.exe === void 0) throw new Error("`savvy build --target exe` requires an `exe` option in the build config");
+		const specs = normalizeExeOptions(config.exe, osCpuForValidate);
+		await (options.runExeBuild ?? runExeBuild)({
+			cwd,
+			outDir: join(cwd, "dist", "dev", "pkg", "bin"),
+			specs
+		});
+		(options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`)))({
+			target: "stdout",
+			contentType: "text/plain",
+			content: `exe: compiled ${specs.length} binary/binaries for ${packageName}`
+		});
+		return;
+	}
+	let overridePartitions = [];
+	let baseEntries = entries;
+	let dualExports;
+	if (config.overrides) {
+		const partitions = [];
+		const overriddenEntryNames = /* @__PURE__ */ new Set();
+		const baseFormatHasCjs = (config.format ?? ["esm"]).includes("cjs");
+		const dualExportKeys = /* @__PURE__ */ new Set();
+		const exportPathByEntry = deriveExportPaths(entries, exportsMap);
+		for (const ov of config.overrides) {
+			const partEntry = {};
+			for (const exportPath of ov.entries) {
+				if (exportPath !== "." && !exportPath.startsWith("./")) throw new Error(`overrides: entry "${exportPath}" must be a canonical export path — use "." for the root or a "./"-prefixed subpath (e.g. "./changesets/markdownlint")`);
+				const entryName = createEntryName(exportPath, false);
+				const src = entries[entryName];
+				if (src === void 0) throw new Error(`overrides: export path "${exportPath}" (entry "${entryName}") is not a build entry of ${packageName}`);
+				partEntry[entryName] = src;
+				overriddenEntryNames.add(entryName);
+				if ((ov.format ?? config.format ?? ["esm"]).includes("cjs")) dualExportKeys.add(exportPath);
+			}
+			partitions.push({
+				entry: partEntry,
+				...ov.format !== void 0 ? { format: ov.format } : {},
+				...ov.externals !== void 0 ? { externals: ov.externals } : {},
+				...ov.bundle !== void 0 ? { bundle: ov.bundle } : {},
+				...ov.bundleNodeModules !== void 0 ? { bundleNodeModules: ov.bundleNodeModules } : {},
+				...ov.bundledPackages !== void 0 ? { bundledPackages: ov.bundledPackages } : {},
+				...ov.dtsExternals !== void 0 ? { dtsExternals: ov.dtsExternals } : {}
+			});
+		}
+		const onlyBase = {};
+		for (const [name, src] of Object.entries(entries)) {
+			if (overriddenEntryNames.has(name)) continue;
+			onlyBase[name] = src;
+			if (baseFormatHasCjs) dualExportKeys.add(exportPathByEntry[name] ?? (name === "index" ? "." : `./${name}`));
+		}
+		overridePartitions = partitions;
+		baseEntries = onlyBase;
+		dualExports = dualExportKeys;
+	}
+	const startMs = Date.now();
+	const { groups, resolution } = target === "dev" ? {
+		groups: [{
+			id: "dev",
+			name: packageName
+		}],
+		resolution: void 0
+	} : deriveProdGroups(publishTargets, packageName);
+	await build({
+		cwd,
+		version,
+		entry: config.overrides !== void 0 ? baseEntries : entries,
+		tsconfigPath,
+		groups,
+		devManifest: config.devManifest,
+		externals: config.externals,
+		...config.bundledPackages !== void 0 ? { bundledPackages: config.bundledPackages } : {},
+		...config.dtsExternals !== void 0 ? { dtsExternals: config.dtsExternals } : {},
+		...config.bundleNodeModules !== void 0 ? { bundleNodeModules: config.bundleNodeModules } : {},
+		...config.bundle !== void 0 ? { bundle: config.bundle } : {},
+		...config.minify !== void 0 ? { minify: config.minify } : {},
+		...config.transform !== void 0 ? { transform: config.transform } : {},
+		...jsx !== void 0 ? { jsx } : {},
+		...config.format !== void 0 ? { format: config.format } : {},
+		...overridePartitions.length > 0 ? { overrides: overridePartitions } : {},
+		...dualExports !== void 0 ? { dualExports } : {}
+	});
+	if (target === "prod" && resolution !== void 0) writeBinding(cwd, resolution);
+	if (target === "prod" && config.meta !== void 0) {
+		const metaGroupId = (groups.find((g) => g.name === packageName) ?? groups[0])?.id ?? "npm";
+		const norm = normalizeMetaOptions(config.meta);
+		const dtsBasenames = {};
+		for (const name of Object.keys(entries)) dtsBasenames[name] = name;
+		await runGenerateMeta({
+			cwd,
+			packageName,
+			tsconfigPath,
+			dtsDir: join(cwd, "dist", "prod", metaGroupId, "pkg"),
+			entries: dtsBasenames,
+			exportPaths: deriveExportPaths(entries, exportsMap),
+			outMetaDir: join(cwd, "dist", "prod", metaGroupId, "meta"),
+			localPaths: [],
+			tsdoc: norm.tsdoc
+		});
+	}
+	if (target === "prod") for (const g of groups) removeDeclarationMaps(join(cwd, "dist", "prod", g.id, "pkg"));
+	const totalMs = Date.now() - startMs;
+	const reportEntries = Object.keys(entries);
+	const report = {
+		package: packageName,
+		targetGroups: groups.map((g) => ({
+			id: g.id,
+			entries: reportEntries,
+			emittedFiles: [],
+			timings: { totalMs },
+			warnings: [],
+			errors: []
+		}))
+	};
+	const explicitFormat = config.output?.format;
+	const rendered = await Effect.runPromise(renderReport([report], {
+		...explicitFormat !== void 0 ? { explicitFormat } : {},
+		noColor: process.env.NO_COLOR !== void 0 || !process.stdout.isTTY
+	}).pipe(Effect.provide(ReportPipelineLive)));
+	const writeOutput = options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`));
+	for (const output of rendered) writeOutput(output);
+}
+
+//#endregion
+export { runBuild };