fix(dbt-tools): bubble real errors and redact SQL across all execDbt* paths

Pulls #943, #944, and #945 into this PR — each was tagged as out-of-scope
in the earlier rounds but they share so much of the same fix surface
(extractDbtError / fallbackExitMessage already in place) that fixing them
in-PR is cleaner than spawning three follow-up PRs.

Closes #943 — execDbtCompile / execDbtCompileInline used to swallow the
real dbt error with `try { … } catch { lines = [] }`. They now capture
the run error, skip the success-only tiers when the primary run failed
(same anti-spurious-data reasoning as execDbtShow), and throw via a new
shared `bubbleDbtError(label, primary, plain)` helper that combines
extractDbtError + fallbackExitMessage with the same SQL-safety,
ANSI-stripping, and category-prefix-dedup guarantees.

Closes #944 — execDbtShow Tier 1 used to assign a truthy non-array
`data.preview` straight into `rows`, returning `{ data: {} }` to callers
and crashing downstream `.map` / `.length`. The else-branch now guards
with `Array.isArray(preview)` and emits empty rows for any unexpected
shape (object, number, etc.).

Closes #945 — execDbtCompileInline's final throw used `e.message`
directly, which is Node's "Command failed: <dbt-path> compile --inline
'<entire user SQL>' …" — leaking PII / secrets templated into the inline
query. The new bubbleDbtError helper routes through fallbackExitMessage,
which redacts the command line for both exit-code and signal/timeout
rejections.

Tests: 41 pass / 0 fail (was 33). New coverage:
- execDbtShow non-array preview shape (object + numeric)
- execDbtCompile error bubbling (real stderr, structured JSON event,
  category-prefix dedup)
- execDbtCompileInline error bubbling
- execDbtCompileInline SQL-redaction canaries for both exit-code and
  signal-kill failure modes

Refs #932

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Haider

packages/dbt-tools/src/dbt-cli.ts

@@ -285,17 +285,20 @@ export async function execDbtShow(sql: string, limit?: number) {
         (previewLine as any).result?.preview ??
         (previewLine as any).result?.rows
 
-      // Guard JSON.parse — fall through to Tier 2 on malformed strings
+      // The previewLine match upstream only checked for truthiness, so a
+      // future dbt version emitting `data.preview = {}` or `= 42` would
+      // flow into `rows` unchecked and the downstream `data: rows` field
+      // would crash callers that do `.map` / `.length`. Guard explicitly
+      // for the three shapes we accept (parsed JSON array, native array,
+      // malformed) and emit an empty result for anything else.
       let rows: Record<string, unknown>[]
       if (typeof preview === "string") {
         const parsed = safeJsonParse(preview)
-        if (Array.isArray(parsed)) {
-          rows = parsed
-        } else {
-          rows = [] // Malformed — will fall through below
-        }
-      } else {
+        rows = Array.isArray(parsed) ? parsed : []
+      } else if (Array.isArray(preview)) {
         rows = preview
+      } else {
+        rows = []
       }
 
       // Return the result — even if empty. An empty preview means the query returned
@@ -464,52 +467,88 @@ function fallbackExitMessage(primary?: ExecFileError, plain?: ExecFileError): st
   return "dbt failed (no exit code reported)"
 }
 
+/**
+ * Build a user-facing error message from a failed `dbt <cmd>` invocation.
+ *
+ * Used by every execDbt* function so all three share the same error UX:
+ *   - structured `level: "error"` event from JSON logs > primary stderr >
+ *     plain-text stderr > redacted exit-status fallback
+ *   - ANSI escapes stripped
+ *   - inline SQL / command-line redacted from any err.message-derived path
+ *   - no doubled prefix when dbt's own category prefix is already present
+ */
+function bubbleDbtError(label: string, primary?: ExecFileError, plain?: ExecFileError): string {
+  const errorLogLines = primary?.stdout ? parseJsonLines(primary.stdout.toString()) : []
+  const real = extractDbtError(errorLogLines, primary, plain)
+  if (real) {
+    const hasDbtCategoryPrefix = /^(Compilation|Database|Runtime|Parsing|Validation|Dependency)\s+Error\b/.test(
+      real,
+    )
+    return hasDbtCategoryPrefix ? real : `${label}: ${real}`
+  }
+  return `${label}: ${fallbackExitMessage(primary, plain) ?? "unknown error"}`
+}
+
 /**
  * Compile a model via `dbt compile --select <model>` and return compiled SQL.
  */
 export async function execDbtCompile(model: string): Promise<{ sql: string }> {
   const args = ["compile", "--select", model, "--output", "json", "--log-format", "json"]
 
-  let lines: Record<string, unknown>[]
+  let lines: Record<string, unknown>[] = []
+  let primaryRunError: ExecFileError | undefined
   try {
     const { stdout } = await run(args)
     lines = parseJsonLines(stdout)
-  } catch {
-    lines = []
+  } catch (e) {
+    primaryRunError = toExecFileError(e)
   }
 
-  // --- Tier 1: known field paths ---
-  const sql = findCompiledSql(lines)
-  if (sql) return { sql }
+  // Skip success-only tiers when the primary run failed (same anti-spurious-
+  // data reasoning as execDbtShow).
+  if (!primaryRunError) {
+    // --- Tier 1: known field paths ---
+    const sql = findCompiledSql(lines)
+    if (sql) return { sql }
 
-  // --- Tier 2: heuristic deep scan ---
-  for (const line of lines) {
-    const found = deepFind(line, (val) => looksLikeSql(val))
-    if (found) return { sql: found as string }
+    // --- Tier 2: heuristic deep scan ---
+    for (const line of lines) {
+      const found = deepFind(line, (val) => looksLikeSql(val))
+      if (found) return { sql: found as string }
+    }
   }
 
-  // --- Tier 3: read compiled SQL from manifest.json (more reliable than stdout) ---
-  // dbt compile writes compiled_code to target/manifest.json even when stdout is logs.
-  // We run compile without JSON flags so it writes to manifest, then read the artifact.
+  // --- Manifest fallback ---
+  // dbt compile writes compiled_code to target/manifest.json even when stdout
+  // is just logs. Re-run plain (no JSON flags) so the artifact is fresh, then
+  // read it back. We tolerate a failure here (a prior successful compile may
+  // have left a usable manifest) but capture the error for later bubbling.
+  let manifestRunError: ExecFileError | undefined
   try {
     await run(["compile", "--select", model])
-  } catch {
-    // Compile may fail (e.g., dbt not found, project errors) — continue to manifest check
-    // since a prior successful compile may have left a usable manifest
+  } catch (e) {
+    manifestRunError = toExecFileError(e)
   }
   const fromManifest = readCompiledFromManifest(model)
   if (fromManifest) return { sql: fromManifest }
 
-  // Last resort: return stdout (may contain logs mixed with SQL)
+  // --- Last resort: plain compile, return raw stdout ---
+  let plainRunError: ExecFileError | undefined
   try {
     const { stdout: plainOut } = await run(["compile", "--select", model])
     return { sql: plainOut.trim() }
   } catch (e) {
-    throw new Error(
-      `Could not compile model '${model}' in any format (JSON, heuristic, or manifest). ` +
-        `Last error: ${e instanceof Error ? e.message : String(e)}`,
-    )
+    plainRunError = toExecFileError(e)
+  }
+
+  // If dbt actually failed at any tier, surface the real dbt error via the
+  // shared helper so the message is SQL-safe, ANSI-stripped, and consistent
+  // with execDbtShow's error UX.
+  if (primaryRunError || plainRunError || manifestRunError) {
+    throw new Error(bubbleDbtError("dbt compile failed", primaryRunError, plainRunError ?? manifestRunError))
   }
+
+  throw new Error(`Could not compile model '${model}' in any format (JSON, heuristic, or manifest).`)
 }
 
 /**
@@ -521,34 +560,45 @@ export async function execDbtCompileInline(
 ): Promise<{ sql: string }> {
   const args = ["compile", "--inline", sql, "--output", "json", "--log-format", "json"]
 
-  let lines: Record<string, unknown>[]
+  let lines: Record<string, unknown>[] = []
+  let primaryRunError: ExecFileError | undefined
   try {
     const { stdout } = await run(args)
     lines = parseJsonLines(stdout)
-  } catch {
-    lines = []
+  } catch (e) {
+    primaryRunError = toExecFileError(e)
   }
 
-  // --- Tier 1: known field paths ---
-  const compiled = findCompiledSql(lines)
-  if (compiled) return { sql: compiled }
+  // Skip success-only tiers when the primary run failed.
+  if (!primaryRunError) {
+    // --- Tier 1: known field paths ---
+    const compiled = findCompiledSql(lines)
+    if (compiled) return { sql: compiled }
 
-  // --- Tier 2: heuristic deep scan ---
-  for (const line of lines) {
-    const found = deepFind(line, (val) => looksLikeSql(val))
-    if (found) return { sql: found as string }
+    // --- Tier 2: heuristic deep scan ---
+    for (const line of lines) {
+      const found = deepFind(line, (val) => looksLikeSql(val))
+      if (found) return { sql: found as string }
+    }
   }
 
   // --- Tier 3: plain text fallback ---
+  let plainRunError: ExecFileError | undefined
   try {
     const { stdout: plainOut } = await run(["compile", "--inline", sql])
     return { sql: plainOut.trim() }
   } catch (e) {
-    throw new Error(
-      `Could not compile inline SQL in any format (JSON, heuristic, or plain text). ` +
-        `Last error: ${e instanceof Error ? e.message : String(e)}`,
-    )
+    plainRunError = toExecFileError(e)
   }
+
+  // bubbleDbtError redacts inline SQL from any err.message fallback — critical
+  // here because we're spawning `dbt compile --inline <user SQL>` and Node's
+  // rejection message embeds the full command line (with the SQL) verbatim.
+  if (primaryRunError || plainRunError) {
+    throw new Error(bubbleDbtError("dbt compile inline failed", primaryRunError, plainRunError))
+  }
+
+  throw new Error("Could not compile inline SQL in any format (JSON, heuristic, or plain text).")
 }
 
 /** Shared: extract compiled SQL from known dbt JSON output formats. */

packages/dbt-tools/test/dbt-cli.test.ts

@@ -421,6 +421,33 @@ describe("execDbtShow", () => {
 
     await expect(execDbtShow("SELECT 1")).rejects.toThrow(/Database Error: connection refused/)
   })
+
+  test("does NOT return malformed data when data.preview is a truthy non-array", async () => {
+    // Regression for #944: the previewLine match only checks truthiness, so a
+    // future dbt version emitting `data.preview = {}` would flow into `rows`
+    // and the downstream `data: rows` field would crash callers that do
+    // `.map` / `.length`. Treat unexpected shapes as empty rows instead.
+    const jsonLines = [JSON.stringify({ data: { preview: {} } })].join("\n")
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      cb(null, jsonLines, "")
+    })
+
+    const result = await execDbtShow("SELECT 1")
+    expect(Array.isArray(result.data)).toBe(true)
+    expect(result.data).toEqual([])
+    expect(result.columnNames).toEqual([])
+  })
+
+  test("also treats numeric data.preview as empty (defence-in-depth)", async () => {
+    const jsonLines = [JSON.stringify({ data: { preview: 42 } })].join("\n")
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      cb(null, jsonLines, "")
+    })
+
+    const result = await execDbtShow("SELECT 1")
+    expect(Array.isArray(result.data)).toBe(true)
+    expect(result.data).toEqual([])
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -513,6 +540,45 @@ describe("execDbtCompile", () => {
     const result = await execDbtCompile("my_model")
     expect(result.sql).toBe("SELECT * FROM final_model")
   })
+
+  // --- Real dbt error bubbling (#943) ---
+
+  test("surfaces real dbt stderr when compile fails", async () => {
+    // Pre-fix: catch { lines = [] } swallowed the real error and the final
+    // throw embedded Node's generic "Command failed: ..." message.
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      const err: any = new Error("Command failed: dbt compile --select foo ...")
+      err.code = 1
+      cb(err, "", "Compilation Error: Model 'foo' depends on a node named 'bar' which was not found")
+    })
+
+    await expect(execDbtCompile("foo")).rejects.toThrow(/Compilation Error.*Model 'foo'.*depends on a node named 'bar'/)
+  })
+
+  test("prefers structured JSON error event over raw stderr", async () => {
+    const errorLog = JSON.stringify({
+      info: { level: "error", msg: "Database Error: relation does not exist" },
+    })
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      const err: any = new Error("Command failed")
+      err.code = 1
+      cb(err, errorLog, "exit status 1")
+    })
+
+    await expect(execDbtCompile("foo")).rejects.toThrow(/Database Error: relation does not exist/)
+  })
+
+  test("does not double the 'dbt compile failed:' prefix on dbt category errors", async () => {
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      const err: any = new Error("Command failed")
+      err.code = 1
+      cb(err, "", "Compilation Error: model not found")
+    })
+
+    const caught = (await execDbtCompile("foo").catch((e) => e)) as Error
+    expect(caught.message).toBe("Compilation Error: model not found")
+    expect(caught.message).not.toMatch(/dbt compile failed: Compilation Error/)
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -533,6 +599,53 @@ describe("execDbtCompileInline", () => {
     const result = await execDbtCompileInline("SELECT * FROM {{ ref('customers') }}")
     expect(result.sql).toBe("SELECT id, name FROM raw.customers")
   })
+
+  // --- Real dbt error bubbling (#943) + SQL redaction (#945) ---
+
+  test("surfaces real dbt error when inline compile fails", async () => {
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      const err: any = new Error("Command failed: dbt compile --inline 'SELECT 1' ...")
+      err.code = 1
+      cb(err, "", "Compilation Error: Undefined macro 'unknown_macro'")
+    })
+
+    await expect(execDbtCompileInline("SELECT 1")).rejects.toThrow(/Compilation Error.*Undefined macro/)
+  })
+
+  test("does NOT embed inline SQL into the surfaced error (no Command-failed leak)", async () => {
+    // Regression for #945: pre-fix the throw used `e.message` directly,
+    // which is Node's "Command failed: <dbt-path> compile --inline '<entire
+    // SQL>' …" format — leaking the user's full query into logs and UI.
+    const sensitiveSql = "SELECT 'PII_TOKEN_compile_xyz' AS secret FROM users WHERE ssn = '111-22-3333'"
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      const err: any = new Error(
+        `Command failed: /usr/local/bin/dbt compile --inline ${sensitiveSql} --output json --log-format json`,
+      )
+      err.code = 2
+      cb(err, "", "")
+    })
+
+    const caught = (await execDbtCompileInline(sensitiveSql).catch((e) => e)) as Error
+    expect(caught.message).not.toContain("PII_TOKEN_compile_xyz")
+    expect(caught.message).not.toContain("111-22-3333")
+    expect(caught.message).toMatch(/dbt compile inline failed: dbt exited with status 2/)
+  })
+
+  test("does NOT leak SQL when inline compile is killed by signal / timeout", async () => {
+    const sensitiveSql = "SELECT 'compile_leak_canary' FROM secrets"
+    mockExecFile.mockImplementation((_cmd: string, _args: string[], _opts: any, cb: Function) => {
+      const err: any = new Error(
+        `Command failed: /usr/local/bin/dbt compile --inline ${sensitiveSql} --output json --log-format json`,
+      )
+      err.killed = true
+      err.signal = "SIGTERM"
+      cb(err, "", "")
+    })
+
+    const caught = (await execDbtCompileInline(sensitiveSql).catch((e) => e)) as Error
+    expect(caught.message).not.toContain("compile_leak_canary")
+    expect(caught.message).toMatch(/dbt compile inline failed: dbt killed by signal SIGTERM/)
+  })
 })
 
 // ---------------------------------------------------------------------------