fix(dbt-tools): move to dbt-integration 0.3.17 so the dbt adapter starts under Bun

.github/workflows/release.yml

@@ -286,9 +286,19 @@ jobs:
             echo "::error::dbt-tools bundle contains hardcoded absolute path in __dirname"
             exit 1
           fi
-          # Verify __dirname was patched to runtime resolution
-          if ! grep -q 'import.meta.dirname' packages/dbt-tools/dist/index.js; then
-            echo "::error::dbt-tools bundle missing import.meta.dirname patch"
+          # The bridge path is built at runtime from the bundle's own URL
+          if ! grep -q 'fileURLToPath(import.meta.url)' packages/dbt-tools/dist/index.js; then
+            echo "::error::dbt-tools bundle lacks fileURLToPath(import.meta.url), which the bridge path is built from"
+            exit 1
+          fi
+          # ...joined with the bare script name, not a literal path ending in it
+          if ! grep -qF '"node_python_bridge.py"' packages/dbt-tools/dist/index.js; then
+            echo "::error::dbt-tools bundle lacks the \"node_python_bridge.py\" name the bridge path is joined from"
+            exit 1
+          fi
+          # No path from this checkout baked into the bundle
+          if [ -z "$GITHUB_WORKSPACE" ] || grep -qF "$GITHUB_WORKSPACE" packages/dbt-tools/dist/index.js; then
+            echo "::error::dbt-tools bundle contains the build checkout path, or GITHUB_WORKSPACE is unset"
             exit 1
           fi
           echo "dbt-tools smoke test passed"

packages/dbt-tools/package.json

@@ -9,11 +9,11 @@
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target node --format esm && bun run script/copy-python.ts",
     "typecheck": "tsc --noEmit",
-    "test": "bun test test/cli.test.ts test/config.test.ts test/dbt-cli.test.ts test/dbt-resolve.test.ts test/build-integrity.test.ts --timeout 30000",
+    "test": "bun test test/cli.test.ts test/config.test.ts test/dbt-cli.test.ts test/dbt-resolve.test.ts test/adapter-bun.test.ts test/stale-manifest.test.ts test/build-integrity.test.ts --timeout 30000",
     "test:e2e": "bun test test/e2e/ --timeout 300000"
   },
   "dependencies": {
-    "@altimateai/dbt-integration": "^0.2.2"
+    "@altimateai/dbt-integration": "^0.3.17"
   },
   "devDependencies": {
     "@tsconfig/bun": "catalog:",

packages/dbt-tools/script/copy-python.ts

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, readFileSync, writeFileSync } from "fs"
+import { cpSync, existsSync, readFileSync } from "fs"
 import { dirname, join } from "path"
 
 const dist = join(import.meta.dir, "..", "dist")
@@ -20,23 +20,18 @@ if (!existsSync(bridgePy)) {
 cpSync(bridgePy, join(dist, "node_python_bridge.py"))
 console.log(`Copied node_python_bridge.py → dist/`)
 
-// 3. Fix the hardcoded __dirname that bun bakes at compile time.
-//    Replace it with a runtime resolution so the bridge script is found
-//    relative to the built index.js, not the CI runner's node_modules.
+// 3. dbt-integration resolves node_python_bridge.py at runtime from its own
+//    location (`fileURLToPath(import.meta.url)`), which in this bundle is dist/,
+//    where step 2 put the script. This only checks that the bundle still has
+//    the references that path is built from and no path baked in at build time;
+//    test/build-integrity.test.ts runs the packaged CLI from another directory
+//    to check where the script is found.
 const indexPath = join(dist, "index.js")
-let code = readFileSync(indexPath, "utf8")
-const pattern = /var __dirname\s*=\s*"[^"]*python-bridge[^"]*"/
-if (pattern.test(code)) {
-  // import.meta.dirname is supported by Bun and Node >= 20.11.0.
-  // Fallback via __require handles older runtimes where import.meta.dirname is unavailable.
-  const replacement = `var __dirname = typeof import.meta.dirname === "string" ? import.meta.dirname : __require("path").dirname(__require("url").fileURLToPath(import.meta.url))`
-  code = code.replace(pattern, replacement)
-  writeFileSync(indexPath, code)
-  console.log(`Patched __dirname in dist/index.js`)
-} else {
-  const found = code.match(/var __dirname[^;]*/)?.[0] ?? "(not found)"
-  console.error(`ERROR: could not find python-bridge __dirname to patch — the bundle format may have changed`)
-  console.error(`  Pattern: ${pattern}`)
-  console.error(`  Nearest match: ${found}`)
+const code = readFileSync(indexPath, "utf8")
+const baked = /var __dirname\s*=\s*"(?:[A-Za-z]:\\\\|\/)/
+if (!code.includes("fileURLToPath(import.meta.url)") || !code.includes(`"node_python_bridge.py"`) || baked.test(code)) {
+  console.error(`ERROR: dist/index.js lacks the references the bridge path is built from, or has a build-time path`)
+  console.error(`  Has the @altimateai/dbt-integration bundle format changed?`)
   process.exit(1)
 }
+console.log(`Checked dist/index.js: bridge path references present, no build-time path`)

packages/dbt-tools/src/adapter.ts

@@ -1,8 +1,10 @@
 import type { Config } from "./config"
 import { bufferLog } from "./log-buffer"
+import { recordManifest } from "./stale-manifest"
 export { getRecentDbtLogs, clearDbtLogs } from "./log-buffer"
 import {
   DBTProjectIntegrationAdapter,
+  DBTProjectIntegrationAdapterEvents,
   DEFAULT_CONFIGURATION_VALUES,
   DBTCommandFactory,
   DBTCommandExecutionInfrastructure,
@@ -15,6 +17,8 @@ import {
   GraphParser,
   SourceParser,
   TestParser,
+  UnitTestParser,
+  SemanticModelParser,
   ExposureParser,
   FunctionParser,
   DocParser,
@@ -63,7 +67,10 @@ function terminal(): DBTTerminal {
     show: async () => {},
     log: (msg: string) => bufferLog(`[dbt] ${msg}`),
     trace: () => {},
-    debug: () => {},
+    // A crash at bridge startup is told only on the bridge's stderr, which the library logs here.
+    debug: (name: string, msg: string) => {
+      if (name === "PythonBridgeStderr") bufferLog(`[dbt:stderr] ${msg}`)
+    },
     info: (_name: string, msg: string) => bufferLog(`[dbt] ${msg}`),
     warn: (_name: string, msg: string) => bufferLog(`[dbt:warn] ${msg}`),
     error: (_name: string, msg: string, e: unknown) => {
@@ -82,6 +89,12 @@ function env(cfg: Config): RuntimePythonEnvironment {
   }
 }
 
+/** Whether this dbt-integration answers a model's lineage, for a caller deciding whether to `create`. */
+export function hasModelLineage(): boolean {
+  const prototype = DBTProjectIntegrationAdapter.prototype as { getModelLineage?: unknown }
+  return typeof prototype.getModelLineage === "function"
+}
+
 export async function create(cfg: Config): Promise<DBTProjectIntegrationAdapter> {
   const config = configuration(cfg)
   const term = terminal()
@@ -141,6 +154,8 @@ export async function create(cfg: Config): Promise<DBTProjectIntegrationAdapter>
       defer,
       changed,
       cloudVariantDetector,
+      // Every variant but fusion-stable runs on a dbt Core command engine, which needs these.
+      { pythonDBTCommandExecutionStrategy: python, dbtConfiguration: config, dbtIntegrationClient: client },
     )
 
   const command = (
@@ -170,19 +185,7 @@ export async function create(cfg: Config): Promise<DBTProjectIntegrationAdapter>
     defer: DeferConfig,
     changed: () => void,
   ): DBTProjectIntegration =>
-    new DBTFusionCommandProjectIntegration(
-      infra,
-      factory,
-      cli,
-      runtime,
-      provider,
-      term,
-      root,
-      diag,
-      defer,
-      changed,
-      cloudVariantDetector,
-    )
+    new DBTFusionCommandProjectIntegration(infra, factory, cli, runtime, provider, term, root, diag, defer, changed)
 
   const adapter = new DBTProjectIntegrationAdapter(
     config,
@@ -200,13 +203,17 @@ export async function create(cfg: Config): Promise<DBTProjectIntegrationAdapter>
     new GraphParser(term),
     new SourceParser(term),
     new TestParser(term),
+    new UnitTestParser(term),
     new ExposureParser(term),
     new FunctionParser(term),
     new DocParser(term),
     term,
     new ModelDepthParser(term, client, config),
+    new SemanticModelParser(term),
   )
 
+  // Before `initialize`, whose parse is the one the commands answer from.
+  adapter.on(DBTProjectIntegrationAdapterEvents.MANIFEST_PARSED, recordManifest)
   try {
     await adapter.initialize()
   } catch (e) {

packages/dbt-tools/src/commands/graph.ts

@@ -1,11 +1,12 @@
 import type { DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
 import { execDbtLs } from "../dbt-cli"
+import { staleManifestNote } from "../stale-manifest"
 
 export async function children(adapter: DBTProjectIntegrationAdapter, args: string[]) {
   const model = flag(args, "model")
   if (!model) return { error: "Missing --model" }
   try {
-    return await adapter.getChildrenModels({ table: model })
+    return fromManifest(await adapter.getChildrenModels({ table: model }))
   } catch (e) {
     // nodeMetaMap/graphMetaMap errors are specific to the library's manifest parsing.
     // Also catch TypeError for property-access failures on undefined nodes.
@@ -23,7 +24,7 @@ export async function parents(adapter: DBTProjectIntegrationAdapter, args: strin
   const model = flag(args, "model")
   if (!model) return { error: "Missing --model" }
   try {
-    return await adapter.getParentModels({ table: model })
+    return fromManifest(await adapter.getParentModels({ table: model }))
   } catch (e) {
     if (
       e instanceof TypeError ||
@@ -35,6 +36,12 @@ export async function parents(adapter: DBTProjectIntegrationAdapter, args: strin
   }
 }
 
+// The note comes first: a long answer can be cut off on its way to the reader.
+function fromManifest<T>(models: T[]) {
+  const stale_manifest = staleManifestNote()
+  return stale_manifest ? { stale_manifest, models } : models
+}
+
 function flag(args: string[], name: string): string | undefined {
   const i = args.indexOf(`--${name}`)
   return i >= 0 ? args[i + 1] : undefined

packages/dbt-tools/src/commands/schema-verify.ts

@@ -1,4 +1,5 @@
 import type { ColumnMetaData, DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
+import { staleManifestNote } from "../stale-manifest"
 
 /**
  * Verify that a model's actual produced columns match the spec declared in
@@ -22,8 +23,16 @@ import type { ColumnMetaData, DBTProjectIntegrationAdapter } from "@altimateai/d
  * Skip cases:
  *   - "no-spec": schema.yml doesn't declare columns for this model — nothing
  *     to verify; agent has no contract to fail against.
+ *
+ * Every answer rests on the manifest, its errors included, so each one says when that's a stale one.
  */
 export async function schemaVerify(adapter: DBTProjectIntegrationAdapter, args: string[]) {
+  const answer = await verify(adapter, args)
+  const stale_manifest = staleManifestNote()
+  return stale_manifest ? { stale_manifest, ...answer } : answer
+}
+
+async function verify(adapter: DBTProjectIntegrationAdapter, args: string[]) {
   const model = flag(args, "model")
   if (!model) return { error: "Missing --model" }
 

packages/dbt-tools/src/failure-text.ts

@@ -0,0 +1,11 @@
+/** What `--format text` prints on stderr for an error answer. */
+export function failureLines(failed: Record<string, unknown>): string[] {
+  const lines: string[] = []
+  // The note comes first, as in the JSON answer: the error rests on that manifest.
+  const stale = failed.stale_manifest
+  if (stale && typeof stale === "object" && "message" in stale) lines.push(String(stale.message))
+  lines.push(String(failed.error))
+  if ("fix" in failed) lines.push(String(failed.fix))
+  if (Array.isArray(failed.logs)) lines.push(failed.logs.join("\n"))
+  return lines
+}

packages/dbt-tools/src/index.ts

@@ -3,6 +3,7 @@ import { existsSync } from "fs"
 import { read, type Config } from "./config"
 import { init } from "./commands/init"
 import { validate } from "./check"
+import { failureLines } from "./failure-text"
 
 const USAGE = {
   commands: {
@@ -37,12 +38,6 @@ function flag(args: string[], name: string): string | undefined {
 
 function diagnose(err: Error): { error: string; fix?: string } {
   const msg = err.message || String(err)
-  if (msg.includes("private field") || msg.includes("#stdin") || msg.includes("#stdout")) {
-    return {
-      error: "Internal error: Bun runtime incompatibility with python-bridge. Please report this issue.",
-      fix: "Try updating: bun install, or file a bug at https://github.com/AltimateAI/altimate-code/issues",
-    }
-  }
   if (msg.includes("IPC channel") || msg.includes("ERR_IPC_CHANNEL_CLOSED")) {
     return {
       error: "Failed to start Python bridge. The dbt Python process exited unexpectedly.",
@@ -75,8 +70,7 @@ function output(result: unknown) {
   if (fmt && typeof result === "object" && result !== null) {
     const obj = result as Record<string, unknown>
     if ("error" in obj) {
-      console.error(String(obj.error))
-      if ("fix" in obj) console.error(String(obj.fix))
+      console.error(failureLines(obj).join("\n"))
       process.exit(1)
     }
     if ("sql" in obj) {
@@ -92,7 +86,7 @@ function output(result: unknown) {
   if (result && typeof result === "object" && "error" in result) process.exit(1)
 }
 
-function bail(err: unknown): never {
+function failure(err: unknown) {
   const result: Record<string, unknown> = diagnose(err instanceof Error ? err : new Error(String(err)))
   // Include buffered dbt logs for diagnostics (see #249 — logs are buffered
   // in-memory instead of written to stderr to avoid TUI corruption).
@@ -105,11 +99,15 @@ function bail(err: unknown): never {
   } catch {
     // log-buffer might not have been loaded yet
   }
-  console.log(JSON.stringify(result, null, 2))
+  return result
+}
+
+function bail(err: unknown): never {
+  console.log(JSON.stringify(failure(err), null, 2))
   process.exit(1)
 }
 
-// Catch unhandled rejections (bluebird throws outside normal promise chains)
+// An error that escapes main() still ends as a JSON error on stdout
 process.on("unhandledRejection", bail)
 process.on("uncaughtException", bail)
 
@@ -142,13 +140,13 @@ async function main() {
   const { configure } = await import("./dbt-cli")
   configure({ pythonPath: cfg.pythonPath, projectRoot: cfg.projectRoot })
 
-  // Lazy import to avoid loading python-bridge until needed
+  // Lazy import: the adapter loads dbt-integration, which commands above don't need
   let adapter
   try {
     const { create } = await import("./adapter")
     adapter = await create(cfg)
   } catch (err) {
-    return diagnose(err instanceof Error ? err : new Error(String(err)))
+    return failure(err)
   }
 
   let result: unknown

packages/dbt-tools/src/stale-manifest.ts

@@ -0,0 +1,30 @@
+import type { ParsedManifest, StaleManifest } from "@altimateai/dbt-integration"
+
+// Set when the project check failed and the last parse read what an earlier parse left on disk.
+let stale: StaleManifest | undefined
+
+/** Takes each parsed manifest from the adapter, whose graph lookups don't say which one they used. */
+export function recordManifest(parsed: ParsedManifest): void {
+  stale = parsed.stale
+}
+
+function ago(ms: number): string {
+  const format = new Intl.RelativeTimeFormat("en")
+  const minutes = Math.round(ms / 60_000)
+  if (minutes < 60) return format.format(-minutes, "minute")
+  const hours = Math.round(minutes / 60)
+  if (hours < 48) return format.format(-hours, "hour")
+  return format.format(-Math.round(hours / 24), "day")
+}
+
+/** What an answer built from the manifest adds, or undefined when the manifest is current. */
+export function staleManifestNote(now = Date.now()) {
+  if (!stale) return undefined
+  const age = Math.max(0, now - stale.writtenAt)
+  return {
+    message: `The dbt project check failed, so this comes from the manifest of the last successful parse, written ${ago(age)}. It may not match the project as it is now.`,
+    manifest_path: stale.manifestPath,
+    written_at: new Date(stale.writtenAt).toISOString(),
+    age_seconds: Math.round(age / 1000),
+  }
+}