Stale-cache bug class is only half-mitigated: ~/.fhir/packages is never invalidated, and clearBunCache misses the global bun cache

[quotentiroler]

installCommand.ts already documents this bug class and works around it for one case:

// Bun caches extracted tgz content keyed by file path, not content hash.
// When the tgz is regenerated at the same path, bun serves stale content.
// Workaround: nuke the .bun cache entry so bun is forced to re-extract.
// See: https://github.com/oven-sh/bun/issues/29372
clearBunCache(packageName);

The same mistake — cache keyed by identity rather than content — appears in two more places that aren't covered.

1. ~/.fhir/packages/<name>@<version> is reused even when the source tgz changed

babelfhir-ts install ./my-ig-0.1.0.tgz extracts to ~/.fhir/packages/my-ig@0.1.0 and reuses that directory on later runs. Since an IG's version only changes at release, every local rebuild during development regenerates from whatever FSH was compiled the first time that version was built. No warning; the run reports success.

Reproduced 2026-08-02 with maxhealth.consent@0.1.0:

1. Built the IG, added a CodeSystem + ValueSet to the FSH.
2. Re-ran the build at the same version → generated package had no valuesets/ directory. Output was from the pre-change FSH.
3. rm -rf ~/.fhir/packages/maxhealth.consent@0.1.0 → rebuild → valuesets/ appears.

Only caught because the expected directory was missing. A subtler change (an added code, a tightened cardinality) would have shipped silently as stale types. CI is unaffected — hosted runners are cold — so this bites exactly the person iterating on an IG, and it looks like their FSH edit "did nothing".

Both consumers have had to work around it by hand:

// fhir/build.mjs (proxy-smart)
rmSync(join(homedir(), ".fhir", "packages", `${PKG_NAME}@${PKG_VERSION}`), { recursive: true, force: true });

Suggested fix: hash the input tarball and store it alongside the extraction; re-extract when it differs. Or extract to a content-addressed directory. A --no-cache flag would be a usable stopgap.

2. clearBunCache misses the global bun cache

It clears node_modules/.bun/<pkg>@… and node_modules/<pkg>/, but not ~/.bun/install/cache/<scope>/<pkg>@<version>@@<registry>@@@1.

Under linker = "isolated", node_modules/.bun/** are hardlinks into the global cache. So clearing only the project-local entries can leave the authoritative copy stale, and the next install re-links the stale content back in. Observed exactly that:

rm -rf node_modules/.bun/@scope+pkg*
bun install          # "2 packages installed" — restored the STALE copy
rm -rf ~/.bun/install/cache/@scope/pkg*
bun install          # correct content

The hardlinking also means anything writing into node_modules in place silently rewrites the global cache for every project on the machine — worth a warning in the docs even if it's out of scope to fix here.

3. Minor: install --skip-install is overloaded

install refers to installing a FHIR IG; --skip-install refers to skipping the npm install step. Two senses of the word in one invocation, and the flag reads as a contradiction. Not urgent, but --no-link / --pack-only / --generate-only would say what it does.

Context

Verified on 1.5.21. Downstream: Max-Health-Inc/proxy-smart fhir/build.mjs and .github/workflows/publish-ig.yml, both of which now carry manual rm -rf workarounds for (1). Related: Max-Health-Inc/proxy-smart#895.

[quotentiroler]

A third site in this bug class, found while working on #143.

The site

generateIntoPackage stages the generated manifest at the extraction root so createPackageFromDir puts it at the tarball root, then leaves it behind:

// Copy package.json to root of extractedRoot so it's at the tarball root
const rootPackageJsonPath = path.join(extractedRoot, 'package.json');
fs.copyFileSync(generatedPackageJsonPath, rootPackageJsonPath);

extractedRoot is the shared cache entry whenever the package was already cached. shouldCleanup = !extractResult.isCached (index.ts:492) deletes temp extractions only, so for a cached package the run writes its own output into ~/.fhir/packages and never takes it back.

Why it stayed invisible

The impact splits on cache layout. Of 171 entries in my cache, 168 have a package/ subdir: the write lands beside the real manifest, and every reader prefers package/package.json (packageParser.ts:802-810), so nothing observes it. Three entries are flat, and all three are locally built IGs installed from a tgz. For those, the IG's own manifest sits at exactly that path.

The failure

The next run falls back to the generated manifest, reads "@types/fhir": ">=0.0.44 <0.1.0" as a FHIR package spec, and builds <cache>/@types/fhir->=0.0.44 <0.1.0.tgz (packageParser.ts:593). That path is unwritable. The stream error fires after the await, so the per-registry catch never sees it and it escapes as an unhandled rejection that kills the process. The first run of a command succeeds and the second one dies, which makes it read like flakiness rather than contamination.

Evidence

Four registry entries were already carrying a stray generated manifest from runs predating this work: hl7.fhir.us.carin-bb@2.2.0, hl7.fhir.uv.smart-app-launch@2.2.0, ihe.iti.pixm@3.1.0, kbv.ita.erp@1.4.4. maxhealth.consent@0.1.0 was the flat casualty.

Worth recording for that one: it never had a root manifest at all. SUSHI writes none into fsh-generated/package, and fhir/build.mjs tars exactly that directory, so the correct repair was deleting the invented file rather than reconstructing one.

Interaction with the workaround already described here

fhir/build.mjs:92-93 removes the whole cache entry before every build as the workaround for item 1. That also happens to mask this: a fresh extract discards the clobbered manifest. Anyone who drops that workaround once item 1 is fixed will start hitting this instead, so the two want to land together.

On the --no-cache stopgap suggested above

The flag name is already taken. main.ts:54 documents --no-cache as deleting the .cache working folder and states explicitly that it does not affect ~/.fhir/packages. A stopgap would need a different name, which argues for going straight to the tarball-hash invalidation.

Fixed in 290f3ee

• restore the extraction root's manifest after the repack, inside a finally
• skip dependency specs that are not FHIR packages (npm scope or semver range) rather than crashing on the cache path built from them

Both are mutation checked: disabling either turns the new tests red.

Still open on this issue

Item 1 (content-based invalidation of ~/.fhir/packages) and item 2 (clearBunCache missing the global bun cache) are untouched by the above.