feat: dbt_health tool: DataPilot project health insights per model
Issue for this PR
Part of the dbt Power User tools build (package P-06, project health). No tracker issue.
Type of change
- New feature
What does this PR do?
Fills in the dbt_health tool (stub from the foundation). It starts the project's dbt adapter through dbt-adapter-access (needs write permission), rebuilds the manifest and waits for it, then runs DataPilot over target/manifest.json (and catalog.json when present) with the project's Python, the way dbt-integration's project_healthcheck does, using a Manual config (config_path, or DataPilot's defaults). It does not use dbt-integration's own healthcheck entry point: no integration implements it, and its All mode would run dbt docs generate.
Returns insights: [{ uniqueId, path, name, severity, message, recommendation, file, properties }]; file and properties are absolute paths under the folder as the system names it, for the project's own models. A parse that fails (dbt parse errors) is a failure with the parse errors and no insights; when only the project check fails, the answer comes from the last good manifest and says so (stale_manifest). A result over 2 MiB of insights is cut (truncated: true, total). When datapilot isn't importable it returns a message naming altimate-datapilot-cli and installs nothing. The text lists at most 100 insights; insights carries them up to that limit. An answer that isn't DataPilot's, or comes with a failing exit, is a failure.
The Claude Code plugin PR (project health in the band, optional git push gate) depends on this and merges after it.
Known limits, for follow-up: a manifest without metadata.project_name gives no file/properties; a project with several thousand insights makes the result larger than the plugin's 4 MiB read limit (a models filter on the tool would fix it).
How did you verify your code works?
bun run typecheckandbun test test/altimate/dbt-health.test.ts test/altimate/dbt-adapter-access.test.ts(40 tests) pass.- Reviewed by independent Claude and Codex reviewers; every finding fixed or answered in the comments below.
Cost side effects
None. No model calls, no warehouse queries; DataPilot reads the local manifest. Starting the dbt adapter and rebuilding the manifest is the same write-permission path the other adapter-backed tools use.
Screenshots / recordings
Checklist
- I have tested my changes locally
- I have not included unrelated changes in this PR
- I checked for cost side effects and described them: none
Changelog: dbt_health tool: DataPilot project health insights per model.
Demo video (hosted)
P-06.mp4 — watch on Notion (Altimate workspace; recorded from the approved head of this PR).
🤖 Generated with Claude Code
Summary by CodeRabbit
- New Features
- Added a dbt health check that reports project insights, manifest issues, and recommendations.
- Added dbt and documentation-sharing tools to the CLI; several are placeholders and currently return a “not implemented” response.
- Bug Fixes
- Improved dbt project access handling, including read-only restrictions, project mismatches, startup failures, and cancellation.
- Improved API requests with configurable timeouts that remain active while responses are processed, cancellation support, and clearer, sanitized error messages.