mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-20 04:59:34 +01:00
fix(web): forward the wheel for any CLI whose registry entry asks for it
The browser's wheel gate named copilot, pi, claude and codex by id, so a custom clis.json entry that launches pi could not get the forwarding #771 gave stock pi: after every tab switch or reload its wheel scrolled an empty local buffer. Copying pi's altScreen value into such an entry made it worse, since the mouse DECSETs were then stripped while nothing forwarded the wheel. The server now publishes every CLI's wheelForward rule as window.__codemanWheelForward, disabled entries included because disabling a CLI leaves its sessions running, and _shouldForwardWheelToApp reads that map instead of an id list. Stock CLIs keep their behaviour, and a minVersion that is not MAJOR.MINOR.PATCH refuses forwarding instead of comparing as passing.
This commit is contained in:
1 parent
e99b42c387
commit
3ef4900e60
12 files changed
+251
-37
No files matched your search
@@ -228,7 +228,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
|
||||
|
||||
**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the whole tmux scrollback ALONE (`source='mux-full-history'`), superseding the byte buffer. First load of each non-shell TUI session requests it (`_fullHistoryLoaded`); Shell selection, drop recovery, clear and a tile's load use `SHELL_LOAD_QUERY` (constants.js), a bounded window of tmux's RENDERED history (`?full=1&tail=1MiB&alt=recording&lines=10000`), never the raw byte recording, whose full-screen repaints replayed at another pane height push copies of their top row into scrollback; the route reports a client `lines=` bound below the history ceiling that left lines in tmux as `truncationReason: 'tail'`, and `alt=recording` falls back to the visible frame over the tailed byte recording when the pane is in the alternate screen (a nested tmux in a remote or Docker case keeps no tmux history; vim/less take it too while open). A Shell scroll-to-top pulls a bounded `?full=1&tail=` window (a window no longer than the browser's buffer is skipped before the downgrade guard, so it never marks the session exhausted); the unbounded pull stays behind **Load full history**. A Shell split-pane Pane B has its own copy of the bounded pull against its own xterm (`TerminalTile._pullHistory`, terminal-tile.js); keep the two in step. → [architecture-invariants#split-pane-sessions](docs/architecture-invariants.md#split-pane-sessions) ⚠️ The capture ends with a RELATIVE cursor move back to the pane's caret (never `CUP`), so no line-deleting transform may run over it; those skips key on `isFullCapture`, never on `?full=1` alone. ⚠️ A re-pull must never shrink the buffer (`_replayWouldShrinkBuffer()`). ⚠️ `captureCols`/`captureRows` are absent when no frame was positioned: test `Number.isFinite`, never truthiness. ⚠️ A frame dropped at the 128 KiB render cap MUST be recovered, and the recovery verifies itself: `_scheduleDroppedOutputRecovery` re-arms (bounded by `DROP_RECOVERY_MAX_ATTEMPTS`) while `_onSessionNeedsRefresh` reports no repaint, but never after a capture-fetch `'deadline'`. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
|
||||
|
||||
**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode, copilot and pi get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, tracked Copilot, or tracked Pi**. Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Pi has no version gate either, and is fullscreen by default since 1.0.0: it enables tracking once at start, so the flag is what survives a tab switch or reload (xterm's own mode does not). ⚠️ Pi deliberately has no `transcriptPageKeys`: its `tuiMode: regular` binds those keys to the editor, so paging there moves a draft's caret. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding)
|
||||
**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode, copilot and pi get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, tracked Copilot, or tracked Pi**. Which CLIs forward is the registry's `wheelForward`, published as `window.__codemanWheelForward` and never an id list in the gate, so a custom `clis.json` entry opts in with it plus `altScreen: 'strip-mux-and-mouse'` (`docs/cli-registry.md`). Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Pi has no version gate either, and is fullscreen by default since 1.0.0: it enables tracking once at start, so the flag is what survives a tab switch or reload (xterm's own mode does not). ⚠️ Pi deliberately has no `transcriptPageKeys`: its `tuiMode: regular` binds those keys to the editor, so paging there moves a draft's caret. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding)
|
||||
**Detached start + service install**: `codeman web -d` relaunches the same entry script `detached:true` (setsid); `nohup` is not what makes it survive. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile + `/api/status` probe), or a second instance attaches to the first one's live sessions. ⚠️ Never report success not observed: poll `/api/status` until the child answers or dies. `--stop` must verify the pid still looks like Codeman (`ps -o command=`) before signalling. Unit/label names live only in `config/service-names.ts`. `service install` bakes the installing shell's PATH into the unit and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install)
|
||||
|
||||
**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ An install with no git checkout (`install.sh` on a machine without a working git leaves the marker `.install-source`) is kind `archive`: it cannot update in place, and both the check and the UI tell it to re-run the installer, never the npm line. ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
|
||||
|
||||
@@ -135,7 +135,7 @@ Further detail: ⚠️ An ADOPTED container may back SEVERAL cases at different
|
||||
|
||||
⚠️ **`param` is TWO namespaces.** `launch.params` keys, `env.configSetenv[].fromParam` and `capabilities.privilegedParams[].param` all name a LAUNCH PARAM; the legacy `<Mode>Config` wire field is a separate namespace, bridged only by `launch.legacyConfigAliases`. Getting `privilegedParams[].param` wrong is SILENT — it is the multi-user bypass clamp's only handle on a CLI's privilege switch, and a wrong name clamps nothing with no load error and no failing test — so `schema.ts` rejects an entry naming a param it never declared. Codex is the entry where the two names differ (`bypassApprovals` vs `dangerouslyBypassApprovals`) and therefore the one that catches a regression.
|
||||
|
||||
⚠️ Five fields are DECLARED-FOR-LATER and read by nothing (`accent`, `capabilities.echo`/`wheelForward`/`keyboardAccessory`/`maxFrameBytes`): all frontend behaviour, transcribed rather than measured (except `accent`, measured against styles.css on 2026-09-21), so re-measure before wiring one up; the list is pinned so it cannot quietly grow. (`shortBadge` left the list when the Settings CLI management list started showing it.)
|
||||
⚠️ Four fields are DECLARED-FOR-LATER and read by nothing (`accent`, `capabilities.echo`/`keyboardAccessory`/`maxFrameBytes`): all frontend behaviour, transcribed rather than measured (except `accent`, measured against styles.css on 2026-09-21), so re-measure before wiring one up; the list is pinned so it cannot quietly grow. (`shortBadge` left the list when the Settings CLI management list started showing it, and `wheelForward` when the browser's wheel gate started reading it.)
|
||||
|
||||
Spawn commands are pinned as literal strings in `test/cli-registry-spawn-golden.test.ts`, remote/docker pane commands in `test/location-overlay-commands.test.ts`. ⚠️ That second golden no longer covers **remote claude or remote omp**: both now have their own arm in `buildRemoteLaunchCommand` (a `--session-id || --resume` pair, and `--continue`, so a respawn continues the same conversation) and never reach `defaultRemoteCommandForMode`, which is what that test asserts. Their real pins are `toContain` substrings in `test/tmux-manager.test.ts` and `test/remote-shared-sessions.test.ts`; changing either arm will NOT fail the golden.
|
||||
|
||||
@@ -267,7 +267,7 @@ Further detail: the `<prefix>: <title>` form (`w3-myapp: fix the login redirect`
|
||||
|
||||
⚠️ **What a mouse-DECSET strip (full or mouse) removes, it must REMEMBER.** Stripping the mouse DECSETs means xterm's `modes.mouseTrackingMode` is permanently `'none'` for those modes, so the browser hand-encodes click reports to compensate (`_sendSyntheticSgrTap`). With no state to consult it did that on EVERY click, which delivered mouse reports to programs that never asked for them: the same pane runs a plain shell whenever the CLI has exited or a `shell` was started inside a claude-mode session, and a shell prints the report as literal text (`[<0;88;20M`), garbling the next line typed. `_recordStrippedMouseMode()` therefore records each stripped sequence as it goes and publishes `cliMouseTracking` through `toState()`, and `_shouldReportMouseToCli()` requires it. ⚠️ Only the TRACKING modes count (1000/1001/1002/1003): 1005/1006 select an ENCODING and 1007 is alt-scroll, and counting those would put the stray reports straight back. ⚠️ The change broadcasts IMMEDIATELY rather than through `broadcastSessionStateDebounced`, because the flag flips when a dialog opens and the user can click that dialog inside the 500ms debounce window. Measured on a live claude 2.x: the CLI holds a tracking mode on continuously in fullscreen (so clicks keep being reported exactly as before; the default inline renderer holds none, measured on 2.1.283 even with `/model` open), while a bash prompt in the same stripped mode reports nothing. Fails toward silence: after a server restart the flag is false until the CLI re-emits, which tmux does at client attach.
|
||||
|
||||
**Wheel forwarding requires observed mouse tracking: Claude ≥ 2.1.187, tracked Codex, tracked Copilot or tracked Pi** (`terminal-ui.js:_shouldForwardWheelToApp`). The original #227 measurement remains valid for **Codex 0.147.0 inline**: `alternate_on=0`, `mouse_any_flag=0`, growing tmux history, and SGR wheel reports do nothing. Claude 2.1.280 inline similarly reports `alternate_on=0`, `mouse_any_flag=0`; forwarding there swallows gestures, so it keeps local scrollback. Fullscreen Claude (`CLAUDE_CODE_NO_FLICKER=1` or `"tui": "fullscreen"`) enables mouse tracking and accepts reports. **Fresh Codex 0.163.0 fullscreen measurement (2026-10-18, isolated local tmux pane)**: `alternate_on=1`, `mouse_any_flag=1`; one `\x1b[<64;10;10M` report moves the transcript one row upward, and `\x1b[<65;10;10M` restores the original screen. This is capability evidence, not a minimum-version promise: untracked Codex (including a 0.162.0 measurement (2026-10) with `mouse_any_flag=0`) keeps local history or the hollow-pane paging fallback. Codex does not publish the Claude-only CLI version field, so its gate requires the observed flag rather than a Claude version. The registry records this as `wheelForward.mode: 'always'` (observed mouse tracking is still required); Claude remains `version-gated`. A stale/false flag after startup cannot authorize forwarding. ⚠️ A strip mode alone is not evidence that a CLI consumes SGR reports. Verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR taps remain independently gated by `_shouldReportMouseToCli()`; the older #325 no-op measurement describes untracked inline Codex and must not be generalized to newer tracked fullscreen renderers. Shift/local-history opt-outs and xterm's native mouse/alternate-screen handling remain intact.
|
||||
**Wheel forwarding requires observed mouse tracking: Claude ≥ 2.1.187, tracked Codex, tracked Copilot or tracked Pi** (`terminal-ui.js:_shouldForwardWheelToApp`). The original #227 measurement remains valid for **Codex 0.147.0 inline**: `alternate_on=0`, `mouse_any_flag=0`, growing tmux history, and SGR wheel reports do nothing. Claude 2.1.280 inline similarly reports `alternate_on=0`, `mouse_any_flag=0`; forwarding there swallows gestures, so it keeps local scrollback. Fullscreen Claude (`CLAUDE_CODE_NO_FLICKER=1` or `"tui": "fullscreen"`) enables mouse tracking and accepts reports. **Fresh Codex 0.163.0 fullscreen measurement (2026-10-18, isolated local tmux pane)**: `alternate_on=1`, `mouse_any_flag=1`; one `\x1b[<64;10;10M` report moves the transcript one row upward, and `\x1b[<65;10;10M` restores the original screen. This is capability evidence, not a minimum-version promise: untracked Codex (including a 0.162.0 measurement (2026-10) with `mouse_any_flag=0`) keeps local history or the hollow-pane paging fallback. Codex does not publish the Claude-only CLI version field, so its gate requires the observed flag rather than a Claude version. The registry records this as `wheelForward.mode: 'always'` (observed mouse tracking is still required); Claude remains `version-gated`. That field is the gate's only per-CLI rule: `renderIndexHtml` publishes every CLI's `wheelForward` (disabled ones included, since their sessions keep running; `never` left out) as `window.__codemanWheelForward`, so a custom `clis.json` entry forwards under its own id, and a `minVersion` that is not `MAJOR.MINOR.PATCH` refuses forwarding. A stale/false flag after startup cannot authorize forwarding. ⚠️ A strip mode alone is not evidence that a CLI consumes SGR reports. Verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR taps remain independently gated by `_shouldReportMouseToCli()`; the older #325 no-op measurement describes untracked inline Codex and must not be generalized to newer tracked fullscreen renderers. Shift/local-history opt-outs and xterm's native mouse/alternate-screen handling remain intact.
|
||||
|
||||
**Copilot also receives forwarded reports** (1.0.95 measured in tmux: alt screen, `mouse_any_flag=1`): its mouse DECSETs are stripped so a drag selects, which also stops xterm encoding the wheel for it, so `_shouldForwardWheelToApp` sends the same SGR reports by hand while `cliMouseTracking` is true; six `\x1b[<64;…M` reports moved its transcript 18 lines, a phone swipe takes the same gate, and there is NO version gate.
|
||||
|
||||
|
||||
@@ -300,7 +300,7 @@ This matters because it is invisible when it is wrong. `capabilities.privilegedP
|
||||
|
||||
## Fields declared for later
|
||||
|
||||
`accent`, `capabilities.echo`, `capabilities.wheelForward`, `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` are **declared but not yet read**. (`shortBadge` was on this list until the CLI management list in Settings started showing it.) They all describe frontend behaviour, and the frontend is deliberately untouched here: `app.js`, `terminal-ui.js` and `styles.css` keep their own hand-authored per-CLI rules, and moving them is its own piece of work verified by a browser/mobile suite the CI gate cannot see.
|
||||
`accent`, `capabilities.echo`, `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` are **declared but not yet read**. (`shortBadge` was on this list until the CLI management list in Settings started showing it, and `capabilities.wheelForward` until the browser's wheel gate started reading it, see below.) They all describe frontend behaviour, and the frontend is deliberately untouched here: `app.js`, `terminal-ui.js` and `styles.css` keep their own hand-authored per-CLI rules, and moving them is its own piece of work verified by a browser/mobile suite the CI gate cannot see.
|
||||
|
||||
Treat those values as **transcribed, not authoritative** — nothing enforces that `echo.policy` matches `_updateLocalEchoState`'s fallthrough, so re-measure before wiring one up. `accent` is the one exception: it was measured against styles.css on 2026-09-21 (method in the comment above `CLAUDE` in `stock.ts`), though nothing keeps it in step with the CSS either. A field that is both wrong and unread is worse than an absent one, because the next reader trusts it; `test/cli-registry-no-id-branching.test.ts` pins the list so it cannot quietly grow, and wiring one up makes its line there fail, which is the direction you want.
|
||||
|
||||
@@ -308,6 +308,10 @@ Treat those values as **transcribed, not authoritative** — nothing enforces th
|
||||
|
||||
Everything else in the interface is live, including `overlays.remote` / `overlays.docker`, which back `defaultRemoteCommandForMode()` and `defaultDockerCommandForMode()` directly. Those two used to be hardcoded `Record<…CommandMode, string>` tables duplicating the registry with nothing keeping the two in step; `test/location-overlay-commands.test.ts` pins every resulting command as a literal string.
|
||||
|
||||
### Wheel forwarding for a custom full-screen CLI
|
||||
|
||||
`capabilities.wheelForward` reaches the browser as `window.__codemanWheelForward` (id to rule, every CLI whose mode is not `never`, disabled ones included, since disabling a CLI leaves its running sessions open), and `_shouldForwardWheelToApp` in terminal-ui.js reads only that map, so a custom entry gets the same wheel as a stock one under its own id. A full-screen TUI that turns mouse tracking on itself (a wrapper around pi, for example) needs two values in its `clis.json` entry, the ones stock pi carries: `"altScreen": "strip-mux-and-mouse"` (the server strips its mouse DECSETs and publishes `cliMouseTracking`, and a drag selects locally) and `"wheelForward": { "mode": "always" }` (the wheel goes to the CLI as SGR reports while that flag is on). With the custom-entry defaults (`strip-mux-only`, `never`) the DECSETs reach xterm, which handles the wheel only until a tab switch or reload replays the pane without them; from then on the wheel scrolls an empty local buffer. ⚠️ Saving the entry from the Settings form rebuilds its capabilities from those defaults, so both values have to be set again in the file after an edit there.
|
||||
|
||||
## Consumers outside the server
|
||||
|
||||
Two things need the catalogue but cannot import TypeScript, so `npm run generate:cli-catalog`
|
||||
|
||||
@@ -596,10 +596,14 @@ export interface CliCapabilities {
|
||||
* Forwarding the wheel to the CLI's own transcript. 'never' keeps local scrollback;
|
||||
* 'version-gated' forwards from `minVersion` on; 'always' forwards at any version. Either
|
||||
* forwarding mode applies only while the CLI has mouse tracking on (`cliMouseTracking`).
|
||||
* Read by the browser's gate (`_shouldForwardWheelToApp` in terminal-ui.js) through
|
||||
* `window.__codemanWheelForward`, which the server builds from this field for every CLI
|
||||
* whose mode is not `never`, disabled ones included (their running sessions stay open).
|
||||
*
|
||||
* ⚠️ Declared only: nothing reads this field yet (see DECLARED-FOR-LATER below). The browser's
|
||||
* gate is `_shouldForwardWheelToApp` in terminal-ui.js, which keeps its own hand-written
|
||||
* per-CLI rules, so changing a value here changes nothing until that gate is changed too.
|
||||
* ⚠️ `cliMouseTracking` is only ever set for a CLI whose mouse DECSETs the server strips
|
||||
* (`altScreen: 'strip-full'` or `'strip-mux-and-mouse'`), so a forwarding mode on any other
|
||||
* `altScreen` never forwards: xterm keeps the DECSETs and encodes the wheel itself, until a
|
||||
* replay drops its mouse mode.
|
||||
*/
|
||||
wheelForward: { mode: 'never' | 'version-gated' | 'always'; minVersion?: string };
|
||||
/**
|
||||
@@ -1009,14 +1013,15 @@ export interface CliOverlays {
|
||||
/**
|
||||
* ⚠️ DECLARED-FOR-LATER: fields no code reads yet.
|
||||
*
|
||||
* `accent`, `overlays.credStore`, `capabilities.echo`, `capabilities.wheelForward`,
|
||||
* `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` all describe FRONTEND
|
||||
* `accent`, `overlays.credStore`, `capabilities.echo`, `capabilities.keyboardAccessory` and
|
||||
* `capabilities.maxFrameBytes` all describe FRONTEND
|
||||
* behaviour, and most of the frontend is deliberately untouched by the change that introduced
|
||||
* this registry — `app.js`, `terminal-ui.js`, `styles.css` and friends keep their own
|
||||
* hand-authored per-CLI rules, and moving them is its own piece of work with its own way of
|
||||
* being verified (a mobile/browser suite the CI gate cannot see). `shortBadge` graduated out of
|
||||
* this list (docs/cli-enable-disable-plan.md, Phase 2): `GET /api/clis` reads it for the
|
||||
* CLI-management Settings list.
|
||||
* CLI-management Settings list, and so did `capabilities.wheelForward`, which the browser's wheel
|
||||
* gate reads through `window.__codemanWheelForward`.
|
||||
*
|
||||
* They are declared now because each entry should describe its CLI completely, and because
|
||||
* transcribing them while the hand-written source is still on screen is when the values are
|
||||
|
||||
@@ -6016,12 +6016,16 @@ Object.assign(CodemanApp.prototype, {
|
||||
// True when a parsed CLI version string ('2.1.187' — banner-parsed on the
|
||||
// server, delivered via session:cliInfo / SessionState.cliVersion) is known
|
||||
// AND >= the minimum. Unknown or unparseable versions return false so
|
||||
// callers keep the conservative behavior.
|
||||
// callers keep the conservative behavior, and so does an unparseable
|
||||
// minimum: it can come from a user's clis.json (`wheelForward.minVersion`).
|
||||
_cliVersionAtLeast(version, minimum) {
|
||||
if (typeof version !== 'string') return false;
|
||||
const parts = version.trim().replace(/^v/, '').split('.').map(Number);
|
||||
if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) return false;
|
||||
const min = minimum.split('.').map(Number);
|
||||
const parse = (v) => {
|
||||
const m = typeof v === 'string' ? /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim()) : null;
|
||||
return m ? m.slice(1).map(Number) : null;
|
||||
};
|
||||
const parts = parse(version);
|
||||
const min = parse(minimum);
|
||||
if (!parts || !min) return false;
|
||||
for (let i = 0; i < 3; i++) {
|
||||
if (parts[i] !== min[i]) return parts[i] > min[i];
|
||||
}
|
||||
@@ -6081,24 +6085,26 @@ Object.assign(CodemanApp.prototype, {
|
||||
if (mode && mode !== 'none') return false;
|
||||
const session = this.sessions?.get(target.sessionId || this.activeSessionId);
|
||||
const sessionMode = session?.mode || 'claude';
|
||||
// GitHub Copilot CLI (and pi, fullscreen by default) scrolls its own transcript on SGR wheel
|
||||
// reports (checked with xterm encoding them natively). Their mouse DECSETs are stripped
|
||||
// server-side so a drag selects locally (strip-mux-and-mouse), which also means xterm no longer
|
||||
// encodes the wheel: send the same reports by hand, but only while the CLI is actually tracking
|
||||
// the mouse. Not gated on a version. On Copilot a stale-false flag falls through to the
|
||||
// PageUp/PageDown fallback like claude's; pi has none on purpose (the `transcriptPageKeys` note
|
||||
// in stock.ts), so there the wheel does nothing until the flag is back.
|
||||
if (sessionMode === 'copilot' || sessionMode === 'pi') return session?.cliMouseTracking === true;
|
||||
if (sessionMode !== 'claude' && sessionMode !== 'codex') return false;
|
||||
if (sessionMode === 'claude' && !this._cliVersionAtLeast(session?.cliVersion, '2.1.187')) return false;
|
||||
// Only while Claude or Codex is actually listening for the mouse. Claude's
|
||||
// inline renderer (2.1.280 measured: alternate_on=0, mouse_any_flag=0), like
|
||||
// older inline Codex, keeps its transcript in real scrollback; SGR reports are
|
||||
// ignored, so forwarding made every swipe and wheel tick dead. Fullscreen
|
||||
// (CLAUDE_CODE_NO_FLICKER=1, or "tui": "fullscreen" in ~/.claude/settings.json)
|
||||
// turns on alt-screen + mode 1003/1006, which the server records as
|
||||
// cliMouseTracking. A stale-false flag after a server restart falls through
|
||||
// to _maybePageCliTranscript, so it never goes dead.
|
||||
// Which CLIs scroll their own transcript on SGR wheel reports is the registry's
|
||||
// `wheelForward` rule, published by renderIndexHtml as `window.__codemanWheelForward`
|
||||
// (id -> rule, `never` left out; a page rendered without the map forwards nothing), so a
|
||||
// custom clis.json entry shaped like pi forwards under its own id. Stock: claude from
|
||||
// 2.1.187 (older versions take the wheel as menu navigation), codex, copilot and pi always.
|
||||
// Their mouse DECSETs are stripped server-side (a drag selects locally), so xterm never
|
||||
// encodes the wheel for them and the reports are sent by hand.
|
||||
const rule = window.__codemanWheelForward?.[sessionMode];
|
||||
if (!rule || (rule.mode !== 'always' && rule.mode !== 'version-gated')) return false;
|
||||
if (rule.mode === 'version-gated' && !this._cliVersionAtLeast(session?.cliVersion, rule.minVersion)) return false;
|
||||
// Only while the CLI is actually listening for the mouse. Claude's inline renderer
|
||||
// (2.1.280 measured: alternate_on=0, mouse_any_flag=0), like older inline Codex and pi's
|
||||
// `tuiMode: regular`, keeps its transcript in real scrollback; SGR reports are ignored, so
|
||||
// forwarding made every swipe and wheel tick dead. Fullscreen (CLAUDE_CODE_NO_FLICKER=1, or
|
||||
// "tui": "fullscreen" in ~/.claude/settings.json; pi's default since 1.0.0) turns on
|
||||
// alt-screen + mouse tracking, which the server records as cliMouseTracking. That flag is
|
||||
// what survives a tab switch or reload, where xterm's own mouse mode does not. A stale-false
|
||||
// flag falls through to _maybePageCliTranscript (PageUp/PageDown for a CLI declaring
|
||||
// `transcriptPageKeys`); pi declares none on purpose (the note in stock.ts), so there the
|
||||
// wheel does nothing until the flag is back.
|
||||
if (session?.cliMouseTracking !== true) return false;
|
||||
// Deliberately NOT gated on _terminalViewportAtBottom(). It used to be, so
|
||||
// that leaving the bottom handed the wheel back to local scrollback and both
|
||||
|
||||
@@ -2133,6 +2133,19 @@ export class WebServer extends EventEmitter {
|
||||
'</head>',
|
||||
() => `<script>window.__codemanKeyboardHoldModes=${JSON.stringify(keyboardHoldClis)};</script>\n</head>`
|
||||
);
|
||||
// Which run modes take the wheel as SGR reports while they track the mouse
|
||||
// (`_shouldForwardWheelToApp`), keyed by id with the `wheelForward` rule itself, so a
|
||||
// custom clis.json entry shaped like pi forwards under its own id. `never` is left out.
|
||||
// Disabled entries are kept (`listClis`, not `enabledClis`): disabling a CLI never ends
|
||||
// its running sessions, and their wheel must keep working across a reload.
|
||||
// `minVersion` is a free string a user's clis.json sets, hence the script escaper.
|
||||
const wheelForwardClis = Object.fromEntries(
|
||||
listClis()
|
||||
.filter((entry) => entry.capabilities.wheelForward.mode !== 'never')
|
||||
.map((entry) => [entry.id, entry.capabilities.wheelForward])
|
||||
);
|
||||
const wheelForwardJson = escapeScriptJson(JSON.stringify(wheelForwardClis));
|
||||
html = html.replace('</head>', () => `<script>window.__codemanWheelForward=${wheelForwardJson};</script>\n</head>`);
|
||||
if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') {
|
||||
html = html.replace('</head>', () => `<script>window.__codemanGestureAvailable=true;</script>\n</head>`);
|
||||
if (settings.gestureControlEnabled === true) {
|
||||
|
||||
@@ -435,7 +435,6 @@ describe('declared-for-later fields', () => {
|
||||
const DECLARED_FOR_LATER = [
|
||||
'accent',
|
||||
'capabilities.echo',
|
||||
'capabilities.wheelForward',
|
||||
'capabilities.keyboardAccessory',
|
||||
'capabilities.maxFrameBytes',
|
||||
// The Docker credential-seeding path still reads its own CRED_STORES table: this shape
|
||||
|
||||
@@ -181,6 +181,78 @@ describe('WebServer.renderIndexHtml', () => {
|
||||
}
|
||||
});
|
||||
|
||||
it('injects the wheelForward rules of every CLI that forwards, custom and disabled entries included', async () => {
|
||||
// A custom clis.json entry shaped like pi (its mouse DECSETs stripped, wheel forwarded)
|
||||
// must reach the browser's gate by its own id, and every `never` stays out. A DISABLED
|
||||
// entry stays in: disabling a CLI never ends its running sessions, so a fullscreen copilot
|
||||
// tab opened before the switch still needs its wheel after a reload (and an entry enabled
|
||||
// after the page loaded already has its rule). A solo window scrolls a terminal too, so
|
||||
// it gets the same map.
|
||||
const path = dataPath('clis.json');
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
const custom = {
|
||||
label: 'PiD',
|
||||
shortBadge: 'PL',
|
||||
accent: '#6b7280',
|
||||
enabled: true,
|
||||
order: 120,
|
||||
kind: 'agent',
|
||||
discovery: { binaries: ['pi-locked'], searchDirs: [], install: { command: {} } },
|
||||
launch: { params: {}, variants: [{ id: 'default', args: [{ lit: 'pi-locked' }] }] },
|
||||
env: { exports: [], unset: [], tmuxSetenvKeys: [], dockerExecEnvNames: [], allowedPrefixes: [], allowedKeys: [] },
|
||||
capabilities: {
|
||||
external: true,
|
||||
requiresMux: true,
|
||||
hooks: 'none',
|
||||
transcript: 'none',
|
||||
altScreen: 'strip-mux-and-mouse',
|
||||
echo: { policy: 'buffer', anchor: { kind: 'none' } },
|
||||
wheelForward: { mode: 'always' },
|
||||
keyboardAccessory: 'agent',
|
||||
privilegedCommandGate: false,
|
||||
startMode: 'interactive',
|
||||
stripInkBloat: false,
|
||||
ralph: false,
|
||||
respawn: false,
|
||||
effort: false,
|
||||
agentSkillInjection: false,
|
||||
statusLineTelemetry: false,
|
||||
model: { source: 'none' },
|
||||
privilegedParams: [],
|
||||
privilegedEnvKeys: [],
|
||||
gates: {},
|
||||
customModelInjection: { kind: 'unsupported' },
|
||||
},
|
||||
overlays: {},
|
||||
};
|
||||
writeFileSync(
|
||||
path,
|
||||
JSON.stringify({ schemaVersion: 1, clis: { copilot: { enabled: false }, 'pi-locked': custom } }),
|
||||
{
|
||||
mode: 0o600,
|
||||
}
|
||||
);
|
||||
reloadCliRegistry();
|
||||
try {
|
||||
for (const solo of [undefined, 'sess-123']) {
|
||||
const { server } = makeServer({});
|
||||
const html = await render(server, solo);
|
||||
const match = html.match(/window\.__codemanWheelForward=(\{[^<]*\});/);
|
||||
expect(match, String(solo)).not.toBeNull();
|
||||
expect(JSON.parse(match![1])).toEqual({
|
||||
claude: { mode: 'version-gated', minVersion: '2.1.187' },
|
||||
codex: { mode: 'always' },
|
||||
pi: { mode: 'always' },
|
||||
copilot: { mode: 'always' },
|
||||
'pi-locked': { mode: 'always' },
|
||||
});
|
||||
}
|
||||
} finally {
|
||||
writeFileSync(path, JSON.stringify({ clis: {} }, null, 2), { mode: 0o600 });
|
||||
reloadCliRegistry();
|
||||
}
|
||||
});
|
||||
|
||||
it('injects the keyboard-hold modes from the keyboardHold capability: inline Claude, never full-height codex', async () => {
|
||||
for (const solo of [undefined, 'sess-123']) {
|
||||
const { server } = makeServer();
|
||||
|
||||
@@ -117,7 +117,9 @@ describe('WebServer index.html <title> templating (#82)', () => {
|
||||
// Likewise the page-key mode list: an array, possibly empty, always injected.
|
||||
.replace(/<script>window\.__codemanTranscriptPageKeys=\[.*?\];<\/script>\n/, '')
|
||||
// And the keyboard-hold mode list, built the same way.
|
||||
.replace(/<script>window\.__codemanKeyboardHoldModes=\[.*?\];<\/script>\n/, '');
|
||||
.replace(/<script>window\.__codemanKeyboardHoldModes=\[.*?\];<\/script>\n/, '')
|
||||
// And the wheel-forwarding rules: an object keyed by run mode, always injected.
|
||||
.replace(/<script>window\.__codemanWheelForward=\{.*?\};<\/script>\n/, '');
|
||||
const beforeTitle = rawTemplate.split('<title>Codeman</title>')[0];
|
||||
const afterTitle = rawTemplate.split('<title>Codeman</title>')[1];
|
||||
expect(html.startsWith(beforeTitle)).toBe(true);
|
||||
|
||||
@@ -28,8 +28,19 @@ import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
|
||||
*/
|
||||
const PAGE_KEY_MODES = STOCK_CLIS.filter((e) => e.capabilities.transcriptPageKeys === true).map((e) => e.id);
|
||||
|
||||
/**
|
||||
* The run modes that take the wheel as SGR reports, read off the shipped registry the way
|
||||
* the server builds `__codemanWheelForward` (every `wheelForward` other than `never`).
|
||||
*/
|
||||
const WHEEL_FORWARD = Object.fromEntries(
|
||||
STOCK_CLIS.filter((e) => e.capabilities.wheelForward.mode !== 'never').map((e) => [e.id, e.capabilities.wheelForward])
|
||||
);
|
||||
|
||||
function loadTerminalUiHarness(
|
||||
windowGlobals: Record<string, unknown> = { __codemanTranscriptPageKeys: PAGE_KEY_MODES }
|
||||
windowGlobals: Record<string, unknown> = {
|
||||
__codemanTranscriptPageKeys: PAGE_KEY_MODES,
|
||||
__codemanWheelForward: WHEEL_FORWARD,
|
||||
}
|
||||
) {
|
||||
const CodemanApp = function CodemanApp(this: any) {};
|
||||
const logs: string[] = [];
|
||||
@@ -927,6 +938,96 @@ describe('pi wheel forwarding (fullscreen by default since 1.0.0)', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('wheel forwarding read from the injected wheelForward map, for any CLI id', () => {
|
||||
// A custom CLI (clis.json, e.g. a pi wrapper under its own id) that strips its mouse
|
||||
// DECSETs gets `cliMouseTracking` like pi, but the gate used to name copilot and pi by id,
|
||||
// so its wheel hit an empty local buffer after every tab switch or reload.
|
||||
function customApp(
|
||||
map: Record<string, unknown> | undefined,
|
||||
session: { mode: string; cliMouseTracking?: boolean; cliVersion?: string }
|
||||
) {
|
||||
const globals: Record<string, unknown> = { __codemanTranscriptPageKeys: PAGE_KEY_MODES };
|
||||
if (map) globals.__codemanWheelForward = map;
|
||||
const { app } = loadTerminalUiHarness(globals);
|
||||
app.activeSessionId = 'sess-1';
|
||||
app.sessions = new Map([['sess-1', session]]);
|
||||
app.terminal = {
|
||||
rows: 36,
|
||||
modes: { mouseTrackingMode: 'none' },
|
||||
buffer: { active: { type: 'normal', viewportY: 0, baseY: 0, length: 36 } },
|
||||
};
|
||||
return app;
|
||||
}
|
||||
|
||||
it('forwards a custom id the map lists as always, only while it tracks the mouse', () => {
|
||||
const map = { 'pi-locked': { mode: 'always' } };
|
||||
const tracking = customApp(map, { mode: 'pi-locked', cliMouseTracking: true });
|
||||
expect(tracking._shouldForwardWheelToApp({ shiftKey: false })).toBe(true);
|
||||
expect(tracking._shouldForwardWheelToApp({ shiftKey: true })).toBe(false);
|
||||
expect(customApp(map, { mode: 'pi-locked', cliMouseTracking: false })._shouldForwardWheelToApp({})).toBe(false);
|
||||
expect(customApp(map, { mode: 'pi-locked' })._shouldForwardWheelToApp({})).toBe(false);
|
||||
});
|
||||
|
||||
it('applies a version-gated rule to a custom id: at or above minVersion only, unknown version never', () => {
|
||||
const map = { 'my-cli': { mode: 'version-gated', minVersion: '2.0.0' } };
|
||||
const at = (cliVersion?: string) =>
|
||||
customApp(map, { mode: 'my-cli', cliMouseTracking: true, cliVersion })._shouldForwardWheelToApp({});
|
||||
expect(at('1.9.9')).toBe(false);
|
||||
expect(at('2.0.0')).toBe(true);
|
||||
expect(at('2.0.1')).toBe(true);
|
||||
expect(at(undefined)).toBe(false);
|
||||
});
|
||||
|
||||
it('a version-gated rule whose minVersion is not three numbers forwards nothing, whatever the CLI version', () => {
|
||||
// The schema takes any string up to 20 characters. A minimum that cannot be read as
|
||||
// MAJOR.MINOR.PATCH must refuse, the conservative answer an unreadable session version gets.
|
||||
for (const minVersion of ['', '0', '2.0', '1.2.3.4', '0.bad.999', 'x.y.z', '2..0', '+2.0.0', '0x1.0.0']) {
|
||||
const app = customApp(
|
||||
{ 'my-cli': { mode: 'version-gated', minVersion } },
|
||||
{ mode: 'my-cli', cliMouseTracking: true, cliVersion: '9.9.9' }
|
||||
);
|
||||
expect(app._shouldForwardWheelToApp({}), JSON.stringify(minVersion)).toBe(false);
|
||||
}
|
||||
// A well-formed minimum keeps working, a leading `v` and surrounding spaces included.
|
||||
for (const minVersion of ['9.9.9', 'v2.0.0', ' 2.0.0 ']) {
|
||||
const app = customApp(
|
||||
{ 'my-cli': { mode: 'version-gated', minVersion } },
|
||||
{ mode: 'my-cli', cliMouseTracking: true, cliVersion: '9.9.9' }
|
||||
);
|
||||
expect(app._shouldForwardWheelToApp({}), JSON.stringify(minVersion)).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it('a version-gated rule with no minVersion (the schema allows it) forwards nothing and does not throw', () => {
|
||||
const app = customApp(
|
||||
{ 'my-cli': { mode: 'version-gated' } },
|
||||
{ mode: 'my-cli', cliMouseTracking: true, cliVersion: '9.9.9' }
|
||||
);
|
||||
expect(app._shouldForwardWheelToApp({})).toBe(false);
|
||||
});
|
||||
|
||||
it('never forwards an id the map leaves out, and nothing at all from a page rendered without the map', () => {
|
||||
expect(
|
||||
customApp(
|
||||
{ 'pi-locked': { mode: 'always' } },
|
||||
{ mode: 'other', cliMouseTracking: true }
|
||||
)._shouldForwardWheelToApp({})
|
||||
).toBe(false);
|
||||
for (const mode of ['claude', 'codex', 'copilot', 'pi']) {
|
||||
expect(
|
||||
customApp(undefined, { mode, cliMouseTracking: true, cliVersion: '9.9.9' })._shouldForwardWheelToApp({}),
|
||||
mode
|
||||
).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it('a map entry of mode never forwards, even for a stock id', () => {
|
||||
expect(
|
||||
customApp({ pi: { mode: 'never' } }, { mode: 'pi', cliMouseTracking: true })._shouldForwardWheelToApp({})
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('the paging gates asked for another pane (a TerminalTile)', () => {
|
||||
it('exports the paging math, and the primary pane runs on it', () => {
|
||||
const { app, sent, windowRef } = hollowApp();
|
||||
|
||||
@@ -49,6 +49,11 @@ const fetchMock = vi.fn();
|
||||
*/
|
||||
const PAGE_KEY_MODES = STOCK_CLIS.filter((e) => e.capabilities.transcriptPageKeys === true).map((e) => e.id);
|
||||
|
||||
/** The wheel-forwarding rules, read off the registry as the server builds `window.__codemanWheelForward`. */
|
||||
const WHEEL_FORWARD = Object.fromEntries(
|
||||
STOCK_CLIS.filter((e) => e.capabilities.wheelForward.mode !== 'never').map((e) => [e.id, e.capabilities.wheelForward])
|
||||
);
|
||||
|
||||
/**
|
||||
* The clock both panes read gesture gaps from (`performance.now()`). Real time by
|
||||
* default; a test that needs a pause or a burst moves it by hand.
|
||||
@@ -62,6 +67,7 @@ function loadContext() {
|
||||
removeEventListener: vi.fn(),
|
||||
CodemanBase: { base: '' },
|
||||
__codemanTranscriptPageKeys: PAGE_KEY_MODES,
|
||||
__codemanWheelForward: WHEEL_FORWARD,
|
||||
};
|
||||
const context = vm.createContext({
|
||||
console: { ...console, log: vi.fn(), debug: vi.fn() },
|
||||
|
||||
@@ -2,6 +2,12 @@ import { readFileSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import vm from 'node:vm';
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
|
||||
|
||||
/** The wheel-forwarding rules, read off the registry as the server builds `window.__codemanWheelForward`. */
|
||||
const WHEEL_FORWARD = Object.fromEntries(
|
||||
STOCK_CLIS.filter((e) => e.capabilities.wheelForward.mode !== 'never').map((e) => [e.id, e.capabilities.wheelForward])
|
||||
);
|
||||
|
||||
function loadTerminalUiHarness() {
|
||||
const CodemanApp = function CodemanApp(this: any) {};
|
||||
@@ -10,7 +16,7 @@ function loadTerminalUiHarness() {
|
||||
let activeElement: unknown = null;
|
||||
// The module hangs its constants off window (CodemanTerminalInput) and the URL branch of
|
||||
// the link provider opens through window.open, so tests need a handle on the same object.
|
||||
const windowRef: Record<string, any> = {};
|
||||
const windowRef: Record<string, any> = { __codemanWheelForward: WHEEL_FORWARD };
|
||||
const context = vm.createContext({
|
||||
window: windowRef,
|
||||
document: {
|
||||
|
||||
Reference in new issue
Block a user