Fix first-run setup failing with ENOENT on the Grail stamp

[jgfoster]

A user's first install died immediately after creating the database:

Setting up GemDB failed: ENOENT: no such file or directory,
open '/Users/…/GemDB/grail/.gemdb-grail-stamp'

prepareFiles recorded Grail as filed into the database before anything created <rootPath>/grail for that record to live in. Python support was then never staged, and every retry failed identically — a permanent first-run failure.

Note what is missing from their log: no Staging Grail … line between Database created and the error. That is the tell.

The same misordering broke upgrades, more quietly

Where <rootPath>/grail did exist, the stamp was written into the previous version's directory. grailNeedsUpdate then compared the bundled stamp against the bundled stamp, found them equal, and skipped staging. So:

• a new version's Grail payload never reached disk, while wearing the new version's label;
• writeCliScripts never re-ran, leaving bin/gemdb at its old contents.

It could not have worked in either order, in fact: stageGrail replaces the directory wholesale, so it deletes the stamp it was just handed.

Why it reached a release

Neither failure reproduces on a machine that has already run an earlier version — the directory is simply there. And the integration suite calls stageGrail itself against a fixture, so it never goes through prepare at all. The gap was a first-run path with no test that could reach it.

The fix

The order now lives in one named place with the reasons attached:

export function stageAndRecordGrail(extensionPath: string, fromPreloadedExtent: boolean): void {
  if (grailNeedsUpdate(extensionPath)) stageGrail(extensionPath);
  if (fromPreloadedExtent) recordGrailInstalled(extensionPath);
}

The condition moved too, and it matters as much as the order. createDatabase now returns {created, preloaded}, so the stamp follows this call having made the database from the shipped extent rather than "the extension ships an extent". An upgrade finds a database carrying whatever Grail was filed into it before; stamping there would claim an install that never happened. Leaving it unstamped is exactly what sends ensureRunning to file the new Grail in.

Tests

src/__tests__/grailStaging.test.ts starts from a root path that does not exist — the condition the existing tests could not express. Reverting to the old order fails two of its five cases, one reproducing the reported error verbatim:

AssertionError: expected [Function] to not throw an error but
'Error: ENOENT: no such file or directory, open '…/GemDB/grail/.gemdb-grail-stamp''

database.test.ts pins the new return value, including that a second call creates nothing.

114 unit tests (was 109), 46 integration. Lint, format, both typechecks clean.

For the affected user

Deleting ~/GemDB/db (or the whole ~/GemDB) and reloading gives the fast path: the database is recreated from the shipped extent and stamped, no file-in. Without that, the fix still recovers them — Grail stages, and because the database already exists it is correctly left unstamped, so the first Python they run files it in, which takes a few minutes once.

🤖 Generated with Claude Code