feat: add altimate-dbt CLI for dbt project operations

[suryaiyer95]

Summary

• New packages/dbt-tools/ TypeScript package wrapping @altimateai/dbt-integration to provide one-shot dbt CLI operations
• 16 commands covering the full dbt workflow: compile, build, run, test, execute SQL, introspect columns/DAG, manage packages
• Config auto-detected via altimate-dbt init, stored at ~/.altimate-code/dbt.json
• Prerequisite validation (doctor) checks Python, dbt-core, and project health before loading the heavy adapter
• Structured JSON output with actionable error + fix fields for all failure modes
• Patch for [email protected] to fix bluebird.promisifyAll crash with class private fields
• Builds with bun build --target node for Node.js runtime (workaround for Bun IPC channel bug)
• /dbt-cli skill teaching AI agents when and how to invoke each command

Architecture

altimate-dbt CLI (packages/dbt-tools/)
  ├── bin/altimate-dbt          # #!/usr/bin/env node shebang
  ├── src/index.ts              # CLI entry: argv dispatch, error handling, JSON output
  ├── src/config.ts             # Read/write ~/.altimate-code/dbt.json
  ├── src/adapter.ts            # Wire DBTProjectIntegrationAdapter (10 parsers, 4 factories)
  ├── src/check.ts              # Prerequisite validation (Python, dbt, project)
  ├── src/commands/             # 9 command files implementing 16 commands
  └── test/                     # 11 tests (config round-trip, CLI dispatch, error paths)

.opencode/skills/dbt-cli/       # AI skill with workflow patterns and invocation guidance
patches/[email protected]  # Fix bluebird.promisifyAll crash

Commands

Category	Commands
Setup	init, doctor
Info	info
Compile	compile, compile-query
Build	build, run, test, build-project
Execute	execute
Introspect	columns, columns-source, column-values, children, parents
Packages	deps, add-packages

Test plan

• bun test --cwd packages/dbt-tools — 11/11 tests pass
• bun turbo typecheck — 0 type errors in dbt-tools
• altimate-dbt init --project-root <path> — writes config, runs health checks
• altimate-dbt doctor — returns structured check results
• altimate-dbt info — returns project info via adapter
• /dbt-cli skill loads and guides AI to run correct commands
• Full compile/build/execute flow requires dbt_core_integration Python module

🤖 Generated with Claude Code

[github-actions]

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

• PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[sentry]

Bug: The children and parents command results are not awaited in index.ts. This causes them to return a Promise that serializes to an empty object {}.
_{Severity: HIGH}

Suggested Fix

Add the await keyword to the calls for the children and parents commands within the switch statement in index.ts. This will ensure the Promise resolves before the result is assigned and serialized.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: packages/dbt-tools/src/index.ts#L157-L160

Potential issue: The `children` and `parents` commands in `graph.ts` are not declared as
`async` but return Promises from the underlying adapter methods. In `index.ts`, the
calls to these functions are not awaited, unlike other commands. Consequently, the
`result` variable holds a Promise object. When this object is serialized with
`JSON.stringify()`, it results in an empty object `{}`. This causes the `altimate-dbt
children` and `altimate-dbt parents` CLI commands to always return `{}` instead of the
expected model dependency data, breaking their functionality.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[sentry]

Bug: The execute command uses a falsy check if (limit), causing --limit 0 to be ignored and the query to run without any limit.
_{Severity: MEDIUM}

Suggested Fix

Change the condition from if (limit) to if (limit !== undefined). This correctly checks for the presence of the limit argument, including 0, ensuring that LIMIT 0 is properly applied to the SQL query.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: packages/dbt-tools/src/commands/execute.ts#L9

Potential issue: In the `execute` command, the code checks `if (limit)` to determine
whether to apply a SQL limit. When a user passes `--limit 0`, the `limit` variable
becomes the number `0`. In JavaScript, `0` is a falsy value, so the condition `if
(limit)` evaluates to false. As a result, the code incorrectly executes the branch for
running the SQL query without a limit, ignoring the user's explicit instruction to
return zero rows. This behavior is incorrect as `LIMIT 0` is a valid SQL operation.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[sentry]

Bug: The format function incorrectly uses stderr to detect errors instead of checking the exitCode, causing successful dbt commands to be reported as failures.
_{Severity: HIGH}

Suggested Fix

Update the format function to check for a non-zero exitCode to identify an error, rather than checking for the existence of stderr. The condition should be changed to if (result?.exitCode !== 0).

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: packages/dbt-tools/src/commands/deps.ts#L16

Potential issue: The `format` function in `deps.ts` and `build.ts` incorrectly
determines command failure by checking for the presence of `result?.stderr`. However,
dbt commands like `dbt deps` can write informational progress messages to `stderr` even
during successful runs. The standard practice for determining success or failure is to
check the command's `exitCode`. Due to this flawed logic, successful dbt operations that
produce any `stderr` output will be incorrectly reported as failures. This causes the
CLI tool to exit with a non-zero status code, which can break automated scripts or CI/CD
pipelines that depend on the exit code to determine the outcome.

[dev-punia-altimate]

🤖 Behavioral Analysis — 3 Finding(s)

🔴 Critical (1)

• F1 packages/dbt-tools/src/index.ts:157 [Missing await — Promise stored as result]
  The children and parents switch cases assign result without await, unlike every other command in the same switch. graph.children() and graph.parents() are not declared async but return the Promise from adapter.getChildrenModels() / adapter.getParentModels(). Without await, result holds an unresolved Promise. (1) output(result) calls JSON.stringify(promise) which serializes to {}, so both commands always print {} instead of actual graph data. (2) The finally { await adapter.dispose() } block tears down the Python bridge while the underlying operation is still in flight. All other commands in the switch correctly use result = await (await import(...)).fn(adapter, rest). — Auto-fixable: Add await before both graph calls: result = await (await import('./commands/graph')).children(adapter, rest) and same for parents.

🟡 Warnings (1)

• F2 packages/dbt-tools/src/commands/build.ts:30 [stderr presence used as error signal — false positives on successful dbt runs]
  The format() helper in both build.ts (line 30) and deps.ts (line 16) uses if (result?.stderr) to decide whether a command failed. dbt consistently writes progress output to stderr on success — lines like 'Running with dbt=1.8.0', 'Found N models', 'Completed successfully'. Any successful build/run/test/deps invocation that produces any stderr will be incorrectly reported as a failure: CLI returns { error: <stderr> } and exits with code 1, breaking any CI pipeline checking exit codes. The correct signal is a non-zero exitCode.

🔵 Nits (1)

• F3 packages/dbt-tools/src/commands/execute.ts:9 — The parsed limit is checked with if (limit). JavaScript treats 0 as falsy, so --limit 0 silently falls back to the unlimited query path. Negative limits (e.g. --limit -1) are truthy and passed to the adapter unchecked.

_{Analysis run | Powered by QA Autopilot}

[dev-punia-altimate]

✅ Tests — All Passed

TypeScript — passed

Python — passed

_{Tested at bf3da562 | Run log | Powered by QA Autopilot}