get-tbd 0.1.28 → 0.1.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin.mjs +3 -3
- package/dist/bin.mjs.map +1 -1
- package/dist/cli.mjs +3 -3
- package/dist/cli.mjs.map +1 -1
- package/dist/docs/SKILL.md +0 -4
- package/dist/docs/guidelines/bun-monorepo-patterns.md +92 -289
- package/dist/docs/guidelines/cli-agent-skill-patterns.md +706 -1240
- package/dist/docs/guidelines/pnpm-monorepo-patterns.md +104 -321
- package/dist/docs/guidelines/supply-chain-hardening.md +237 -0
- package/dist/docs/shortcuts/standard/new-validation-plan.md +1 -1
- package/dist/index.mjs +1 -1
- package/dist/{src-D2xEmH4L.mjs → src-CJyVkC3V.mjs} +2 -2
- package/dist/{src-D2xEmH4L.mjs.map → src-CJyVkC3V.mjs.map} +1 -1
- package/dist/tbd +3 -3
- package/package.json +1 -1
package/dist/docs/SKILL.md
CHANGED
|
@@ -17,10 +17,6 @@ description: >-
|
|
|
17
17
|
allowed-tools: Bash(tbd:*), Read, Write
|
|
18
18
|
---
|
|
19
19
|
|
|
20
|
-
---
|
|
21
|
-
title: tbd Workflow
|
|
22
|
-
description: Full tbd workflow guide for agents
|
|
23
|
-
---
|
|
24
20
|
**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**
|
|
25
21
|
|
|
26
22
|
1. **Beads**: Git-native issue tracking (tasks, bugs, features).
|
|
@@ -34,7 +34,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
|
|
|
34
34
|
| **flowmark** | latest | [github.com/jlevy/flowmark](https://github.com/jlevy/flowmark) — Markdown auto-formatter (via `uvx`). |
|
|
35
35
|
| **publint** | ^0.3.20 (0.3.21 too recent) | [npmjs.com/package/publint](https://www.npmjs.com/package/publint) — **Pinned to 0.3.20 (2026-05-08) per the 14-day rule**; 0.3.21 (2026-05-13) is 9 days old today. Incremental: re-enabled TS/TSX file existence checks; `exports["default"]` support. |
|
|
36
36
|
| **actions/checkout** | v6 | [github.com/actions/checkout/releases](https://github.com/actions/checkout/releases) — v6.0.2 (2026-01-09). Credentials now stored in `$RUNNER_TEMP` rather than `.git/config`; Node 24 runtime; requires runner ≥ 2.327.1. |
|
|
37
|
-
| **oven-sh/setup-bun** | v2 | [github.com/oven-sh/setup-bun](https://github.com/oven-sh/setup-bun) — v2.2.0 (2026-03-14). Migrated to Node.js 24 runtime ahead of GitHub
|
|
37
|
+
| **oven-sh/setup-bun** | v2 | [github.com/oven-sh/setup-bun](https://github.com/oven-sh/setup-bun) — v2.2.0 (2026-03-14). Migrated to Node.js 24 runtime ahead of GitHub’s **2026-06-02 deadline** that forces all Node.js 20 actions to Node.js 24. |
|
|
38
38
|
| **lefthook** | ^2.1.5 (2.1.7/2.1.8 too recent) | [github.com/evilmartians/lefthook/releases](https://github.com/evilmartians/lefthook/releases) — **Pinned to 2.1.5 (2026-04-06) per the 14-day rule**; 2.1.7 and 2.1.8 both shipped 2026-05-19 (3 days old). Patch-level since 2.1.1: dependency bumps and config-warning improvements. v2 still excludes regexp `exclude` and `skip_output` from v1. |
|
|
39
39
|
| **npm-check-updates** | ^22.0.0 (22.2.0 too recent) | [npmjs.com/package/npm-check-updates](https://www.npmjs.com/package/npm-check-updates) — **Major version jump from 19 to 22.** **Pinned to 22.0.0 (2026-04-25) per the 14-day rule**; 22.2.0 (2026-05-12) is 10 days old today. Now pure ESM; named imports only (`import { run } from 'npm-check-updates'`); `.ncurc.js` with `module.exports` no longer works in `"type": "module"` projects (use `.ncurc.cjs`). **Critical for supply chain: now ships `--cooldown <days>` to refuse versions younger than the specified age.** See [Supply-Chain Mitigation](#supply-chain-mitigation). |
|
|
40
40
|
|
|
@@ -62,9 +62,9 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
|
|
|
62
62
|
|
|
63
63
|
6. **Review “Open Research Questions”** section for any resolved items
|
|
64
64
|
|
|
65
|
-
7. **Honor the 14-day package-age rule** when bumping versions in code examples.
|
|
66
|
-
[Supply-Chain Mitigation](#supply-chain-mitigation) — versions cited here should
|
|
67
|
-
≥14 days old at the time the table is updated, except where a clearly-noted
|
|
65
|
+
7. **Honor the 14-day package-age rule** when bumping versions in code examples.
|
|
66
|
+
See [Supply-Chain Mitigation](#supply-chain-mitigation) — versions cited here should
|
|
67
|
+
be ≥14 days old at the time the table is updated, except where a clearly-noted
|
|
68
68
|
security exception applies.
|
|
69
69
|
|
|
70
70
|
* * *
|
|
@@ -146,17 +146,18 @@ research stock.
|
|
|
146
146
|
- Missing some pnpm features: no `pnpm deploy`, less strict `node_modules` (phantom
|
|
147
147
|
dependencies possible)
|
|
148
148
|
|
|
149
|
-
- **Notable**: Bun was acquired by Anthropic on 2025-12-02 — Anthropic
|
|
149
|
+
- **Notable**: Bun was acquired by Anthropic on 2025-12-02 — Anthropic’s first
|
|
150
150
|
acquisition. Bun powers Claude Code (which ships as a `bun build --compile`
|
|
151
|
-
executable), the Claude Agent SDK, and other Anthropic AI tooling, signaling
|
|
152
|
-
|
|
153
|
-
(2026-05-13) is the last Zig-based release.
|
|
154
|
-
generated by Claude agents over ~6 days, 6,755
|
|
155
|
-
2026-05-14 and passes 99.8% of the test suite.
|
|
156
|
-
Zig
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
151
|
+
executable), the Claude Agent SDK, and other Anthropic AI tooling, signaling strong
|
|
152
|
+
ongoing investment and maintenance.
|
|
153
|
+
**Language transition**: Bun 1.3.14 (2026-05-13) is the last Zig-based release.
|
|
154
|
+
A full Rust rewrite (~960K lines, generated by Claude agents over ~6 days, 6,755
|
|
155
|
+
commits) merged to `main` on 2026-05-14 and passes 99.8% of the test suite.
|
|
156
|
+
The transition was motivated by Zig’s no-AI-contribution policy conflicting with the
|
|
157
|
+
Bun team’s workflow.
|
|
158
|
+
The external API surface (`bun`, `bunx`, `bun install`, `bun test`, `bun build`) is
|
|
159
|
+
unchanged; consumers should expect no breakage but watch the 1.4.x release notes for
|
|
160
|
+
migration details.
|
|
160
161
|
|
|
161
162
|
**Assessment**: Bun workspaces are functional and fast, but less strict than pnpm.
|
|
162
163
|
The text-based `bun.lock` format (since Bun 1.2) resolves the earlier diffability
|
|
@@ -1709,11 +1710,11 @@ This is a unique advantage that the pnpm ecosystem does not offer natively.
|
|
|
1709
1710
|
|
|
1710
1711
|
**Details**:
|
|
1711
1712
|
|
|
1712
|
-
npm-check-updates (`ncu`) works with Bun.
|
|
1713
|
-
instead of `pnpm install` after updates.
|
|
1714
|
-
14-day package-age rule** — see
|
|
1715
|
-
for the rationale and exception
|
|
1716
|
-
flag that enforces this directly.
|
|
1713
|
+
npm-check-updates (`ncu`) works with Bun.
|
|
1714
|
+
The main difference is using `bun install` instead of `pnpm install` after updates.
|
|
1715
|
+
**All upgrade commands must honor the 14-day package-age rule** — see
|
|
1716
|
+
[Supply-Chain Mitigation](#supply-chain-mitigation) for the rationale and exception
|
|
1717
|
+
process. `ncu` v22+ ships a native `--cooldown` flag that enforces this directly.
|
|
1717
1718
|
|
|
1718
1719
|
**Root `package.json` scripts**:
|
|
1719
1720
|
|
|
@@ -1728,13 +1729,12 @@ flag that enforces this directly.
|
|
|
1728
1729
|
```
|
|
1729
1730
|
|
|
1730
1731
|
**Note on npm-check-updates v22**: v22 is pure ESM, named imports only
|
|
1731
|
-
(`import { run } from 'npm-check-updates'`), and config files must be
|
|
1732
|
-
`.ncurc.
|
|
1733
|
-
|
|
1734
|
-
package-age rule.
|
|
1732
|
+
(`import { run } from 'npm-check-updates'`), and config files must be `.ncurc.cjs` (not
|
|
1733
|
+
`.ncurc.js`) in projects with `"type": "module"`. The `--cooldown <days>` flag is the
|
|
1734
|
+
recommended enforcement point for the 14-day package-age rule.
|
|
1735
1735
|
|
|
1736
|
-
**Assessment**: Identical workflow to pnpm.
|
|
1737
|
-
include `--cooldown 14`.
|
|
1736
|
+
**Assessment**: Identical workflow to pnpm.
|
|
1737
|
+
`bunx` replaces `npx`. Always include `--cooldown 14`.
|
|
1738
1738
|
|
|
1739
1739
|
* * *
|
|
1740
1740
|
|
|
@@ -1810,216 +1810,19 @@ in core library code if the library needs to work in Node.js environments.
|
|
|
1810
1810
|
|
|
1811
1811
|
## Supply-Chain Mitigation
|
|
1812
1812
|
|
|
1813
|
-
|
|
1814
|
-
|
|
1815
|
-
|
|
1816
|
-
|
|
1813
|
+
Supply-chain hardening applies to **every repo, not just new monorepos**, so the full
|
|
1814
|
+
policy and hands-on enforcement now live in a standalone guideline:
|
|
1815
|
+
**`tbd guidelines supply-chain-hardening`**. It covers the cross-ecosystem 14-day
|
|
1816
|
+
cool-off plus the Node/pnpm/Bun specifics — lifecycle-script allowlists, lockfile
|
|
1817
|
+
discipline, `npm-check-updates --cooldown 14`, the CI audit gate, and the
|
|
1818
|
+
`check-package-age` pre-push guard.
|
|
1819
|
+
Deeper background and the named-incident watch list:
|
|
1820
|
+
<https://github.com/jlevy/supply-chain-hardening>.
|
|
1817
1821
|
|
|
1818
|
-
|
|
1819
|
-
|
|
1820
|
-
|
|
1821
|
-
|
|
1822
|
-
similar campaigns ran through 2025 (`debug`, `chalk`, `ansi-styles` lookalikes;
|
|
1823
|
-
`expr-eval` post-install RCE). pnpm shipped `minimumReleaseAge` as a default in
|
|
1824
|
-
v11.0 (1 day). Bun ships a built-in trusted-dependency allowlist and `bun audit`.
|
|
1825
|
-
The settings below are stricter than the ecosystem defaults and intentionally so.
|
|
1826
|
-
|
|
1827
|
-
### The 14-day package-age rule
|
|
1828
|
-
|
|
1829
|
-
**Never install or upgrade to a package version less than 14 days old.**
|
|
1830
|
-
|
|
1831
|
-
Why 14 days specifically:
|
|
1832
|
-
|
|
1833
|
-
- **Detection window**: most malicious publishes are reported and yanked within
|
|
1834
|
-
3–7 days; 14 days gives a generous buffer past that median.
|
|
1835
|
-
- **Patch-level releases ship dangerous code more often**: many compromises arrive
|
|
1836
|
-
as `1.2.3 → 1.2.4` patch bumps. A trailing window neutralizes the entire class
|
|
1837
|
-
of "fresh patch is malicious" attacks regardless of which dependency moved.
|
|
1838
|
-
- **Cheap to enforce, cheap to wait**: there is essentially no business cost to
|
|
1839
|
-
waiting 14 days on a routine upgrade, and the upside is large.
|
|
1840
|
-
|
|
1841
|
-
Scope:
|
|
1842
|
-
|
|
1843
|
-
- Applies to **`dependencies`, `devDependencies`, `peerDependencies`, and
|
|
1844
|
-
`optionalDependencies`** alike. devDependencies (bundlers, linters, test
|
|
1845
|
-
runners) have historically been *more* dangerous than runtime deps because
|
|
1846
|
-
they execute with full developer privileges on every install.
|
|
1847
|
-
- Applies to **transitive dependencies** to the extent the package manager
|
|
1848
|
-
enforces it (see below). Direct deps are the primary control point.
|
|
1849
|
-
- Applies to **upgrades and new installs**. Existing pins resolved before this
|
|
1850
|
-
policy was adopted are grandfathered until their next planned upgrade.
|
|
1851
|
-
|
|
1852
|
-
Exception process: if a security patch within the 14-day window is needed —
|
|
1853
|
-
e.g., a CVE patch published yesterday that fixes a vulnerability you are
|
|
1854
|
-
exposed to — the exception **must** be documented in the upgrade commit message
|
|
1855
|
-
or PR description, including:
|
|
1856
|
-
|
|
1857
|
-
- The CVE ID (or vulnerability description if no CVE yet).
|
|
1858
|
-
- A link to the upstream release notes.
|
|
1859
|
-
- A reviewer sign-off line (`Reviewed-by: …`).
|
|
1860
|
-
|
|
1861
|
-
No exception is "trivial" — even a `prettier` patch is in scope. The whole
|
|
1862
|
-
point of the rule is that we don't trust ourselves to spot-judge which fresh
|
|
1863
|
-
versions are safe.
|
|
1864
|
-
|
|
1865
|
-
### Enforcement: Bun
|
|
1866
|
-
|
|
1867
|
-
Bun blocks arbitrary lifecycle scripts by default via an internal allowlist of
|
|
1868
|
-
trusted packages. To extend that allowlist for your repo, declare the packages
|
|
1869
|
-
explicitly in `package.json`:
|
|
1870
|
-
|
|
1871
|
-
```json
|
|
1872
|
-
{
|
|
1873
|
-
"trustedDependencies": [
|
|
1874
|
-
"esbuild",
|
|
1875
|
-
"sharp"
|
|
1876
|
-
]
|
|
1877
|
-
}
|
|
1878
|
-
```
|
|
1879
|
-
|
|
1880
|
-
Anything not in the allowlist runs without `postinstall`/`preinstall`/`install`
|
|
1881
|
-
scripts. This is the most important single mitigation Bun gives you out of the
|
|
1882
|
-
box.
|
|
1883
|
-
|
|
1884
|
-
`bun audit` (documented at [bun.com/docs/pm/cli/audit](https://bun.com/docs/pm/cli/audit))
|
|
1885
|
-
checks the installed tree against the npm advisory database:
|
|
1886
|
-
|
|
1887
|
-
```bash
|
|
1888
|
-
# Run as part of CI; non-zero exit on findings
|
|
1889
|
-
bun audit --audit-level=moderate
|
|
1890
|
-
|
|
1891
|
-
# JSON output for parsing in scripts
|
|
1892
|
-
bun audit --json
|
|
1893
|
-
```
|
|
1894
|
-
|
|
1895
|
-
Bun does **not yet** ship a built-in equivalent of pnpm's `minimumReleaseAge`,
|
|
1896
|
-
so age enforcement is handled at the upgrade-tool layer (see below).
|
|
1897
|
-
|
|
1898
|
-
### Enforcement: cross-tool tooling
|
|
1899
|
-
|
|
1900
|
-
**`npm-check-updates --cooldown`** is the primary upgrade-time check. Use it
|
|
1901
|
-
even on Bun-managed projects (via `bunx`):
|
|
1902
|
-
|
|
1903
|
-
```bash
|
|
1904
|
-
# Refuse any candidate version younger than 14 days
|
|
1905
|
-
bunx npm-check-updates --cooldown 14
|
|
1906
|
-
|
|
1907
|
-
# Interactive upgrade with the 14-day filter applied
|
|
1908
|
-
bunx npm-check-updates --cooldown 14 --target minor --interactive
|
|
1909
|
-
|
|
1910
|
-
# CI-style check: exits non-zero if upgrades are available
|
|
1911
|
-
bunx npm-check-updates --cooldown 14 --errorLevel 2
|
|
1912
|
-
```
|
|
1913
|
-
|
|
1914
|
-
**Direct registry query** (when in doubt about a specific version):
|
|
1915
|
-
|
|
1916
|
-
```bash
|
|
1917
|
-
# Show all publish times for a package
|
|
1918
|
-
npm view typescript time
|
|
1919
|
-
|
|
1920
|
-
# Show the time of a specific version
|
|
1921
|
-
npm view typescript time.6.0.3
|
|
1922
|
-
```
|
|
1923
|
-
|
|
1924
|
-
If `npm view <pkg> time.<version>` reports less than 14 days ago, **wait**.
|
|
1925
|
-
|
|
1926
|
-
### Enforcement: lockfile discipline
|
|
1927
|
-
|
|
1928
|
-
- **Always commit `bun.lock`** (the text JSONC lockfile, default since Bun 1.2).
|
|
1929
|
-
- **Use `bun install --frozen-lockfile` in CI** so any drift between
|
|
1930
|
-
`package.json` and `bun.lock` fails the build instead of silently resolving
|
|
1931
|
-
to fresh versions.
|
|
1932
|
-
- **Never run `bun update` (or `bun install` on a fresh `node_modules` with an
|
|
1933
|
-
unpinned `package.json`) without lockfile review.** Treat lockfile diffs the
|
|
1934
|
-
same as code diffs.
|
|
1935
|
-
- In a monorepo, **a single root `bun.lock`** is the source of truth; per-package
|
|
1936
|
-
lockfiles are an anti-pattern.
|
|
1937
|
-
|
|
1938
|
-
### Enforcement: provenance and signatures
|
|
1939
|
-
|
|
1940
|
-
- Prefer dependencies that publish with [npm provenance attestations](https://docs.npmjs.com/generating-provenance-statements).
|
|
1941
|
-
Major projects (TypeScript, Vitest, Prettier, ESLint, etc.) ship these.
|
|
1942
|
-
- Run `npm audit signatures` (or the upcoming `bun audit signatures` once it
|
|
1943
|
-
ships) in CI on a periodic basis to catch tampered packages.
|
|
1944
|
-
|
|
1945
|
-
### Sample CI gate
|
|
1946
|
-
|
|
1947
|
-
Add this job to the CI workflow alongside lint/test:
|
|
1948
|
-
|
|
1949
|
-
```yaml
|
|
1950
|
-
audit:
|
|
1951
|
-
runs-on: ubuntu-latest
|
|
1952
|
-
steps:
|
|
1953
|
-
- uses: actions/checkout@v6
|
|
1954
|
-
- uses: oven-sh/setup-bun@v2
|
|
1955
|
-
with:
|
|
1956
|
-
bun-version: latest
|
|
1957
|
-
- run: bun install --frozen-lockfile
|
|
1958
|
-
- name: Vulnerability audit
|
|
1959
|
-
run: bun audit --audit-level=moderate
|
|
1960
|
-
- name: Package-age check
|
|
1961
|
-
run: bunx npm-check-updates --cooldown 14 --errorLevel 0
|
|
1962
|
-
# errorLevel 0 logs but doesn't fail — flip to 2 once you've cleared
|
|
1963
|
-
# the existing backlog.
|
|
1964
|
-
```
|
|
1965
|
-
|
|
1966
|
-
### Recommended local script
|
|
1967
|
-
|
|
1968
|
-
Drop a `scripts/check-package-age.mjs` (or `.ts`) one-liner in the repo that a
|
|
1969
|
-
pre-push hook can call:
|
|
1970
|
-
|
|
1971
|
-
```ts
|
|
1972
|
-
#!/usr/bin/env bun
|
|
1973
|
-
// Refuses to commit if any direct dependency in package.json was published
|
|
1974
|
-
// less than COOLDOWN_DAYS ago. Intended for the pre-push hook.
|
|
1975
|
-
import pkg from '../package.json' with { type: 'json' };
|
|
1976
|
-
|
|
1977
|
-
const COOLDOWN_MS = 14 * 24 * 60 * 60 * 1000;
|
|
1978
|
-
const now = Date.now();
|
|
1979
|
-
const all = { ...pkg.dependencies, ...pkg.devDependencies };
|
|
1980
|
-
|
|
1981
|
-
let violations = 0;
|
|
1982
|
-
for (const [name, spec] of Object.entries(all)) {
|
|
1983
|
-
const version = String(spec).replace(/^[\^~=<>]+/, '');
|
|
1984
|
-
const meta = await (await fetch(`https://registry.npmjs.org/${name}`)).json();
|
|
1985
|
-
const publishedAt = meta.time?.[version];
|
|
1986
|
-
if (!publishedAt) continue;
|
|
1987
|
-
const ageMs = now - new Date(publishedAt).getTime();
|
|
1988
|
-
if (ageMs < COOLDOWN_MS) {
|
|
1989
|
-
const days = (ageMs / 86_400_000).toFixed(1);
|
|
1990
|
-
console.error(`✗ ${name}@${version} is only ${days} days old (< 14)`);
|
|
1991
|
-
violations++;
|
|
1992
|
-
}
|
|
1993
|
-
}
|
|
1994
|
-
process.exit(violations > 0 ? 1 : 0);
|
|
1995
|
-
```
|
|
1996
|
-
|
|
1997
|
-
Wire it into lefthook (see Appendix E):
|
|
1998
|
-
|
|
1999
|
-
```yaml
|
|
2000
|
-
pre-push:
|
|
2001
|
-
commands:
|
|
2002
|
-
package-age:
|
|
2003
|
-
glob: "package.json"
|
|
2004
|
-
run: bun scripts/check-package-age.ts
|
|
2005
|
-
```
|
|
2006
|
-
|
|
2007
|
-
### Exception bookkeeping
|
|
2008
|
-
|
|
2009
|
-
When you take an exception, leave a one-line marker in `package.json` adjacent
|
|
2010
|
-
to the pin:
|
|
2011
|
-
|
|
2012
|
-
```jsonc
|
|
2013
|
-
{
|
|
2014
|
-
"devDependencies": {
|
|
2015
|
-
// Exception: CVE-2026-XXXX patch within 14d window. Reviewed 2026-05-21.
|
|
2016
|
-
"vitest": "4.1.7"
|
|
2017
|
-
}
|
|
2018
|
-
}
|
|
2019
|
-
```
|
|
2020
|
-
|
|
2021
|
-
(JSON strict-parsers will reject `//` comments — use a JSONC-aware tool or
|
|
2022
|
-
move the note to a `README.md` / `CHANGELOG.md` entry instead.)
|
|
1822
|
+
**Bun specifics**: Bun blocks lifecycle scripts by default — extend the allowlist via
|
|
1823
|
+
`trustedDependencies` in `package.json`, run `bun audit` in CI with
|
|
1824
|
+
`bun install --frozen-lockfile`, and commit `bun.lock`. Bun has no native release-age
|
|
1825
|
+
gate yet, so enforce the 14-day cool-off with `bunx npm-check-updates --cooldown 14`.
|
|
2023
1826
|
|
|
2024
1827
|
* * *
|
|
2025
1828
|
|
|
@@ -2073,8 +1876,8 @@ move the note to a `README.md` / `CHANGELOG.md` entry instead.)
|
|
|
2073
1876
|
## Best Practices
|
|
2074
1877
|
|
|
2075
1878
|
1. **Follow the 14-day package-age rule** for every dependency install and upgrade.
|
|
2076
|
-
See [Supply-Chain Mitigation](#supply-chain-mitigation).
|
|
2077
|
-
`bunx npm-check-updates --cooldown 14` and `bun audit` in CI; declare
|
|
1879
|
+
See [Supply-Chain Mitigation](#supply-chain-mitigation).
|
|
1880
|
+
Use `bunx npm-check-updates --cooldown 14` and `bun audit` in CI; declare
|
|
2078
1881
|
`trustedDependencies` explicitly; commit `bun.lock`; use
|
|
2079
1882
|
`bun install --frozen-lockfile` in CI.
|
|
2080
1883
|
|
|
@@ -2084,57 +1887,57 @@ move the note to a `README.md` / `CHANGELOG.md` entry instead.)
|
|
|
2084
1887
|
3. **Enable `isolatedDeclarations`** in `tsconfig.base.json` for dramatically faster DTS
|
|
2085
1888
|
generation with Bunup.
|
|
2086
1889
|
|
|
2087
|
-
|
|
1890
|
+
4. **Use Bunup’s auto-exports** (`exports: true`) to keep `package.json` exports
|
|
2088
1891
|
synchronized with build output.
|
|
2089
1892
|
|
|
2090
|
-
|
|
1893
|
+
5. **Use Biome for formatting + linting** via a single `biome.json`. Use
|
|
2091
1894
|
`biome check --write` locally and `biome ci` in CI for stricter checks.
|
|
2092
1895
|
|
|
2093
|
-
|
|
1896
|
+
6. **Add `bun update` after `changeset version`** to fix workspace reference resolution
|
|
2094
1897
|
in the lockfile.
|
|
2095
1898
|
|
|
2096
|
-
|
|
1899
|
+
7. **Use `bun publish` per package** instead of `changeset publish` to ensure proper
|
|
2097
1900
|
workspace resolution.
|
|
2098
1901
|
|
|
2099
|
-
|
|
1902
|
+
8. **Run CLI from source with `bun`** directly — no need for `tsx` or any TypeScript
|
|
2100
1903
|
execution wrapper.
|
|
2101
1904
|
|
|
2102
|
-
|
|
1905
|
+
9. **Consider `bun --compile`** for distributing CLI tools as standalone executables,
|
|
2103
1906
|
especially for users who don’t have Node.js or Bun installed.
|
|
2104
1907
|
|
|
2105
|
-
|
|
2106
|
-
|
|
1908
|
+
10. **Use `bun test`** for testing — fake timers are now supported (v1.3.4+). Switch to
|
|
1909
|
+
Vitest only if you need test isolation, browser mode, or sharding.
|
|
2107
1910
|
|
|
2108
|
-
|
|
1911
|
+
11. **Keep the root `package.json` private** with `"private": true` and only workspace
|
|
2109
1912
|
tooling.
|
|
2110
1913
|
|
|
2111
|
-
|
|
1914
|
+
12. **Scope your package names** with `@org/package-name` for GitHub Packages
|
|
2112
1915
|
compatibility.
|
|
2113
1916
|
|
|
2114
|
-
|
|
1917
|
+
13. **Validate before publish** with `publint` in CI and before every release.
|
|
2115
1918
|
|
|
2116
|
-
|
|
1919
|
+
14. **Use lefthook** for git hooks with `biome check` in pre-commit (single command
|
|
2117
1920
|
replaces separate format + lint hooks).
|
|
2118
1921
|
|
|
2119
|
-
|
|
1922
|
+
15. **Add the `"bun"` export condition** to let Bun consumers import TypeScript source
|
|
2120
1923
|
directly, bypassing compiled output.
|
|
2121
1924
|
|
|
2122
|
-
|
|
1925
|
+
16. **Use dynamic git-based versioning** for dev builds — the pattern works identically
|
|
2123
1926
|
with Bun, and `bun` replaces `tsx` for script execution.
|
|
2124
1927
|
|
|
2125
|
-
|
|
1928
|
+
17. **Use `biome ci`** in CI workflows instead of `biome check` — it’s stricter and
|
|
2126
1929
|
produces cleaner output for CI logs.
|
|
2127
1930
|
|
|
2128
|
-
|
|
1931
|
+
18. **Consider ESM-only output** for Bun-native CLI tools and packages targeting modern
|
|
2129
1932
|
Node.js (>=22). Only add CJS if specific consumers require it.
|
|
2130
1933
|
|
|
2131
|
-
|
|
1934
|
+
19. **Use flowmark** for Markdown formatting in pre-commit hooks — Biome does not format
|
|
2132
1935
|
Markdown, and consistent Markdown formatting improves documentation quality.
|
|
2133
1936
|
|
|
2134
|
-
|
|
1937
|
+
20. **Add golden/CLI tests** with `tryscript` alongside `bun test` for CLI tools — they
|
|
2135
1938
|
catch regressions in help text, output formatting, and argument parsing.
|
|
2136
1939
|
|
|
2137
|
-
|
|
1940
|
+
21. **Consider tag-triggered OIDC releases** as an alternative to the Changesets GitHub
|
|
2138
1941
|
Action — they provide npm provenance attestation and automatic GitHub Releases.
|
|
2139
1942
|
|
|
2140
1943
|
* * *
|
|
@@ -2157,12 +1960,12 @@ move the note to a `README.md` / `CHANGELOG.md` entry instead.)
|
|
|
2157
1960
|
It is diffable in code review and supported by GitHub rendering.
|
|
2158
1961
|
The binary `bun.lockb` is deprecated.
|
|
2159
1962
|
|
|
2160
|
-
4. **Biome plugin ecosystem**: Biome v2.4 (Feb 2026) added experimental embedded
|
|
2161
|
-
|
|
2162
|
-
|
|
2163
|
-
|
|
2164
|
-
|
|
2165
|
-
|
|
1963
|
+
4. **Biome plugin ecosystem**: Biome v2.4 (Feb 2026) added experimental embedded snippet
|
|
1964
|
+
formatting (CSS/GraphQL inside JS/TS template literals), 15 HTML accessibility rules
|
|
1965
|
+
enabled by default, and promoted Vue 3 / Next.js / Qwik rules to stable.
|
|
1966
|
+
The rule set continues growing toward parity with security and accessibility ESLint
|
|
1967
|
+
plugins. Custom ESLint rules remain a reason to keep ESLint (see craft-agents-oss case
|
|
1968
|
+
study in Appendix G).
|
|
2166
1969
|
|
|
2167
1970
|
5. **Bun workspace strictness**: Bun still uses flat `node_modules` (no
|
|
2168
1971
|
content-addressable store).
|
|
@@ -2176,40 +1979,40 @@ move the note to a `README.md` / `CHANGELOG.md` entry instead.)
|
|
|
2176
1979
|
The `--minify` and `--bytecode` flags help with startup time but not binary size.
|
|
2177
1980
|
|
|
2178
1981
|
7. ~~**TypeScript 6.0**~~: **SHIPPED** 2026-03-23. TypeScript 6.0 is the last
|
|
2179
|
-
JavaScript-based release; `strict: true` is the default; ESM is the default
|
|
2180
|
-
|
|
2181
|
-
for the codebase as part of the May 2026 currency refresh;
|
|
2182
|
-
`tsconfig.base.json` for now-redundant flag declarations.
|
|
1982
|
+
JavaScript-based release; `strict: true` is the default; ESM is the default module
|
|
1983
|
+
system; ~9 compiler settings flipped defaults.
|
|
1984
|
+
Currently 6.0.3. Adopt for the codebase as part of the May 2026 currency refresh;
|
|
1985
|
+
review `tsconfig.base.json` for now-redundant flag declarations.
|
|
2183
1986
|
|
|
2184
1987
|
8. **TypeScript 7.0 (Project Corsa, Go rewrite)**: Beta shipped 2026-04-21 as
|
|
2185
|
-
`@typescript/native-preview` (binary `tsgo`). Claims ~10x type-check speed
|
|
2186
|
-
|
|
2187
|
-
Visual Studio 2026 18.6 Insiders by default.
|
|
2188
|
-
builds yet** — wait for stable (expected mid-to-late
|
|
2189
|
-
DTS generation landscape for Bunup and tsdown once stable.
|
|
1988
|
+
`@typescript/native-preview` (binary `tsgo`). Claims ~10x type-check speed and ~3x
|
|
1989
|
+
less memory; passes 95%+ of the test suite.
|
|
1990
|
+
Available in Visual Studio 2026 18.6 Insiders by default.
|
|
1991
|
+
**Do not adopt for production builds yet** — wait for stable (expected mid-to-late
|
|
1992
|
+
2026). May change the DTS generation landscape for Bunup and tsdown once stable.
|
|
2190
1993
|
|
|
2191
1994
|
9. **Bunup maturity**: Bunup is iterating rapidly (0.16.31 as of May 2026, up from 0.4.x
|
|
2192
1995
|
a few months earlier).
|
|
2193
1996
|
The API surface (`defineConfig`, `defineWorkspace`, `exports`, `compile`) appears
|
|
2194
1997
|
stable, but pin versions carefully.
|
|
2195
1998
|
|
|
2196
|
-
10. **Bun + Anthropic + Rust rewrite**: Bun was acquired by Anthropic on
|
|
2197
|
-
|
|
2198
|
-
|
|
2199
|
-
(~960K lines, generated by Claude agents over ~6 days) merged to
|
|
2200
|
-
2026-05-14 and passes 99.8% of the test suite.
|
|
2201
|
-
Zig-based release.** External API surface (`bun`, `bunx`,
|
|
2202
|
-
`bun test`, `bun build`, `bun --compile`) is unchanged, but watch
|
|
2203
|
-
release notes for migration details.
|
|
2204
|
-
open-source community continues to benefit equally as
|
|
2205
|
-
integrates more deeply with Anthropic
|
|
1999
|
+
10. **Bun + Anthropic + Rust rewrite**: Bun was acquired by Anthropic on 2025-12-02
|
|
2000
|
+
(Anthropic’s first acquisition) and now powers Claude Code, the Claude Agent SDK,
|
|
2001
|
+
and other Anthropic AI tooling.
|
|
2002
|
+
A full Rust rewrite (~960K lines, generated by Claude agents over ~6 days) merged to
|
|
2003
|
+
`main` on 2026-05-14 and passes 99.8% of the test suite.
|
|
2004
|
+
**Bun 1.3.14 is the last Zig-based release.** External API surface (`bun`, `bunx`,
|
|
2005
|
+
`bun install`, `bun test`, `bun build`, `bun --compile`) is unchanged, but watch
|
|
2006
|
+
1.4.x release notes for migration details.
|
|
2007
|
+
Monitor whether the broader open-source community continues to benefit equally as
|
|
2008
|
+
the codebase integrates more deeply with Anthropic’s AI tooling.
|
|
2206
2009
|
|
|
2207
2010
|
11. **`bun audit`**: Now a documented command
|
|
2208
2011
|
([bun.com/docs/pm/cli/audit](https://bun.com/docs/pm/cli/audit)) with
|
|
2209
|
-
`--audit-level=<low|moderate|high|critical>` and `--json` output.
|
|
2210
|
-
a required CI check (see
|
|
2211
|
-
A `bun audit signatures`
|
|
2212
|
-
yet shipped — monitor.
|
|
2012
|
+
`--audit-level=<low|moderate|high|critical>` and `--json` output.
|
|
2013
|
+
Should be a required CI check (see
|
|
2014
|
+
[Supply-Chain Mitigation](#supply-chain-mitigation)). A `bun audit signatures`
|
|
2015
|
+
equivalent to npm’s signature verification has not yet shipped — monitor.
|
|
2213
2016
|
|
|
2214
2017
|
* * *
|
|
2215
2018
|
|
|
@@ -2486,17 +2289,17 @@ testing features.
|
|
|
2486
2289
|
**Notes**:
|
|
2487
2290
|
|
|
2488
2291
|
- All pinned versions above are ≥14 days old as of 2026-05-21 per the
|
|
2489
|
-
[Supply-Chain Mitigation](#supply-chain-mitigation) policy.
|
|
2490
|
-
may exist (`@biomejs/biome` 2.4.15, `lefthook` 2.1.8,
|
|
2491
|
-
22.2.0) but were too fresh at the time of this document update.
|
|
2292
|
+
[Supply-Chain Mitigation](#supply-chain-mitigation) policy.
|
|
2293
|
+
Newer releases may exist (`@biomejs/biome` 2.4.15, `lefthook` 2.1.8,
|
|
2294
|
+
`npm-check-updates` 22.2.0) but were too fresh at the time of this document update.
|
|
2492
2295
|
- `"check:ci": "biome ci ."` uses `biome ci` (stricter than `biome check` — errors on
|
|
2493
2296
|
formatting issues)
|
|
2494
2297
|
- `bun run --filter '*' <script>` delegates to each workspace package
|
|
2495
2298
|
- The `@changesets/changelog-github` dependency is optional — use
|
|
2496
2299
|
`"changelog": "@changesets/cli/changelog"` in `.changeset/config.json` for a simpler
|
|
2497
2300
|
built-in changelog generator
|
|
2498
|
-
- `npm-check-updates` v22+ is pure ESM. Add `--cooldown 14` to every invocation per
|
|
2499
|
-
|
|
2301
|
+
- `npm-check-updates` v22+ is pure ESM. Add `--cooldown 14` to every invocation per the
|
|
2302
|
+
14-day package-age rule (see Supply-Chain Mitigation section).
|
|
2500
2303
|
|
|
2501
2304
|
### Appendix C: Complete biome.json Example
|
|
2502
2305
|
|