fix(drivers): resolve warehouse SDKs from disk instead of reporting them missing
Issue for this PR
Closes #671
Closes #295
Closes #1075
Closes #61
Closes #769
Closes #764
Closes #713
Closes #670
Closes #659
Type of change
- Bug fix
- New feature
- Refactor / code improvement
- Documentation
What does this PR do?
The bug. A bare import("snowflake-sdk") inside the compiled Bun binary resolves against bunfs, which has no node_modules. An SDK the user had already installed was therefore invisible to the runtime, which reported it as “not installed.” That one root cause sits under all nine issues above.
Why it works. packages/drivers/src/resolve.ts routes all twelve drivers through a shared resolver. loadOptionalDriver() tries the ambient resolver first, then searches intended on-disk roots: the managed install directory, ALTIMATE_BIN_DIR, operator-explicit NODE_PATH, the executable tree, and the installed drivers package tree. It imports the resolved absolute entry instead of a bare specifier, which works outside bunfs.
Project and ancestor node_modules directories are deliberately not implicit roots. A workspace-controlled SDK is executable content and can receive resolved warehouse configuration. Users can instead use the consent-gated managed installer or choose an explicit NODE_PATH.
Supporting changes:
- Durable install location. On-demand installs go to
<XDG_DATA>/altimate-code/drivers;~/.altimate/binis rebuilt by the curl installer during self-upgrade. - Consent-gated installer. The model-facing
warehouse_install_drivertool requests external-directory and exact npm-command approval before it creates, repairs, or installs anything. An already-usable driver remains a no-op; a resolvable but unloadable driver passes both approvals before forced repair. - Atomic readiness and repair. Installs are serialized per target directory and recheck readiness inside the queue. A timed-out npm operation settles only after bounded process-tree teardown; Windows verifies only a successful
taskkill. - Honest failures. A present package that throws on import is reported as broken rather than missing. Target-directory verification prevents an ambient copy from turning npm success into a false positive.
- Secure ClickHouse intent.
tls,ssl, or HTTPS protocol intent defaults tohttps://on port 8443 and conflicting plaintext configuration fails before client creation. Explicit ports must be integers from 1 through 65535; invalid values fail closed rather than silently selecting a default endpoint. - Catalogue alignment. MongoDB is now included in binary externals and published optional peer metadata.
driver-catalogue.test.tspins every declaration site toDRIVER_PACKAGES.
build.ts’s autoloadPackageJson: true remains load-bearing: it lets a compiled binary resolve external packages from disk.
How was this verified?
The original implementation was exercised in the environment where the bug occurs: a production-style compiled binary, an empty cwd, no NODE_PATH, and a real isolated pg install.
bare import("pg") : FAILED: Cannot find package 'pg' from '/$bunfs/root/probe.js'
loadOptionalDriver : OK, keys=Client,Connection,DatabaseError,Pool,Query
The final local head passed:
| Check | Result |
|---|---|
Full packages/drivers suite | 222 pass, 0 fail |
| Resolver unit suite | 66 pass, 0 fail |
| ClickHouse unit suite | 72 pass, 0 fail |
| Installer permission suite | 5 pass, 0 fail |
| Driver catalogue consistency | 7 pass, 0 fail |
| Release-preflight unit suite | 41 pass, 0 fail |
bun turbo typecheck | 13/13 packages |
| Opencode pre-release build + binary smoke | pass |
Upstream marker guard and git diff --check | pass |
| Codex Security full scan + late-delta addendum | complete; late delta has 0 reportable findings |
The original driver Docker and real Snowflake e2e results remain documented in the commit history. Native Windows execution was not performed locally; Windows quoting, taskkill outcomes, async spawn errors, and timeout behavior have focused unit coverage and CI is rerunning on this head.
Review follow-up
The original three-member consensus review accepted the teardown, serialization, trust-root, permission, and transport fixes. A second full three-round Council review of the late delta voted ship-delta unanimously, weighted 3.5/3.5, with high confidence and no dealbreakers. Every current review thread has a tested fix and has been replied to and resolved.
Screenshots / recordings
Not a UI change.
Checklist
- I have tested my changes locally
- I have not included unrelated changes in this PR
Risk: ambient imports and intended managed/operator roots keep their existing precedence. The intentional compatibility change is that project-only SDK copies are no longer executed implicitly; the managed installer or explicit NODE_PATH is the supported alternative. Conflicting ClickHouse secure/plaintext configuration and invalid explicit ports now fail closed.
🤖 Generated with Claude Code