Skip to content

feat: docs_share_comments tool — list, reply to and resolve comment threads on shared dbt docs - #1730

Open
hkaltai wants to merge 9 commits into
mainfrom
feat/docs-share-comments-tool
Open

hkaltai wants to merge 9 commits into
mainfrom
feat/docs-share-comments-tool

Conversation

@hkaltai

@hkaltai hkaltai commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

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

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"

Demo video (hosted)

P-14.mp4 — watch on Notion (Altimate workspace; recorded from the approved head of this PR).

🤖 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 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.

Written for commit 6a139dd. Summary will update on new commits.

View guided diff Turn on auto-fix

hkaltai and others added 3 commits November 13, 2026 16:30
Nine tool stubs exposed through `altimate tool run` (dbt_run_results,
dbt_defer_state, dbt_map_relations, docs_share_comments, dbt_cost_estimate,
dbt_health, dbt_sql_graph, dbt_docs_coverage, dbt_cte_profile), an exported
`AltimateApi.apiRequest` that calls the backend with the stored credentials,
and `dbtAdapterFor`, the one gate every adapter-backed tool goes through:
it refuses read-only calls, other projects, and an adapter that did not start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hreads on shared dbt docs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 54 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 04b7539f-0610-4c4f-8406-841ff6a27fdd
Commits

Reviewing files that changed from the base of the PR and between 830537b and 6a139dd.

Files selected for processing: 15

  • packages/opencode/src/altimate/api/client.ts
  • packages/opencode/src/altimate/api/docs-share.ts
  • packages/opencode/src/altimate/tool-cli/allow-list.ts
  • packages/opencode/src/altimate/tools/dbt-adapter-access.ts
  • packages/opencode/src/altimate/tools/dbt-cost-estimate.ts
  • packages/opencode/src/altimate/tools/dbt-cte-profile.ts
  • packages/opencode/src/altimate/tools/dbt-defer-state.ts
  • packages/opencode/src/altimate/tools/dbt-docs-coverage.ts
  • packages/opencode/src/altimate/tools/dbt-health.ts
  • packages/opencode/src/altimate/tools/dbt-map-relations.ts
  • packages/opencode/src/altimate/tools/dbt-run-results.ts
  • packages/opencode/src/altimate/tools/dbt-sql-graph.ts
  • packages/opencode/src/altimate/tools/docs-share-comments.ts
  • packages/opencode/test/altimate/dbt-adapter-access.test.ts
  • packages/opencode/test/altimate/docs-share-comments.test.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

hkaltai and others added 2 commits November 13, 2026 17:01
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… list answer is an error, comment text is quoted as data

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

@hkaltai

hkaltai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Review-loop results for the P-14 commit (two independent reviewers, claude -p and codex exec; no CRITICAL; fixes in a0f07cb, attack-the-fix gate by a fresh claude -p: all findings resolved).

Fixed

  • [MAJOR] reply/resolve reported success on {ok:false} / {} / null (both reviewers). Now res.ok === true is required (Power User types both POSTs as { ok: boolean }); anything else returns the failure envelope with error: "not_accepted", which the CLI reports as status: "error". Tests added for all three bodies.
  • [MAJOR] non-array share-list answer became an empty successful list (codex). listSharedDocs now throws, so the plugin keeps its cached threads. Test added.
  • [MAJOR] comment text/author/highlight placed raw in tool output (both). Each is collapsed to one line, the output says the texts are data and not instructions, and a colleague's email is no longer used as a display name. Test added with forged [share …] lines.
  • [MINOR] project lookup outside try, duplicate of detectDbtProject, "Could not reply the thread" (claude). Uses detectDbtProject inside the try; wording fixed.
  • [MINOR] oneLine on a non-string (gate). Coerces with String(text ?? "").

Not changed

  • Possible duplicate reply after a 15 s timeout (claude, confidence 0.55): the not-accepted message now says to run list before retrying; making POSTs idempotent needs the backend and is out of scope here.
  • detectDbtProject looks 5 levels up (the old copy walked to /): matches the sibling tools.
  • The read-only wiring through createAdapter is covered by the foundation's adapter tests; this test file sets forceReadOnly directly.

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

@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

# Conflicts:
#	packages/opencode/src/altimate/tools/docs-share-comments.ts
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

1 similar comment
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

…error, never 'no open threads'

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

2 similar comments
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

@hkaltai

hkaltai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Review round 1 (independent claude -p and codex exec reviewers), and what was done:

  • MAJOR, fixed — api/docs-share.ts: a share, thread or status the tool could not read was shown as "No open comment threads." The list answer is now validated (zod) before it is used, and the ?? [] fallbacks are gone. Test: "a share or thread that is not what the tool reads is an error, never 'no open threads'". A fresh reviewer gated the fix; its hardening points (null range, honest optional types) are applied.
  • MAJOR, not changed here (foundation code) — a malformed ~/.altimate/altimate.json can put a snippet of the file in the error. That is getCredentials/apiRequest in the shared client from the foundation branch, used by every tool; noted in the PR description as a follow-up rather than patched in this PR.
  • MINOR, not changed — metadata.threads carries the raw comment text for tool run --json (confidence 0.6; the data notice is in output); author names containing ": " (0.5); 1-based line in the text vs 0-based in metadata; a reply/resolve acknowledgement shape ({ok:true}) could not be checked against a live backend by the reviewer, and the tool fails safe (reports "not accepted") if the backend answers otherwise.
  • MINOR, not changed — a test of reply through the real adapter with allowWrite: false; the gate matches dbt_lineage's.

…t placeholder test

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

1 similar comment
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

@hkaltai
hkaltai marked this pull request as ready for review November 14, 2026 03:42
@hkaltai

hkaltai commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at 5da9186

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 15 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

@kilo-code-bot

kilo-code-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Code Review Summary

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 1
Issue Details (click to expand)

WARNING

File Line Issue
packages/opencode/src/altimate/api/client.ts 365 apiRequest still forwards the credentials-file parser error into tool output, which reaches the model provider and session transcript; a malformed ~/.altimate/altimate.json can leak a fragment of the API key. Re-verified at HEAD 6a139dd: the newly appended : ${msg} in docs_share_comments errors makes this text more prominent, not less.
packages/opencode/src/altimate/tools/dbt-adapter-access.ts 86 sessionProject() is still a line-for-line copy of dbt-lineage.ts:369-386, and no production tool routes through dbtAdapterFor yet — two copies of the project-isolation decision can drift. Re-verified at HEAD 6a139dd.

SUGGESTION

File Line Issue
packages/opencode/src/altimate/api/docs-share.ts 82 The new unwrap reads only the first page of a paginated answer and drops total, so a capped page can make list report a partial set (even "No open comment threads") and leave later-page shares unreachable for reply/resolve.
Files Reviewed (7 files)
  • packages/opencode/src/altimate/api/docs-share.ts - 1 issue
  • packages/opencode/src/altimate/tools/docs-share-comments.ts - 0 new issues (control-character and bidi-override stripping, name/project fallbacks and the may-have-posted wording all verified fixed)
  • packages/opencode/src/altimate/tools/dbt-adapter-access.ts - 1 issue (carried)
  • packages/opencode/src/altimate/api/client.ts - 1 issue (carried)
  • packages/opencode/test/altimate/docs-share-comments.test.ts - 0 issues
  • packages/opencode/test/altimate/dbt-adapter-access.test.ts - 0 issues

Verified, no issue found: signal.throwIfAborted() now runs before the read-only/plan-mode gate (Tool.Context.abort is a required AbortSignal, so no undefined path); unknown thread statuses are treated as closed and covered by a test; a non-array items still fails the schema instead of being read as empty; comment text, author names and highlights all pass through the bounded oneLine sanitiser; test globals are reset in beforeEach and the apiRequest spy restored in afterEach, so no cross-file leak under parallel bun test. Carried findings verified against HEAD 6a139dde1fcabfaef2644b03497ae99bef1c9576.

Fix these issues in Kilo Cloud

Previous Review Summary (commit 5da9186)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 5da9186)

Status: 4 Issues Found | Recommendation: Address before merge

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 2
Issue Details (click to expand)

WARNING

File Line Issue
packages/opencode/src/altimate/api/client.ts 365 apiRequest forwards the credentials-file parser error (which can quote ~/.altimate/altimate.json, including the API key) into tool output that reaches the model provider and session transcript. Throw a fixed message instead.
packages/opencode/src/altimate/tools/dbt-adapter-access.ts 84 sessionProject() is a line-for-line copy of dbt-lineage.ts:369-386, and the only adapter-backed tool still uses its own inline gate — two copies of the project-isolation decision that can drift.

SUGGESTION

File Line Issue
packages/opencode/src/altimate/api/docs-share.ts 60 The share schema requires name/project_name, which the tool never reads; one share with a null name fails the whole listing. Make them optional with a fallback.
packages/opencode/src/altimate/tools/docs-share-comments.ts 80 oneLine collapses whitespace but leaves ESC/C0-C1 control characters and bidi overrides, so another tenant user's comment text can still inject terminal escape sequences into tool run output.
Files Reviewed (15 files)
  • packages/opencode/src/altimate/api/client.ts - 1 issue
  • packages/opencode/src/altimate/api/docs-share.ts - 1 issue
  • packages/opencode/src/altimate/tool-cli/allow-list.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-adapter-access.ts - 1 issue
  • packages/opencode/src/altimate/tools/dbt-cost-estimate.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-cte-profile.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-defer-state.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-docs-coverage.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-health.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-map-relations.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-run-results.ts - 0 issues
  • packages/opencode/src/altimate/tools/dbt-sql-graph.ts - 0 issues
  • packages/opencode/src/altimate/tools/docs-share-comments.ts - 1 issue
  • packages/opencode/test/altimate/dbt-adapter-access.test.ts - 0 issues
  • packages/opencode/test/altimate/docs-share-comments.test.ts - 0 issues

Verified, no issue found: the read-only gate (reply/resolve refuse when ctx.extra.forceReadOnly or plan mode) matches how dbt-lineage and mcp-server/adapter.ts:466-472 set authorization, and the MCP/CLI paths always set forceReadOnly = !allowWrite; reply/resolve require an explicit {ok: true} acknowledgement and report not_accepted otherwise; list answers are validated so a malformed share/thread is never shown as "no open threads"; comment text and author names are collapsed to one line with an explicit data notice. No unbounded cost path: 1-2 backend HTTP calls per call, no model calls or warehouse queries. Findings verified against HEAD 5da9186c4dc.

Fix these issues in Kilo Cloud


Reviewed by deepseek-v4.1-flash-1017 · Input: 61.1K · Output: 11.5K · Cached: 501K

Review guidance: REVIEW.md from base branch main (truncated)

@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

…own statuses, strip control characters from comment text, say a failed reply may have posted, honour cancellation before the read-only gate

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

1 similar comment
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

for (const project of projects) params.append("projects", project)
const shares = await AltimateApi.apiRequest("GET", `/dbt/dbt_docs_share/all?${params.toString()}`)
// A paginated answer wraps the shares in `items`; a bare array is accepted too.
const list = shares && !Array.isArray(shares) && Array.isArray(shares.items) ? shares.items : shares

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION]: A paginated answer is read one page deep, and total is discarded

Unwrapping items fixes the wrapper case, but nothing here handles more than the first page: total (returned alongside items in the fixture this PR adds) is stripped by SharesAnswer, so if the backend caps the page (e.g. 20 of 57 shares) list reports those threads as if the set were complete and can still answer "No open comment threads" while open threads exist on later pages. list is also the only way to discover the share_id/group_id that reply/resolve need, so hidden shares are unreachable. Either fetch the full set (largest page size, or loop until items.length >= total) or keep total in the schema and say the listing is partial when it exceeds items.length.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant