fix: altimate-dbt compile, execute, and children commands fail with runtime errors

.github/meta/commit.txt

@@ -1,10 +1,30 @@
-fix: comprehensive XSS hardening for trace viewer HTML
+fix: `altimate-dbt` compile, execute, and children commands — CLI fallbacks for dbt 1.11+ (#252)
 
-Systematically escape all user-controllable fields in `viewer.ts`:
+The `@altimateai/dbt-integration` library's JSON output parsing breaks with
+newer dbt versions (1.11.x) where the log format changed. Three commands
+were affected:
 
-- Escape `span.kind` and `span.status` in detail panel, waterfall, tree, and log views
-- Escape `span.spanId` in `data-sid` attributes
-- Coerce all numeric fields with `Number()` to prevent string injection via `.toLocaleString()`
-- Add single-quote escaping (`'`) to the `e()` function for defense-in-depth
+- `execute`: `dbt show` output no longer contains `data.preview` in the
+ expected format — `d[0].data` throws when the filter returns empty.
+- `compile`: `dbt compile` output no longer contains `data.compiled` —
+ same `o[0].data` pattern failure.
+- `children`: `nodeMetaMap.lookupByBaseName()` fails when the manifest
+ file-path resolution doesn't populate the model-name lookup map.
+
+Additionally, `tryExecuteViaDbt` in opencode incorrectly expected
+`raw.table` on `QueryExecutionResult`, which actually has `{ columnNames,
+columnTypes, data }` — causing the dbt-first execution path to always
+fall through to native drivers silently.
+
+Fixes:
+- Add try-catch in execute/compile/graph commands with fallback to direct
+ `dbt` CLI subprocess calls (`dbt show`, `dbt compile`, `dbt ls`)
+- New `dbt-cli.ts` module with resilient multi-format JSON output parsing
+ (handles `data.preview`, `data.rows`, `data.compiled`, `data.compiled_code`,
+ `result.node.compiled_code`)
+- Fix `tryExecuteViaDbt` to recognize `QueryExecutionResult` shape first,
+ then fall back to legacy `raw.table` format
+
+Closes #252
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/workflows/ci.yml

@@ -22,6 +22,7 @@ jobs:
  outputs:
  typescript: ${{ steps.filter.outputs.typescript }}
  drivers: ${{ steps.filter.outputs.drivers }}
+ dbt-tools: ${{ steps.filter.outputs.dbt-tools }}
  steps:
  - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
@@ -45,6 +46,8 @@ jobs:
  - 'packages/opencode/test/altimate/drivers-e2e.test.ts'
  - 'packages/opencode/test/altimate/drivers-docker-e2e.test.ts'
  - 'packages/opencode/test/altimate/connections.test.ts'
+ dbt-tools:
+ - 'packages/dbt-tools/**'
 
  # ---------------------------------------------------------------------------
  # Main TypeScript tests — excludes driver E2E tests (separate job) and
@@ -196,6 +199,84 @@ jobs:
  # ALTIMATE_CODE_CONN_BIGQUERY_TEST='...' bun test test/altimate/drivers-bigquery-e2e.test.ts
  # ALTIMATE_CODE_CONN_DATABRICKS_TEST='...' bun test test/altimate/drivers-databricks-e2e.test.ts
 
+ # ---------------------------------------------------------------------------
+ # dbt-tools unit tests — fast (< 5s), run on PRs when dbt-tools changes.
+ # ---------------------------------------------------------------------------
+ dbt-tools:
+ name: dbt-tools
+ needs: changes
+ if: needs.changes.outputs.dbt-tools == 'true' || github.event_name == 'push'
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2
+ with:
+ bun-version: "1.3.10"
+
+ - name: Install dependencies
+ run: bun install
+
+ - name: Run dbt-tools unit tests
+ run: bun run test
+ working-directory: packages/dbt-tools
+
+ # ---------------------------------------------------------------------------
+ # dbt-tools E2E — slow (~3 min), only on push to main.
+ # Tests dbt CLI fallbacks against real dbt versions (1.8, 1.10, 1.11) and
+ # real Python environments (venv, uv, system).
+ # ---------------------------------------------------------------------------
+ dbt-tools-e2e:
+ name: "dbt-tools E2E"
+ needs: changes
+ if: github.event_name == 'push'
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2
+ with:
+ bun-version: "1.3.10"
+
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+ with:
+ python-version: "3.11"
+
+ - name: Install uv
+ run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+ - name: Install dependencies
+ run: bun install
+
+ - name: Cache dbt venvs
+ uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+ with:
+ path: packages/dbt-tools/test/.dbt-venvs
+ key: dbt-venvs-${{ runner.os }}-1.8-1.10-1.11
+
+ - name: Cache Python env scenarios
+ uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+ with:
+ path: packages/dbt-tools/test/.dbt-resolve-envs
+ key: dbt-resolve-envs-${{ runner.os }}-v1
+
+ - name: Set up dbt versions
+ run: ./test/e2e/setup-versions.sh 1.8 1.10 1.11
+ working-directory: packages/dbt-tools
+
+ - name: Set up Python env scenarios
+ run: ./test/e2e/setup-resolve.sh venv uv system
+ working-directory: packages/dbt-tools
+
+ - name: Run dbt-tools E2E tests
+ run: bun run test:e2e
+ working-directory: packages/dbt-tools
+ env:
+ DBT_E2E_VERSIONS: "1.8,1.10,1.11"
+ DBT_RESOLVE_SCENARIOS: "venv,uv,system"
+
  marker-guard:
  name: Marker Guard
  runs-on: ubuntu-latest

packages/dbt-tools/package.json

@@ -9,7 +9,8 @@
  "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 --timeout 30000"
+ "test": "bun test test/cli.test.ts test/config.test.ts test/dbt-cli.test.ts test/dbt-resolve.test.ts --timeout 30000",
+ "test:e2e": "bun test test/e2e/ --timeout 300000"
  },
  "dependencies": {
  "@altimateai/dbt-integration": "^0.2.2"

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

@@ -1,18 +1,34 @@
 import type { DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
+import { execDbtCompile, execDbtCompileInline } from "../dbt-cli"
 
 export async function compile(adapter: DBTProjectIntegrationAdapter, args: string[]) {
  const model = flag(args, "model")
  if (!model) return { error: "Missing --model" }
- const sql = await adapter.unsafeCompileNode(model)
- return { sql }
+ try {
+ const sql = await adapter.unsafeCompileNode(model)
+ return { sql }
+ } catch (e) {
+ // Use TypeError check (not message strings) to work across V8 and Bun/JavaScriptCore
+ if (e instanceof TypeError) {
+ return execDbtCompile(model)
+ }
+ throw e
+ }
 }
 
 export async function query(adapter: DBTProjectIntegrationAdapter, args: string[]) {
  const sql = flag(args, "query")
  if (!sql) return { error: "Missing --query" }
  const model = flag(args, "model")
- const result = await adapter.unsafeCompileQuery(sql, model)
- return { sql: result }
+ try {
+ const result = await adapter.unsafeCompileQuery(sql, model)
+ return { sql: result }
+ } catch (e) {
+ if (e instanceof TypeError) {
+ return execDbtCompileInline(sql, model)
+ }
+ throw e
+ }
 }
 
 function flag(args: string[], name: string): string | undefined {

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

@@ -1,13 +1,23 @@
 import type { DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
+import { execDbtShow } from "../dbt-cli"
 
 export async function execute(adapter: DBTProjectIntegrationAdapter, args: string[]) {
  const sql = flag(args, "query")
  if (!sql) return { error: "Missing --query" }
  const model = flag(args, "model") ?? ""
  const raw = flag(args, "limit")
  const limit = raw !== undefined ? parseInt(raw, 10) : undefined
- if (limit !== undefined && !Number.isNaN(limit)) return adapter.immediatelyExecuteSQLWithLimit(sql, model, limit)
- return adapter.immediatelyExecuteSQL(sql, model)
+ try {
+ if (limit !== undefined && !Number.isNaN(limit)) return await adapter.immediatelyExecuteSQLWithLimit(sql, model, limit)
+ return await adapter.immediatelyExecuteSQL(sql, model)
+ } catch (e) {
+ // Library's dbt show parsing may fail with newer dbt versions — fall back to direct CLI.
+ // Use TypeError check (not message strings) to work across V8 and Bun/JavaScriptCore.
+ if (e instanceof TypeError || (e instanceof Error && e.message.includes("Could not find previewLine"))) {
+ return execDbtShow(sql, limit)
+ }
+ throw e
+ }
 }
 
 function flag(args: string[], name: string): string | undefined {

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

@@ -1,15 +1,38 @@
 import type { DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
+import { execDbtLs } from "../dbt-cli"
 
-export function children(adapter: DBTProjectIntegrationAdapter, args: string[]) {
+export async function children(adapter: DBTProjectIntegrationAdapter, args: string[]) {
  const model = flag(args, "model")
  if (!model) return { error: "Missing --model" }
- return adapter.getChildrenModels({ table: model })
+ try {
+ return 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.
+ if (
+ e instanceof TypeError ||
+ (e instanceof Error && (e.message.includes("nodeMetaMap has no entries") || e.message.includes("graphMetaMap")))
+ ) {
+ return execDbtLs(model, "children")
+ }
+ throw e
+ }
 }
 
-export function parents(adapter: DBTProjectIntegrationAdapter, args: string[]) {
+export async function parents(adapter: DBTProjectIntegrationAdapter, args: string[]) {
  const model = flag(args, "model")
  if (!model) return { error: "Missing --model" }
- return adapter.getParentModels({ table: model })
+ try {
+ return await adapter.getParentModels({ table: model })
+ } catch (e) {
+ if (
+ e instanceof TypeError ||
+ (e instanceof Error && (e.message.includes("nodeMetaMap has no entries") || e.message.includes("graphMetaMap")))
+ ) {
+ return execDbtLs(model, "parents")
+ }
+ throw e
+ }
 }
 
 function flag(args: string[], name: string): string | undefined {

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

@@ -14,7 +14,40 @@ function find(start: string): string | null {
  }
 }
 
-function python(): string {
+/**
+ * Discover the Python binary, checking multiple environment managers.
+ *
+ * Priority:
+ * 1. Project-local .venv/bin/python (uv, pdm, venv, poetry in-project)
+ * 2. VIRTUAL_ENV/bin/python (activated venv)
+ * 3. CONDA_PREFIX/bin/python (conda)
+ * 4. `which python3` / `which python` (system PATH)
+ * 5. Fallback "python3" (hope for the best)
+ */
+function python(projectRoot?: string): string {
+ // Check project-local venvs first (most reliable for dbt projects)
+ if (projectRoot) {
+ for (const venvDir of [".venv", "venv", "env"]) {
+ const py = join(projectRoot, venvDir, "bin", "python")
+ if (existsSync(py)) return py
+ }
+ }
+
+ // Check VIRTUAL_ENV (set by activate scripts)
+ const virtualEnv = process.env.VIRTUAL_ENV
+ if (virtualEnv) {
+ const py = join(virtualEnv, "bin", "python")
+ if (existsSync(py)) return py
+ }
+
+ // Check CONDA_PREFIX (set by conda activate)
+ const condaPrefix = process.env.CONDA_PREFIX
+ if (condaPrefix) {
+ const py = join(condaPrefix, "bin", "python")
+ if (existsSync(py)) return py
+ }
+
+ // Fall back to PATH-based discovery
  for (const cmd of ["python3", "python"]) {
  try {
  return execFileSync("which", [cmd], { encoding: "utf-8" }).trim()
@@ -35,7 +68,7 @@ export async function init(args: string[]) {
 
  const cfg: Config = {
  projectRoot: project,
- pythonPath: py ?? python(),
+ pythonPath: py ?? python(project),
  dbtIntegration: "corecommand",
  queryLimit: 500,
  }