Skip to content

Inbox: Linear hover cards and the Linear key in Settings → Accounts - #3146

Draft
backnotprop wants to merge 21 commits into
mainfrom
feat/inbox-linear-key-setting
Draft

backnotprop wants to merge 21 commits into
mainfrom
feat/inbox-linear-key-setting

Conversation

@backnotprop

@backnotprop backnotprop commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

Closes #3120. Carries #3063 by @Raj1v (Linear hover cards; their commit keeps their authorship in this branch's history) and adds a Settings row for the Linear API key, merged with current main.

What changes for a person

Hover cards for Linear issues (the Inbox only). Hovering or tapping a https://linear.app/<workspace>/issue/ENG-123 link opens a card like the GitHub and GitLab ones: team, title, Linear's own workflow state (name, colour, icon), author, priority, project, estimate, labels, assignee, description, attached GitHub PRs, the latest comment, a comment count, and Open in Linear ↗. A bare ENG-123 in a message becomes a link when ENG is one of the workspace's team keys (never inside code, a URL, a path or a longer word).

Settings → Accounts → Linear. Paste a Linear personal API key and press Save. Once it's saved the row says "Key saved, ending in 1234" with Replace and Remove. With no saved key and LINEAR_API_KEY in the Inbox's environment, it says "Using LINEAR_API_KEY" and asks for nothing. Cards and identifiers work right after a save, with no restart. Without a key, a Linear card says "Add your Linear API key in Settings → Accounts to see details here."

Plan review, code review, annotate and every other @plannotator/ui host register nothing and are unchanged.

How the key is kept

  • In a private file (0600) in the Inbox's data folder (inbox/linear-key), like Voice's OpenAI key. Never in config.json.
  • A pasted key wins over LINEAR_API_KEY, which stays the fallback.
  • The window only learns the key's source and last 4 characters. The key never appears in an answer, an SSE frame or a log.
  • POST /api/inbox/linear/key has the same guards as Voice's key: same-origin, serverSession, HTTPS only over the tailnet, not on the device door.
  • The key goes only to https://api.linear.app/graphql as the Authorization header, with read-only queries, a timeout and no redirects. Avatars come only from Linear's public image hosts, fetched without the key.

Safety and load

  • Nothing is fetched on page load. A card is fetched only on hover or tap. The team keys (for bare identifiers) are read once, when prose on screen first shows something shaped like an identifier.
  • Linear's text is shown as text: a description or comment line that would open a raw HTML block or a directive (:::question, :::note) is shown as code, also inside a quote, list item, alert or heading. Nothing from Linear reaches the HTML renderer, and it never draws a callout or an answerable question card. The check after that parses the result as the renderer does and walks every block except code and math, so a new block type is covered too. If anything would still get through, the whole text becomes one code block.
  • A link to another workspace's issue gets no card. The server answers not found, and once the window knows the key's workspace the link stays plain.
  • Saving, replacing or removing the key drops every card cached or still being fetched under the old key. A key Linear refuses drops the card it had.
  • Open in Linear uses the issue's own link only when it is an https linear.app link. Otherwise it uses the link from the message.

Shared UI (packages/ui), all additive

  • utils/refCardProviders (new): registerRefCardProvider, registerPlainTextLinker, providedRefCardTarget, providedRefCardView, providedRefCardLabel, plainTextLinkSpans, usePlainTextLinkers, and the types RefCardProvider, PlainTextLinker, PlainTextLinkSpan. Empty by default.
  • components/LinearRefCardView (new): LinearRefCardView (optional noKeyText), LinearStateIcon, htmlAsText.
  • components/RefHoverCard: also exports RefCardAvatar, RefCardMarkdown, RefCardStateIcon, refCardTimeAgo. RefCardView hands a provider's ref to its View, and the card's accessible name uses a provider's label. Both apply only when a provider is registered.
  • utils/refCard: refCardTarget asks the providers after the forge parser (main's Bitbucket rule is unchanged).
  • components/InlineMarkdown: adds the registered linkers' spans, never over a URL, a path or a host path; with none registered, the output is unchanged.
  • core 0.25.32 adds ./linear-ref-card and InboxLinearKeyState, and forgeRefKey no longer throws for a platform with no forge spec. ui pins it. Publish core first (HANDOFF.md).

The Pi server is not touched: the Inbox is Bun-only.

Tests

  • packages/server/inbox-linear-cards.test.ts, packages/server/inbox-linear-key.test.ts: stubbed fetch and fake keys only, no network.
  • packages/inbox/linearCards.test.tsx: identifiers, provider, card, and no fetch until prose shows a candidate.
  • packages/ui/components/LinearRefCardView.test.ts: no raw HTML line from Linear becomes an HTML block (including after ~~~). The card it renders shows no question card, directive or raw HTML in any container: the top level, a quote, a quote in a list, a nested quote, an alert, a list item, a heading, a table cell, or a directive body. Open in Linear never leaves linear.app.
  • packages/inbox/linearKeySettings.test.tsx (DOM): the Settings row keeps the last Save or Remove after you leave Settings and come back.
  • packages/inbox/linearCards.test.tsx also covers a hover's load for a Linear ref, and another workspace's link as a plain link.
  • Neighbours pass: InlineMarkdown.test.ts, refCard.test.ts, RefHoverCard.dom.test.tsx and four InlineMarkdown.* DOM files, tests/inbox-structure.test.ts (size ceilings), scripts/check-sibling-deps.test.ts. tsc is clean for core, server, ui (and strict consumer), inbox and apps/inbox.

e2e: inbox-ref-cards.spec.ts

Raj1v and others added 15 commits November 10, 2026 14:09
- core 0.25.24 and ui pins it: ui imports the new ./linear-ref-card
  subpath, which the published core 0.25.22 lacks, so smoke:package
  failed. 0.25.23 on main is unpublished; 0.25.24 carries its call-tree
  too. HANDOFF's Publishing & versioning says publish core first.
- The card's latest comment: Linear lists a connection newest first with
  `first` and oldest first with `last` (its public schema), so
  `comments(last: 1)` was the oldest comment. Now `comments(first: 1)`.
- A test that the key reaches only api.linear.app's authorization header:
  not an avatar fetch, an answer, the route's body or a console line.
- Docs: LINEAR_API_KEY in environment.md, /api/inbox/linear-refs in the
  Server API table, Linear in the Inbox's hover-card section, and the
  ref card providers seam in packages/ui/README.md.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
One row under Accounts, built like Voice's API key row: a password field
and Save; once saved, "Key saved, ending in 1234" with Replace and Remove;
with no saved key but LINEAR_API_KEY in the Inbox's environment, "Using
LINEAR_API_KEY". The key is kept in inbox/linear-key (0600) on this
computer and wins over the env var; the page only learns its source and
last 4 (settings `linear_key`, POST /api/inbox/linear/key, owner only,
HTTPS over the tailnet, as voice's key).

A save or removal drops the cards and teams read under the old key (server
`forget()`, window `refreshLinearCards`), so bare identifiers link at once.
The card's no-key line now says "Add your Linear API key in Settings →
Accounts to see details here." (`noKeyText`; ui's default names no
Settings).

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Other open PRs hold 0.25.24 to 0.25.28. ui pins 0.25.29; HANDOFF says publish core before ui at release.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
The providers change named every card by its link, so a #12 that GitHub answers as a pull request was "Issue #12" for screen readers (inbox-ref-cards.spec.ts:271). A provider's own label still wins; a forge card takes its kind from the answer again, and from the link while it loads, as before.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
`.ib-prow .ib-ctl { flex: none }` kept the field and Save at their own width when the row wraps, so Save ran past the window at 320 px (inbox-accounts.spec.ts:329, 25 px sideways on CI). The Linear row's control now shrinks to the window.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Owner's rule: no comments in code. Only lines we wrote; the contributor's are untouched.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Owner's rule: no comments in code. Only lines we wrote; the contributor's are untouched, except his header sentence about the key's source, cut back to what it said before.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Conflicts: App.tsx's configurePlannotatorUI moved to configureUI.ts on main, so
installLinearCards moved there too; inbox.ts keeps main's Bitbucket reader and
combine route beside the Linear key and cards; the tailnet guest tier is gone on
main, so the Linear key route drops its owner-only check and the settings field
its guest condition, like Voice's key. InlineMarkdown keeps main's host paths and
the plain-text linkers; refCard keeps main's Bitbucket rule before the providers.
core goes to 0.25.32 (main is at 0.25.31), ui pins it, bun.lock is main's with
the two core lines. api.ts stays at its size ceiling: the Linear key's settings
field and save call live in LinearKeySettings.tsx (module augmentation, as
scheduled/client.ts does).
…rd styles

- The window no longer reads the team keys when it loads: a probe linker asks
  for them once prose on screen first shows something shaped like ENG-123, and
  a key change reads them again only if prose already asked. A card is still
  fetched only on hover or tap.
- The description and latest comment go through htmlAsText: a line that would
  open a raw HTML block (top level or in a quote) is shown as code, so nothing
  from Linear reaches the renderer's HTML path.
- "Pull requests" is a plain label, not uppercase tracked; the latest comment
  sits under a rule instead of a bordered, tinted well.
- installLinearCards returns its uninstall, for the test.
@backnotprop backnotprop changed the title Inbox: paste the Linear key in Settings → Accounts Inbox: Linear hover cards and the Linear key in Settings → Accounts Nov 16, 2026
…link)

- htmlAsText tracks backtick fences only, closed as the parser closes them
  (`~~~` is plain text to it), and then asks the parser itself: if anything
  would still be an HTML block (top level or in a quote), every line that
  could open one is shown as code.
- A key change bumps a generation: answers asked under the old key are never
  cached or shown (asked again under the new one), and fetches in flight are
  dropped. A refresh Linear refuses (signed_out) no longer keeps the old card,
  and the stale limit counts from the last good fetch.
- A link to another workspace's ENG-1 is not the key's ENG-1: the server
  caches per workspace and answers not found when the issue's own link names
  another workspace; the window makes it a plain link once it knows the key's
  workspace (the first Linear link asks for it).
- Open in Linear uses the issue's link only when it is an https linear.app
  link (checked on the server and in the card), else the message's link.
…g Settings

The page's settings model is not reread after a save, so coming back to
Settings showed the key state from the first read (a removed key as saved).
The row remembers the last save's answer over the read it replaced; a newer
settings read wins again. Found while taking the screenshots.
Main's forgeRefKey reads FORGE_SPECS[platform].numbersByKind, which threw for
a Linear ref ("linear" has no forge spec), so loadRefCard threw before asking
and every Linear card stayed on its loading skeleton. A platform with no spec
gets no kind in its key. Found in the browser while taking the screenshots;
the new window test drives loadRefCard with a Linear ref and fails without it.
htmlAsText now treats a line that opens a directive (:::question, :::note)
like one that opens a raw HTML block, behind quote, list, task and heading
markers too, so Linear text never draws a callout or an answerable question
card. The check after it parses the result as the renderer does and walks
the content of every block except code and math, so a quote in a list, an
alert or a block type added later cannot hide one; failing that, the whole
text is one code block. A test per container renders the card.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Inbox: hover cards for Linear issue links

2 participants