gh-glance 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **Full-table columns can be resized with a mouse or keyboard.** Visible header
+  grips support left-button dragging, while `w` opens a keyboard width mode for
+  one- and five-cell adjustments and selected-column or active-tab resets.
+- **Width choices persist automatically per user and per tab.** Only deviations
+  from the built-in defaults are stored, so resetting a column or tab cleanly
+  returns it to the source-controlled layout.
+- **`gh-glance` now widens its own poll interval when the API budget is
+  draining.** The rate limit is per token, not per process, so several panes
+  spent one budget while each throttled as though it were alone: seven panes
+  exhausted a 5,000/hour REST limit in under half an hour (measured 8,500
+  calls/hour). Each pane now reads `gh api rate_limit` once a minute -- a probe
+  that does not itself count against the limit -- infers how much of the budget
+  is its own by comparing its spend against the token's total, and slows down to
+  fit, up to a 60-second ceiling. A single pane is unaffected and stays at 5
+  seconds. The status bar shows `throttled 18s` whenever the interval has
+  widened, and `r` still refreshes immediately.
+- **`GH_GLANCE_REFRESH` sets the poll interval for every pane in a shell.** Same
+  2-3600 second range as `--refresh`, which still takes precedence.
+
+### Changed
+
+- **Oversized saved widths fit safely in narrower panes.** They are temporarily
+  reduced toward the defaults when the stock full table fits, without changing
+  the saved preference; widening the pane restores the preferred widths.
+- **Terminal mouse reporting is released on every cleanup path.** Clean quit,
+  signals, crashes, and the interactive remote-setup handoff disable button and
+  SGR reporting before the primary screen is restored.
+
+### Fixed
+
+- **The cost model understated the Actions tab by half.** `gh run list` issues
+  two REST requests, not one -- `GET /actions/runs` and
+  `GET /actions/workflows` -- so a pane on Actions costs about 1,620 requests an
+  hour rather than the 900 `--doctor` reported, and roughly three panes fill an
+  hourly budget rather than five. The figure was wrong in `--doctor`, in the
+  README's per-tab table, and in ADR 0001's request count. Measured with
+  `GH_DEBUG=api`; the projection and the new throttle now read one shared table.
+- **`--doctor` reads the API budget from the right server.** `gh api rate_limit`
+  was the one `gh api` call sent without `--hostname`, so with
+  `--repo host/owner/name` the reported budget came from github.com while every
+  other call went to the tenant. A rate limit is per token *per server*, so the
+  two figures belong to unrelated limits.
+
 ## [0.6.1] - 2026-08-06
 
 ### Security
@@ -574,6 +647,9 @@ 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.8.0...HEAD
+[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
 [0.5.1]: https://github.com/juan294/gh-glance/releases/tag/v0.5.1

package/README.md

@@ -21,16 +21,16 @@ without switching to the browser.
 [1:Actions (4)]   2:Issues (3)    3:PRs (2)    4:Security (0)
 ────────────────────────────────────────────────────────────────────────────
 ╭─ Actions ────────────────────────────────────────────────────────────────╮
-│     TITLE                    WORKFLOW   BRANCH         TIME    UPDATED   │
+│     TITLE                   │WORKFLOW  │BRANCH        │TIME   │UPDATED   │
 │ ──────────────────────────────────────────────────────────────────────── │
-│ >+  ci: pin actions to comm… #443 CI    develop        1m20s   2d ago    │
-│  x  fix: restore the primar… #442 Code… develop        1m28s   2d ago    │
-│  !  chore: bump dependencies #441 CI    dependa…int-10 56h49m  2d ago    │
-│  -  docs: update the readme  #440 CI    develop        15s     3d ago    │
+│ >+  ci: pin actions to comm… #443 CI    develop        1m20s   9d ago    │
+│  x  fix: restore the primar… #442 Code… develop        1m28s   9d ago    │
+│  !  chore: bump dependencies #441 CI    dependa…int-10 222h8m  9d ago    │
+│  -  docs: update the readme  #440 CI    develop        15s     10d ago   │
 │                                                                          │
 │                                                                          │
 ╰───────────────────────────────────────────────────────────────── 4 of 4 ─╯
-⣾ Fetching  Move: ↑↓ | Open: Ent | Refresh: r | Quit: q
+⣾ Fetching  Move: ↑↓ | Open: Ent | Refresh: r | Width: w | Quit: q     0.8.0
 ```
 
 > Captured from a real run at 76 columns with `GH_GLANCE_ICONS=unicode`, so the
@@ -73,6 +73,8 @@ current.
   that have GitHub Advanced Security enabled -- 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
@@ -88,10 +90,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
 
@@ -230,8 +235,42 @@ stdout isn't a terminal rather than streaming redraw frames into a pipe.
 | `PgUp` / `PgDn` | Move a page at a time |
 | `Enter` | Open the selected item, or accept an onboarding prompt |
 | `r` | Refresh the current tab now |
+| `w` | Adjust table column widths |
 | `?` | Show the keys without leaving the dashboard (any key closes it) |
-| `q` / `Esc` / `Ctrl+C` | Quit |
+| `q` / `Esc` / `Ctrl+C` | Quit (`Esc` leaves width mode) |
+
+### Adjusting column widths
+
+Press `w` to adjust the named fixed-width columns in the visible full table.
+The flexible **TITLE** or **SUMMARY** column, status and severity cells, and
+compact layouts are not adjustable. Outside width mode, the normal arrow,
+`Tab`, `Enter`, and refresh meanings above are unchanged.
+
+| Key | In width mode |
+|---|---|
+| `Tab` / `Shift+Tab` | Select the next / previous adjustable column |
+| `←` / `→` | Resize the selected column by one cell |
+| `Shift+←` / `Shift+→` | Resize the selected column by five cells |
+| `r` | Reset the selected column to its default |
+| `R` | Reset every width on the active tab |
+| `Enter` / `Esc` / `w` | Finish and leave width mode |
+| `q` / `Ctrl+C` | Quit globally |
+
+While the mode is active, the ordinary status hints are replaced by a bounded
+line such as:
+
+```text
+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.
+
+While gh-glance is running, terminal-native text selection may require your
+terminal's mouse-reporting bypass modifier, commonly `Shift`.
 
 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
@@ -278,11 +317,62 @@ 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_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. |
 
+### Saved column widths
+
+Width choices are saved automatically, globally for the current user and
+separately for each tab. They are not repository-specific. Only deviations from
+the built-in defaults are stored: `r` removes the selected column's deviation,
+and `R` removes every deviation for the active tab.
+
+The versioned preference file is resolved in this order:
+
+```text
+$XDG_CONFIG_HOME/gh-glance/preferences.json              absolute XDG root
+~/Library/Application Support/gh-glance/preferences.json macOS fallback
+~/.config/gh-glance/preferences.json                     Linux fallback
+```
+
+`XDG_CONFIG_HOME` is used only when it is a non-empty absolute path. An unknown
+file version or a corrupt, malformed, or unreadable document falls back to the
+built-in defaults rather than preventing the dashboard from starting. Within an
+otherwise valid document, unknown or invalid entries are ignored individually
+while valid deviations still load. If a write fails, resizing still works for
+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 and host being watched. In inferred mode,
+the host and current working directory form the identity, so rows from one
+checkout cannot appear in another. 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 complete.
+
+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.
+It is recovery state owned by the UI, not a configuration interface.
+
 ## GitHub Enterprise and EMU
 
 **The common case needs no configuration.** Authenticate once --
@@ -363,15 +453,17 @@ through GraphQL instead — a separate 5,000/hour allowance. With the default
 
 | Visible tab | REST / hour | GraphQL / hour |
 |---|---|---|
-| Actions | ~900 | ~240 |
-| Issues or Pull Requests | ~240 | ~1,560 |
-| Security | ~2,220 | ~240 |
-
-Security is the expensive one because it is three endpoints rather than one,
-and watching it costs just under half the REST budget. 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 | ~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.
 
 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
@@ -380,9 +472,25 @@ 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.
 
-So a pane left open all day shares the budget with your other `gh` commands
-rather than exhausting it, but it is not free, and parking it on the Security
-tab is the case worth knowing about.
+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
+this pane by comparing its own spend against the token's total, and slows down
+to fit -- up to a 60-second ceiling. The status bar says `throttled 18s` while
+that is in effect, and `r` still refreshes immediately. Nothing is shared
+between panes: the token's own counter is what they all read, so it also notices
+a `gh pr checks --watch` or anything else spending on the same token.
+
+`GH_GLANCE_REFRESH=30` sets a wider floor for every pane in a shell; `--refresh`
+still wins per pane. The adaptive interval only ever widens from that floor, so
+a single pane on a healthy budget stays at 5 seconds and shows no badge.
 
 ## Limitations
 
@@ -406,13 +514,21 @@ tab is the case worth knowing about.
   runs requested -- so scrolling that tab has little to move through. The count
   in the bottom edge always says how much you are seeing out of how much was
   fetched.
-- **Minimum width.** Each tab drops to a compact layout (icon, title, and one
-  other column) at its own threshold, so a narrow pane keeps as much as that
-  particular tab can fit: Security holds its full set down to 44 columns,
-  Issues to 50, Actions to 56, Pull Requests to 61. Below 24 columns nothing
-  useful fits, so the pane says `too narrow` and keeps the frame, tab bar and
-  quit hint; widening it recovers immediately. The status bar has its own
-  breakpoint and drops to bare keys (`↑↓ Ent r q`) rather than truncating.
+- **Minimum width and compact layout.** Compact descriptors remain fixed and
+  non-adjustable. With the built-in full widths, Security fits down to 44
+  columns, Issues to 50, Actions to 56, and Pull Requests to 61. A narrower
+  preference can lower the active tab's full-layout floor. An oversized
+  preference is fitted temporarily toward the defaults as the pane narrows, so
+  it never forces compact while the stock full table still fits. The saved width
+  itself is not changed, and widening restores it. When no eligible full layout
+  fits, the active tab uses its fixed compact layout. Below 24 columns the pane
+  says `too narrow` and keeps the frame, tab bar and quit hint. The status bar
+  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.
@@ -464,7 +580,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. |