Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
b2c66b1
feat(inbox): hover cards for Linear issues
Raj1v Nov 10, 2026
488797d
Merge remote-tracking branch 'origin/main' into linear-hover-cards
backnotprop Nov 11, 2026
d903b7a
Linear hover cards: core 0.25.24, latest comment, key test, docs
backnotprop Nov 11, 2026
ec28e33
Inbox: paste the Linear key in Settings → Accounts
backnotprop Nov 11, 2026
33e0035
core 0.25.29 for the Linear subpath (0.25.24 to 0.25.28 are taken)
backnotprop Nov 11, 2026
129eb53
Merge linear-hover-cards (core 0.25.29) into feat/inbox-linear-key-se…
backnotprop Nov 11, 2026
34cb5f1
Ref hover card: a forge card is named by what the answer says it is
backnotprop Nov 12, 2026
e707704
Settings → Accounts → Linear: the key field fits a 320 px phone
backnotprop Nov 12, 2026
d73d81f
Merge linear-hover-cards (ref card label fix) into feat/inbox-linear-…
backnotprop Nov 12, 2026
c74161d
Drop the code comments our commits added
backnotprop Nov 12, 2026
4a74168
Drop the code comments our commits added
backnotprop Nov 12, 2026
8276a09
Merge linear-hover-cards (comments dropped) into feat/inbox-linear-ke…
backnotprop Nov 12, 2026
bc7ece5
Merge origin/main into feat/inbox-linear-key-setting
backnotprop Nov 16, 2026
a374637
Linear cards: nothing fetched on page load, Linear's text as text, ca…
backnotprop Nov 16, 2026
9665c62
Merge remote-tracking branch 'origin/main' into feat/inbox-linear-key…
backnotprop Nov 16, 2026
061ba7b
Linear cards: review fixes (fences, old keys, other workspaces, Open …
backnotprop Nov 16, 2026
f601270
Settings → Linear: the row keeps the last Save or Remove after leavin…
backnotprop Nov 16, 2026
ca293c7
Merge remote-tracking branch 'origin/main' into feat/inbox-linear-key…
backnotprop Nov 16, 2026
639b67d
Linear cards load again: forgeRefKey takes a provider's platform
backnotprop Nov 16, 2026
7242066
Linear cards: directives in Linear text show as text, in every container
backnotprop Nov 16, 2026
c3e3f47
Merge remote-tracking branch 'origin/main' into feat/inbox-linear-key…
backnotprop Nov 16, 2026
7c6fc44
Merge branch 'main' into feat/inbox-linear-key-setting
backnotprop Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions docs/agent-guides/environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@
| `PLANNOTATOR_INSTALL_CALLDIFF` | **Read by the install scripts only.** Set to `1` / `true` / `yes` to ALSO install the optional pinned, pruned CallDiff core used by code review's Call Flow analysis (about 5 MB on macOS arm64, Node.js 22.18+). The runtime is strictly opt-in and is NOT installed by default. The normal path is in-app: enabling Call flow consents to one background install of core plus exactly the language packs required by the current changed files; later missing languages install automatically under the same consent, while the Languages list supports install-ahead. Each target gets one automatic attempt per review session; a failed target then requires an explicit Retry in that session. Equivalent to `--with-call-flow` (PowerShell: `-WithCallFlow`) or `{ "installCallFlow": true }` in `~/.plannotator/config.json`; precedence is flag > env var > config. `--minimal` always excludes it. Off by default. |
| `PLANNOTATOR_CALLDIFF_PATH` | Development override for a built CallDiff `0.6.0` package root containing `dist/run.js`; the exact pinned Tree-sitter core and any desired optional grammars must already exist under its `node_modules`. Managed language-pack installation is disabled for overrides. Normal installs use the selective managed core and grammar cache under the Plannotator data directory. |
| `OPENAI_API_KEY` | Not Plannotator's own, read when the Inbox's voice dictation uses the OpenAI API (`engine: "api"`) and no key was pasted in Settings → Voice. A pasted key wins. It is read from the Inbox's environment and never reaches a page: Settings says only that it is in use. |
| `LINEAR_API_KEY` | Not Plannotator's own (the name Linear's tools use). A Linear personal API key; with it, the Inbox shows hover cards for Linear issue links and links bare identifiers (`ENG-123`) of the workspace's teams (see "Hover cards for issue, PR and MR links" in [inbox-window.md](inbox-window.md)). The fallback: a key pasted in Settings → Accounts → Linear wins (`packages/server/inbox-linear-key.ts`, as Voice's OpenAI key). Read from the Inbox's environment on each fetch, sent only as the `Authorization` header to `https://api.linear.app/graphql` (redirects refused), never logged and never sent to a page. Neither set: no request leaves the computer and a Linear link's card points to Settings → Accounts. |
| `CHROME_PATH` | Not Plannotator's own (the name Chrome launchers share). `plannotator shape frame` uses that Chrome, Chromium, Edge or Brave to take its picture instead of looking in the usual places (`/Applications` and `~/Applications` on macOS, `PATH` on Linux, Program Files and `LOCALAPPDATA` on Windows; `findChrome` in `apps/hook/server/shape-frame.ts`). Set but missing: no picture, as with no Chrome. Nothing is ever downloaded. |
| `http_proxy` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY` / `no_proxy` | Not Plannotator's own. Bun's `fetch` sends even `http://127.0.0.1` through a proxy these name, so the CLI adds `127.0.0.1,localhost,::1` to `NO_PROXY` and `no_proxy` (existing entries kept) in its own environment at start, before any request (`apps/hook/server/loopback-no-proxy.ts`, `packages/shared/loopback-proxy.ts`); every child it starts inherits them. Code that runs inside a host's process (the OpenCode plugin, the Pi extension's Inbox link) leaves the host's environment alone and passes `proxy: false` on its loopback requests instead, which Bun 1.4 honors and Node ignores. Not covered: the Claude Code mod's `$.http.fetch` (Claude Code's own client), and Node with `NODE_USE_ENV_PROXY=1` (#3350). |

Expand Down
2 changes: 2 additions & 0 deletions docs/agent-guides/inbox-accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,5 @@ On a phone the row is in the sidebar's sheet. A tap closes that sheet and opens
- `tests/e2e/inbox-accounts.spec.ts`: the compiled binary in Chromium at 1440, 780, on a phone and at 320: the usage in one column, the account in use first, a row's confirm under it, phone rows of 44 px with no hover word, no `@` with organizations named after the address, and nothing running past its edge with 12 accounts of long names. PNGs in `.local/proof/inbox-accounts-step1/`.
- `tests/e2e/inbox-accounts-peek.spec.ts`: the compiled binary in Chromium: no shift in the foot across a slow read, the peek opened during it, the row's place, the amber at 90%, the peek and its block to Settings, login expired, the phone's sheet, and no Usage without `cswap`. PNGs in `.local/proof/inbox-accounts-step2/`.
- `tests/e2e/inbox-accounts-machines.spec.ts`: compiled Inboxes linked through the real CLI: one block per machine with five machines, "on <machine>" and the "Most room" hover from real far answers, the near machine in the peek, where focus lands on Tab and across a far answer, a slow machine moving nothing above it, a phone at 390, a machine asleep, and an older far side: a real one with `PLANNOTATOR_E2E_OLDER_BINARY` naming an older build; without one (CI) this build, with the window given the answer that door's refusal becomes. PNGs in `.local/proof/inbox-accounts-step3/`.

**Linear** (below the machines; `packages/inbox/components/LinearKeySettings.tsx`). One row for the key the Inbox's Linear hover cards use (see "Linear issues" in `inbox-window.md`), built like Settings → Voice's API key row: empty, a password field ("lin_api_…") and Save, with "Shows Linear issues when you hover their links. Kept on <computer>, never shown again."; 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" and nothing to paste. The key goes to `POST /api/inbox/linear/key` and is kept in `inbox/linear-key` (0600) on this computer; the page only ever learns its source and last 4. Set on the computer or over the tailnet's HTTPS. Not on a paired phone (Settings is not on the device door). Tests: `packages/server/inbox-linear-key.test.ts`.
1 change: 1 addition & 0 deletions docs/agent-guides/inbox-window.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
- Behaviour (`useRefHoverCards(rootRef)`, event delegation on the region, so `InlineMarkdown` is unchanged): opens on hover or `:focus-visible` focus after the delay; Tab from the focused link moves into the card, Shift+Tab from its first control back; a press inside pins it (`data-ref-card-pinned`: it stays when the pointer leaves, scrolls, shows Close); Escape (used, so the thread's own Escape skips it), Close or a press outside close it, focus back on the link when it was in the card; a page scroll closes an unpinned card and moves a pinned one; one card on the page at a time. On a touch screen (`(hover: none)`, or a touch pointer) a tap shows it as a bottom sheet instead of following the link (44 px targets, its scrim closes on click so the tap never lands underneath). The Inbox's `MessageBody` calls it on each body (`packages/inbox/components/Thread.tsx`).
- The seam: `configurePlannotatorUI({ refCardTransport })` / `setRefCardTransport` (`packages/ui/utils/refCard.ts`; the client keeps an answer 30 s per ref and shares one request between hovers). Default none: no card and no request, so every `@plannotator/ui` host that installs none is unchanged. Plan review, annotate and code review install one over their own `GET /api/ref` (see "Hover cards for #refs" in `guides-and-shared-ui.md`). The Inbox installs one over `GET /api/inbox/ref?url=` (`packages/inbox/App.tsx`), and turns on `refCardBitbucket` (`setRefCardBitbucket`): Bitbucket Cloud pull request links (`https://bitbucket.org/<workspace>/<repo>/pull-requests/N`) get a card there, read by the Inbox server through the review app's Bitbucket credentials (`fetchBbPRCard`, passed to `createRefCards` as its `bitbucket` reader). A Bitbucket read shares the CLIs' slots and has their limit (`bitbucketTimeoutMs`, default `REF_TIMEOUT_MS`): past it its requests are aborted, the slot is free again and the card answers `unavailable`; a `bitbucketTokenCommand` that never answers is killed with what it started (`CommandOptions.signal`) after `BITBUCKET_TOKEN_COMMAND_TIMEOUT_MS`. Off by default, so plan review, annotate, code review and other hosts keep Bitbucket links plain and ask nothing; a Bitbucket issue link never gets a card. The link parser and the card's data types are browser-safe in `@plannotator/core/forge-ref-card` (`parseForgeRefUrl`, `forgeRefKey`, `ForgeRefCardData`, `ForgeRefCardResult`).
- The fetch (`packages/server/ref-cards.ts`, `createRefCards`, reusable by any server): one read-only GraphQL `query` per ref through this computer's own CLI (the module refuses to load a non-query): GitHub `gh api graphql` (`issueOrPullRequest`, both kinds in one call); GitLab `glab api graphql` (`project.issue` or `project.mergeRequest` by the link's kind, since GitLab numbers them apart). Hosts: github.com and gitlab.com, plus the hosts this computer's own gh or glab is signed in to (`readSignedInHosts`: `gh auth status --json hosts`, a host counting only when an account there says `state: "success"`, else its text form, and `glab auth status`, read once per 5 min, `REF_AUTH_HOSTS_MS`; an answer with no host, as from a failed or timed-out `auth status`, only for 30 s, `REF_FAILURE_MS`), which covers GitHub Enterprise and self-managed GitLab; `--hostname <host>` is passed on every call, github.com and gitlab.com too, so `GH_HOST`, `GITLAB_HOST` or the working folder's git remote never pick the host; any other host answers `unsupported` without running anything, so a link or a cloned repo's origin naming `github.evil.example` can never make the CLI send `GH_ENTERPRISE_TOKEN` or `GITLAB_TOKEN` there. Owner and repo go as strings (`-f`; `-F` would turn a repo named `2048`, `true` or `null` into another type). GitHub accounts follow #2157's rule: the active account first; when GitHub refuses it (404/401/403/SAML), each other account signed in on that host is tried through its own token in `GH_TOKEN` (`GH_ENTERPRISE_TOKEN` on GHES) for that child only, and the account that could see a repo is remembered for it (memory only, never logged). Cache per ref: fresh 60 s (`REF_FRESH_MS`), a failure 30 s (`REF_FAILURE_MS`); a stale answer is served at once while one refresh runs, up to 15 min, and a failed refresh keeps it and holds off the next for 30 s; hovers of one ref share one request; at most 2 CLIs at once; a rate-limit answer pauses that host for 60 s (`REF_RATE_LIMIT_MS`); each CLI is killed after 8 s. Memory is bounded for the life of the Inbox: at most 500 refs (`REF_CACHE_MAX`) and 200 remembered repo accounts (`REF_REPO_ACCOUNTS_MAX`), least recently used dropped first; answers past 15 min, failures past 30 s and finished holds are dropped at the next fetch; at most 500 lookups wait for a CLI (`REF_MAX_WAITING`, above a Board request's 200 links), and one more answers `unavailable` at once without being cached. Avatars are fetched once from GitHub's avatar host, the GitLab host itself or Gravatar (64 KB, png/jpeg/gif/webp) and inlined as data URIs, since the window's CSP takes no remote image (at most 500 kept, `AVATAR_CACHE_MAX`, and 8 MB of data URIs in all, `AVATAR_CACHE_MAX_BYTES`).
- Linear issues (#3063, the Inbox only). With a Linear API key (pasted in Settings → Accounts → Linear, else `LINEAR_API_KEY`; see `inbox-accounts.md` and `environment.md`), a pasted `https://linear.app/<workspace>/issue/ENG-123` gets the same card behaviour, drawn by `LinearRefCardView` (`packages/ui/components/LinearRefCardView.tsx`; Linear's text as text, `htmlAsText`: a line that would open a raw HTML block or a directive (`:::question`, `:::note`), at the top level or behind quote, list or heading markers, is shown as code, so no raw HTML, no callout and no answerable question card comes from Linear; the renderer's own parse then checks every block that can hold others, and the whole text becomes one code block if anything would still get through): team, title, Linear's own workflow state name, colour and icon, author, priority, project, estimate, labels, assignee, the description, attached GitHub PRs ("Pull requests"), the latest comment, a comment count (Linear gives no total, so it stops at 100) and **Open in Linear ↗**. A bare `ENG-123` in prose becomes a link only when `ENG` is one of the workspace's team keys (`GET /api/inbox/linear-refs`; never inside code, a URL, a path or a longer word). Nothing is fetched on page load: the window asks for the teams once prose on screen first shows something shaped like an identifier, and a card is fetched only on hover or tap. The fetch (`packages/server/inbox-linear-cards.ts`, put in front of `createRefCards` by `withLinearCards`, so `/api/inbox/ref` answers it): one read-only GraphQL `query` POSTed to `api.linear.app` with the key as the `Authorization` header (never logged, never in an answer), the same cache rules as above; avatars only from `public.linear.app` / `static.linear.app`, fetched without the key. No key: nothing is fetched, no identifier links, and a Linear link's card says "Add your Linear API key in Settings → Accounts to see details here." (`NO_KEY_TEXT`, passed to the card as `noKeyText`; ui's own default names no Settings). A link to another workspace than the key's gets no card: the server answers it not found (cached per workspace), and once the window knows the key's workspace it stays a plain link. "Open in Linear" uses the issue's own link only when it is an https linear.app link. Saving or removing the key drops every card cached or still being fetched under the old key, and a key Linear refuses drops the card it had. Saving or removing the key also drops the window's cached cards and reads the teams again (`refreshLinearCards`). The window installs it through `@plannotator/ui/utils/refCardProviders` (`packages/inbox/linearCards.tsx`; see "Hover-card providers" in `packages/ui/README.md`); plan review, code review and annotate show no Linear cards. A test with its own `refRunner` gets no Linear source. Tests: `packages/server/inbox-linear-cards.test.ts`, `packages/inbox/linearCards.test.tsx`.
- Exposure: the window's read guard (another site's request is `403 cross_origin`), the owner's page over the tailnet like every read route, and never the device door (not in its allowlist), so phones and the relay never get a card or make this computer run a CLI. Tests: `packages/server/ref-cards.test.ts` (parsers for both forges, one request per ref, the cache and its bounds, the account fallback, rate limits, the errors, the route's guards and the door, Bitbucket through a stand-in reader), `packages/ui/utils/refCard.test.ts` (which links get a card: Bitbucket pull requests only with `refCardBitbucket`), `packages/ui/components/RefHoverCard.dom.test.tsx` (raw-HTML and `<details>` body links: click, middle click, Cmd or Ctrl-click, Enter), `tests/e2e/inbox-ref-cards.spec.ts` (compiled binary with a scripted `gh` and `glab` on PATH, `tests/e2e/fake-forge.ts`; `PLANNOTATOR_REF_CARD_SHOTS` keeps screenshots).
- The sidebar:
- The Tater mark (24 frames over 3.5 s, paused offscreen, the first frame under reduced motion). The sprite strip slides by `transform` inside a one-frame window (`.ib-tater` / `.ib-tater-strip` in `inbox.css`), so the compositor runs the loop and the page restyles about 8 times a second instead of 60; a `background-position` loop restyled the page 60 times a second while idle (#2593).
Expand Down
Loading