feat: dbt_health tool: DataPilot project health insights per model

HK
9h ago
+1222-6

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 typecheck and bun 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.