projmux 0.4.5 → 0.4.7

package/docs/testing.md

@@ -0,0 +1,57 @@
+# Testing
+
+The local validation contract is exposed through make targets so CI, agents,
+and humans run the same entrypoints.
+
+## Targets
+
+- `make test` runs the fast Go unit suite. These tests avoid tmux, TTY, GUI,
+  and host shell dependencies.
+- Picker unit coverage includes the backend-neutral item/action contract, fzf
+  adapter mapping, native title-focused filtering, numeric selection, and
+  shared close actions.
+- `make test-integration` builds `test/docker/Dockerfile` and runs
+  `test/integration/linux-smoke.sh` in Docker. It validates Linux dependency
+  discovery, tmux config generation/install, app config reload against a real
+  `tmux` server, and notify queue CRUD.
+- `make test-install-smoke` builds the same Docker image and runs
+  `test/install/smoke.sh`. It validates `make install`, atomic binary
+  replacement into an isolated install dir, `tmux apply`, and post-install
+  `notify reconcile` initialization with a fresh HOME/XDG state tree.
+- `make test-e2e` builds the same Docker image and runs
+  `test/e2e/linux-smoke.sh`. It validates a minimal real-tmux workflow:
+  sessions, panes, config sourcing, reply-state notify reconciliation, focus
+  notify fallback, and status notify rendering.
+
+## Docker-Covered Checks
+
+The Docker suites are intended to cover portable Linux behavior that can be
+made deterministic in a container:
+
+- binary build and source install into an isolated prefix
+- `doctor` dependency checks for `tmux`, `fzf`, `git`, and `stty`
+- tmux config print/install/apply paths
+- notify queue push/list/ack/reconcile state transitions
+- focus fallback behavior when a tmux server has sessions but no attached
+  client
+- status rendering that only depends on tmux state and local files
+
+The test container disables networking during `docker run`. The image build may
+use the network to fetch the pinned base image, apt packages, and pinned fzf
+version, but suite execution should not need network access after the image is
+built.
+
+## Host-Only Checks
+
+The Docker suites do not replace checks that depend on a real host terminal,
+desktop shell, or OS integration:
+
+- terminal emulator key delivery and swallowing for `Alt-1..5`, `Ctrl-N`, and
+  CSI-u chords
+- Windows Terminal and WSL interop
+- macOS host path, shell, and GUI behavior
+- desktop notification click callbacks
+- terminal-specific popup rendering and interactive key dispatch
+
+Keep those checks as manual or host-run smoke validation until a dedicated
+host harness exists.

package/docs/upgrading.md

@@ -0,0 +1,100 @@
+# Upgrading
+
+projmux has two update surfaces:
+
+- `projmux shell` reads the cached release status before opening the app. When
+  the cache is fresh and a newer release is available, startup shows a picker
+  with Update Now, Later, and Skip This Version actions.
+- Settings > About > Update shows the current version, detected installer,
+  cached latest version, Check Updates, and Update Now actions.
+
+Startup never reaches the network. Refresh the cache explicitly when you want
+projmux to check GitHub Releases:
+
+```sh
+projmux update check
+```
+
+Apply the cached update through the detected installer:
+
+```sh
+projmux update apply
+```
+
+Use `--dry-run` to see the planned action and `--no-apply` to skip reloading
+the live tmux config after the binary changes.
+
+## npm Installs
+
+The recommended install path is:
+
+```sh
+npm install -g projmux
+```
+
+For npm-managed installs, `projmux update apply` runs:
+
+```sh
+npm update -g projmux
+projmux tmux apply
+```
+
+The npm shim sets `PROJMUX_INSTALLER=npm` so projmux can detect this path
+automatically. You can also update manually with `npm update -g projmux`.
+
+## Go Installs
+
+If you installed with `go install`, `projmux update apply` delegates to the
+same atomic replacement flow as `projmux upgrade`:
+
+```sh
+projmux upgrade                                  # @latest, replace + apply
+projmux upgrade --ref @v0.4.0                    # pin a specific tag
+projmux upgrade --ref @main                      # track a branch
+projmux upgrade --target /usr/local/bin/projmux  # replace another path
+projmux upgrade --no-apply                       # skip 'projmux tmux apply'
+projmux upgrade --dry-run                        # print the steps only
+```
+
+`projmux upgrade` reinstalls via `go install`, atomically replaces the active
+file, and reapplies the live tmux config so a running `-L projmux` server picks
+up new bindings without a restart.
+
+The command reads `PROJMUX_PROJDIR` from the calling shell and memoizes the
+primary path to `~/.config/projmux/projdir`, so the new binary keeps the same
+project root context as the one it replaces.
+
+To switch the saved project root during the upgrade:
+
+```sh
+PROJMUX_PROJDIR=/new/path projmux upgrade
+
+# Multi-path also works; only the primary entry is persisted.
+PROJMUX_PROJDIR="/main/repos:/secondary/repos" projmux upgrade
+```
+
+## GitHub Release Installs
+
+When `PROJMUX_INSTALLER=github-release`, `projmux update apply` downloads the
+latest matching `projmux_<version>_<goos>_<goarch>.tar.gz` asset from GitHub
+Releases, extracts the binary, atomically replaces the current executable, and
+then runs `projmux tmux apply` unless `--no-apply` is set.
+
+Set the installer explicitly if you manage a release binary outside npm or Go:
+
+```sh
+export PROJMUX_INSTALLER=github-release
+```
+
+## Source Checkouts
+
+Source installs are updated from the checkout:
+
+```sh
+git pull --ff-only
+make install
+```
+
+`projmux update apply` reports an actionable error for
+`PROJMUX_INSTALLER=source` because source trees may have local changes and need
+the repository's normal review and test flow.

package/docs/usage-tracking.md

@@ -0,0 +1,153 @@
+# Usage tracking
+
+`projmux usage` and `projmux status usage` report authoritative 5-hour
+and weekly utilisation for both Claude Code and the Codex CLI. Both
+adapters read from the upstream's own view of the account so the
+percentages match what `claude /usage` and `codex` show natively.
+
+## Adapters
+
+### Claude (`internal/core/usage/adapters/claude`)
+
+OAuth-authenticated HTTPS fetch:
+
+- `GET https://api.anthropic.com/api/oauth/usage` with the bearer token
+  read from `~/.claude/.credentials.json`.
+- On HTTP 401 the adapter performs a single refresh round-trip:
+  `POST https://api.anthropic.com/api/oauth/token` with the stored
+  refresh token, then rewrites `.credentials.json` with the rotated
+  access/refresh pair before retrying the usage call.
+- Tokens are never logged.
+
+Throttle: 5 minutes (`ThrottleHinter`). The `60s` cadence used in 0.3
+trips 429 in practice, so the adapter raises the manager's per-adapter
+floor.
+
+429 backoff (`BackoffStater`):
+
+- Base `30m`, doubling per consecutive 429, cap `60m`.
+- A `Retry-After` header (when ≥ 60s) raises the floor.
+- During backoff `Collect` short-circuits — no network call, prior
+  rows are preserved.
+- A clean 200 resets the consecutive counter.
+- `--force` (BackoffResetter) clears the persisted state and attempts
+  the call regardless of streak.
+
+### Codex (`internal/core/usage/adapters/codex`)
+
+Local rollout JSONL parser. No network calls.
+
+- Walks `${HOME}/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl`
+  newest-first by mtime (NOT filename — Dropbox-synced rollouts can
+  arrive out of order).
+- Caps the search to 8 days back so a stale tree never blocks the
+  status interval.
+- Parses each line until it finds the latest `token_count` record's
+  `rate_limits` payload:
+  ```json
+  {
+    "limit_id": "codex",
+    "primary": { "used_percent": 8.0, "resets_at": "..." },
+    "secondary": { "used_percent": 4.5, "resets_at": "..." }
+  }
+  ```
+- `primary` → 5h window, `secondary` → weekly window.
+
+Codex shares the manager's default `30s` throttle (no
+`ThrottleHinter`). It does not implement `BackoffStater` — local-only
+read.
+
+## Snapshot store
+
+```
+${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/snapshots.json
+```
+
+JSON document keyed by adapter, recording:
+
+- per-window `Snapshot{Model, Window, Pct, Limit, ResetsAt, UpdatedAt}`
+- per-adapter `last_collect` timestamp (drives the throttle)
+- per-adapter `Backoff{Until, Consecutive}` (drives the cooldown)
+
+Adapter failures merge over the prior slice rather than replacing it,
+so a 429 keeps the last known good rows visible. Force-redirect the
+file at install time via `PROJMUX_USAGE_STATE_DIR` to share the cache
+across machines (Dropbox, iCloud Drive).
+
+## CLI
+
+### `projmux usage`
+
+```
+projmux usage [--model codex|claude|all] [--window 5h|weekly|all]
+              [--json] [--force|-f]
+```
+
+Calls `Manager.Collect` (or `ForceCollect` with `--force`), filters by
+model/window, and renders the tab-aligned table:
+
+```
+MODEL   WINDOW  PCT   RESETS_AT                STALE
+claude  5h      80%   2026-05-07T14:00:00+09:00
+claude  weekly  35%   2026-05-09T00:00:00+09:00
+codex   5h      8%    2026-05-07T11:30:00+09:00
+codex   weekly  4%    2026-05-09T00:00:00+09:00
+```
+
+`STALE` is `*` when `now - UpdatedAt > 10m`. A `--json` payload returns
+the `Snapshot` array; if any adapter is in backoff, the wrapper
+`{snapshots, backoff: {model: {until, consecutive}}}` is emitted
+instead. A backoff note is appended to the human table:
+
+```
+claude is in backoff, try again in 30m (use --force to bypass)
+```
+
+### `projmux status usage`
+
+```
+projmux status usage [--max-width N] [--force|-f]
+```
+
+The HUD bar wired to the tmux status interval. Triggers an
+opportunistic refresh: `MaybeCollect(throttle=30s)` (subject to
+per-adapter throttle and active backoff). Errors are swallowed unless
+`PROJMUX_USAGE_DEBUG` is set. Then loads the cache and renders.
+
+Output degrades through six tiers as `--max-width` shrinks:
+
+1. Long form with last-sync age + bars: `Claude (3m) 5h [████████░░]
+   80% · weekly [...]   Codex 5h [...] 20% · weekly [...]`
+2. Drop the age indicator (legacy long form).
+3. Drop the weekly bar.
+4. Drop bars entirely (`Claude 5h:80% weekly:30%`).
+5. Single-letter labels (`C 5h:80% weekly:30%`).
+6. Hard rune-truncate with trailing `…`.
+
+The age indicator's colour ramps with staleness: dim grey
+(<1h), yellow (1–6h), bold red (≥6h). Codex opts out of the indicator
+because the rollout file is always near-current (no throttle gap to
+report).
+
+## Force semantics
+
+`--force` / `-f` does two things:
+
+1. Bypasses the per-adapter throttle gate so every adapter's `Collect`
+   runs even if `now - last_collect < throttle`.
+2. Calls `BackoffResetter.ResetBackoff` on adapters that implement it,
+   clearing the in-memory and on-disk backoff so the network call
+   attempts regardless of any active 429 cooldown.
+
+A force that itself returns 429 records a fresh `consecutive=1` —
+forcing does NOT preserve the prior streak (the user explicitly chose
+to attempt now). Bind it to a tmux key (e.g. `prefix U`) for a manual
+"refresh now" gesture.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `PROJMUX_USAGE_STATE_DIR` | Override snapshot directory. Resolved verbatim, no `~` expansion. |
+| `PROJMUX_USAGE_DEBUG` | Surface adapter errors from `status usage` to stderr. |
+| `PROJMUX_USAGE_LIMITS_PATH` | Deprecated; read but ignored (limits come from upstream APIs). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -17,15 +17,17 @@
   },
   "files": [
     "npm/projmux.js",
+    "docs/*.md",
+    "docs/assets/*",
     "README.md",
     "README-ko.md",
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.4.5",
-    "@projmux/darwin-x64": "0.4.5",
-    "@projmux/linux-arm64": "0.4.5",
-    "@projmux/linux-x64": "0.4.5"
+    "@projmux/darwin-arm64": "0.4.7",
+    "@projmux/darwin-x64": "0.4.7",
+    "@projmux/linux-arm64": "0.4.7",
+    "@projmux/linux-x64": "0.4.7"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",