chore(nix): add bun node_modules normalization scripts

[xilec]

Before Submitting This PR

• I have searched existing issues and pull requests (including closed ones) to ensure this isn't a duplicate
• I have read CONTRIBUTING.md

Human Written Description

These scripts are needed for the nixpkgs upstream packaging. nixpkgs stores bun dependencies as a fixed-output derivation, which requires node_modules/ to be byte-identical every time it is produced from the same bun.lock. Out of the box bun install --linker=isolated does not give us that — two runs on different machines (and even two runs on the same machine) can differ in subtle ways. These scripts patch the output so the hash is stable.

Having them live in the Handy repo — rather than in the nixpkgs tree — is the preferred approach and matches how opencode does it: any future bun/Handy bump can update the scripts in one place.

What the scripts do

Everything is wired behind a single entry point, normalize-install.ts, which runs three small passes in order:

1. canonicalize-node-modules.ts — rebuilds node_modules/.bun/node_modules/ symlinks in sorted order, preserving the exact targets bun picked.
2. heal-peer-dep-bins.ts — adds any .bin/<peer> entries that bun's installer intended to create but skipped.
3. normalize-bun-binaries.ts — rebuilds each package's private .bin/ directory in sorted order, again preserving bun's targets.

The orchestrator is what package.nix in nixpkgs calls. Each sub-script is still runnable standalone for debugging.

Why the heal pass exists (the non-obvious part)

Bun's isolated installer decides whether to create a .bin/<name> link by checking, at the moment the linker runs, whether the target file exists on disk. For most dependencies that's fine because the installer waits for the provider package to finish before linking the consumer. But for circular peer dependencies (e.g. browserslist ↔ update-browserslist-db, eslint ↔ eslint-utils), that wait is skipped to avoid a deadlock — so the two sides race, and whichever one finishes last silently drops one or more .bin/ entries.

The outcome depends on CPU load, thread scheduling, filesystem latency, etc., so even the same bun.lock with the same bun version can produce different .bin/ sets between Linux and macOS (and in principle between two runs on the same host). We've observed this concretely in Handy's install.

The heal pass reads each package's peerDependencies, finds the bins the peer declares, and creates any missing symlinks — producing the complete .bin/ set that bun would have produced without the race. Advantages:

• It matches bun's intended behavior, not a stripped-down version of it.
• It's idempotent: if bun ever fixes the race upstream, the script becomes a no-op and the hash stays the same.
• It does not depend on Handy's own manifest — works for any bun install with peer dependencies.

Closest upstream tracker for the family of races: oven-sh/bun#28147.

Cross-platform verification

Verified on bun 1.3.11 via a temporary GitHub Actions matrix (ubuntu-latest + macos-latest):

system	node_modules NAR hash
x86_64-linux	sha256-DMhAdAzgh0O9cOSXDVspSykEfOF3TwNtbjOhPuFUOyw=
aarch64-darwin	sha256-J7Z1CAZXy5+VNdYGusQgg1Pw1XZjAPdgpkdcVNSnghA=

Both sides have 88 .bin/ entries (matching byte-for-byte); the remaining differences are only genuine native-binary packages (@esbuild/*, @rollup/rollup-*, @tailwindcss/oxide-*, @tauri-apps/cli-*, lightningcss-*). Re-running the orchestrator on the same tree does not change the hash.

Because bun still downloads only the host-matching native binary set, the nixpkgs side stores one hash per system (linux + darwin) rather than a single cross-platform hash. That part lives in philocalyst/nixpkgs#1.

Related Issues/Discussions

Required by NixOS/nixpkgs#507754
Needed by philocalyst/nixpkgs#1
Upstream reference: oven-sh/bun#28147

Testing

• Scripts are only used during Nix builds; no impact on regular development
• Verified on Linux (local NixOS) and macOS (GitHub Actions): reproducible, idempotent, hashes stable
• Each sub-script is standalone-runnable for debugging

AI Assistance

• No AI was used in this PR
• AI was used (please describe below)

If AI was used:

• Tools used: Claude Code
• How extensively: AI helped write and debug the scripts; the approach (healing circular peer-dep bins and canonicalizing symlink order) and the cross-platform verification methodology were designed and validated interactively.

[y0usaf]

Tried these locally against Handy's current Bun install and found two spots where the scripts seem to change the install tree, rather than just normalize its ordering.

[y0usaf]

I think this goes a bit further than normalization. This loop doesn't preserve the targets Bun picked; it re-selects them by highest semver / string order. When I tried it against Handy's current bun.lock, it rewired entries under node_modules/.bun/node_modules like minimatch (3.1.2 -> 9.0.5) and brace-expansion (1.1.12 -> 2.0.2). Since that directory is still on the upward resolution path, that can change what actually gets resolved at runtime. Could we make the link creation deterministic without changing which target each slug points to?

[xilec]

Confirmed — reproduces exactly on a fresh bun install --linker=isolated (minimatch 3.1.2 → 9.0.5, brace-expansion 1.1.12 → 2.0.2). Fixed in 4236f7b: the script now reads the existing symlinks in .bun/node_modules/, removes them, and recreates them in sorted order with bun's exact targets — no re-selection.

[y0usaf]

I think this is skipping most packages in an isolated Bun install. isDirectory() uses lstat, so symlinked package dirs don't count as directories here, and collectPackages() only walks the small set of real directories. On a fresh install of Handy's current lockfile, running this took the nested .bin links from 86 down to 27 and dropped entries like vite, parser, tsc, and eslint. Was the intent to follow package symlinks here as well?

[xilec]

Confirmed — reproduced 86 → 27 on the current lockfile (losing vite, eslint, tsc, parser etc.). Fixed in 4236f7b by a simpler primitive: instead of re-deriving bins from package manifests, the script now reads the existing .bin/ symlinks bun produced and recreates them in sorted order with the same targets. This also avoids the side-effect of adding .bin/ entries bun deliberately omits for peer deps.

[xilec]

@kakapt could you take a look when you have a moment?

@philocalyst could you verify the scripts produce the same hash on macOS? On Linux (x86_64, bun 1.3.3) I get:

bun install --linker=isolated --force --frozen-lockfile --ignore-scripts --no-progress --cpu="*" --os="*"
bun --bun .nix/scripts/canonicalize-node-modules.ts
bun --bun .nix/scripts/normalize-bun-binaries.ts
nix hash path node_modules
# sha256-gREugUONMaECdqeEgLqzn6P/JNIq7zfUtRhclXhqdZc=

If a fresh run on your mac yields a different hash, that tells us bun still picks different targets across platforms and we need a stronger normalization step.

[philocalyst]

I got sha256-H54AsWPGku8qHx1OvkhD6fWFRU4QcRAnTbHa+gFWi18= ... @xilec

bun install v1.3.11 (af24e281)

+ @playwright/test@1.58.0
+ @tauri-apps/cli@2.10.0
+ @types/node@24.9.1
+ @types/react@18.3.26
+ @types/react-dom@18.3.7
+ @types/react-select@5.0.1
+ @typescript-eslint/eslint-plugin@8.49.0
+ @typescript-eslint/parser@8.49.0
+ @vitejs/plugin-react@4.7.0
+ eslint@9.39.1
+ eslint-plugin-i18next@6.1.3
+ prettier@3.6.2
+ typescript@5.6.3
+ vite@6.4.1
+ @tailwindcss/vite@4.1.16
+ @tauri-apps/api@2.10.1
+ @tauri-apps/plugin-autostart@2.5.1
+ @tauri-apps/plugin-clipboard-manager@2.3.2
+ @tauri-apps/plugin-dialog@2.6.0
+ @tauri-apps/plugin-fs@2.4.4
+ @tauri-apps/plugin-global-shortcut@2.3.1
+ @tauri-apps/plugin-opener@2.5.2
+ @tauri-apps/plugin-os@2.3.2
+ @tauri-apps/plugin-process@2.3.1
+ @tauri-apps/plugin-sql@2.3.1
+ @tauri-apps/plugin-store@2.4.1
+ @tauri-apps/plugin-updater@2.10.0
+ i18next@25.7.2
+ immer@11.1.3
+ lucide-react@0.542.0
+ react@18.3.1
+ react-dom@18.3.1
+ react-i18next@16.4.1
+ react-select@5.10.2
+ sonner@2.0.7
+ tailwindcss@4.1.16
+ tauri-plugin-macos-permissions-api@2.3.0
+ zod@3.25.76
+ zustand@5.0.8

658 packages installed [641.00ms]
[canonicalize-node-modules] rebuilt 320 links
[normalize-bun-binaries] rebuilt 87 links

[xilec]

Update: pushed a new revision that adds a third normalization pass — heal-peer-dep-bins.ts — and a single orchestrator entry point (normalize-install.ts).

The two original scripts canonicalized symlink order, but it turned out Bun's isolated installer can also produce a different .bin/ set across machines. Cause is a timing race in how it links .bin/<peer> entries for circular peer-dependency pairs (e.g. browserslist ↔ update-browserslist-db, eslint ↔ eslint-utils) — whichever side finishes last silently drops some entries. See the header of .nix/scripts/heal-peer-dep-bins.ts for the full write-up, and oven-sh/bun#28147 for the closest upstream tracker. The new pass heals the set by reading peerDependencies and adding back the intended entries — idempotent, and becomes a no-op if bun ever fixes the race.

Verified on bun 1.3.11 via a GH Actions matrix:

• x86_64-linux: sha256-DMhAdAzgh0O9cOSXDVspSykEfOF3TwNtbjOhPuFUOyw=
• aarch64-darwin: sha256-J7Z1CAZXy5+VNdYGusQgg1Pw1XZjAPdgpkdcVNSnghA=

Both sides now have 88 .bin/ entries matching byte-for-byte; remaining diffs are only genuine native-binary packages (@esbuild/*, @rollup/rollup-*, @tailwindcss/oxide-*, @tauri-apps/cli-*, lightningcss-*). This is the reason philocalyst/nixpkgs#1 stores one hash per system rather than a single universal hash.

@philocalyst — this should match the hash you'll get if you run bun --bun .nix/scripts/normalize-install.ts after bun install --linker=isolated on aarch64-darwin. The previous 87-entry output you saw lines up with one .bin/browserslist that the race was dropping.

@y0usaf — if you have a minute, another pass would be appreciated. The two issues you originally flagged are addressed in 4236f7b (the scripts now read and preserve bun's chosen targets instead of re-deriving them), and the new commit on top adds the heal pass for the cross-platform race we later found. Would be good to confirm the three-pass flow looks sensible end-to-end.

@kakapt — would appreciate another look when you have a moment.

[y0usaf]

Re-checked after 4236f7b — both prior issues fixed, heal pass for the peer-dep race looks correct, three-pass ordering makes sense. LGTM.

[xilec]

Hi @cjpais — quick status update:

• Scripts verified: although these scripts aren't exercised by Handy's own CI, I validated them separately in my fork via custom GitHub Actions workflows on both Ubuntu and macOS runners — all green.
• Review: approved by @y0usaf.

From my side the PR is ready to merge whenever you have a moment.

[cjpais]

Okay thanks for confirmation and update merging