feat: docs_share_comments tool ā€” list, reply to and resolve comment threads on shared dbt docs

HK
1d ago
+1185-0

Issue for this PR

None.

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Replaces the docs_share_comments stub with a working tool (P-14, team comments).

  • api/docs-share.ts (new): listSharedDocs (GET /dbt/dbt_docs_share/all?projects=ā€¦), listTenantUsers (GET /users/chat), replyToThread, resolveThread, all through AltimateApi.apiRequest (api/client.ts:355).
  • tools/docs-share-comments.ts: docs_share_comments { action: list|reply|resolve, project?, share_id?, group_id?, text? }.
    • list returns the open (Pending) threads with each message's author named from users/chat; the project defaults to the name: of the dbt project holding the working directory.
    • reply and resolve refuse on a read-only call (ctx.extra?.forceReadOnly === true) and in plan mode, and validate share_id, group_id and non-empty text.
  • Test: test/altimate/docs-share-comments.test.ts (23 tests; the backend is replaced at AltimateApi.apiRequest, nothing is sent).

This branch currently includes the shared foundation commits (feat/pu-mods-foundation), which are not on main yet; the P-14 change is the last commit. Merge the foundation first, then retarget/rebase.

Changelog line: docs_share_comments: list, reply to and resolve comment threads on shared dbt docs.

Not verified: that a key stored by altimate-code (~/.altimate/altimate.json) is accepted by the docs-share endpoints.

How did you verify your code works?

  • bun test test/altimate/docs-share-comments.test.ts in packages/opencode: 23 pass, 0 fail.

  • bun typecheck in packages/opencode: clean.

  • Drove altimate tool run docs_share_comments against a local fake backend: list (cwd project and explicit), read-only refusal of reply/resolve, and --allow-write posting to the right endpoints with the stored key.

  • Peer review (claude + codex as independent reviewers): one MAJOR fixed (malformed share/thread/status shown as "no open threads"), gated by a fresh reviewer.

Follow-up for the foundation, not changed here: AltimateApi.getCredentials parses ~/.altimate/altimate.json with JSON.parse, and its error text can carry a snippet of that file; apiRequest forwards it. Worth replacing with a fixed message in the shared client.

Cost side effects

None. The tool makes one to two HTTP calls to the Altimate backend per list, one per reply/resolve; no model calls or warehouse queries.

Screenshots / recordings

Demo video (real run: branch-built CLI tool run docs_share_comments, then a Claude Code session with the plugin from altimate-claude-plugin#26 against a local stand-in for the backend): /Users/harish/.quikim/artifacts/pu-mods/videos/P-14.mp4.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

šŸ¤– Generated with Claude Code

Summary by cubic

Implements the docs_share_comments tool so altimate-code can list, reply to, and resolve comment threads on shared dbt docs, and lays the foundation for the other dbt Power User tools.

  • list returns open (Pending) threads with author names; reply and resolve take share_id and group_id, and refuse on read-only or plan-mode calls.
  • The project defaults to the name: in the dbt_project.yml holding the working directory.
  • Posts must be acknowledged by the backend; an unexpected or malformed list answer (a share, thread, or status the tool can't read) is an error, never "no open threads".
  • Comment text is formatted as single-line, clearly-marked data so it cannot pose as another thread or author.
  • Adds AltimateApi.apiRequest, which calls the backend with the stored credentials, and dbtAdapterFor, the gate that refuses read-only calls, other projects, and an adapter that didn't start.
  • Exposes eight more tool stubs (dbt_run_results, dbt_defer_state, dbt_map_relations, dbt_cost_estimate, dbt_health, dbt_sql_graph, dbt_docs_coverage, dbt_cte_profile) that return a "not implemented" failure.
  • Adds tests for the comments tool, the adapter gate, and apiRequest; no requests are sent in tests.

Rollout

  • This branch includes the feat/pu-mods-foundation commits, which aren't on main yet; merge that foundation first, then rebase/retarget this PR.
  • Not verified that a key stored by altimate-code is accepted by the docs-share endpoints.