Skip to content

feat: Buzz entity links — rich preview cards + in-app navigation for repos, PRs, and issues - #4695

Open
thomaspblock wants to merge 5 commits into
mainfrom
spec/buzz-entity-links
Open

feat: Buzz entity links — rich preview cards + in-app navigation for repos, PRs, and issues#4695
thomaspblock wants to merge 5 commits into
mainfrom
spec/buzz-entity-links

Conversation

@thomaspblock

Copy link
Copy Markdown
Contributor

Summary

Gives Buzz-hosted git entities the same "GitHub-style" chat experience GitHub links already get: rich preview cards, real titles, and click-through — except clicks navigate in-app to the Projects view instead of a browser.

  • Spec: docs/buzz-entity-links.md — link scheme, slices, and deferred work (buzz://project, OS deep links, web routes).
  • Canonical buzz:// deep links: new desktop/src/shared/lib/entityLink.ts with builders + strict parser for buzz://pr?id=…&owner=…&d=…, buzz://issue?…, and buzz://repo?owner=…&d=…, mirrored by a Rust module (crates/buzz-cli/src/links.rs) with a shared golden-format test so the two implementations can't drift.
  • Preview cards: linkPreview.ts recognizes buzz:// entity links and HTTPS relay clone URLs ({origin}/git/<pubkey>/<repo>, the shape agents paste today). Both normalize onto the canonical buzz:// href, so the two spellings of a repo dedupe to one Buzz-provider card (BuzzMark logo) rendered by link-preview-attachment.tsx.
  • Title enrichment: PR/issue cards fetch the real subject from the relay event (subject tag or first content line) via useResolvedLinkPreviews.ts; the cache is community-scoped and reset in resetCommunityState().
  • In-app navigation: clicking a card or inline anchor routes through goProject(owner:dtag) instead of handing the URL to the OS (markdown/entityLinks.tsx). Entity-link and external-anchor logic were extracted out of markdown.tsx to stay under the file-size ratchet.
  • Agent side: buzz pr open, buzz issues create, and buzz repos create now return a ready-made link field, and base_prompt.md instructs agents to paste it verbatim when announcing work.

Test plan

  • Desktop unit tests: 4,147 pass, including new entityLink.test.mjs and linkPreview.test.mjs coverage (golden formats, malformed-link rejection, clone-URL/buzz:// dedupe)
  • Rust: cargo test -p buzz-cli golden-format test, clippy + fmt clean
  • Biome + tsc --noEmit clean; pre-push hooks (desktop-tauri-checks, rust-tests, desktop-test) pass
  • Manual: paste a relay clone URL and a buzz://pr link in a channel — verify one card each, real PR title, and in-app navigation to the Projects view

Design doc for buzz:// links to Buzz-hosted repositories, projects, pull
requests, and issues, with GitHub-parity preview cards in chat, in-app and
OS-level deep-link handling, CLI link output, and agent prompt guidance.
Spec only — no implementation.

Signed-off-by: Thomas Petersen <thomasp@squareup.com>
Relay git URLs ({relay-origin}/git/<pubkey>/<repo>) pasted in chat now get
the same rich preview card treatment as GitHub links. Detection keys on the
/git/<64-hex-pubkey>/<repo> path shape since relay hosts differ per
community; the card links to the browsable web repo page (/repos/<d-tag>)
rather than the raw git transport endpoint. First implemented slice of the
Buzz entity links spec (docs/buzz-entity-links.md).

Signed-off-by: Thomas Petersen <thomasp@squareup.com>
Desktop renders buzz://pr|issue|repo links as Buzz preview cards with
titles enriched from the relay event's subject tag, and clicking a card
or inline link navigates in-app to the project detail view. The CLI's
pr open / issues create / repos create now return a matching link field,
and the agent base prompt tells agents to paste it when announcing work.

Signed-off-by: Thomas Petersen <thomasp@squareup.com>
Signed-off-by: Thomas Petersen <thomasp@squareup.com>
Clone-URL previews rewrote their href to the relay web page, so clicking
the card opened an external browser instead of the Projects view. Normalize
the href to the canonical buzz://repo deep link, which wires up the same
in-app click handler as explicit entity links, dedupes both spellings of a
repo, and makes inline clone-URL anchors navigate in-app too.

Signed-off-by: Thomas Petersen <thomasp@squareup.com>
thomaspblock added a commit that referenced this pull request Aug 4, 2026
@thomaspblock

Copy link
Copy Markdown
Contributor Author

Screenshots of the new Buzz entity link cards (captured via the E2E mock bridge).

Repo card from an HTTPS clone URL

An agent pastes the relay clone URL ({origin}/git/<pubkey>/<repo>) — it renders as a Buzz · repo card, and both the card and the inline link navigate in-app to the project.

01-repo-card

PR and issue cards from buzz:// deep links

buzz://pr?… and buzz://issue?… links render as cards with the real subject fetched from the relay event (not the hex fallback).

02-pr-issue-cards

Dedupe: two spellings, one card

The same repository referenced as a clone URL and a buzz://repo deep link in one message produces a single card.

03-dedupe

@thomaspblock
thomaspblock marked this pull request as ready for review August 4, 2026 10:27
@thomaspblock
thomaspblock requested a review from a team as a code owner August 4, 2026 10:27
@thomaspblock
thomaspblock enabled auto-merge (squash) August 4, 2026 10:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant