gh-glance 0.7.0 → 0.9.1

package/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-08-11
+
+### Fixed
+
+- **Package-boundary verification supports npm 12.** The release test accepts
+  both npm 11's array-shaped `npm pack --json` result and npm 12's
+  package-name-keyed result, so the existing OIDC publication workflow can
+  verify the CLI-only package boundary before publishing.
+
+## [0.9.0] - 2026-08-11
+
+### Added
+
+- **Security keeps a bounded priority view when newest pages fill.** Dependabot
+  and code-scanning sources add critical/high lanes only when their newest 100
+  open alerts fill the base page, then merge and de-duplicate the result. A `+`
+  marker stays explicit when any lane fills; the app never claims an unbounded
+  repository is complete.
+- **Adaptive polling now protects both GitHub budgets.** REST and GraphQL spend
+  are measured separately, including failed calls, and the safer interval wins
+  without lowering the configured refresh floor. `--doctor` reports the same
+  conservative model.
+- **Terminal state has explicit non-colour and linear-rendering channels.** A
+  stable ASCII `x` marks fetch failure, selected rows include `selected` in
+  their accessibility label, narrow errors begin with the recovery action, and
+  short help always retains Quit, Refresh, and the full-help command.
+- **PTY child-process coverage is available as an informational signal.**
+  `npm run test:coverage:runtime` summarizes observed `index.mjs` functions on
+  scheduled/manual coverage runs without adding a threshold or release gate.
+
+### Changed
+
+- **Dashboard recovery state is account-scoped and safe across panes.** Cache
+  version 2 includes `GH_CONFIG_DIR`/`hosts.yml` identity and one-way digests of
+  supported token variables, rejects the old unscoped cache, and uses bounded
+  locked three-way merges so simultaneous panes preserve unrelated targets,
+  tabs, and width choices. Successful quiet polls checkpoint freshness on a
+  bounded cadence.
+- **Settled automatic polling is visually quiet.** `Fetching` is reserved for
+  startup/manual work, unchanged Security observations slow to a 60-second
+  cadence, and cache-hydrated tabs clear their initial loading state.
+- **Mouse reporting is opt-in through Width mode.** Press `w` before dragging a
+  header divider; outside that mode the terminal keeps ordinary mouse behavior.
+- **The npm package is explicitly CLI-only.** The executable remains supported,
+  while package-root and deep JavaScript imports now fail through `exports: {}`.
+
+### Fixed
+
+- **Manual Security refresh now clears every source backoff after the in-flight
+  guard admits the request.** Re-authenticating and pressing `r` cannot leave a
+  previously failed source silently asleep.
+- **Concurrent persistence no longer loses a later update.** Same-target tabs
+  merge independently, and both cache and width writers adopt the merged disk
+  snapshot before their next save.
+- **Selections stay attached to visible items as lists change.** Insertions
+  above a row reconcile the viewport without opening a different item; a missing
+  item clears selection instead of selecting a replacement.
+- **Quitting aborts in-flight `gh ... view --web` children.** The app no longer
+  waits for a stalled browser-open command after terminal teardown begins.
+- **Row failures reset only when row content changes.** Unchanged parent renders
+  no longer clear an error boundary, while corrected data can recover in place.
+- **Status hints now describe only controls that can act.** Empty lists do not
+  advertise movement or opening, compact layouts do not advertise width mode,
+  and Security does not advertise an unsupported open action.
+
+## [0.8.0] - 2026-08-11
+
+### Added
+
+- **Last-known-good dashboard rows now survive process restarts.** Successfully
+  parsed Actions, Issues, Pull Requests, and Security state is stored in a
+  private, target-scoped cache. It retains five recent targets and 60 rows per
+  tab, ignores corrupt or unwritable state, and never stores credentials.
+
+### Changed
+
+- **Development tooling was refreshed.** The paired CodeQL actions now use
+  4.37.6, and the development-only `globals` lock entry is 17.9.0.
+
+### Fixed
+
+- **Status updates no longer accumulate old footer lines during prolonged rate
+  limiting.** The dashboard leaves the terminal's physical bottom row as a
+  scroll guard while preserving incremental rendering.
+- **Restarting during a live rate limit no longer shows an empty dashboard.**
+  Cached rows remain visible below the current error with an explicit `stale`
+  age, while repository targets remain isolated.
+- **Blind Security refreshes preserve known alerts.** A failed observation
+  cannot replace last-known-good Security rows with a false empty result, and an
+  identical healthy response clears the warning after recovery.
+
 ## [0.7.0] - 2026-08-10
 
 ### Added
@@ -621,7 +712,10 @@ engineering, security, QA and UX. What follows is what changed as a result.
 - The `main` field from `package.json`. It advertised the file as importable,
   but importing it took over the terminal or exited the host process.
 
-[Unreleased]: https://github.com/juan294/gh-glance/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/juan294/gh-glance/compare/v0.9.1...HEAD
+[0.9.1]: https://github.com/juan294/gh-glance/compare/v0.9.0...v0.9.1
+[0.9.0]: https://github.com/juan294/gh-glance/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/juan294/gh-glance/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/juan294/gh-glance/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/juan294/gh-glance/releases/tag/v0.6.1
 [0.6.0]: https://github.com/juan294/gh-glance/releases/tag/v0.6.0

package/README.md

@@ -30,19 +30,20 @@ without switching to the browser.
 │                                                                          │
 │                                                                          │
 ╰───────────────────────────────────────────────────────────────── 4 of 4 ─╯
-⣾ Fetching  Move: ↑↓ | Open: Ent | Refresh: r | Width: w | Quit: q     0.7.0
+⣾ Fetching  Move: ↑↓ | Open: Ent | Refresh: r | Width: w | Quit: q     0.9.1
 ```
 
 > Captured from a real run at 76 columns with `GH_GLANCE_ICONS=unicode`, so the
 > status icons render in a browser. With a Nerd Font (the default) they are
 > Octicon glyphs instead.
 >
-> The `>` on the first row is the cursor. Three more markers appear when they
+> The `>` on the first row is the cursor. Four more markers appear when they
 > apply: a `+` after a tab's count means the list was truncated by the fetch
 > limit, a `!` after the Actions count means the newest run failed — so "is CI
-> red" is answerable without switching to that tab — and a `?` in place of the
-> Security count means its endpoints could not be read, which is not the same
-> as there being nothing to report.
+> red" is answerable without switching to that tab — an `x` means the tab's
+> latest fetch failed, and a `?` in place of the Security count means its
+> endpoints could not be read, which is not the same as there being nothing to
+> report.
 
 <!-- contract:allow-emoji -- the check/cross above stand in for Nerd Font
      Octicons the app actually draws; they are literal examples, not decoration. -->
@@ -64,22 +65,23 @@ current.
 - **Issues** -- open issues: title, author, first label, age
 - **Pull Requests** -- open PRs: title, author, branch, review status
   (approved / changes requested / pending), age
-- **Security** -- open Dependabot alerts: package, summary, age, sorted with the
-  most severe first and with severity spelled out in its own column, not carried
-  by colour alone. One page of 100 newest alerts is fetched and ranked, so on a
-  repository with more open alerts than that the ranking covers the newest 100
-  rather than everything -- the `+` marker on the count is what tells you.
-  Code scanning and secret scanning alerts are included too, on repos/plans
-  that have GitHub Advanced Security enabled -- see [Limitations](#limitations).
+- **Security** -- open Dependabot, code-scanning, and secret-scanning alerts,
+  sorted with the most severe first and with severity spelled out rather than
+  carried by colour alone. Each source starts with its newest 100 open alerts.
+  When that page is full, Dependabot and code scanning also fetch bounded
+  critical/high priority lanes before merging and de-duplicating the result.
+  The `+` marker means at least one bounded lane filled, so the visible priority
+  set may still be incomplete. Code and secret scanning require GitHub Advanced
+  Security -- see [Limitations](#limitations).
 - Tab bar with live counts, pinned to the top of the pane above a divider,
   switchable via `1`-`4`, arrow keys, or `Tab`/`Shift+Tab`
 - Adjustable full-table columns, with visible header grips, a keyboard width
   mode, and preferences kept separately for each tab
 - `lazygit`-style panel frame: the tab name sits in the top border, the
   visible-of-total row count in the bottom
-- A `Fetching` indicator that brightens on every refresh and animates during the
-  first load or while a workflow run is executing, so the pane says when it's
-  working without spending a line on it
+- A `Fetching` indicator that brightens while a tab's first request is settling
+  or during a manual refresh. Settled automatic polls do not flash it; the
+  spinner still animates during first load or while a workflow run is executing
 - Status icons are real GitHub Octicons (via the Nerd Font glyph set), not emoji
   -- with a plain-ASCII fallback for terminals without one
 - Readable without colour: severity has its own column, a failing newest run puts
@@ -90,10 +92,13 @@ current.
   answers "is CI red" without colour
 - Says when it is stale rather than showing old data silently, and marks a tab
   whose last refresh failed
+- Keeps the last successfully parsed rows visible during temporary failures and
+  across a restart, scoped to the repository being watched
 - Adapts row count to the terminal pane's height live, on resize
 - Enters the terminal's alternate screen buffer on launch (like `lazygit`,
   `htop`, `vim`) so the shell prompt that launched it stays out of view, and
-  is restored cleanly on exit
+  is restored cleanly on exit without old status lines accumulating below the
+  frame
 
 ## Prerequisites
 
@@ -116,6 +121,10 @@ That is the whole install. `gh-glance` ships as a single `index.mjs` with no
 build step, so there is nothing to compile and nothing to configure -- the
 package is the source you can read in this repository.
 
+The installed package is a CLI, not a JavaScript library. The `gh-glance`
+executable is supported; package-root and deep imports are intentionally
+blocked so an internal test seam cannot become an accidental public API.
+
 Every published version is built and signed by GitHub Actions from a tagged
 commit on `main`, never from a maintainer's laptop, and carries [npm
 provenance](https://docs.npmjs.com/generating-provenance-statements) linking
@@ -260,14 +269,15 @@ line such as:
 Width: BRANCH 14  Tab select  <- -> resize  r reset  Esc done
 ```
 
-In an interactive terminal, you can also left-drag a visible `│` header grip.
-Pressing a grip selects its column and enters width mode; releasing the button,
-including outside the header, ends the drag. Row clicking, hover behavior, and
-pointer-shape changes are not supported. Mouse resizing has the same interactive
-terminal requirement as keyboard input.
+After pressing `w`, you can also left-drag a visible `│` header grip. Mouse
+reporting is enabled only while width mode owns the input, so a click outside
+that mode does not enter it. Releasing the button, including outside the header,
+ends the drag. Row clicking, hover behavior, and pointer-shape changes are not
+supported.
 
-While gh-glance is running, terminal-native text selection may require your
-terminal's mouse-reporting bypass modifier, commonly `Shift`.
+While width mode is active, terminal-native text selection may require your
+terminal's mouse-reporting bypass modifier, commonly `Shift`. Outside width
+mode, gh-glance leaves mouse reporting disabled.
 
 The cursor tracks the *item*, not the row position, so it stays on what you
 selected as new rows arrive above it. `Enter` works on Actions, Issues and Pull
@@ -313,12 +323,13 @@ Environment variables work too, and the flags take precedence:
 |---|---|
 | `GH_REPO=owner/name` | Watch a specific repository instead of the current directory's. A host-qualified `GH_REPO` does **not** route the security-alert endpoints -- use `GH_HOST` or `--repo host/owner/name` for that |
 | `GH_HOST=<host>` | Send every call to a GitHub Enterprise or EMU host instead of `github.com`. Routes both the list commands and the alert endpoints |
-| `GH_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GH_CONFIG_DIR` | Not read by `gh-glance` -- passed through to `gh` untouched, along with the proxy variables. `gh-glance` handles no credentials of its own. Separate `GH_CONFIG_DIR` values can isolate simultaneous panes on different accounts; see [No account pinning](#limitations) |
+| `GH_TOKEN`, `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN` | Used by `gh`. gh-glance never logs or stores these values, but hashes each set value locally as part of the account-scoped cache namespace so panes with different credentials cannot hydrate each other's rows. The raw values are not written to disk. |
+| `GH_CONFIG_DIR` | Selects `gh`'s account configuration and contributes its normalized identity to the cache namespace. Separate values can isolate simultaneous panes on different accounts; see [No account pinning](#limitations). |
 | `GH_GLANCE_REFRESH=<seconds>` | Active-tab poll interval, 2-3600. Sets it once for every pane in a shell; `--refresh` takes precedence. This is a floor -- see [Rate limit](#rate-limit) |
 | `GH_GLANCE_ICONS=unicode` | Plain ASCII status icons, for terminals without a Nerd Font |
 | `GH_GLANCE_NO_ANIMATION=1` | Freeze the spinner — no motion at all |
 | `NO_COLOR=1` | Disable colour. Status stays readable: severity has its own column, a failing newest run puts a `!` on the Actions tab, and the active tab is bracketed. Note that run-state glyphs are not all distinct -- see the feature list above |
-| `INK_SCREEN_READER=true` | Switch the renderer to a linear, unthrottled mode. The status icons carry text labels for it, but this path has not been tested against a real screen reader — treat it as unverified rather than supported. |
+| `INK_SCREEN_READER=true` | Switch the renderer to a linear, unthrottled mode. Automated PTY coverage checks that status and selection labels reach this Ink path, but it has not been validated with real assistive technology — treat it as automated rendering coverage, not claimed screen-reader support. |
 
 ### Saved column widths
 
@@ -344,6 +355,37 @@ the live session and width mode reports `Widths not saved`; a later successful
 write clears the warning. The UI owns this file, so direct editing is not the
 primary configuration workflow.
 
+### Last-known-good dashboard cache
+
+Successfully parsed dashboard rows are also saved automatically, in
+`dashboard-cache.json` beside `preferences.json`:
+
+```text
+$XDG_CONFIG_HOME/gh-glance/dashboard-cache.json
+~/Library/Application Support/gh-glance/dashboard-cache.json
+~/.config/gh-glance/dashboard-cache.json
+```
+
+The cache is scoped to the repository, host, and effective `gh` account
+namespace. In inferred mode, the host and current working directory also form
+the identity, so rows from one checkout or credential context cannot appear in
+another. The namespace uses `GH_CONFIG_DIR`/`hosts.yml` identity plus one-way
+digests of supported token environment variables; raw credentials are never
+stored. It retains at most five recent targets and 60 rows per tab; a shortened
+cached tab keeps its `+` marker rather than presenting the saved count as exact.
+
+Only successfully parsed, non-blind observations replace saved rows. A failed
+request can add a live error or `?` marker, but it cannot turn known Security
+alerts or other last-known-good rows into an empty result. Missing, corrupt,
+unknown-version, or unwritable cache state is ignored rather than blocking the
+dashboard. On POSIX systems, gh-glance restricts its config directory to `0700`
+and the cache file to `0600`. The file contains repository data, including
+titles, authors, branches, and Security findings, but never GitHub credentials.
+Both persistence files use a bounded advisory lock before atomic replacement.
+The cache merges independent targets and tabs, while preferences merge columns,
+so simultaneous panes do not overwrite one another's unrelated state. It is
+recovery state owned by the UI, not a configuration interface.
+
 ## GitHub Enterprise and EMU
 
 **The common case needs no configuration.** Authenticate once --
@@ -387,9 +429,9 @@ Collects, in one plain-text block: the `gh-glance`, Node and `gh` versions;
 which hosts `gh` is authenticated for; how the repository target resolved and
 from where; your remaining REST and GraphQL budget plus what this configuration
 will spend per hour; the relevant environment variables; a read-only
-`Repository access` probe; and one probe per dashboard endpoint with the exact
-argv it sent, its outcome, and how any error was classified (`unavailable`,
-`rate-limited`, `auth-problem` or `other`).
+`Repository access` probe; and each bounded dashboard probe, including the
+Security priority lanes, with the exact argv it sent, its outcome, and how any
+error was classified (`unavailable`, `rate-limited`, `auth-problem` or `other`).
 
 The `Repository access` probe shows whether the target resolves for the active
 `gh` credentials. A failed GitHub resolution response cannot distinguish a
@@ -424,17 +466,18 @@ through GraphQL instead — a separate 5,000/hour allowance. With the default
 
 | Visible tab | REST / hour | GraphQL / hour |
 |---|---|---|
-| Actions | ~1,620 | ~240 |
-| Issues or Pull Requests | ~300 | ~1,560 |
-| Security | ~2,280 | ~240 |
-
-Security is the most expensive, because it is three endpoints rather than one,
-and watching it costs just under half the REST budget. But Actions is not cheap
-either -- it is a third of the budget, and it is the tab every pane opens on,
-because one `gh run list` issues two REST requests rather than one. You do not
-have to take these figures on trust: `gh-glance --doctor` reports your actual
-remaining budget alongside what your configuration projects, which matters on a
-GitHub Enterprise tenant where the ceiling may not be 5,000 at all.
+| Actions | up to ~1,800 | ~240 |
+| Issues or Pull Requests | up to ~480 | ~1,560 |
+| Security | ~2,280 normally; up to ~4,440 | ~240 |
+
+Security is the most expensive. A repository whose newest alert pages are not
+full uses the three base endpoint calls and lands near 2,280 REST requests per
+hour. A full page activates bounded critical/high lanes for Dependabot and code
+scanning, raising the safe projection to about 4,440. Actions is not cheap
+either: one `gh run list` issues two REST requests. `gh-glance --doctor` reports
+the conservative projection beside the server's actual REST and GraphQL
+budgets, which matters on a GitHub Enterprise tenant where the ceilings may not
+be 5,000.
 
 Two things pull the real number down. Any endpoint that fails in a way
 `gh-glance` recognises backs off instead of being re-asked every tick — a
@@ -443,6 +486,13 @@ hour, an authorization failure every 30 seconds, a rate limit every minute.
 Pressing `r` clears that backoff and retries immediately. And `--refresh`
 scales the whole figure: doubling the interval halves it.
 
+When a refresh fails, the last successful rows stay visible below the live
+error instead of disappearing. If gh-glance is restarted while GitHub is still
+rate-limiting, it loads the saved rows for that same target immediately. Their
+age remains explicit through the `stale` label, and the rate-limit banner still
+describes the current failed request; cached data never turns a failure into a
+false success.
+
 One pane on Actions costs about a third of an hourly REST budget, so roughly
 three panes fill it. Past that, `gh-glance` widens its own poll interval: it
 reads your remaining budget once a minute, works out how much of it belongs to
@@ -458,7 +508,6 @@ a single pane on a healthy budget stays at 5 seconds and shows no badge.
 
 ## Limitations
 
-
 - **Security tab**: code scanning and secret scanning alerts require [GitHub
   Advanced Security](https://docs.github.com/en/code-security/getting-started/github-security-features).
   On repos/plans without it, `gh-glance` doesn't crash or spam errors -- it
@@ -490,12 +539,13 @@ a single pane on a healthy budget stays at 5 seconds and shows no badge.
   has its own breakpoint and drops to bare keys (`↑↓ Ent r q`) rather than
   truncating.
 - **Mouse reporting lifecycle.** Interactive sessions enable terminal mouse
-  reporting for header drags and disable it before handing the terminal back.
-  See [Adjusting column widths](#adjusting-column-widths) for text-selection
-  behavior while it is active.
-- Issues and pull requests are fetched 150 at a time and alerts 100 at a time.
-  A count is shown as `n+` when it was truncated, so the number is never
-  presented as exact when it is not.
+  reporting only after `w` enters width mode, and disable it when that mode or
+  the app exits. See [Adjusting column widths](#adjusting-column-widths) for
+  text-selection behavior while it is active.
+- Issues and pull requests are fetched 150 at a time. Each Security source has
+  a newest-100 lane; full Dependabot and code-scanning pages activate bounded
+  priority lanes. A count is shown as `n+` when any lane fills, so the number is
+  never presented as exact when it is not.
 - The Actions **TIME** column measures from the run's start to its last update.
   `gh` exposes no completion timestamp, so a workflow that was re-run later
   reports the span up to the re-run rather than its original duration.
@@ -544,7 +594,7 @@ in some terminals, which would shift every column to their right.
 | Security tab shows `?` instead of a number | The alert endpoints could not be read at all -- an expired SAML session, a token without `security_events`, or an org OAuth restriction. `?` means "unknown", not "zero"; run `gh-glance --doctor` to see which probe failed and how it was classified. |
 | A failing tab seems to have stopped retrying | It backs off deliberately, rather than re-spawning `gh` every five seconds against an endpoint that is refusing. Press `r` to clear the backoff and retry now. |
 | `unknown argument: -v` | `-v` used to mean `--version` and no longer does, because this CLI also has `--verbose`. Use `--version` or `--verbose` explicitly. |
-| `stale 2m` in the status bar | The visible tab has not refreshed successfully for a while — usually a network drop. |
+| `stale 2m` in the status bar | The visible tab has not refreshed successfully for a while — usually a network drop or rate limit. Last-known-good rows can remain visible, including after restart; the live error above the table explains why they are stale. |
 | It exits immediately when piped | Intentional. It is a full-screen dashboard, not a reporting command. |
 | It stopped updating and you cannot tell why | Run `gh-glance --verbose 2>gh-glance.log`, reproduce, then read the log: one line per `gh` call with its duration and outcome. It is redacted the same way `--doctor` is, so it is safe to attach to a bug report. `--doctor --verbose` logs the probes too. |
 | `--verbose` refuses to start | stderr is still your terminal, where the log would draw over the dashboard. Redirect it to a file. |