@savvy-web/mcp 1.3.3 → 1.3.5

package/content/packages/tsdown-plugins/api.md

@@ -0,0 +1,183 @@
+---
+id: packages/tsdown-plugins/api
+title: "@savvy-web/tsdown-plugins — API reference"
+summary: "@savvy-web/tsdown-plugins API reference: 156 documented symbols."
+tier: packages
+source: generated
+tags: [tsdown-plugins, api]
+priority: 0.4
+related: []
+---
+
+# @savvy-web/tsdown-plugins — API reference
+
+## class
+
+- [`BuildCollector`](silk://packages/tsdown-plugins/api/class/buildcollector) — Stateful build-event accumulator. The write surface is synchronous so it can be called directly from tsdown's customLogger and API Extractor's messageCallback (both invoked synchronously). `snapshot` builds the immutable BuildReport the Effect render pipeline consumes.
+- [`BuildCollectorTag`](silk://packages/tsdown-plugins/api/class/buildcollectortag)
+- [`BuildReport`](silk://packages/tsdown-plugins/api/class/buildreport)
+- [`ConfigValidationError`](silk://packages/tsdown-plugins/api/class/configvalidationerror) — A savvy.build.ts or publishConfig.targets config is structurally invalid; raised before any build work.
+- [`ConfigValidator`](silk://packages/tsdown-plugins/api/class/configvalidator) — Fast-fail config validator; runs first in the bundler over the resolved config.
+- [`DiagnosticEntry`](silk://packages/tsdown-plugins/api/class/diagnosticentry) — A captured warning or error, from tsdown's logger, rolldown's onLog, or API Extractor.
+- [`EmittedFile`](silk://packages/tsdown-plugins/api/class/emittedfile) — One emitted output file with its in-memory byte size (gzip only when --verbose).
+- [`EnvironmentDetector`](silk://packages/tsdown-plugins/api/class/environmentdetector)
+- [`ExecutorResolver`](silk://packages/tsdown-plugins/api/class/executorresolver)
+- [`FormatSelector`](silk://packages/tsdown-plugins/api/class/formatselector)
+- [`MetaGenerationError`](silk://packages/tsdown-plugins/api/class/metagenerationerror) — API Extractor meta generation failed for an entry.
+- [`OutputRenderer`](silk://packages/tsdown-plugins/api/class/outputrenderer)
+- [`PassReport`](silk://packages/tsdown-plugins/api/class/passreport) — One build pass within a target group (js / dts / loose / exe / meta).
+- [`ReportTimings`](silk://packages/tsdown-plugins/api/class/reporttimings)
+- [`TargetGroupReport`](silk://packages/tsdown-plugins/api/class/targetgroupreport)
+- [`TsconfigResolver`](silk://packages/tsdown-plugins/api/class/tsconfigresolver) — Resolves a TypeScript `ParsedCommandLine` to a portable, JSON-serializable tsconfig (compilerOptions-only) for virtual TypeScript environments.
+
+## function
+
+- [`ambientOutName`](silk://packages/tsdown-plugins/api/function/ambientoutname) — Output basename (including the preserved declaration extension) for an ambient export, derived from the export KEY — consistent with how JS entries are named.
+- [`analyzeReexportBarrel`](silk://packages/tsdown-plugins/api/function/analyzereexportbarrel) — Analyze an entry source as a candidate pure re-export barrel: classify its re-exported names into value vs type-only and report whether it is expressible as a thin stub. Pure parsing — no I/O.
+- [`applySubdirMetaEntries`](silk://packages/tsdown-plugins/api/function/applysubdirmetaentries) — For each `outSubdir` override, point its meta entry at the isolated sub-package barrel.
+- [`assertNoEntryCollisions`](silk://packages/tsdown-plugins/api/function/assertnoentrycollisions) — Throw ConfigValidationError if any ambient output name collides with a JS build-entry name. The JS entry names carry no extension, so each ambient `outName` is compared with its declaration extension stripped.
+- [`buildEmittedManifest`](silk://packages/tsdown-plugins/api/function/buildemittedmanifest) — Compute the final manifest bytes for a TargetGroup (catalog resolution + standard transforms).
+- [`buildMetricsPlugin`](silk://packages/tsdown-plugins/api/function/buildmetricsplugin) — Rolldown plugin that records emitted-file metrics into the BuildCollector via writeBundle (which fires for the JS pass AND the emitDtsOnly dts pass — verified against tsdown 0.22.3), plus a defensive onLog for rolldown-level diagnostics that bypass tsdown's logger. Append it to each build pass's `plugins` array. `bytes` is taken from the in-memory chunk/asset content (no fs); `gzip` is computed only when `verbose`.
+- [`buildResolvedTsconfig`](silk://packages/tsdown-plugins/api/function/buildresolvedtsconfig) — Build the portable absolute-path tsconfig object (ported from rslib writeBundleTempConfig).
+- [`buildTargetGroups`](silk://packages/tsdown-plugins/api/function/buildtargetgroups) — 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.
+- [`cjsDefaultInterop`](silk://packages/tsdown-plugins/api/function/cjsdefaultinterop) — 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.
+- [`classifyDtsExport`](silk://packages/tsdown-plugins/api/function/classifydtsexport) — Classify an export value: - `ambient` — a types-only declaration source (bare `.d.ts` string, or `{ types: "*.d.ts" }` with no runtime source). - `mixed` — a declaration `types` AND a compilable runtime source (`import`/`require`/`default` → `.ts`/`.tsx`). - `none` — anything else (normal runtime export, json, etc.).
+- [`collectExportNames`](silk://packages/tsdown-plugins/api/function/collectexportnames) — Collect every name a module exports (named re-exports, namespace re-exports, and local `export` declarations). Used to test whether a barrel's re-exports are a strict subset of a base entry, so a stub re-exporting from that base resolves every symbol. Pure parsing — no I/O.
+- [`computeExeFileName`](silk://packages/tsdown-plugins/api/function/computeexefilename) — The exact filename `@tsdown/exe` emits for a SEA target, mirroring tsdown's `resolveOutputFileName`: base fileName + `-<platform>-<arch>` + `.exe` on win. Single source of truth so the manifest value never drifts from the on-disk file.
+- [`copyAmbientDts`](silk://packages/tsdown-plugins/api/function/copyambientdts) — Copy each ambient `.d.ts` export's source verbatim into `outDir/<outName>`, byte-stable (an unchanged file keeps its timestamp). The copy is NOT compiled or bundled, so the build owns two fast-fail checks: the source must exist, and it must be self-contained — a relative import/export/reference would not resolve once the file is flattened to the package root. Throws ConfigValidationError on a missing source or any relative specifier.
+- [`copyPublicDir`](silk://packages/tsdown-plugins/api/function/copypublicdir) — Copy the CONTENTS of `sourceDir` into `outDir`, additively. Each `sourceDir/<rel>` copies to `outDir/<rel>` — only the `public/` directory itself is dropped; the substructure under it is preserved (`public/tsconfig/ecma.json` becomes `<pkg>/tsconfig/ecma.json`, NOT `<pkg>/ecma.json`). The published manifest mirrors this drop via `transformExports`, which strips a leading `public/` from export values. This function NEVER deletes: `outDir` is the shared package root that the JS/dts passes own, so deleting "files not in source" would wipe the build product. Stale-asset pruning on a non-clean rebuild is therefore out of scope (a full build's `clean: true` handles it). Collision guard: when a destination already exists, identical bytes mean a prior copy of the same asset (skipped); anything else — differing bytes, a directory where a file is needed, or a file where a parent directory is needed — means a built output occupies that path, so it throws ConfigValidationError rather than clobbering it or surfacing a raw fs error.
+- [`createTimer`](silk://packages/tsdown-plugins/api/function/createtimer) — Create a wall-clock timer. (Date.now is fine in runtime build code.)
+- [`createTsdownLogger`](silk://packages/tsdown-plugins/api/function/createtsdownlogger) — A tsdown `customLogger` that routes warnings/errors into the BuildCollector instead of the console. Paired with `logLevel: "silent"` in the same build config: silent suppresses tsdown's own console output while this logger still receives every message (verified against tsdown 0.22.3). info/success are dropped — file metrics come from the writeBundle plugin and timing from our timer.
+- [`declarationExt`](silk://packages/tsdown-plugins/api/function/declarationext) — The declaration-file extension of a path, or undefined when it is not a declaration file.
+- [`defaultManifestTransform`](silk://packages/tsdown-plugins/api/function/defaultmanifesttransform) — The default `transform` applied to every package's manifest when its `savvy.build.ts` does not provide one of its own. Strips the build/dev-only fields in `NON_PUBLISHED_FIELDS` from the emitted package.json. This is the pattern nearly every package repeated by hand (inherited from rslib-builder); `defineBuild` now applies it automatically so a package needs a `transform` only when it has genuinely custom manifest work to do (e.g. silk promoting workspace deps to peerDependencies). A custom transform REPLACES this default — re-export it and call it from a custom transform to keep the stripping. `targetGroup` is accepted (so this is assignable wherever the full transform signature is expected) but unused; the strip is identical for every group. Pure: the supplied `pkg` is NOT mutated — a shallow copy with the fields removed is returned, so external callers invoking this from a custom transform keep their input intact.
+- [`deriveExportPaths`](silk://packages/tsdown-plugins/api/function/deriveexportpaths) — Map entry names to export paths using the package exports map. index maps to ".".
+- [`deriveTargetGroupOptions`](silk://packages/tsdown-plugins/api/function/derivetargetgroupoptions) — Derive the JS-pass tsdown options for one TargetGroup (per-module JS, no dts).
+- [`emitManifest`](silk://packages/tsdown-plugins/api/function/emitmanifest) — Rolldown plugin: emit the transformed package.json + LICENSE/README into the output pkg/ root.
+- [`extractAmbientDts`](silk://packages/tsdown-plugins/api/function/extractambientdts) — Extract the types-only `.d.ts` exports from a package's `exports` map. Pure. Throws ConfigValidationError on a mixed export (Decision 2) or an ambient-vs-ambient output-name collision.
+- [`extractEntries`](silk://packages/tsdown-plugins/api/function/extractentries)
+- [`findRelativeSpecifiers`](silk://packages/tsdown-plugins/api/function/findrelativespecifiers)
+- [`flattenIssues`](silk://packages/tsdown-plugins/api/function/flattenissues) — Flatten a build snapshot into the aggregated, de-duplicated issues artifact. Pure.
+- [`formatTime`](silk://packages/tsdown-plugins/api/function/formattime)
+- [`generateMeta`](silk://packages/tsdown-plugins/api/function/generatemeta) — Generate the api-model meta bundle from already-emitted .d.ts. Writes tsdoc.json (idempotent), runs the extractor per entry, merges if needed, and writes the "virtual TS env" trio to outMetaDir (`<unscoped>.api.json` + the final `package.json` + a portable `tsconfig.json`), copying that trio into each localPaths dir. The api-extractor `tsdoc-metadata.json` is a published-package artifact and is written into `dtsDir` (the built pkg/), not the meta bundle.
+- [`isTargetObject`](silk://packages/tsdown-plugins/api/function/istargetobject) — True when a target value is the object form (carries registry/name/from).
+- [`mixedDtsExportError`](silk://packages/tsdown-plugins/api/function/mixeddtsexporterror) — The shared mixed-export error (Decision 2), used by both the extractor and the manifest transform.
+- [`nodeBuiltinDefaultInterop`](silk://packages/tsdown-plugins/api/function/nodebuiltindefaultinterop) — 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): 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): 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.
+- [`normalizeBinPaths`](silk://packages/tsdown-plugins/api/function/normalizebinpaths) — FINAL guard: strip leading ./ from bin paths (npm 11.x drops ./-prefixed bins).
+- [`normalizeExeOptions`](silk://packages/tsdown-plugins/api/function/normalizeexeoptions) — Normalize `exe` (object or array) into one fully-resolved spec per binary. Pure function; structural validation (missing fileName, empty targets) lives in the config-validation layer.
+- [`normalizeLooseFiles`](silk://packages/tsdown-plugins/api/function/normalizeloosefiles) — Resolve a `looseFiles` map into normalized build descriptors. Pure (no filesystem): a missing `source` is surfaced later by tsdown's entry resolution. Throws ConfigValidationError on any structural problem so the bundler's ConfigValidator surfaces it as a typed, fast-fail config error.
+- [`normalizeMetaOptions`](silk://packages/tsdown-plugins/api/function/normalizemetaoptions) — Fill defaults so downstream code never branches on undefined.
+- [`packageJsonEntries`](silk://packages/tsdown-plugins/api/function/packagejsonentries) — Derive a tsdown `entry` record (name to source path) from a package.json.
+- [`readTsconfigJsx`](silk://packages/tsdown-plugins/api/function/readtsconfigjsx) — Read the jsx-relevant compilerOptions from a package's own tsconfig.json (best-effort; returns empty on absence or parse error).
+- [`removeDeclarationMaps`](silk://packages/tsdown-plugins/api/function/removedeclarationmaps) — 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.
+- [`renderReexportStub`](silk://packages/tsdown-plugins/api/function/renderreexportstub) — Render a thin re-export-stub `.d.ts`/`.d.cts` body: named re-exports of `valueNames` and `typeNames` from `baseSpecifier` (the published file of the base entry, e.g. `./index.js` for the ESM `.d.ts` or `./index.cjs` for the CJS `.d.cts`). Names are sorted so the output is deterministic. Returns the empty string when there is nothing to re-export.
+- [`renderReport`](silk://packages/tsdown-plugins/api/function/renderreport)
+- [`resolveJsxConfig`](silk://packages/tsdown-plugins/api/function/resolvejsxconfig) — Resolve the effective JSX config: an explicit override wins; otherwise infer from the tsconfig values. Returns undefined when no JSX transform is needed (preserve/none).
+- [`resolveManifest`](silk://packages/tsdown-plugins/api/function/resolvemanifest) — 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.
+- [`resolveNextVersions`](silk://packages/tsdown-plugins/api/function/resolvenextversions) — Resolve the next release version of every workspace package from pending changesets. Walks up from `cwd` to the monorepo root via `@manypkg/get-packages`, seeds the map with each package's CURRENT version, then overlays `newVersion` for changeset-affected packages via `@changesets/get-release-plan`. Never rejects: any failure (not a workspace, missing `.changeset/config.json`, parse error) degrades to current versions (or an empty map).
+- [`resolvePortableTsconfig`](silk://packages/tsdown-plugins/api/function/resolveportabletsconfig) — Resolves the package's effective compiler options (following `extends`) into a portable, JSON-serializable tsconfig for the meta release bundle.
+- [`resolveTargets`](silk://packages/tsdown-plugins/api/function/resolvetargets) — Resolve a `publishConfig.targets` map into the distinct groups to build and every target bound to one. Pure; throws ConfigValidationError on structurally-invalid config.
+- [`rewriteMetaVersions`](silk://packages/tsdown-plugins/api/function/rewritemetaversions) — Rewrite a meta `package.json` so the package's own `version` and any workspace-sibling dependency version reflect their NEXT release version from `versions`. Pure: returns a new object, never mutates the input. External/catalog-resolved deps (names absent from `versions`) are left as-is.
+- [`runExeBuild`](silk://packages/tsdown-plugins/api/function/runexebuild) — Compile each SEA binary via tsdown's exe mode. One tsdown build per spec.
+- [`runMetaPass`](silk://packages/tsdown-plugins/api/function/runmetapass) — Meta-pass orchestrator: derives export paths, filters bin/ entries, resolves optimistic next-versions, and calls generateMeta once per publish group.
+- [`serializeIssues`](silk://packages/tsdown-plugins/api/function/serializeissues) — Serialize the issues artifact to pretty JSON with a trailing newline.
+- [`transformBin`](silk://packages/tsdown-plugins/api/function/transformbin) — Rewrite bin: TS targets to bin/[command].js (string to bin/cli.js); strip leading ./ otherwise.
+- [`transformExports`](silk://packages/tsdown-plugins/api/function/transformexports) — Rewrite an exports map: TS string targets become a types/import conditions object. Each TS condition also gets a `require` entry when `dual` is `true` (uniform) or when the export key is in the `dual` Set (per-entry). The output path is derived from the export KEY via the shared entry-name function, never from the source path, so the manifest target always matches the emitted file. Export keys in `subdirExports` are built into an isolated `<key>/index.*` subdir (e.g. an RSPress `./runtime`), so their conditions gain an `/index` segment.
+- [`transformManifest`](silk://packages/tsdown-plugins/api/function/transformmanifest) — Apply the full standard manifest transform (excluding catalog resolution, done upstream).
+- [`writeDtsEmitTsconfig`](silk://packages/tsdown-plugins/api/function/writedtsemittsconfig) — Derive a dts-EMIT variant of an already-written resolved tsconfig that adds `stableTypeOrdering: true`, and return its path. This makes the TypeScript declaration emitter (rolldown-plugin-dts on `typescript@6`) order union/type members deterministically, so a multi-union `.d.ts` (e.g. an Effect `Layer.Layer<…>` requirement channel) does not flip member order across otherwise-identical builds (#156). It is kept in a SEPARATE file from the api-extractor tsconfig on purpose: `@microsoft/api-extractor` pins `typescript ~5.9`, which predates the flag and hard-errors on the unknown compiler option — so only the emit passes (which run on TS6) ever see it, while the api-extractor compile reads the original clean config. Best-effort: if the base tsconfig cannot be read or parsed (e.g. a synthetic test path that was never written), the original path is returned unchanged — the emit then simply keeps TS's default ordering rather than aborting the build at this layer.
+- [`writeIssuesArtifact`](silk://packages/tsdown-plugins/api/function/writeissuesartifact) — Write the aggregated issues artifact to `<cwd>/dist/<target>/issues.json`. Returns the path written.
+- [`writeResolvedTsconfig`](silk://packages/tsdown-plugins/api/function/writeresolvedtsconfig) — Write the resolved tsconfig to a temp file and return its absolute path.
+- [`writeTargetsBinding`](silk://packages/tsdown-plugins/api/function/writetargetsbinding) — Write the target-to-group binding to dist/prod/targets.json for the release action to consume. Returns the path.
+
+## interface
+
+- [`AmbientDtsEntry`](silk://packages/tsdown-plugins/api/interface/ambientdtsentry) — One ambient `.d.ts` export resolved for copy + manifest.
+- [`BuildEmittedManifestOptions`](silk://packages/tsdown-plugins/api/interface/buildemittedmanifestoptions)
+- [`BuildGroupSpec`](silk://packages/tsdown-plugins/api/interface/buildgroupspec) — A prod/dev group to build: its folder id and the resolved package name its manifest carries.
+- [`BuildIssues`](silk://packages/tsdown-plugins/api/interface/buildissues) — The aggregated build-issues artifact written to `dist/<target>/issues.json`.
+- [`BuildTargetGroupsOptions`](silk://packages/tsdown-plugins/api/interface/buildtargetgroupsoptions)
+- [`CopyAmbientDtsOptions`](silk://packages/tsdown-plugins/api/interface/copyambientdtsoptions)
+- [`CssOptions`](silk://packages/tsdown-plugins/api/interface/cssoptions) — CSS handling for a partition's JS pass, forwarded VERBATIM to tsdown's `css` option (consumed by `@tsdown/css`). Structurally typed so tsdown-plugins takes no dependency on `@tsdown/css`. The package whose runtime is built must install `@tsdown/css`; tsdown loads it lazily.
+- [`DerivedTsdownOptions`](silk://packages/tsdown-plugins/api/interface/derivedtsdownoptions) — The JS pass: per-module JavaScript, no declarations. The build runs TWO tsdown passes per TargetGroup to the SAME outDir: - pass 1 (this) emits per-module JS (`unbundle: true`) with `dts: false` and the default `clean: true`, so it starts from a fresh outDir; - pass 2 (`DerivedDtsPassOptions`) emits ONLY bundled declarations (`unbundle: false`, `dts: { emitDtsOnly: true }`) with `clean: false`, so it must NOT wipe pass 1. We cannot do this in a single pass: tsdown's `unbundle` maps to rolldown `output.preserveModules` for the WHOLE build, and the dts plugin shares it — so one pass gives EITHER per-module JS + per-module dts OR bundled JS + bundled dts. Per-module dts breaks type portability (TS2883) when a package exports only its root entry, and bundling the JS re-bundles workspace consumers (e.g. silk re-bundling silk-effects crashes at runtime). The split keeps per-module JS (no re-bundle hazard) AND bundled, self-contained declarations (no TS2883).
+- [`DeriveOptions`](silk://packages/tsdown-plugins/api/interface/deriveoptions)
+- [`DiagnosticInput`](silk://packages/tsdown-plugins/api/interface/diagnosticinput)
+- [`EmitManifestOptions`](silk://packages/tsdown-plugins/api/interface/emitmanifestoptions)
+- [`EntryOverride`](silk://packages/tsdown-plugins/api/interface/entryoverride) — One entry partition built with its own format + bundling posture, layered into the SAME outDir as the base build (clean:false). Anything omitted falls back to the base build's value. `entry` is a subset of the package's entries (`entryName -> source path`).
+- [`ExeConfig`](silk://packages/tsdown-plugins/api/interface/execonfig) — One SEA binary to compile.
+- [`ExeRewrite`](silk://packages/tsdown-plugins/api/interface/exerewrite) — Describes a SEA binary the bundler compiled for this package. When present, transformManifest rewrites every `exports`/`bin` value equal to `source` to the emitted binary path and adds it to `files` so it ships in the tarball.
+- [`ExeSeaConfig`](silk://packages/tsdown-plugins/api/interface/exeseaconfig) — SEA seaConfig overrides (subset; the rest are defaulted).
+- [`ExeTarget`](silk://packages/tsdown-plugins/api/interface/exetarget) — A resolved per-platform SEA target. `platform` uses the tsdown/tsdown/exe token (win, not win32).
+- [`ExeTargetInput`](silk://packages/tsdown-plugins/api/interface/exetargetinput) — A target before nodeVersion defaulting (platform/arch only).
+- [`ExtractAmbientOptions`](silk://packages/tsdown-plugins/api/interface/extractambientoptions)
+- [`ExtractOptions`](silk://packages/tsdown-plugins/api/interface/extractoptions)
+- [`ExtractResult`](silk://packages/tsdown-plugins/api/interface/extractresult)
+- [`Formatter`](silk://packages/tsdown-plugins/api/interface/formatter)
+- [`FormatterContext`](silk://packages/tsdown-plugins/api/interface/formattercontext)
+- [`GenerateMetaOptions`](silk://packages/tsdown-plugins/api/interface/generatemetaoptions)
+- [`JsxConfig`](silk://packages/tsdown-plugins/api/interface/jsxconfig) — Resolved JSX transform settings. The shape mirrors the subset of rolldown's JsxOptions, but the bundler consumes it to populate the generated dts tsconfig's `jsx`/`jsxImportSource`, not by forwarding it into rolldown's input options.
+- [`LooseFileSpec`](silk://packages/tsdown-plugins/api/interface/loosefilespec) — One standalone bundled output file, declared by its literal output filename.
+- [`MetaOptions`](silk://packages/tsdown-plugins/api/interface/metaoptions) — The `meta` field on defineBuild. Absent means no api-model generation.
+- [`MetaResult`](silk://packages/tsdown-plugins/api/interface/metaresult)
+- [`ModuleExportNames`](silk://packages/tsdown-plugins/api/interface/moduleexportnames) — The set of names a module exports, plus whether that set is fully known.
+- [`NextVersions`](silk://packages/tsdown-plugins/api/interface/nextversions) — Result of resolving next release versions for a workspace.
+- [`NormalizedExe`](silk://packages/tsdown-plugins/api/interface/normalizedexe) — Fully-resolved SEA binary spec (no optionals).
+- [`NormalizedLooseFile`](silk://packages/tsdown-plugins/api/interface/normalizedloosefile) — A loose file resolved to a concrete build descriptor.
+- [`NormalizedMeta`](silk://packages/tsdown-plugins/api/interface/normalizedmeta) — Fully-resolved meta options (no optionals).
+- [`PackageJsonEntriesOptions`](silk://packages/tsdown-plugins/api/interface/packagejsonentriesoptions)
+- [`PackageJsonLike`](silk://packages/tsdown-plugins/api/interface/packagejsonlike)
+- [`PkgOsCpu`](silk://packages/tsdown-plugins/api/interface/pkgoscpu) — The package's own os/cpu fields, used to infer a single platform target.
+- [`PlainDiagnostic`](silk://packages/tsdown-plugins/api/interface/plaindiagnostic) — A diagnostic flattened to a plain JSON object (only defined fields are present).
+- [`PortableTsconfig`](silk://packages/tsdown-plugins/api/interface/portabletsconfig) — Portable, JSON-serializable tsconfig.json (compilerOptions-only).
+- [`PublishTargetObject`](silk://packages/tsdown-plugins/api/interface/publishtargetobject) — A single object-form publish target. Uses `from` XOR `name` (never both).
+- [`ReexportBarrelAnalysis`](silk://packages/tsdown-plugins/api/interface/reexportbarrelanalysis) — The analysis of an entry source treated as a candidate re-export barrel.
+- [`RenderedOutput`](silk://packages/tsdown-plugins/api/interface/renderedoutput)
+- [`RenderReportOptions`](silk://packages/tsdown-plugins/api/interface/renderreportoptions)
+- [`ResolvedCompilerOptions`](silk://packages/tsdown-plugins/api/interface/resolvedcompileroptions) — Compiler options with enum values converted to their string equivalents.
+- [`ResolvedGroup`](silk://packages/tsdown-plugins/api/interface/resolvedgroup) — A distinct byte-variant build group (one per distinct resolved name).
+- [`ResolvedTarget`](silk://packages/tsdown-plugins/api/interface/resolvedtarget) — A resolved registry target (one per `publishConfig.targets` key).
+- [`ResolvedTsconfig`](silk://packages/tsdown-plugins/api/interface/resolvedtsconfig)
+- [`ResolvedTsconfigOptions`](silk://packages/tsdown-plugins/api/interface/resolvedtsconfigoptions)
+- [`RunExeBuildOptions`](silk://packages/tsdown-plugins/api/interface/runexebuildoptions) — Options for compiling SEA binaries.
+- [`RunMetaPassOptions`](silk://packages/tsdown-plugins/api/interface/runmetapassoptions) — Options for the meta-pass orchestrator.
+- [`TargetGroupRef`](silk://packages/tsdown-plugins/api/interface/targetgroupref)
+- [`TargetResolution`](silk://packages/tsdown-plugins/api/interface/targetresolution) — The full resolution of `publishConfig.targets`: the distinct groups to build, and every target bound to one.
+- [`Timer`](silk://packages/tsdown-plugins/api/interface/timer)
+- [`TransformManifestOptions`](silk://packages/tsdown-plugins/api/interface/transformmanifestoptions)
+- [`TsconfigJsx`](silk://packages/tsdown-plugins/api/interface/tsconfigjsx) — The jsx-relevant slice of a tsconfig's compilerOptions.
+- [`TsdocOptions`](silk://packages/tsdown-plugins/api/interface/tsdocoptions) — TSDoc / doc-warning configuration. suppressWarnings is doc functionality, so it lives here.
+- [`TsdocTagDefinition`](silk://packages/tsdown-plugins/api/interface/tsdoctagdefinition) — A single TSDoc tag definition (parity with api-extractor's TSDoc config).
+- [`TsdownLogger`](silk://packages/tsdown-plugins/api/interface/tsdownlogger) — Structural match for tsdown's Logger interface (tsdown 0.22.x).
+- [`ValidationInput`](silk://packages/tsdown-plugins/api/interface/validationinput) — The normalized facts the validator checks, assembled by the bundler before any build work.
+- [`WarningSuppressionRule`](silk://packages/tsdown-plugins/api/interface/warningsuppressionrule) — An api-extractor message-suppression rule. messageId is exact-matched; pattern (regex or substring) is AND-matched against the text.
+
+## type
+
+- [`BuildFormat`](silk://packages/tsdown-plugins/api/type/buildformat) — An output module format the build can emit.
+- [`BuildPlatform`](silk://packages/tsdown-plugins/api/type/buildplatform) — Bundling platform for the JS pass. Defaults to "node". Use "browser" for web runtime partitions.
+- [`DtsExportClass`](silk://packages/tsdown-plugins/api/type/dtsexportclass) — Classification of a single export value for ambient-.d.ts handling.
+- [`DualExports`](silk://packages/tsdown-plugins/api/type/dualexports) — Which exports get a CJS `require` condition. `true`/`false` apply uniformly to every TS export; a Set marks ONLY the listed export keys (e.g. "./changesets/markdownlint") as dual — used by per-entry format overrides.
+- [`Environment`](silk://packages/tsdown-plugins/api/type/environment)
+- [`ExeBuild`](silk://packages/tsdown-plugins/api/type/exebuild) — A minimal structural type for tsdown's build, kept loose so this package keeps no tsdown runtime dep (interface-only).
+- [`Executor`](silk://packages/tsdown-plugins/api/type/executor)
+- [`Json`](silk://packages/tsdown-plugins/api/type/json)
+- [`LooseFiles`](silk://packages/tsdown-plugins/api/type/loosefiles) — Map of literal output filename to its source (bare string) or a `{ source, format }` spec.
+- [`OutputFormat`](silk://packages/tsdown-plugins/api/type/outputformat)
+- [`PassKind`](silk://packages/tsdown-plugins/api/type/passkind)
+- [`PublishTargets`](silk://packages/tsdown-plugins/api/type/publishtargets) — The `publishConfig.targets` map, keyed by target id (`npm`, `github`, or a custom key).
+- [`PublishTargetValue`](silk://packages/tsdown-plugins/api/type/publishtargetvalue) — A `publishConfig.targets` value: `true` (well-known registry, base name), a string (name override), or an object.
+- [`TargetGroupId`](silk://packages/tsdown-plugins/api/type/targetgroupid) — A build group id: "dev" or any prod byte-variant id (e.g. "npm", "github", a custom key).
+- [`TsdownBuild`](silk://packages/tsdown-plugins/api/type/tsdownbuild) — Signature compatible with tsdown's `build(inlineConfig)`.
+
+## variable
+
+- [`CiAnnotationsFormatter`](silk://packages/tsdown-plugins/api/variable/ciannotationsformatter)
+- [`ConfigValidatorLive`](silk://packages/tsdown-plugins/api/variable/configvalidatorlive) — Live ConfigValidator: wraps the synchronous rule set, surfacing ConfigValidationError as a typed Effect failure.
+- [`DEFAULT_EXE_NODE_VERSION`](silk://packages/tsdown-plugins/api/variable/default_exe_node_version) — Default Node runtime embedded in the SEA (parity with the vitest-agent reference).
+- [`EnvironmentDetectorLive`](silk://packages/tsdown-plugins/api/variable/environmentdetectorlive)
+- [`ExecutorResolverLive`](silk://packages/tsdown-plugins/api/variable/executorresolverlive)
+- [`FormatSelectorLive`](silk://packages/tsdown-plugins/api/variable/formatselectorlive)
+- [`JsonFormatter`](silk://packages/tsdown-plugins/api/variable/jsonformatter)
+- [`MarkdownFormatter`](silk://packages/tsdown-plugins/api/variable/markdownformatter)
+- [`OutputRendererLive`](silk://packages/tsdown-plugins/api/variable/outputrendererlive)
+- [`ReportPipelineLive`](silk://packages/tsdown-plugins/api/variable/reportpipelinelive)
+- [`SilentFormatter`](silk://packages/tsdown-plugins/api/variable/silentformatter)
+- [`TerminalFormatter`](silk://packages/tsdown-plugins/api/variable/terminalformatter)

package/{public/content → content}/standards/api-model-pipeline.md

@@ -17,7 +17,8 @@ the next build.
 
 ### Pipeline
 
-1. A library package sets `apiModel` in its rslib config.
+1. A library package built by `@savvy-web/bundler` emits a model by default; the
+   `meta` option in its `savvy.build.ts` controls it (`false` opts out).
 2. `build:prod` emits `<unscoped>.api.json` (a Microsoft API Extractor model file).
 3. The `api-extractor-llms` library renders that model into LLM-lean
    markdown.
@@ -43,8 +44,8 @@ management, making the pipeline compatible with upstream tooling.
 
 ## Examples
 
-A package `@savvy-web/silk-effects` with `apiModel` in its rslib config builds
-`silk-effects.api.json`. The renderer produces entries such as:
+A package `@savvy-web/silk-effects` built by `@savvy-web/bundler` emits
+`silk-effects.api.json` on its prod build. The renderer produces entries such as:
 
 ```text
 silk://packages/silk-effects/api/class/SilkPublishability
@@ -59,5 +60,5 @@ docs.
 
 The resource taxonomy that governs where generated and hand-authored docs live is at
 `silk://packages/mcp/resource-taxonomy`. The `api-extractor-llms` library
-is the renderer; the `@savvy-web/rslib-builder` build tool exposes the `apiModel`
-config option.
+is the renderer; the `@savvy-web/bundler` build tool emits the model via its
+`meta` option.

package/index.d.ts

@@ -4,8 +4,6 @@ import { WorkspaceDiscoveryError, WorkspaceRoot } from "workspaces-effect";
 //#region src/resources/schema.d.ts
 /** A manifest entry = decoded front-matter + the derived uri + lastModified. */
 declare const ManifestEntry: Schema.Struct<{
-  uri: typeof Schema.String;
-  lastModified: Schema.optional<typeof Schema.String>;
   id: Schema.filter<typeof Schema.String>;
   title: typeof Schema.NonEmptyString;
   summary: typeof Schema.NonEmptyString;
@@ -25,12 +23,12 @@ declare const ManifestEntry: Schema.Struct<{
   related: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
     default: () => ReadonlyArray<string>;
   }>;
+  uri: typeof Schema.String;
+  lastModified: Schema.optional<typeof Schema.String>;
 }>;
 type ManifestEntry = Schema.Schema.Type<typeof ManifestEntry>;
 declare const Manifest: Schema.Struct<{
   entries: Schema.Array$<Schema.Struct<{
-    uri: typeof Schema.String;
-    lastModified: Schema.optional<typeof Schema.String>;
     id: Schema.filter<typeof Schema.String>;
     title: typeof Schema.NonEmptyString;
     summary: typeof Schema.NonEmptyString;
@@ -50,6 +48,8 @@ declare const Manifest: Schema.Struct<{
     related: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
       default: () => ReadonlyArray<string>;
     }>;
+    uri: typeof Schema.String;
+    lastModified: Schema.optional<typeof Schema.String>;
   }>>;
 }>;
 type Manifest = Schema.Schema.Type<typeof Manifest>;
@@ -77,7 +77,7 @@ declare class DocIndex {
   private constructor();
   static fromManifest(manifest: Manifest, bodies: Readonly<Record<string, string>>): DocIndex;
   search(query: string, opts?: SearchOptions): SearchResult[];
-  /** Never return empty: surface the top entries (by priority) as low-confidence. */
+  /** Browse fallback: surface the top entries (by priority) as low-confidence. */
   private fallback;
 }
 //#endregion
@@ -104,7 +104,7 @@ interface McpContext {
  * {@link DepsLive}; the leftover `CommandExecutor` + `FileSystem` flow up to the
  * host platform layer.
  */
-declare const SilkRuntimeLive: Layer.Layer<import("@savvy-web/silk-effects").SilkWorkspaceAnalyzer | import("workspaces-effect").WorkspaceRoot | Turbo.TurboInspector | Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.ReleasePlanner, import("workspaces-effect").WorkspaceDiscoveryError, import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path | import("@effect/platform/CommandExecutor").CommandExecutor>;
+declare const SilkRuntimeLive: Layer.Layer<Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.ReleasePlanner | import("@savvy-web/silk-effects").SilkWorkspaceAnalyzer | Turbo.TurboInspector | import("workspaces-effect").WorkspaceRoot, import("workspaces-effect").WorkspaceDiscoveryError, import("@effect/platform/CommandExecutor").CommandExecutor | import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path>;
 //#endregion
 //#region src/server.d.ts
 /** Build the server and connect it over stdio. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "1.3.3",
+	"version": "1.3.5",
 	"private": false,
 	"description": "The savvy MCP server — Silk Suite tooling and library knowledge for coding agents",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/mcp",
@@ -36,7 +36,7 @@
 		"@effect/rpc": "^0.75.1",
 		"@effect/sql": "^0.51.1",
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@savvy-web/silk-effects": "1.5.0",
+		"@savvy-web/silk-effects": "1.5.2",
 		"effect": "^3.21.4",
 		"fuse.js": "^7.4.0",
 		"workspaces-effect": "^1.2.0",

package/resources/doc-index.js

@@ -70,7 +70,7 @@ var DocIndex = class DocIndex {
 		const tokens = query.toLowerCase().split(/\s+/).filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
 		const raw = tokens.length > 0 ? this.fuse.search(tokens.map((t) => `'${t}`).join(" | ")) : [];
 		const filteredByTier = opts.tier ? raw.filter((r) => r.item.tier === opts.tier) : raw;
-		const ranked = filteredByTier.length > 0 ? filteredByTier.map((r) => toRanked(r.item, r.score, r.matches ?? [])) : this.fallback(opts.tier);
+		const ranked = filteredByTier.length > 0 ? filteredByTier.map((r) => toRanked(r.item, r.score, r.matches ?? [])) : tokens.length === 0 ? this.fallback(opts.tier) : [];
 		ranked.sort((a, b) => b.confidence - a.confidence || (b.item.priority ?? .5) - (a.item.priority ?? .5));
 		const present = new Set(ranked.map((r) => r.item.uri));
 		const seeAlso = [];
@@ -98,7 +98,7 @@ var DocIndex = class DocIndex {
 			related: item.related
 		}));
 	}
-	/** Never return empty: surface the top entries (by priority) as low-confidence. */
+	/** Browse fallback: surface the top entries (by priority) as low-confidence. */
 	fallback(tier) {
 		return this.entries.filter((e) => tier ? e.tier === tier : true).slice().sort((a, b) => (b.priority ?? .5) - (a.priority ?? .5)).slice(0, 5).map((item) => ({
 			item,

package/resources/index.js

@@ -1,6 +1,7 @@
 import { renderCatalogMarkdown } from "./catalog.js";
 import { readDocBody } from "./load.js";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 
 //#region src/resources/index.ts
 const resourceName = (entry) => `silk_${entry.id.replace(/[^A-Za-z0-9]/g, "_")}`;
@@ -21,7 +22,15 @@ function registerAllResources(server, deps) {
 		text: renderCatalogMarkdown(manifest)
 	}] }));
 	const byUri = new Map(manifest.entries.map((e) => [e.uri, e]));
-	const readBody = (uri, relPath) => bodies ? bodies[uri] ?? "" : readDocBody(contentRoot, relPath);
+	const readBody = (uri, relPath) => {
+		if (bodies) return bodies[uri] ?? "";
+		try {
+			return readDocBody(contentRoot, relPath);
+		} catch (err) {
+			if (err?.code === "ENOENT") throw new McpError(ErrorCode.InvalidParams, `Resource not found: ${uri}`);
+			throw new McpError(ErrorCode.InternalError, `Failed to read resource: ${uri}`);
+		}
+	};
 	server.registerResource("silk_doc", new ResourceTemplate("silk://{+path}", { list: async () => ({ resources: manifest.entries.filter((e) => e.status !== "deprecated").map((e) => ({
 		name: resourceName(e),
 		uri: e.uri,

package/resources/load.js

@@ -14,16 +14,16 @@ import { fileURLToPath } from "node:url";
 */
 /**
 * Locate the directory holding `manifest.json` + the content markdown. The
-* built bundle copies `public/` next to the emitted chunk (`<pkg>/public/content`);
-* the source layout keeps it under the package root (`packages/mcp/public/content`).
+* built bundle flattens `public/` to the package root, so the content lands at
+* `<pkg>/content`; the source layout keeps it under `packages/mcp/public/content`.
 * Probe both and fail loudly if neither has a manifest, so a broken build surfaces a
 * clear path list instead of an opaque ENOENT later in {@link loadManifest}.
 */
 function resolveContentRoot() {
 	const here = dirname(fileURLToPath(import.meta.url));
-	const candidates = [join(here, "..", "public", "content"), join(here, "..", "..", "public", "content")];
+	const candidates = [join(here, "..", "content"), join(here, "..", "..", "public", "content")];
 	for (const candidate of candidates) if (existsSync(join(candidate, "manifest.json"))) return candidate;
-	throw new Error(`[savvy-mcp] cannot locate public/content with a manifest.json (tried: ${candidates.join(", ")})`);
+	throw new Error(`[savvy-mcp] cannot locate content with a manifest.json (tried: ${candidates.join(", ")})`);
 }
 function loadManifest(contentRoot) {
 	const raw = JSON.parse(readFileSync(join(contentRoot, "manifest.json"), "utf8"));

package/tools/docs-search.js

@@ -6,7 +6,7 @@ import { ParseResult, Schema } from "effect";
 * The `silk_docs_search` MCP tool: a read-only Fuse-backed search over the
 * resource corpus. Takes a plain keyword/phrase query (no operator DSL),
 * returns ranked results with normalized higher-is-better confidence, and
-* never returns empty.
+* returns an empty result set for a real query that matches nothing.
 *
 * @packageDocumentation
 */

package/public/content/guides/choosing-a-builder.md

@@ -1,140 +0,0 @@
----
-id: guides/choosing-a-builder
-title: Choosing a builder (rslib vs bun)
-summary: When to reach for @savvy-web/rslib-builder vs @savvy-web/bun-builder for a Silk package.
-tier: guides
-source: hand
-tags: [build]
-priority: 0.5
-related: [packages/rslib-builder/overview]
----
-
-## Overview
-
-The Silk Suite has two zero-config build tools for TypeScript libraries:
-
-| Package | Bundler core | Primary target |
-| --- | --- | --- |
-| `@savvy-web/rslib-builder` | rsbuild / rspack | Node.js (pnpm monorepos) |
-| `@savvy-web/bun-builder` | Bun.build() | Bun monorepos |
-
-Both tools auto-detect entry points from `package.json` `exports`, emit `dist/dev/`
-and `dist/npm/` build modes, generate rolled-up `.d.ts` declarations via API
-Extractor, resolve `catalog:` and `workspace:` protocol references for publishing,
-and transform the output `package.json` for publish readiness.
-
-## `@savvy-web/rslib-builder`
-
-The **ecosystem default** for packages inside the `savvy-web/systems` monorepo and
-any pnpm-managed Silk Suite package.
-
-### What it does
-
-- Zero-config builds via `NodeLibraryBuilder.create({})` in `rslib.config.ts`
-- Reads `exports` to discover entry points; builds `dist/dev/` and `dist/npm/`
-- Generates type declarations and emits a Microsoft API Extractor model
-  (`<unscoped>.api.json`) on the npm build
-- Transforms the output `package.json`: resolves `pnpm catalog:` references,
-  flips `private: true` to publish-ready based on `publishConfig.access`, rewrites
-  export paths from `.ts` to `.js`, adds type conditions
-- Supports dual-format ESM+CJS builds when needed (e.g. `@savvy-web/silk` for CJS
-  consumers)
-- Peer dependencies: `@rslib/core`, `@typescript/native-preview`
-
-### Configuration
-
-```typescript
-import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
-
-export default NodeLibraryBuilder.create({
-  externals: ["effect", "@effect/platform"],
-  apiModel: {
-    tsdoc: {
-      tagDefinitions: [{ tagName: "@since", syntaxKind: "block" }],
-    },
-  },
-});
-```
-
-Pass `apiModel: true` (or an options object) to enable API Extractor model
-emission. See `silk://packages/rslib-builder/overview` for full details.
-
-### When to use it
-
-- You are building a package inside `savvy-web/systems` (or a pnpm-based Silk repo)
-- You need dual-format ESM+CJS output
-- You want API Extractor model emission for MCP doc generation
-- The package uses `pnpm catalog:` or `workspace:` protocol in its dependencies
-
-## `@savvy-web/bun-builder`
-
-For **Bun-managed monorepos** where Bun.build() is the preferred bundler.
-
-### What it does
-
-- Zero-config builds via `BunLibraryBuilder.create({})` in `bun.config.ts`
-- Auto-detects entry points from `package.json` `exports`
-- Bundled or bundleless output (`bundle: false` preserves source structure)
-- Rolled-up `.d.ts` in bundled mode; raw `.d.ts` in bundleless mode
-- API Extractor model generation on npm builds (enabled by default)
-- TSDoc warnings reported with source locations; severity configurable per
-  environment (`"fail"` in CI, `"log"` locally)
-- Resolves Bun `catalog:` and `workspace:` protocol references for publishing
-- Peer dependencies: `@microsoft/api-extractor`, `@typescript/native-preview`,
-  `typescript`, `@types/bun`
-
-### Configuration
-
-```typescript
-import { BunLibraryBuilder } from "@savvy-web/bun-builder";
-
-export default BunLibraryBuilder.create({
-  bundle: true,       // default; set false for bundleless
-  apiModel: true,     // default; emits model on npm build
-});
-```
-
-Build via:
-
-```bash
-bun run bun.config.ts              # all modes
-bun run bun.config.ts --env-mode dev
-bun run bun.config.ts --env-mode npm
-```
-
-### When to use it
-
-- You are in a Bun-managed workspace (`bun.lock`, Bun catalog protocol)
-- You want sub-second build iteration times
-- You do not need rspack's CJS-to-ESM interop (which is important for certain
-  bundled GitHub Actions scenarios)
-
-## Decision guide
-
-```text
-Is this a package in savvy-web/systems (pnpm monorepo)?
-  Yes → rslib-builder
-
-Does the package need dual-format ESM+CJS output?
-  Yes → rslib-builder
-
-Is this a Bun-managed workspace?
-  Yes → bun-builder
-
-Are you building a GitHub Action (bundled Node.js 24 binary)?
-  Use @savvy-web/github-action-builder instead — see silk://guides/building-a-github-action
-```
-
-## Common pitfalls
-
-**rslib-builder:** Relative imports inside source must use `.js` extensions
-(ESM requirement). The build will report "cannot find module" on missing extensions.
-
-**bun-builder:** The Bun catalog protocol uses `workspaces.catalog` in the root
-`package.json`, distinct from pnpm's catalog. Do not mix the two in the same
-workspace.
-
-## See also
-
-- `silk://packages/rslib-builder/overview` — full rslib-builder reference
-- `silk://guides/building-a-github-action` — GitHub Actions use a separate builder