{"id":"@lssm-tech/tool.bun","slug":"tool.bun","name":"@lssm-tech/tool.bun","version":"5.0.6","path":"packages/tools/bun","manifestPath":"packages/tools/bun/package.json","manifestBlobSha":"e43ecd687249dc00db4bc334e9465d8c530bf404","layer":"tools","physicalArea":null,"primaryArea":"tooling-and-agent-delivery","classification":{"privateDeclared":null,"catalogFamily":"sharedLibs","catalogKind":"tool","catalogStatus":"active","adoptionMode":"operator-only","stability":"stable"},"description":"Shared Bun build presets and CLI for ContractSpec packages","descriptionOrigin":"package.json","catalog":{"family":"sharedLibs","kind":"tool","status":"active","adoptionMode":"operator-only","stability":"stable","platforms":["server"],"runtimes":["node"],"entrypoints":[".","./pack-staging","./pack-verification"],"documentation":[{"title":"Tool Bun documentation","url":"https://www.npmjs.com/package/%40lssm-tech%2Ftool.bun","kind":"readme"}],"examples":[],"replacements":[],"nonAdoptableRationale":"This tool is published for execution by operators, not as a reusable library dependency."},"canonicalImports":[],"scripts":{"publish:pkg":"bun publish --tolerate-republish --ignore-scripts --verbose","publish:pkg:canary":"bun publish:pkg --tag canary","test":"bun test","typecheck":"bun test test/types.test.ts"},"scriptStatus":"complete pinned manifest","dependencies":{"glob":"catalog:build","typescript":"catalog:"},"devDependencies":{},"peerDependencies":{},"optionalDependencies":{},"peerDependenciesMeta":{},"bundledDependencies":null,"dependencyStatus":"complete pinned manifest","exports":{".":{"types":"./index.d.ts","default":"./index.js"},"./pack-staging":{"types":"./pack-staging.d.ts","default":"./lib/pack-staging/index.mjs"},"./pack-verification":{"types":"./src/pack-verification/index.d.mts","default":"./src/pack-verification/index.mjs"}},"publishExports":null,"types":"./index.d.ts","files":["bin","lib","index.d.ts","index.js","pack-staging.d.ts","src/pack-verification","README.md","CHANGELOG.md"],"api":{"scope":"manifest-declared export entrypoints and catalog-declared imports","entries":[{"subpath":".","importPath":"@lssm-tech/tool.bun","target":{"types":"./index.d.ts","default":"./index.js"},"targets":[{"conditions":["types"],"target":"./index.d.ts","sourcePath":"packages/tools/bun/index.d.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/index.d.ts","sourceStatus":"verified source file"},{"conditions":["default"],"target":"./index.js","sourcePath":"packages/tools/bun/index.js","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/index.js","sourceStatus":"verified source file"}]},{"subpath":"./pack-staging","importPath":"@lssm-tech/tool.bun/pack-staging","target":{"types":"./pack-staging.d.ts","default":"./lib/pack-staging/index.mjs"},"targets":[{"conditions":["types"],"target":"./pack-staging.d.ts","sourcePath":"packages/tools/bun/pack-staging.d.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/pack-staging.d.ts","sourceStatus":"verified source file"},{"conditions":["default"],"target":"./lib/pack-staging/index.mjs","sourcePath":"packages/tools/bun/lib/pack-staging/index.mjs","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/lib/pack-staging/index.mjs","sourceStatus":"verified source file"}]},{"subpath":"./pack-verification","importPath":"@lssm-tech/tool.bun/pack-verification","target":{"types":"./src/pack-verification/index.d.mts","default":"./src/pack-verification/index.mjs"},"targets":[{"conditions":["types"],"target":"./src/pack-verification/index.d.mts","sourcePath":"packages/tools/bun/src/pack-verification/index.d.mts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/src/pack-verification/index.d.mts","sourceStatus":"verified source file"},{"conditions":["default"],"target":"./src/pack-verification/index.mjs","sourcePath":"packages/tools/bun/src/pack-verification/index.mjs","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/src/pack-verification/index.mjs","sourceStatus":"verified source file"}]}],"entryCount":3,"namedSymbolCoverage":"catalog declarations only; exhaustive TypeScript symbols not extracted","installationStatus":"not verified"},"docsLinks":[{"title":"Tool Bun documentation","url":"https://www.npmjs.com/package/%40lssm-tech%2Ftool.bun","kind":"readme","pinnedUrl":null,"sourceStatus":"declared link; destination not verified"}],"sourceUrls":{"package":"https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun","manifest":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/package.json","readme":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/README.md","guide":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/tool.bun.txt"},"readme":{"status":"available","body":"# @lssm-tech/tool.bun\n\nWebsite: https://contractspec.io\n\n**Shared Bun build presets and CLI for ContractSpec packages. Provides the `contractspec-bun-build` binary used by nearly every package's `build`, `dev`, and `prebuild` scripts.**\n\n## What It Provides\n\n- **Layer**: tool\n- **Consumers**: all monorepo packages (via `contractspec-bun-build` in their scripts)\n\n## Installation\n\n`npm install @lssm-tech/tool.bun`\n\nor\n\n`bun add @lssm-tech/tool.bun`\n\n## Usage\n\n```bash\nnpx contractspec-bun-build --help\n# or\nbunx contractspec-bun-build --help\n```\n\n## Typed Config\n\nThe ordered configuration filenames are owned by this package's\n`contractspec.development.configInputs` manifest binding. Runtime discovery uses\nthis validated list. The pending affected-work planner integration can use the\nsame authority to bind configuration dependencies to the invoking workspace.\nThis metadata describes dependencies; it does not authorize execution or waive\nartifact qualification.\n\nThe root package export includes TypeScript declarations for config presets:\n\n```ts\nimport {\n\tdefineConfig,\n\tmoduleLibrary,\n\ttype BuildConfig,\n} from \"@lssm-tech/tool.bun\";\n\nconst config: BuildConfig = {\n\t...moduleLibrary,\n\tstyleMode: \"copy\",\n};\n\nexport default defineConfig(() => config);\n```\n\n## Pack Staging Helpers\n\n`@lssm-tech/tool.bun/pack-staging` holds the contributor helpers that package\npack verifiers share: `stageBuiltPackage`, `stageWorkspaceDependencies`,\n`workspacePackageRoots`, `literalize`, `catalogVersions` and `run`. They run\nunder Bun inside a repository workspace, rewrite `workspace:`/`catalog:` ranges\nto publishable ranges in staged copies and never publish anything.\n`stageWorkspaceDependencies(root, run, manifestRoot)` stages the transitive\n`workspace:` runtime closure of the manifest you name explicitly.\n\n```ts\nimport {\n  run,\n  stageBuiltPackage,\n  stageWorkspaceDependencies,\n} from \"@lssm-tech/tool.bun/pack-staging\";\n\nconst staged = await stageBuiltPackage(packageRoot, join(temporaryRoot, \"pkg\"));\nconst closure = await stageWorkspaceDependencies(artifacts, run, packageRoot);\n```\n\n## Pack Verification Helpers\n\n`@lssm-tech/tool.bun/pack-verification` holds the production-pack verifier\nthat package `pack:verify` scripts share. It runs under Bun inside a repository\nworkspace, works in a temporary directory you own and never publishes.\n\n- `packReproducibly(packageRoot, root, run)` stages the built package (dist\n  without test or build-state files, README, production manifest) and packs it\n  twice with `npm pack --ignore-scripts`. It fails unless both tarballs are\n  byte-identical and the source manifest is unchanged.\n- `inspectPackedArtifact(tarball, root, run, { requiredDependencies })` rejects\n  source, test or build-state entries, private dependency protocols, source\n  export targets, missing required direct dependencies and undeclared runtime\n  imports in the emitted JavaScript.\n- `verifyPackConsumer(packageRoot, root, tarball, manifest, run)` builds and\n  packs the workspace dependency closure, installs everything into a clean\n  consumer, imports every declared subpath in Node and Bun and type-checks them\n  with the nearest `node_modules/.bin/tsgo` up to the workspace root. The\n  install resolves third-party dependencies from the npm registry.\n\nThe production manifest uses `publishConfig.exports`, writes `workspace:`\nranges as `^<version>` and `catalog:` ranges as the catalog's verbatim value,\nand drops dev dependencies, scripts and `publishConfig`. A closure dependency\nthat declares a `pack:production` script produces its own tarball.\n`packProductionPackage`, `stageProductionPackage`, `stageLocalDependencies`,\n`productionManifest`, `assertRuntimeImportClosure` and `runCommand` are the\nbuilding blocks.\n\n```ts\nimport {\n  inspectPackedArtifact,\n  packReproducibly,\n  runCommand,\n  verifyPackConsumer,\n} from \"@lssm-tech/tool.bun/pack-verification\";\n\nconst { tarball, sha256 } = await packReproducibly(packageRoot, root, runCommand);\nconst manifest = await inspectPackedArtifact(tarball, root, runCommand, {\n  requiredDependencies: [\"@lssm-tech/lib.schema\"],\n});\nawait verifyPackConsumer(packageRoot, root, tarball, manifest, runCommand);\n```\n\n## Private Build Entries\n\nDeclaration builds resolve dev-only workspace dependencies from the selected\nTypeScript build project's source and compiler configuration. Test-only dependencies\nexcluded by that project do not trigger unrelated declaration builds. Runtime\ndependencies and required peers retain their artifact checks, and optional peers\nretain their type-only reference checks. Computed module expressions or relative\nimports outside the resolved project retain all dev dependencies conservatively.\nTest workflows continue to use the package's complete declared dependencies.\n\nNon-UI packages can opt into `entryMode: 'module-closure'` with explicit literal\n`entry` paths and `exports: { rewrite: false }`. The existing manifest is the\nauthority for supported exports: source export targets remain compatibility roots,\nincluding subpaths that the root barrel does not export. Runtime-relative imports\nare followed and each reachable module is emitted once per target. A new private\nhelper never becomes a package export merely because it exists. Edit the manifest\ndeliberately when adding a public entry. An exact subpath blocked with `null`\nin both frozen source and published maps adds no closure or emitted target.\nA block present in only one map fails validation. This mode implies no-bundle emission and\nuses sequential worker batches capped at 64 files or 8 MiB of source.\nA single module larger than 8 MiB fails explicitly in this opt-in mode.\nFor mixed packages, browser emission starts only at exact frozen exports that\nadvertise a browser target and follows their private dependencies. Unrelated\nNode-only public roots still build for Bun and Node and remain part of declaration\nemission. Shared-package inference retains browser output for those advertised\nroots; explicitly disabling browser remains an error. Node-only imports reachable\nfrom any browser root are rejected, and full-graph source validation still applies\nto backend roots. Direct entry mode retains its existing target inference.\nSingle-entry tsconfig-override builds honor `noBundle` just like the normal\nCLI path and explicit closure batches. Local helpers stay separate, so React\ncontexts and shared module state retain their identity. Bundled builds keep\ntheir existing behavior. The override worker resolves configured local\nTypeScript aliases to relative emitted modules while keeping declared external\npackages external; missing emitted helpers or assets fail validation. Platform\nentry selection, native worklets, client directives and explicit style copying\nremain separate parts of the existing build pipeline.\n\n```js\nexport default defineConfig({\n  ...moduleLibrary,\n  entry: ['src/index.ts', 'src/service.ts'],\n  entryMode: 'module-closure',\n  exports: { rewrite: false },\n});\n```\n\nThe initial opt-in supports non-UI relative JavaScript/TypeScript graphs and\ndeclared external packages. Computed imports/requires, local aliases, wildcard\nexports, assets and unadvertised platform-suffixed source graphs fail explicitly.\nAn exact frozen public native/ios/android implementation root may use its\n`dist/native` layout; an exact web/browser root may use its existing root/browser\nlayout. Only those advertised files are admitted, never private platform siblings\nor platform discovery. Published target paths must match the existing entry\nselection, and disabled targets still fail. Platform declaration aliases remain\nunsupported. Frozen conditional source exports retain every branch as a closure\nand declaration root. Each published condition must point to its matching source\nbranch, honoring source condition order and default fallback. Browser reachability\nstarts at that condition's source rather than unrelated native or backend branches.\nMulti-source maps are checked across every combination of their source/published\ncondition names, including custom conditions, up to twelve distinct names per\nexport. Larger or conflicting layouts fail explicitly and can use direct mode.\nKeep other platform graphs in `direct` mode. This\ndoes not change UI/Metro conditional exports or the existing direct-mode watcher.\nDeclarations continue to use the package's complete TypeScript configuration.\nFull builds retain transactional rollback, and standalone transpile failures must\nnever be treated as usable outputs. Closure mode freezes manifest bytes even when\n`prebuild` runs; it validates both source and published export mappings instead.\nAdvertised runtime conditions must have enabled build targets. Browser claims\nare checked against the complete compatibility closure, not only intentional\nentries: a legacy-only Node builtin import fails before output is replaced.\nIts dev watcher recomputes reachability on source edits, including newly imported\nprivate files, serializes producers and retains the previous good output after a\nfailed rebuild. It builds the Bun target by default (`--all-targets` includes the\nadvertised targets). Manifest/compiler/build-config edits require restarting dev\nand terminate the watcher explicitly instead of using stale configuration.\n\nPackages can emit implementation-only files without adding them to generated package exports. Use `exports.exclude` for files that public entries import relatively but consumers must not import as package subpaths:\n\n```js\nexport default {\n\tentry: ['src/**/*.ts', 'src/**/*.tsx'],\n\texports: {\n\t\trewrite: true,\n\t\texclude: ['src/**/internal/**'],\n\t},\n};\n```\n\nThe files still build into `dist`, but `prebuild` omits matching paths from `exports` and `publishConfig.exports`.\n\n## Node ESM Relative Specifiers\n\nDeclared dependencies, optional dependencies and peers are explicitly external\nfor JavaScript builds, including their subpaths. This preserves package boundaries\nwhen workspace TypeScript paths point at dependency source files: bundling local\ncode must not inline a dependency and leak its transitive imports into the caller.\nCustom `external` entries remain additive. Development-only packages are not\nautomatically treated as runtime dependencies.\n\nBun resolves TypeScript aliases before external flags. A temporary resolved\ntsconfig removes aliases belonging to external packages while retaining local\naliases, so package boundaries survive that resolution order. The source config\nis not edited, and temporary configuration is removed after success or failure.\n\nShared-target inference follows runtime imports through local barrels, including\nliteral dynamic imports and NodeNext `.js` specifiers resolving to TypeScript.\nUnselected tests remain excluded; custom source layouts and import cycles are\nsupported. This is local source inference, not qualification of external packages\nor dynamic nonliteral imports for browser execution.\nExecutable shebangs are normalized only in scanner input; source files remain\nunchanged and continue to build as CLI entry points.\n\nPresets and default configuration share build-entry pattern definitions, including\n`.spec.tsx` and `.test-support.ts`/`.test-support.tsx` exclusions. Test helpers are\nnot production entries, generated public subpaths, or target-inference roots.\nKeep test helpers excluded from package declaration tsconfigs as well.\nExplicit entry overrides remain supported, and test-runner\ndiscovery is independent of these build/export patterns.\n\nEvery production transpile target normalizes emitted relative ESM specifiers\nafter Bun writes the complete target. Static imports, re-exports, and literal\ndynamic imports, and declaration import types (`import(\"./module\").Type` and\n`typeof import(\"./module\")`) resolve in this deterministic order:\n\n1. an existing exact file;\n2. a sibling `.js` file;\n3. an `index.js` file in the referenced directory.\n\nExact `.` and `..` directory references resolve only to their index, never a\nsimilarly named sibling file. Declaration-only sidecars retain the same public\ntypes while their emitted specifiers use NodeNext-compatible `.js` paths.\n\nQuery strings and URL fragments are preserved. The normalizer is idempotent and\nsyntax-aware, so import-shaped comments and ordinary strings are not changed. If\nany relative specifier cannot be resolved, the target fails before any emitted\nfile is rewritten; incomplete Node ESM graphs cannot be published accidentally.\n\nThe TypeScript 7 parser and declaration emitter prefer the native binding for\nthe current runtime architecture. If the package manager ran under a compatible\nalternate architecture (for example, x64 Node under Rosetta with arm64 Bun),\nthe tool deterministically falls back to the installed same-platform binding.\n\n## Style Exports\n\n`contractspec-bun-build` scans public CSS style entries separately from TypeScript entries so style files do not affect JavaScript output roots.\n\nDefault style entries:\n\n- `styles/**/*.css`\n- `src/*.css`\n- `!**/*.module.css`\n\nPackages can override or disable style entries from their build config:\n\n```js\nexport default {\n\tstyleEntry: ['styles/**/*.css'],\n\t// or: styles: { entry: ['styles/**/*.css'] },\n\t// or: styleEntry: false,\n};\n```\n\nBy default, style entries are processed with `bun build`. Packages that need to preserve CSS directives for another processor, such as Tailwind `@source`, `@custom-variant`, `@theme`, or `@tailwind`, can copy style files unchanged:\n\n```js\nexport default {\n\tstyleEntry: ['src/styles/**/*.css'],\n\tstyleMode: 'copy',\n\t// or: styles: { entry: ['src/styles/**/*.css'], mode: 'copy' },\n};\n```\n\nStyle entries are exported under the `style` and `default` conditions, for example `./styles/globals.css`.\n\n## Type Declaration Emit\n\n`contractspec-bun-build types` emits package declarations with stable\nTypeScript 7 (`tsc`) by generating a temporary declaration-only tsconfig and\nwriting `.d.ts` files to `dist`.\n\n## Platform Variants\n\n`contractspec-bun-build` recognizes platform suffixes in public TypeScript entries and emits conditional exports plus matching build outputs:\n\n| Source suffix | Export condition | Build output |\n| --- | --- | --- |\n| `.web` | `browser` | `dist/browser/*` plus the Bun default when no base entry exists |\n| `.native` | `react-native` | `dist/native/*` |\n| `.ios` | `ios` | `dist/native/*` |\n| `.android` | `android` | `dist/native/*` |\n\nExact subpaths such as `./foo.web`, `./foo.native`, `./foo.ios`, and `./foo.android` are exported alongside canonical subpaths such as `./foo`.\n\n## Public Entry Points\n\n- `contractspec-bun-build` -> `./bin/contractspec-bun-build.mjs`\n- `.` — `./index.js`\n\n## Local Commands\n\n- `bun run test` — bun test\n- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose\n- `bun run publish:pkg:canary` — bun publish:pkg --tag canary\n\n## Recent Updates\n\n- Normalize emitted relative Node ESM specifiers and fail closed on incomplete graphs\n- Add copy mode for public CSS style files that must preserve framework directives\n- Add direct CSS style subpath exports for public style files\n- Replace eslint+prettier by biomejs to optimize speed\n- Add multi platform support to bun build\n- Use-client within lib surface-runtime\n\n## Notes\n\n- Changes here affect every package's build pipeline -- test broadly before merging\n- Do not remove or rename CLI sub-commands (`transpile`, `types`, `dev`, `prebuild`) without updating all consumers\n- Keep runtime dependencies deliberate: `glob` powers source discovery and\n  stable `typescript` powers declaration emit and artifact parsing\n- The published package contains only the binary, runtime library, typed root\n  export, README, and changelog; conformance tests stay in the repository\n\n\n### Artifact normalization snapshots\n\nRelative-import normalization uses the same source snapshot as its AST offsets. A concurrent normalizer that already produced the identical output is an idempotent no-op. If a file differs from both the parsed source and expected normalized output at publication checks, normalization reparses the graph up to three attempts. Continuous conflicts fail with an explicit changed-artifact error and preserve the observed newer file. A successful normalization is not a lock against arbitrary external emitters; build orchestration must still isolate output directories during emission.\n\n### Artifact parser deadlines\n\nEach emitted-artifact parse has a two-minute I/O deadline. Snapshot disposal and\nAPI shutdown each have a two-second grace period before process termination and\nworkspace cleanup. Timeout is an error, never successful artifact validation, and\nthe serialized parser queue remains usable after rejection. Large graphs and\nNodeNext/native specifier checks remain in the conformance suite.\n\nCompiler stdout is drained concurrently. If its pipe remains open ten seconds\nafter the compiler exits, the build fails explicitly and cancels the reader.\nThis deadline does not limit compilation time and never treats missing output\nas a successful build.\n\nParser RPC failures include the current snapshot/project/file-batch phase. A\nparser process exit rejects pending RPCs immediately with its exit status and\nbounded stderr tail, rather than waiting silently until the I/O deadline.\n\nMulti-file artifact validation partitions native parser projects by source bytes\n(8 MiB) and file count (16). A single larger file remains intact. Projects close\nbetween groups, preserving ordered AST results and full validation while avoiding\none native project retaining a large monorepo's repeated bundled source graphs.\n\nDeclaration compilation uses `noEmitOnError` so type/root-boundary failures cannot\nwrite partial declarations, including escaped output in sibling source trees.\nConsumers must still honor the nonzero build result; previous valid artifacts do\nnot qualify a new source revision.\n\nConcrete published declaration paths are required once a dependency declares a\n`build:types` producer. Missing artifacts fail before consumer compilation instead\nof silently falling back to sibling sources. Source-only dependencies remain\nsupported. Standalone `.d.ts`/`.d.mts`/`.d.cts` inputs retain their suffix and are\ncopied after successful type checking; generated sibling declarations take priority.\n\nDependency freshness checks read the same discovered source timestamps with at\nmost eight concurrent metadata reads. They preserve the maximum timestamp and\nfirst source-order error, and settle every started read before returning.\n\nStandalone declaration copying uses TypeScript's resolved input list. This covers\ncustom layouts such as root-level `ui/` and respects explicit project exclusions\ninstead of assuming every package uses `src/`.\n\nUnused optional workspace peers do not impose declaration-build prerequisites.\nThe builder conservatively checks selected source files and resolved compiler\noptions for peer references, including type-only imports. Required dependencies\nand referenced optional peers still require their advertised declaration artifacts.\n\nTypes-only builds materialize configured style entries before relative-import\nvalidation, using the same copy/build mode as JavaScript bundles. A cold checkout\ntherefore includes styles referenced by emitted declarations without weakening\nartifact-integrity checks.\n\nArtifact parsing explicitly opens the temporary tsconfig project and selects that\nproject for every batch. It never relies on emitted files finding an ancestor or\ninferred project. Each project contains the requested JavaScript/declaration roots\nonly, with dependency resolution, ambient type discovery, and default libraries\ndisabled. All requested roots must still yield ASTs, and relative-import closure\nvalidation still rejects unresolved artifacts before writes. This isolates parsing\nfrom consumer tsconfig exclusions and keeps byte/file batch limits effective.\n\n### Full package output rebuilds\n\nStandard consumers run `contractspec-bun-build build` from their `build` script.\nBun still runs package `prebuild` lifecycle hooks; custom pipelines retain their\nexplicit stages. This source-distributed tool has no build script. Run conformance\nwith `bun run test` separately. Turbo hashes builder runtime sources directly.\n\n`contractspec-bun-build build` saves the previous `dist`, emits JavaScript and\ndeclarations into a fresh output tree, and validates both stages before discarding\nthe previous tree. A failed stage restores the previous output. This removes\nobsolete nested declarations after output layouts change without guessing whether\nindividual declaration-only modules are stale. Standalone `transpile` retains its\nTurbo declaration-preservation behavior. Hand-authored declarations belong in the\nconfigured source inputs so successful type generation copies them into output.\n\nAn exclusive `.contractspec-build.lock` records the owner PID, hostname, and\nunique token. Concurrent full producers wait up to five minutes and then fail\nexplicitly; every successful caller runs its own build. Only a same-host owner\nwhose PID probe returns ESRCH is automatically recovered. Live/reused PIDs,\npermission failures, and foreign-host ownership never authorize reclamation.\n\nA dead owner's interrupted output is rolled back before rebuilding. A commit\nmarker distinguishes completed builds from interrupted backup cleanup. Recovery\nclaims serialize competing reclaimers, and lock directories retire by atomic\nrename before deletion. Retired `.released-*` and `.recovered-*` directories may\nremain after process termination; they are ignored by Git and preserve any\nremaining backup for inspection.\n\nOwnerless legacy locks, invalid journals, failed rollback, and interrupted\nrecovery claims require manual recovery: first inspect live producers, preserve\nboth current output and the lock directory outside the package, restore the\nprevious `lock/dist` when present, and only remove the lock after establishing\nthat no producer is using it. Never delete a live lock or infer death from age.\n\nThe standalone `transpile` and `types` commands take the same lock, so a\nbundle-only or declaration-only writer never interleaves with a full rebuild or\nwith each other in one package. They update `dist` in place without a backup\njournal, so a crashed partial writer leaves nothing to restore. Watch-mode `dev`\nand Turbo cache restoration are not serialized by this lock. Use one workspace\nbuild owner when consumers must read dependency output while it remains stable.\n\n### Bun override builds\n\nBun 1.4.2 can emit `directory mismatch` when its CLI reads a\n`--tsconfig-override` file ([upstream report](https://github.com/oven-sh/bun/issues/25730)).\nThe shared builder runs builds requiring an override through `Bun.build()` in\nan isolated child process. A resolver marks declared external package imports\nand their subpaths external before workspace aliases can inline them; local\naliases remain available. This also preserves boundaries on Bun versions whose\nJavaScript API does not honor the custom tsconfig option.\n\nThe source tsconfig remains unchanged, temporary configs are cleaned after\nsuccess or failure, and build diagnostics remain visible. Builds without an\noverride continue to use the Bun CLI. This is a compatible internal fix with\nno consumer configuration changes.\n\nDeclaration resolution honors a dependency's explicit published export map.\nPackages with intentional roots receive exact aliases, so inferred declaration\nreferences cannot choose an implicit wildcard pointing at unpublished private\nfiles. Existing declared wildcard maps and legacy packages without a published\nmap retain their previous fallback resolution.\n\nOn Windows, the native TypeScript artifact parser detects named-pipe readiness\nwithout opening the pipe, preserving the connection for the actual API client.\nWorkspace dependency identities use portable repository-relative paths on every\nhost. Neither correction changes package exports or builder commands.\n","sourcePath":"packages/tools/bun/README.md","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/bun/README.md","blobSha":"acff8c435cb26b995149750edf22e3c59bab2f59","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","origin":"README recovered byte-for-byte from pinned aggregate guide","integrity":"exact Git blob match","executionStatus":"not executed"},"provenance":{"repository":"lssm-tech/contractspec","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","manifestOrigin":"pinned GitHub manifest fetch","manifestComplete":true,"publicationPolicyApplied":false},"areaSlug":"tooling-and-agent-delivery","areaTitle":"CLI, authoring and agent tooling","displayName":"tool.bun","runtimes":["node"],"platforms":["server"],"kind":"tool","scope":"Package manifest","canonicalRoute":"/docs/packages/tool.bun/","contextUrl":"/docs/packages/tool.bun.context.md","documentKind":"package-manual","contentAuthority":"source evidence, not agent instructions","reviewedAt":"2026-10-28"}