@savvy-web/bundler 0.12.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Savvy Web Strategy, LLC
+
+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

@@ -15,22 +15,16 @@ 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:
+Add a `savvy.build.ts` to the package root:
 
 ```ts
 // savvy.build.ts
-import { defineBuild, runBuild } from "@savvy-web/bundler";
+import { build } from "@savvy-web/bundler";
 
-const config = defineBuild({
+await build({
   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+):
@@ -60,7 +54,7 @@ The bundler ships its shared TypeScript base as a subpath export. Extend it from
 ```json
 {
  "$schema": "https://json.schemastore.org/tsconfig",
- "extends": ["@savvy-web/bundler/tsconfig/ecma.json"]
+ "extends": "@savvy-web/bundler/tsconfig/ecma.json"
 }
 ```
 
@@ -168,6 +162,25 @@ const config = defineBuild({
 
 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.
 
+## Ambient type exports
+
+Most declarations are generated from your source. For a types-only export backed by a hand-authored declaration file — global augmentations, module shims, ambient `declare` blocks — point the `exports` entry straight at a `.d.ts`, either as a bare string or under a `types` key:
+
+```json
+{
+  "exports": {
+    "./globals": "./src/globals.d.ts",
+    "./env": { "types": "./src/env.d.ts" }
+  }
+}
+```
+
+The build copies each declaration file verbatim into every built target dir and rewrites its published manifest pointer to a key-derived `{ types: "./<name>.d.ts" }`, preserving the source's `.d.ts`/`.d.cts`/`.d.mts` extension. No `transform` and no post-build copy step are involved.
+
+Two constraints keep the copy sound. The declaration must be self-contained — a relative `import` or `export` inside it fails the build, since nothing pulls the referenced file into the output. And an export that pairs a hand-authored `types` with a runtime source (`import`/`require`/`default`) fails too: the bundler generates types from a runtime source, so the two cannot be mixed on one entry.
+
+One further limit on scope: ambient declarations are supported only as named subpath exports (such as `"./globals"` or `"./env"`); a package must ship at least one JS or exe entry alongside its ambient declarations (a purely types-only package with no JS entries is not supported).
+
 ## 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:
@@ -297,9 +310,10 @@ const config = defineBuild({
 
 ## 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.
+- **One self-executing config** — `savvy.build.ts` is a top-level `await build({...})` call that derives `cwd` and `argv` from process globals. No main guard, no `export default`, no factory-notation config file.
 - **Build targets** — `dev` for local linking, `prod` for a resolved publishable manifest (which also emits 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.
+- **Ambient type exports** — a types-only `exports` entry backed by a hand-authored `.d.ts` (a bare string or `{ types }`) is copied verbatim into every target dir with its manifest pointer rewritten to a key-derived path, no custom `transform` or post-build copy needed; the declaration must be self-contained and may not be mixed with a runtime source.
 - **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.
@@ -320,6 +334,7 @@ const config = defineBuild({
 
 ## API
 
+- `build(input?, overrides?)` — the front door: calls `defineBuild(input)` then `runBuild`, deriving `cwd` from the entry script's directory (`process.argv[1]`) and `argv` from `process.argv.slice(2)`. Pass `overrides` (any `RunOptions` key) as the test IO seam.
 - `defineBuild(input)` — normalizes a build config (`externals`, `bundle`, `bundleNodeModules`, `bundledPackages`, `dtsExternals`, `minify`, `devManifest`, `transform`, `output`, `meta`, `jsx`, `exe`, `format`, `overrides`, `looseFiles`, `define`, `plugins`), 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`/`--verbose` from `options.argv`, reads `package.json` at `options.cwd`, derives entries, drives the build for the selected target and renders a report. `--verbose` expands the report to a per-file table; the report is quiet by default. Every IO dependency on `options` is injectable for tests.
 - `parseArgs(argv)` — the argument parser behind `runBuild`, exported for embedding.

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BuildFormat, BuildPlatform, BuildReport, BuildTargetGroupsOptions, CssOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, LooseFiles, MetaOptions, MetaResult, NextVersions, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+import { AmbientDtsEntry, BuildFormat, BuildPlatform, BuildReport, BuildTargetGroupsOptions, CopyAmbientDtsOptions, CssOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, LooseFiles, MetaOptions, MetaResult, NextVersions, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform, extractAmbientDts } from "@savvy-web/tsdown-plugins";
 import { Plugin, Plugin as Plugin$1 } from "rolldown";
 
 //#region src/config.d.ts
@@ -242,9 +242,23 @@ interface RunOptions {
     reports: ReadonlyArray<BuildReport>;
     now?: () => Date;
   }) => string | undefined;
+  /** Injectable ambient-.d.ts copier (defaults to copyAmbientDts). */
+  readonly copyAmbientDts?: ((o: CopyAmbientDtsOptions) => void) | undefined;
 }
 /** Run a build from a normalized config. Pure orchestration; all IO injectable. @public */
 declare function runBuild(config: BuildConfig, options: RunOptions): Promise<void>;
+/**
+ * Sugar front door: define + run in one call, deriving `cwd`/`argv` from process globals.
+ *
+ * `cwd` is the directory of the entry script (`process.argv[1]`) — the faithful equivalent of the
+ * old `import.meta.dirname`, correct even when invoked by an explicit path from another directory.
+ * `argv` is `process.argv.slice(2)`, so `--target` and friends are read internally; the package.json
+ * build scripts stay `node savvy.build.ts --target <t>`. `overrides` merges last as the test/advanced
+ * IO seam (the same injectables as {@link RunOptions}).
+ *
+ * @public
+ */
+declare function build(input?: BuildConfigInput, overrides?: Partial<RunOptions>): Promise<void>;
 //#endregion
-export { type BuildConfig, type BuildConfigInput, type BuildEntryOverride, type OutputConfig, type ParsedArgs, type Plugin, type RunOptions, defaultManifestTransform, defineBuild, parseArgs, runBuild };
+export { type AmbientDtsEntry, type BuildConfig, type BuildConfigInput, type BuildEntryOverride, type OutputConfig, type ParsedArgs, type Plugin, type RunOptions, build, defaultManifestTransform, defineBuild, extractAmbientDts, parseArgs, runBuild };
 //# sourceMappingURL=index.d.ts.map

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/bundler",
-	"version": "0.12.0",
+	"version": "1.0.1",
 	"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,13 +24,12 @@
 			"types": "./index.d.ts",
 			"import": "./index.js"
 		},
-		"./ecma.json": "./public/ecma.json",
-		"./tsconfig/ecma.json": "./public/ecma.json",
+		"./tsconfig/ecma.json": "./tsconfig/ecma.json",
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@savvy-web/tsdown-plugins": "0.12.0",
-		"@tsdown/exe": "^0.22.1",
+		"@savvy-web/tsdown-plugins": "1.0.1",
+		"@tsdown/exe": "^0.22.3",
 		"effect": "^3.21.4",
 		"rolldown": "^1.1.3",
 		"tsdown": "^0.22.3"

package/run.js

@@ -1,7 +1,7 @@
-import { parseArgs } from "./config.js";
-import { BuildCollector, ConfigValidator, ConfigValidatorLive, ReportPipelineLive, buildEmittedManifest, buildTargetGroups, computeExeFileName, createEntryName, deriveExportPaths, normalizeExeOptions, normalizeLooseFiles, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveTargets, runExeBuild, runMetaPass, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding } from "@savvy-web/tsdown-plugins";
+import { defineBuild, parseArgs } from "./config.js";
+import { BuildCollector, ConfigValidationError, ConfigValidator, ConfigValidatorLive, ReportPipelineLive, assertNoEntryCollisions, buildEmittedManifest, buildTargetGroups, computeExeFileName, copyAmbientDts, createEntryName, deriveExportPaths, extractAmbientDts, normalizeExeOptions, normalizeLooseFiles, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveTargets, runExeBuild, runMetaPass, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding } from "@savvy-web/tsdown-plugins";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { Effect } from "effect";
 
 //#region src/run.ts
@@ -96,12 +96,23 @@ async function runBuild(config, options) {
 		dir: "bin"
 	} : void 0;
 	const entries = packageJsonEntries({
-		pkg,
-		cwd,
+		pkg: {
+			exports: exportsMap ?? pkg.exports,
+			bin: pkg.bin
+		},
 		...config.exe !== void 0 ? { excludeSources: [exeEntrySource] } : {}
 	});
 	const hasJsEntries = Object.keys(entries).length > 0;
 	validateSubdirOverrides(config.overrides, entries, packageName);
+	const ambient = extractAmbientDts({
+		exports: exportsMap ?? pkg.exports,
+		bin: pkg.bin
+	}, {});
+	assertNoEntryCollisions(Object.keys(entries), ambient);
+	if (ambient.length > 0 && !hasJsEntries && config.exe === void 0) throw new ConfigValidationError({
+		path: "exports",
+		reason: "a types-only package with only ambient .d.ts exports is not supported — add at least one JS entry (or an exe) alongside the ambient declarations"
+	});
 	if (target === "meta") {
 		(options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`)))({
 			target: "stdout",
@@ -248,6 +259,14 @@ async function runBuild(config, options) {
 			});
 		}
 		if (target === "prod") for (const g of groups) removeDeclarationMaps(join(cwd, "dist", "prod", g.id, "pkg"));
+		if (ambient.length > 0 && (target === "dev" || target === "prod")) {
+			const copyAmbient = options.copyAmbientDts ?? copyAmbientDts;
+			for (const g of groups) copyAmbient({
+				ambient,
+				srcCwd: cwd,
+				outDir: target === "dev" ? join(cwd, "dist", "dev", "pkg") : join(cwd, "dist", "prod", g.id, "pkg")
+			});
+		}
 		if (config.exe !== void 0 && exeSpec !== void 0 && exeRewrite !== void 0 && exeFileName !== void 0) {
 			const runExe = options.runExeBuild ?? runExeBuild;
 			const groupOutDir = (g) => target === "dev" ? join(cwd, "dist", "dev", "pkg") : join(cwd, "dist", "prod", g.id, "pkg");
@@ -293,6 +312,24 @@ async function runBuild(config, options) {
 	await renderAndWrite();
 	writeIssuesBestEffort();
 }
+/**
+* Sugar front door: define + run in one call, deriving `cwd`/`argv` from process globals.
+*
+* `cwd` is the directory of the entry script (`process.argv[1]`) — the faithful equivalent of the
+* old `import.meta.dirname`, correct even when invoked by an explicit path from another directory.
+* `argv` is `process.argv.slice(2)`, so `--target` and friends are read internally; the package.json
+* build scripts stay `node savvy.build.ts --target <t>`. `overrides` merges last as the test/advanced
+* IO seam (the same injectables as {@link RunOptions}).
+*
+* @public
+*/
+async function build(input = {}, overrides = {}) {
+	return runBuild(defineBuild(input), {
+		cwd: process.argv[1] ? dirname(process.argv[1]) : process.cwd(),
+		argv: process.argv.slice(2),
+		...overrides
+	});
+}
 
 //#endregion
-export { runBuild };
+export { build, runBuild };

package/{public → tsconfig}/ecma.json

@@ -8,12 +8,12 @@
 		"declarationMap": false,
 		"emitDeclarationOnly": false,
 		"esModuleInterop": true,
+		"exactOptionalPropertyTypes": true,
 		"explainFiles": false,
 		"forceConsistentCasingInFileNames": true,
 		"incremental": true,
 		"isolatedDeclarations": false,
 		"isolatedModules": true,
-		"exactOptionalPropertyTypes": true,
 		"jsx": "preserve",
 		"lib": ["esnext"],
 		"module": "nodenext",
@@ -28,8 +28,8 @@
 		"target": "es2025",
 		"tsBuildInfoFile": "${configDir}/dist/.tsbuildinfo.lib",
 		"typeRoots": ["${configDir}/node_modules/@types", "${configDir}/types"],
-		"verbatimModuleSyntax": true,
-		"types": ["node"]
+		"types": ["node"],
+		"verbatimModuleSyntax": true
 	},
 	"exclude": ["${configDir}/node_modules", "${configDir}/dist/**/*"],
 	"include": [