fix(service-datasource): the mongodb and sqlite-wasm arms tell you how to install the optional driver they are missing (#7385)

[os-help]

Fixes #7385

All three of sqlite-wasm, mongodb and turso are built from OPTIONAL packages in the same factory, so all three have to answer "the package is not here". After #7314 / PR #7384 fixed the libSQL arm, the other two still answered with the fault and nothing else:

sqlite-wasm driver requested but @objectstack/driver-sqlite-wasm is not installed (…).
mongodb driver requested but @objectstack/driver-mongodb is not installed (…).

No install command, no statement of what happens next, and not even the name of the datasource that failed — while the turso arm one screen below stated all three. One class of problem, two qualities of answer, decided by nothing but which driver the admin picked in Setup.

What landed

A shared missingDriverPackageMessage(driver, args) builder over a small OptionalDriverPackage descriptor, plus per-driver wrappers and the same constant seam #7384 introduced for libSQL:

• SQLITE_WASM_DRIVER_PACKAGE / SQLITE_WASM_DRIVER_INSTALL_COMMAND / missingSqliteWasmDriverMessage
• MONGODB_DRIVER_PACKAGE / MONGODB_DRIVER_INSTALL_COMMAND / missingMongodbDriverMessage

all re-exported from the package index, so a host that renders its own remedy reads one declaration instead of re-typing a command.

#7384's two discipline points are kept verbatim, because each was a fix for a measured failure rather than a style choice. The message names the datasource (several may be declared and only one of them is this engine). It names exactly one fix and no escape hatch — no OS_ALLOW_DRIVER_CONNECT_FAILURE (it would only hide a package that does not exist) and no OS_DATABASE_URL / --database (they select the HOST's default datasource and can do nothing for the one that failed), which is the connect-failure-remedy.ts failure of #5794. And the import error is interpolated at the end and in full, which is what keeps isUnbuiltWorkspaceFailure able to recognise a half-built checkout from these arms at all — the re-throw drops the original code, so only that text survives.

The consequence sentence is per-engine, not copied

#7384 wrote its consequence around a REMOTE database being shadowed by a local one. That is true for mongo and false for sqlite-wasm, which opens a local file and has no remote to shadow — so copying the prose would have produced a remedy that reads well and lies.

• mongodb — "a silent fallback would open a local database that accepts writes while the MongoDB server this datasource points at stays untouched, and every write would land in the wrong database." Same substance as libSQL, because mongo is likewise a server this process connects to.
• sqlite-wasm — "stepping down to the in-process memory driver would accept every write and drop it at shutdown, leaving the file this datasource names empty, and stepping down to the native better-sqlite3 build would need exactly the native addon a WASM datasource is chosen to avoid." Its own two real costs: durability (datasource-autoconnect 的联邦查询测试在本地必现失败：ext_note 读到 6～12 行而非 2 行（CI 绿，需第二台机器复核） #4083) and the native addon this driver id exists to avoid.

A test asserts the sqlite-wasm text does not contain wrong database / stays untouched, so the libSQL prose cannot be copied back onto it later.

Optionality, measured (the card asked)

Neither package is a runtime dependency of @objectstack/service-datasource — both are devDependencies only, which is how the construction suites build real drivers. So from this package's own manifest both arms' missing-package path is reachable, and the messages' "It is an OPTIONAL package" is true.

Reachability differs per package once a host is in the picture, and the doc comments say so rather than overclaiming:

package	@objectstack/runtime	@objectstack/cli	reachable when
@objectstack/driver-turso	not a dep	optional peer	genuinely absent (the #7384 case)
@objectstack/driver-mongodb	optionalDependencies	dependencies	--omit=optional, or a direct install of this service
@objectstack/driver-sqlite-wasm	dependencies	dependencies	a direct install of this service, or a half-built workspace

For a CLI or runtime host, sqlite-wasm's common real cause is therefore an unbuilt workspace, not an uninstalled package — which is exactly why the verbatim import error matters: isUnbuiltWorkspaceFailure reads it downstream and re-routes the remedy to pnpm install && pnpm build instead of telling a contributor to install what they already have. A test pins that classification for both arms.

Tests

20 new cases: #7384's 7-case content-pinned pattern mirrored per arm, plus a parity block asserting all three optional arms now answer in one shape (toThrow() alone would have stayed green through the whole defect). Because both packages resolve inside this workspace, the arm-level case cannot simply ask for the driver and watch it fail the way the turso one does — it stages the absence with vi.doMock + vi.resetModules, undone in finally so the real construction suites are untouched.

One fixture outside the factory's own test file was re-spelled: datasource-connection-service.test.ts's "the factory-wrapped optional-driver form" case hand-spelled the pre-#7385 sentence, so it would have gone on pinning a shape the factory can no longer emit. It now builds its input from missingSqliteWasmDriverMessage itself. The property under test is unchanged. That is a one-fixture extension beyond the dispatched file surface, flagged here deliberately.

Reverse verification, two stages, both partial-red and explained:

1. Arms reverted to the pre-fix inline throws, builders kept — exactly the 2 arm-level cases go red (expected 'sqlite-wasm driver requested but @obj…' to contain 'npm install @objectstack/driver-sqlit…'), 292 of 294 green. That is the honest shape: the content pins test the exported builders, and the arm-level case is the only thing binding those builders to the arms.
2. Builders reverted to the old wording — 15 of the 20 new cases go red. The 5 that survive are informative rather than a gap: "names the package that is missing" (the old sentence named it too) and the three unbuilt-workspace classification pins (the old sentence also interpolated the import error). Those five are regression guards for properties the old text already had, not detectors of what it lacked.

Not touched, per the card: the turso arm and missingTursoDriverMessage (merged hours earlier, its wording pinned by #7384's own tests), and #7243's datasource.pool surfaces. Converging turso onto the shared builder is left as a provably inert one-liner for whoever wants it — the parity test is what makes it provable.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 10:40am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 1 changed package(s). ✅