Skip to content

Commit a698abc

Browse files
sahrizviclaude
andcommitted
fix(drivers): address PR bot review — transitive deps, load probe, telemetry, quoting
CodeRabbit and cubic-dev-ai findings on #1122. Each verified before fixing. **A missing transitive dependency read as a missing driver.** `isModuleNotFound` matched any "Cannot find module/package" text, but a driver whose own dependency tree is incomplete raises exactly that shape — observed for real inside a compiled binary as `Cannot find package 'pg-protocol' from '.../pg/lib/ connection.js'`, where pg itself is installed. The predicate now takes the specifier and, when the runtime names the module it could not find, only counts a name matching what was asked for. Without a specifier it stays conservative. **A broken install could not be repaired.** `warehouse_install_driver` gated on `isDriverInstalled`, which only asks whether the package resolves. A copy that resolves but throws on import — a native addon for another platform, or a half-written install — answered "already installed", so the one command that could fix it declined to run. It now probes an actual load. **Failed installs were recorded as successes.** `Tool` reads `metadata.success === false` as its soft-failure signal (tool/tool.ts), and every sibling warehouse tool sets it. This tool omitted it, so a failed install skipped failure telemetry entirely. **Install hints broke on paths containing spaces.** The printed `npm install --prefix <dir>` is meant to be pasted; an unquoted path split and npm received the wrong prefix. Added `shellQuote` and applied it at both sites. **Two test-quality fixes.** CodeRabbit and cubic independently flagged that "does not fall back when an ambiently-resolvable package fails to load" never reaches the branch it names — its fixture is not ambiently resolvable, so the disk fallback handles it first. Renamed to what it actually proves, with the ambient branch now pinned directly through `isModuleNotFound`. Separately, a comment claimed the catalogue test kept the tool's `DRIVER_NAMES` and alias map in step with `DRIVER_PACKAGES`; no such test existed. It does now, and it also asserts every `DRIVER_MAP` type resolves to an installable driver — removing the alias map fails it, which is the #61 gap this PR set out to close. Tests: 177 drivers unit (was 172), 4,714 opencode. Typecheck clean, 0 lint errors. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 9589cc2 commit a698abc

5 files changed

Lines changed: 148 additions & 15 deletions

File tree

‎packages/drivers/src/resolve.ts‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@ import { createRequire } from "node:module"
2525
import { pathToFileURL } from "node:url"
2626
import { spawn } from "node:child_process"
2727

28+
/** Quote a path for inclusion in a copy-pasteable shell command. */
29+
export function shellQuote(value: string): string {
30+
return /^[A-Za-z0-9_./@:-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`
31+
}
32+
2833
/** Every driver in this package and the npm packages it needs at runtime. */
2934
export const DRIVER_PACKAGES = {
3035
postgres: ["pg"],
@@ -80,7 +85,7 @@ export class DriverNotInstalledError extends Error {
8085
super(
8186
`${label} driver not installed.\n` +
8287
`Install it with the warehouse_install_driver tool, or run:\n` +
83-
` npm install --prefix ${driverInstallDir()} ${packages.join(" ")}\n` +
88+
` npm install --prefix ${shellQuote(driverInstallDir())} ${packages.join(" ")}\n` +
8489
`Searched ${searched.length} location${searched.length === 1 ? "" : "s"}: ${searched.join(", ")}`,
8590
)
8691
this.name = "DriverNotInstalledError"
@@ -290,7 +295,7 @@ export async function loadOptionalDriver(driver: DriverName, specifier: string):
290295
// Only a resolution failure means "look elsewhere". A package that resolves
291296
// ambiently but throws while loading is a broken install, and re-reporting
292297
// it as missing would send the user to install what they already have.
293-
if (!isModuleNotFound(ambientError)) throw loadFailure(driver, specifier, ambientError)
298+
if (!isModuleNotFound(ambientError, specifier)) throw loadFailure(driver, specifier, ambientError)
294299

295300
const roots = driverSearchRoots()
296301
const resolved = resolveOptionalPackage(specifier, roots)
@@ -306,11 +311,27 @@ export async function loadOptionalDriver(driver: DriverName, specifier: string):
306311
}
307312
}
308313

309-
/** True when `error` means the module could not be resolved, not that it failed while loading. */
310-
export function isModuleNotFound(error: unknown): boolean {
314+
/**
315+
* True when `error` means **`specifier` itself** could not be resolved.
316+
*
317+
* A package that loads but whose own dependency tree is incomplete raises the
318+
* same error shape — `Cannot find package 'pg-protocol' from '…/pg/lib/
319+
* connection.js'` — for a driver that is very much installed. Treating that as
320+
* "not installed" sends the user to reinstall something already present. So
321+
* when the runtime names the module it could not find, only a name matching
322+
* what we asked for counts as missing.
323+
*/
324+
export function isModuleNotFound(error: unknown, specifier?: string): boolean {
325+
const message = error instanceof Error ? error.message : String(error)
326+
const named = /Cannot find (?:module|package)\s+['"]([^'"]+)['"]/i.exec(message)
327+
328+
if (named && specifier) {
329+
const missing = named[1]!
330+
return missing === specifier || missing === packageNameOf(specifier)
331+
}
332+
311333
const code = (error as { code?: string } | null)?.code
312334
if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") return true
313-
const message = error instanceof Error ? error.message : String(error)
314335
return /Cannot find (module|package)/i.test(message)
315336
}
316337

@@ -333,7 +354,7 @@ export async function loadOptionalPackage(specifier: string): Promise<any | unde
333354
try {
334355
return await import(/* @vite-ignore */ specifier)
335356
} catch (ambientError) {
336-
if (!isModuleNotFound(ambientError)) throw ambientError
357+
if (!isModuleNotFound(ambientError, specifier)) throw ambientError
337358
const resolved = resolveOptionalPackage(specifier)
338359
if (!resolved) return undefined
339360
return await import(/* @vite-ignore */ pathToFileURL(resolved).href)

‎packages/drivers/test/resolve-unit.test.ts‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
DRIVER_PACKAGES,
1919
isModuleNotFound,
2020
npmInstallArgs,
21+
shellQuote,
2122
DriverNotInstalledError,
2223
driverInstallDir,
2324
driverLabel,
@@ -229,9 +230,10 @@ describe("loadOptionalDriver", () => {
229230
expect(err.message).toContain("Searched")
230231
})
231232

232-
test("does not fall back when an ambiently-resolvable package fails to load", async () => {
233-
// A package that resolves but throws on import is broken, not absent.
234-
// Reporting it as "not installed" sends the user to install what they have.
233+
test("reports a disk-resolved package that throws on import as a load failure", async () => {
234+
// Named for what it actually exercises: the fixture is not ambiently
235+
// resolvable, so this covers the on-disk load path, not the ambient rethrow.
236+
// The ambient branch is pinned directly in the isModuleNotFound tests below.
235237
const broken = path.join(tmpRoot, "ambient")
236238
installFakePackage(broken, "altimate-ambient-broken", "throw new Error('boom')")
237239
process.env["ALTIMATE_DRIVER_DIR"] = broken
@@ -350,6 +352,26 @@ describe("isModuleNotFound", () => {
350352
expect(isModuleNotFound(new Error("Cannot find module 'mysql2/promise'"))).toBe(true)
351353
})
352354

355+
test("a missing transitive dependency is NOT the driver going missing", () => {
356+
// Observed for real when importing pg's entry inside a compiled binary:
357+
// `Cannot find package 'pg-protocol' from '.../pg/lib/connection.js'`.
358+
// pg is installed; its dependency tree is incomplete. Classifying that as
359+
// "not installed" sends the user to reinstall what they already have.
360+
const transitive = new Error("Cannot find package 'pg-protocol' from '/x/node_modules/pg/lib/connection.js'")
361+
362+
expect(isModuleNotFound(transitive, "pg")).toBe(false)
363+
// Same error with no specifier context stays conservative.
364+
expect(isModuleNotFound(transitive)).toBe(true)
365+
})
366+
367+
test("the driver's own absence still counts as missing", () => {
368+
const own = new Error("Cannot find package 'pg' from '/$bunfs/root/index.js'")
369+
370+
expect(isModuleNotFound(own, "pg")).toBe(true)
371+
// Subpath specifiers resolve against their package name.
372+
expect(isModuleNotFound(new Error("Cannot find module 'mysql2'"), "mysql2/promise")).toBe(true)
373+
})
374+
353375
test("does NOT classify a load-time failure as missing", () => {
354376
// The distinction that matters: a package that resolves but throws while
355377
// initialising (broken native binding) must not be reported as absent.
@@ -403,3 +425,21 @@ describe("half-installed packages", () => {
403425
expect(resolved!.includes(path.join("good", "node_modules"))).toBe(true)
404426
})
405427
})
428+
429+
describe("shellQuote", () => {
430+
test("leaves ordinary paths alone", () => {
431+
expect(shellQuote("/Users/x/.local/share/altimate-code/drivers")).toBe(
432+
"/Users/x/.local/share/altimate-code/drivers",
433+
)
434+
})
435+
436+
test("quotes a path with spaces so the printed command is copy-pasteable", () => {
437+
// The install hint is meant to be pasted; an unquoted path with spaces
438+
// splits and npm receives the wrong --prefix.
439+
expect(shellQuote("/Users/x/My Drive/drivers")).toBe("'/Users/x/My Drive/drivers'")
440+
})
441+
442+
test("escapes embedded single quotes", () => {
443+
expect(shellQuote("/tmp/it's here")).toBe(`'/tmp/it'\\''s here'`)
444+
})
445+
})

‎packages/opencode/src/altimate/tools/warehouse-add.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { PostConnectSuggestions } from "./post-connect-suggestions"
66
import { Telemetry } from "../../telemetry"
77
// altimate_change end
88
// altimate_change start — report driver readiness when adding a warehouse
9+
import { shellQuote } from "@altimateai/drivers/resolve"
910
import {
1011
driverForWarehouseType,
1112
driverInstallDir,
@@ -166,7 +167,7 @@ function driverReadinessNote(type: string): string {
166167
return (
167168
`\n\nNOTE: the ${driverLabel(driver)} driver is not installed yet, so this connection cannot be used until it is.\n` +
168169
`Run the warehouse_install_driver tool with driver="${driver}", or install it manually:\n` +
169-
` npm install --prefix ${driverInstallDir()} ${packages}`
170+
` npm install --prefix ${shellQuote(driverInstallDir())} ${packages}`
170171
)
171172
} catch {
172173
// A driver probe must never fail an add whose configuration was stored.

‎packages/opencode/src/altimate/tools/warehouse-install-driver.ts‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import z from "zod"
22
import { Tool } from "../../tool/tool"
33
import {
44
DRIVER_PACKAGES,
5+
loadOptionalDriver,
56
driverInstallDir,
67
driverLabel,
78
installOptionalDriver,
@@ -10,7 +11,8 @@ import {
1011
} from "@altimateai/drivers/resolve"
1112

1213
// Listed literally rather than derived from DRIVER_PACKAGES so zod infers a
13-
// concrete union; the catalogue test in packages/drivers keeps the two in step.
14+
// concrete literal union. driver-catalogue.test.ts pins this list, and the alias
15+
// map below, against DRIVER_PACKAGES and the registry's DRIVER_MAP.
1416
const DRIVER_NAMES = [
1517
"postgres",
1618
"redshift",
@@ -33,6 +35,8 @@ const DRIVER_NAMES = [
3335
*/
3436
interface InstallDriverMetadata {
3537
[key: string]: any
38+
/** Read by Tool as the soft-failure signal (tool/tool.ts). */
39+
success: boolean
3640
driver: DriverName
3741
installed: boolean
3842
alreadyPresent: boolean
@@ -61,11 +65,15 @@ export const WarehouseInstallDriverTool = Tool.define("warehouse_install_driver"
6165
const label = driverLabel(driver)
6266
const dir = driverInstallDir()
6367

64-
if (isDriverInstalled(driver)) {
68+
// Resolution is not usability. A package that resolves but throws on import —
69+
// a native addon built for another platform, or a half-written copy — used to
70+
// report "already installed", so the one command that could repair it refused
71+
// to run. Probe an actual load and only decline when it succeeds.
72+
if (isDriverInstalled(driver) && (await driverLoads(driver))) {
6573
return {
6674
title: `${label} driver: already installed`,
67-
metadata: { driver, installed: true, alreadyPresent: true, dir },
68-
output: `The ${label} driver is already installed and resolvable. No action taken.`,
75+
metadata: { success: true, driver, installed: true, alreadyPresent: true, dir },
76+
output: `The ${label} driver is already installed and loads correctly. No action taken.`,
6977
}
7078
}
7179

@@ -76,6 +84,7 @@ export const WarehouseInstallDriverTool = Tool.define("warehouse_install_driver"
7684
return {
7785
title: `${label} driver: install FAILED`,
7886
metadata: {
87+
success: false,
7988
driver,
8089
installed: false,
8190
alreadyPresent: false,
@@ -91,7 +100,7 @@ export const WarehouseInstallDriverTool = Tool.define("warehouse_install_driver"
91100

92101
return {
93102
title: `${label} driver: installed`,
94-
metadata: { driver, installed: true, alreadyPresent: false, dir: result.dir },
103+
metadata: { success: true, driver, installed: true, alreadyPresent: false, dir: result.dir },
95104
output:
96105
`Installed the ${label} driver (${packages}) into ${result.dir}.\n` +
97106
`It is available now — connections using ${driver} will work without restarting the session.`,
@@ -127,3 +136,21 @@ export function driverForWarehouseType(type: string): DriverName | undefined {
127136

128137
export { DRIVER_PACKAGES, driverInstallDir, isDriverInstalled, installOptionalDriver, driverLabel }
129138
export type { DriverName }
139+
140+
/**
141+
* True when every package the driver needs actually imports.
142+
*
143+
* Separates "resolvable" from "usable". Either failure mode — genuinely absent,
144+
* or present but unloadable — means the install should proceed, so both answer
145+
* false; the distinction is already reported in the error text the user sees.
146+
*/
147+
async function driverLoads(driver: DriverName): Promise<boolean> {
148+
for (const pkg of DRIVER_PACKAGES[driver]) {
149+
try {
150+
await loadOptionalDriver(driver, pkg)
151+
} catch {
152+
return false
153+
}
154+
}
155+
return true
156+
}

‎packages/opencode/test/altimate/driver-catalogue.test.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { describe, expect, test } from "bun:test"
1212
import * as fs from "fs"
1313
import * as path from "path"
1414
import { DRIVER_PACKAGES } from "@altimateai/drivers/resolve"
15+
import { driverForWarehouseType } from "../../src/altimate/tools/warehouse-install-driver"
1516

1617
const repoRoot = path.resolve(import.meta.dir, "../../../..")
1718
const driversPkgPath = path.join(repoRoot, "packages/drivers/package.json")
@@ -24,6 +25,14 @@ const expectedPackages = [...new Set(Object.values(DRIVER_PACKAGES).flat())].sor
2425
/** Optional infra externals that are not warehouse drivers. */
2526
const NON_DRIVER_EXTERNALS = new Set(["keytar", "ssh2", "dockerode", "@azure/identity"])
2627

28+
/** Names inside a `const X = [ "a", "b" ] as const` literal. */
29+
function readLiteralList(source: string, marker: string): string[] {
30+
const start = source.indexOf(marker)
31+
expect(start, `${marker} not found`).toBeGreaterThan(-1)
32+
const end = source.indexOf("]", start)
33+
return [...source.slice(start + marker.length, end).matchAll(/"([^"]+)"/g)].map((m) => m[1]!)
34+
}
35+
2736
function readBlock(file: string, startMarker: string, endMarker: string): string {
2837
const source = fs.readFileSync(file, "utf8")
2938
const start = source.indexOf(startMarker)
@@ -87,4 +96,39 @@ describe("driver catalogue consistency", () => {
8796
expect(registered.has(name), `${file} loads an optional SDK but is not in DRIVER_PACKAGES`).toBe(true)
8897
}
8998
})
99+
100+
test("the install tool's DRIVER_NAMES matches DRIVER_PACKAGES", () => {
101+
// The tool declares its zod enum literally so the parameter type is a
102+
// concrete union. Nothing pinned it to the catalogue until now, so a new
103+
// driver could be installable by the resolver but unreachable by the tool.
104+
const toolSource = fs.readFileSync(
105+
path.join(repoRoot, "packages/opencode/src/altimate/tools/warehouse-install-driver.ts"),
106+
"utf8",
107+
)
108+
const names = [...readLiteralList(toolSource, "const DRIVER_NAMES = [")].sort()
109+
110+
expect(names).toEqual(Object.keys(DRIVER_PACKAGES).sort())
111+
})
112+
113+
test("every registry warehouse type maps to a driver the tool can install", () => {
114+
// DRIVER_MAP accepts aliases (postgresql, mariadb, mssql, fabric, mongo).
115+
// Each must resolve through driverForWarehouseType or a connection added
116+
// under that alias silently skips the readiness check added for #61.
117+
const registry = fs.readFileSync(
118+
path.join(repoRoot, "packages/opencode/src/altimate/native/connections/registry.ts"),
119+
"utf8",
120+
)
121+
const mapBlock = registry.slice(
122+
registry.indexOf("const DRIVER_MAP: Record<string, string> = {"),
123+
registry.indexOf("}", registry.indexOf("const DRIVER_MAP: Record<string, string> = {")),
124+
)
125+
const types = [...mapBlock.matchAll(/^\s*([a-z0-9]+)\s*:/gm)].map((m) => m[1]!)
126+
127+
expect(types.length).toBeGreaterThan(12)
128+
for (const type of types) {
129+
// sqlite is bundled with the runtime and needs no optional SDK.
130+
if (type === "sqlite") continue
131+
expect(driverForWarehouseType(type), `registry type "${type}" has no installable driver`).toBeDefined()
132+
}
133+
})
90134
})

0 commit comments

Comments
 (0)