@savvy-web/bundler 0.2.1 → 0.4.0

package/README.md

@@ -87,7 +87,16 @@ 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:
+The bundler generates an [API Extractor](https://api-extractor.com/) api-model from a package's type declarations. 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/`.
+
+The `meta` field on `defineBuild` is tri-state and controls these:
+
+- **Omitted** (or `undefined`) — generation runs with default options. `--target meta` works with no configuration and `--target prod` emits the meta asset. This is the default; you do not need a `meta` field to use `--target meta`.
+- **An object** — override the defaults: `localPaths` (directories the api-model is copied into on `--target meta`) and `tsdoc` (warning suppression and custom tags).
+- **`false`** — opt out entirely; both `--target meta` and the prod meta asset become no-ops.
 
 ```ts
 const config = defineBuild({
@@ -101,14 +110,10 @@ const config = defineBuild({
     },
   },
 });
-```
-
-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.
+// Or opt out of api-model generation altogether:
+// const config = defineBuild({ meta: false });
+```
 
 ## Executable binaries
 
@@ -197,6 +202,22 @@ const config = defineBuild({
 
 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.
 
+## Loose files
+
+Every output above lands at a path the package's `exports` map addresses. Some files have to sit at a fixed name the runtime resolves by convention, outside that graph — a pnpm config dependency, for one, forbids runtime `dependencies` and resolves its `pnpmfile.mjs`/`pnpmfile.cjs` by filename at the package root. Use `looseFiles` to emit a standalone bundled file at a literal output path, with no exports entry, no declaration and no api-model:
+
+```ts
+const config = defineBuild({
+  bundleNodeModules: true,
+  looseFiles: {
+    "pnpmfile.mjs": "./src/pnpmfile.ts",
+    "pnpmfile.cjs": "./src/pnpmfile.ts",
+  },
+});
+```
+
+Each key is the literal output filename written into the package root; each value is a source path (a bare string) or a `{ source, format }` object. The format is inferred from the key extension — `.mjs` is ESM, `.cjs` is CJS — so the example above bundles the one source into both an ESM and a CJS file from a single config. A `.js` key is format-ambiguous and needs an explicit `format`. Pair `looseFiles` with `bundleNodeModules` so each file is self-contained, since a config dependency cannot resolve runtime `dependencies` of its own.
+
 ## 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:
@@ -222,6 +243,28 @@ const config = defineBuild({
 });
 ```
 
+## Build-time constants
+
+The build injects `process.env.__PACKAGE_VERSION__` as a compile-time constant set to the package's version, so source can read its own version without importing `package.json` at runtime:
+
+```ts
+// somewhere in src/
+const version = process.env.__PACKAGE_VERSION__;
+// the reference is replaced at build time with the package's version as a string literal
+```
+
+Add your own compile-time replacements with the `define` field. Values are inserted verbatim, so string literals must be pre-quoted:
+
+```ts
+const config = defineBuild({
+  define: {
+    "process.env.FLAG": JSON.stringify("on"),
+  },
+});
+```
+
+`define` merges with the auto-injected version constant; a key of `process.env.__PACKAGE_VERSION__` in your own `define` wins.
+
 ## 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.
@@ -235,8 +278,10 @@ const config = defineBuild({
 - **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.
+- **Loose files** — `looseFiles` emits standalone bundled files at literal output paths outside the exports/declaration/api-model graph, with the format inferred from the key extension; pair with `bundleNodeModules` for self-contained pnpm config-dependency pnpmfiles.
 - **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`.
+- **Build-time constants** — the package version is injected as `process.env.__PACKAGE_VERSION__`, and the `define` field adds your own verbatim compile-time replacements.
 - **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.
@@ -244,7 +289,7 @@ const config = defineBuild({
 
 ## 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.
+- `defineBuild(input)` — normalizes a build config (`externals`, `bundle`, `bundleNodeModules`, `bundledPackages`, `dtsExternals`, `minify`, `devManifest`, `transform`, `output`, `meta`, `jsx`, `exe`, `format`, `overrides`, `looseFiles`, `define`), 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.
 

package/config.js

@@ -18,7 +18,9 @@ function defineBuild(input = {}) {
 		jsx: input.jsx,
 		exe: input.exe,
 		format: input.format,
-		overrides: input.overrides
+		overrides: input.overrides,
+		looseFiles: input.looseFiles,
+		define: input.define
 	};
 }
 function parseArgs(argv) {

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BuildFormat, BuildTargetGroupsOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, MetaOptions, MetaResult, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+import { BuildFormat, BuildTargetGroupsOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, LooseFiles, MetaOptions, MetaResult, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
 
 //#region src/config.d.ts
 interface BuildEntryOverride {
@@ -75,7 +75,13 @@ interface BuildConfigInput {
     targetGroup: TargetGroupRef;
   }) => Json;
   readonly output?: OutputConfig;
-  readonly meta?: MetaOptions;
+  /**
+   * API-model (meta) generation. Tri-state: omit it (or `undefined`) to generate with
+   * DEFAULT options — `savvy build --target meta` always works and `--target prod` emits the
+   * meta release asset. Pass an object to override the defaults (`localPaths`, `tsdoc`). Pass
+   * `false` to opt OUT entirely — both `--target meta` and the prod meta asset become no-ops.
+   */
+  readonly meta?: MetaOptions | false;
   readonly jsx?: JsxConfig | undefined;
   readonly exe?: ExeConfig | ReadonlyArray<ExeConfig> | undefined;
   /**
@@ -90,6 +96,21 @@ interface BuildConfigInput {
    * an otherwise ESM-only package (e.g. silk's `./changesets/markdownlint`).
    */
   readonly overrides?: ReadonlyArray<BuildEntryOverride> | undefined;
+  /**
+   * Standalone bundled output files emitted at literal paths (e.g. pnpm config-dependency
+   * pnpmfiles), outside the exports/dts/meta graph. Keys are literal output filenames; values
+   * are a source path (bare string) or `{ source, format }`. Format is inferred from a
+   * `.mjs`/`.cjs` key and required for an ambiguous `.js` key. Pair with `bundleNodeModules`
+   * to make each file self-contained.
+   */
+  readonly looseFiles?: LooseFiles | undefined;
+  /**
+   * Compile-time global replacements forwarded to the tsdown/rolldown build `define`.
+   * Values are inserted VERBATIM, so string literals must be quoted:
+   * `{ "process.env.FLAG": JSON.stringify("on") }`. Merged with the auto-injected
+   * `process.env.__PACKAGE_VERSION__` define; a user key of the same name wins.
+   */
+  readonly define?: Record<string, string> | undefined;
 }
 interface BuildConfig {
   readonly formats: ReadonlyArray<"esm">;
@@ -126,12 +147,16 @@ interface BuildConfig {
     targetGroup: TargetGroupRef;
   }) => Json) | undefined;
   readonly output?: OutputConfig | undefined;
-  readonly meta?: MetaOptions | undefined;
+  readonly meta?: MetaOptions | false | 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;
+  /** Standalone bundled output files emitted at literal paths, outside the exports/dts/meta graph. */
+  readonly looseFiles?: LooseFiles | undefined;
+  /** Compile-time global replacements forwarded to the build `define` (merged with the auto-version). */
+  readonly define?: Record<string, string> | undefined;
 }
 /** Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts). */
 declare function defineBuild(input?: BuildConfigInput): BuildConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/bundler",
-	"version": "0.2.1",
+	"version": "0.4.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",
@@ -24,10 +24,11 @@
 			"types": "./index.d.ts",
 			"import": "./index.js"
 		},
-		"./ecma.json": "./public/ecma.json"
+		"./ecma.json": "./public/ecma.json",
+		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@savvy-web/tsdown-plugins": "0.2.1",
+		"@savvy-web/tsdown-plugins": "0.4.0",
 		"@tsdown/exe": "^0.22.1",
 		"tsdown": "^0.22.2"
 	},

package/run.js

@@ -1,5 +1,5 @@
 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 { ConfigValidator, ConfigValidatorLive, ReportPipelineLive, buildTargetGroups, createEntryName, generateMeta, normalizeExeOptions, normalizeLooseFiles, 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";
@@ -73,11 +73,19 @@ async function runBuild(config, options) {
 		...publishTargets !== void 0 ? { targets: publishTargets } : {},
 		...config.exe !== void 0 ? { exe: config.exe } : {},
 		osCpu: osCpuForValidate,
-		...config.meta !== void 0 ? { meta: config.meta } : {}
+		...config.meta !== void 0 && config.meta !== false ? { meta: config.meta } : {},
+		...config.looseFiles !== void 0 ? { looseFiles: config.looseFiles } : {}
 	})).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);
+		if (config.meta === false) {
+			(options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`)))({
+				target: "stdout",
+				contentType: "text/plain",
+				content: `meta: generation disabled (meta: false) for ${packageName}`
+			});
+			return;
+		}
+		const norm = normalizeMetaOptions(config.meta ?? {});
 		const dtsBasenames = {};
 		for (const name of Object.keys(entries)) dtsBasenames[name] = name;
 		await runGenerateMeta({
@@ -153,6 +161,7 @@ async function runBuild(config, options) {
 		baseEntries = onlyBase;
 		dualExports = dualExportKeys;
 	}
+	const looseFiles = config.looseFiles !== void 0 ? normalizeLooseFiles(config.looseFiles) : void 0;
 	const startMs = Date.now();
 	const { groups, resolution } = target === "dev" ? {
 		groups: [{
@@ -177,13 +186,15 @@ async function runBuild(config, options) {
 		...config.transform !== void 0 ? { transform: config.transform } : {},
 		...jsx !== void 0 ? { jsx } : {},
 		...config.format !== void 0 ? { format: config.format } : {},
+		...config.define !== void 0 ? { define: config.define } : {},
 		...overridePartitions.length > 0 ? { overrides: overridePartitions } : {},
-		...dualExports !== void 0 ? { dualExports } : {}
+		...dualExports !== void 0 ? { dualExports } : {},
+		...looseFiles !== void 0 ? { looseFiles } : {}
 	});
 	if (target === "prod" && resolution !== void 0) writeBinding(cwd, resolution);
-	if (target === "prod" && config.meta !== void 0) {
+	if (target === "prod" && config.meta !== false) {
 		const metaGroupId = (groups.find((g) => g.name === packageName) ?? groups[0])?.id ?? "npm";
-		const norm = normalizeMetaOptions(config.meta);
+		const norm = normalizeMetaOptions(config.meta ?? {});
 		const dtsBasenames = {};
 		for (const name of Object.keys(entries)) dtsBasenames[name] = name;
 		await runGenerateMeta({