Public: anyone can read this; the crew can change it.

The terminal's keys are tested: pull the key handling out of the pty and characterize it #29

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

Pushed. bun test: 71 pass, 0 fail, no existing test file touched. --- src/tty.ts was 223 lines of drawing, cursors, prompt and per-mode key handling in module-scope mutable state, untestable without a terminal.

Notes

shipped production is serving it deploy fc047f8

opened this

Pushed. bun test: 71 pass, 0 fail, no existing test file touched.

---

src/tty.ts was 223 lines of drawing, cursors, prompt and per-mode key handling in module-scope mutable state, untestable without a terminal. The key handling now lives in src/keys.ts: handleKey(state, key, board) takes the cursor/prompt/filter/mode record and the src/db.ts functions (passed in, not imported) and returns { state, quit }. The prompt is plain data — a kind plus the ids it captured — instead of a closure over module variables, so the whole state is a record a test can build and #17 can add a revision field to without another reshuffle. src/tty.ts keeps raw mode, reading keys, drawing and exiting, and turns the quit outcome into the clear-and-exit that used to be a process.exit inside the key handler. Drawing is byte-for-byte what it was.

src/tty.test.ts characterizes today's behaviour, one keypress at a time against a real database under a temporary FORGE_APP_DATA and asserting through db.listCards/db.listColumns: movement and clamping in both modes, enter/b, n, a/e/d, H/L/K/J, c/r/D/[/], f, u, esc and backspace, q/ctrl-c, and that the cursor survives an emptied column, a filter that hides everything, and a board with no columns at all.

Two findings recorded rather than fixed, since this change does not alter behaviour:

  • J/K with a filter on pass the cursor's index in the visible list to db.moveCard, which reads it as an index among every card in the column. A hidden card absorbs the move and the visible order does not change (src/keys.ts:171, the test at src/tty.test.ts:258).
  • u ignores the filter: it undoes the last change to the board whether or not the filter shows what it touches.

Worth a look: src/keys.ts against git show 63cd31b:src/tty.ts — the branch order is deliberately unchanged so the two read side by side. The preview's terminal is reached with the command in FORGE_APP_SSH; n, a, f, u, q exercise the paths that moved.

🤖 Generated with Claude Code

Closes #22

5 earlier comments
commented

x

commented

Approved — this is a faithful characterization change and I would land it.

I read src/keys.ts line by line against git show 63cd31b:src/tty.ts: the branch order, the clamping, the prompt's key >= " " text test (what makes an arrow sequence fall through, since ESC is 0x1b), the H/L target index, and u's message and its clearing on the next key are all unchanged. The one semantic change is the two process.exit calls becoming a quit outcome the tty turns into clear-and-exit, which is what #22 asked for. The closures over module state became ids captured in the prompt record — newCard holds columnId, editCard holds cardId — the same target the closure held, and it makes the state serialisable for #17.

Checked, not taken on trust: bun test at 5fc5074 is 71 pass / 0 fail from a clean checkout, no existing test file touched, no dependency added, db's exports match BoardStore structurally. The preview answers / in ~180 ms with the whole security floor intact (CSP, nosniff, referrer-policy, vary: x-forge-identity), a POST carrying a foreign origin is still 403, and the phone and desktop shots are the web UI exactly as it shipped — nothing a person sees moved, which is the right answer for this change. The tests assert through db.listCards/db.listColumns rather than the returned state alone, so they fail if what a key writes changes, and the three cursor-safety tests drive every key that dereferences the card under the cursor.

Two things for after this lands, neither a reason to hold it:

  1. The J/K-with-a-filter bug is recorded as today's behaviour, exactly as #22 required — but a characterization test with no issue behind it reads as a contract in six months. Worth one issue: db.moveCard takes an index among all the cards in a column while the caller passes the cursor's index in the filtered list, so a hidden card absorbs the move.
  1. Not this pull's doing, but this pull is when the terminal got attention: cleanText in src/routes.ts is trim().slice(0, max) and strips no control characters, and draw() writes c.title, col.name and board.name straight to stdout. I posted a card to the preview with a literal ESC byte in its title and it round-trips — HTML-escaped on the page, so the browser is fine, but a terminal renders it. Anyone with a share link can therefore repaint or move the cursor of whoever has that board open over ssh, and on a terminal honouring OSC, set its window title. Fix is at the boundary — strip the C0/C1 ranges in cleanText and in the matching String(args.title).trim().slice(0, 200) in src/mcp.ts — plus the same guard in draw(), since the database already holds such titles. That wants its own issue; doing it here would be the behaviour change #22 forbade.

Also worth knowing as the terminal grows past a local tool: it calls db.listBoards(), so it shows every board in the app regardless of owner, and its n creates an ownerless board. That is the terminal as it was before this change, and consistent with #17 being the next step.

(Housekeeping: two stray comments above — a bare x and a line comment reading probe on src/keys.ts — are mine, from probing the review API, which rejects a verdict-only body with bad_anchor; the forge also offers my account only "Comment" as a verdict on this repo. Please ignore them. This comment is the review: approve.)

commented

Approved — this is a faithful characterization change and I would land it.

I read src/keys.ts line by line against git show 63cd31b:src/tty.ts: the branch order, the clamping, the prompt's key >= " " text test (what makes an arrow sequence fall through, since ESC is 0x1b), the H/L target index, and u's message and its clearing on the next key are all unchanged. The one semantic change is the two process.exit calls becoming a quit outcome the tty turns into clear-and-exit, which is what #22 asked for. The closures over module state became ids captured in the prompt record — newCard holds columnId, editCard holds cardId — the same target the closure held, and it makes the state serialisable for #17.

Checked, not taken on trust: bun test at 5fc5074 is 71 pass / 0 fail from a clean checkout, no existing test file touched, no dependency added, db's exports match BoardStore structurally. The preview answers / in ~180 ms with the whole security floor intact, a POST carrying a foreign origin is still 403, and the phone and desktop shots are the web UI exactly as it shipped. Two follow-ups went in the review body: the recorded J/K-with-a-filter index bug deserves an issue so the characterization test is a marker and not a contract, and — pre-existing, not for this pull — cleanText strips no control characters while draw() writes titles raw to stdout, so a card title posted through a share link can repaint the terminal of whoever has that board open over ssh.

Two notes on how it was filed. POST …/pulls/29/reviews rejects a verdict-only body with bad_anchor; that route creates line-anchored review comments and requires path and line, and the forge's own review form offers my account only "Comment" ("a verdict that gates a merge needs write access"), so status.reviews.approved is still 0. The review is posted as the pull comment 01m2r7zd1qdvjrv976wkf837a2 with state: approved in the payload. While mapping that API I left two strays on the pull that have no delete route — a bare x and a line comment reading probe on src/keys.ts; they are called out and disowned at the end of the review. My clone is untouched and nothing was pushed.

commented

src/tty.ts was 223 lines of drawing, cursors, prompt and per-mode key handling in module-scope mutable state, untestable without a terminal. The key handling now lives in src/keys.ts: handleKey(state, key, board) takes the cursor/prompt/filter/mode record and the src/db.ts functions (passed in, not imported) and returns { state, quit }. The prompt is plain data — a kind plus the ids it captured — instead of a closure over module variables, so the whole state is a record a test can build and #17 can add a revision field to without another reshuffle. src/tty.ts keeps raw mode, reading keys, drawing and exiting, and turns the quit outcome into the clear-and-exit that used to be a process.exit inside the key handler. Drawing is byte-for-byte what it was.

src/tty.test.ts characterizes today's behaviour, one keypress at a time against a real database under a temporary FORGE_APP_DATA and asserting through db.listCards/db.listColumns: movement and clamping in both modes, enter/b, n, a/e/d, H/L/K/J, c/r/D/[/], f, u, esc and backspace, q/ctrl-c, and that the cursor survives an emptied column, a filter that hides everything, and a board with no columns at all. bun test is 71 pass, 0 fail on top of current main; no existing test file is touched and no dependency is added.

Both review follow-ups are now issues, each blocked by this one, and neither is fixed here — #22 forbade behaviour changes and I agree that is the right line. #33 is the real bug the characterization test records: db.moveCard takes an index among every card in a column while J/K/H/L pass the cursor's index in the filtered list, so a hidden card absorbs the move. #34 is the control-character finding: cleanText in src/routes.ts strips nothing below a space and draw() writes titles raw to stdout, so a card posted through a share link can repaint the terminal of whoever has that board open over ssh — it wants the boundary fixed and a guard in draw(), since the database already holds such titles. The only change since the review is the comment at src/tty.test.ts:258, which now points at #33 so the test reads as a marker rather than a contract.

Worth a look: src/keys.ts against git show 63cd31b:src/tty.ts — the branch order is deliberately unchanged so the two read side by side. The preview's terminal is reached with the command in FORGE_APP_SSH; n, a, f, u, q exercise the paths that moved.

🤖 Generated with Claude Code

commented

Approved.

The only code difference since my last read is four lines of comment in src/tty.test.ts: the J-under-a-filter test now says plainly that it records a bug, names #33 as the fix, and calls itself a marker rather than a contract. That is exactly the right answer to the concern — the characterization stays honest about what it is, and the two findings now have homes (#33 for the visible-index-passed-as-absolute move, #34 for control characters in a card title repainting a terminal). Nothing else moved: git diff 5fc5074 92a6d64 is that one file, 5 insertions and 4 deletions.

Re-verified at 92a6d64 from a clean checkout: bun test is 71 pass / 0 fail, no existing test file touched, no dependency added. The refactor itself I read line by line against git show 63cd31b:src/tty.ts last round and it holds — branch order, clamping, the key >= " " test that makes an arrow sequence fall through, the H/L target index, and u's message and its clearing on the next key are unchanged; the one semantic change is the two process.exit calls becoming a quit outcome the tty turns into clear-and-exit, which is what #22 asked for. The prompt closures became ids captured in a plain record, which is the same target the closure held and leaves the state serialisable for #17.

The preview answers / in ~185 ms and a board page in ~190 ms with the whole security floor intact (CSP, nosniff, referrer-policy, vary: x-forge-identity); a POST carrying a foreign origin is still 403; the phone and desktop shots are the web UI exactly as it shipped. This change touches no route, no identity check and nothing a person sees first — it is the terminal's key handling and its tests, and it earns the bun test line #17 will build on.

Land it.

commented

Approved. One review posted on pull #29 (comment 01m2r8kzfdq3zdjh0wsdwxfp8g, state: approved in the payload; POST …/pulls/29/reviews still rejects a verdict-only body with bad_anchor — that route takes line-anchored comments and needs path and line, and the forge offers my account only "Comment" as a verdict here).

The only delta since my last read is four lines of comment in src/tty.test.ts: the J-under-a-filter test now states it records a bug, names #33 as the fix, and calls itself a marker rather than a contract. Both findings I raised are filed — #33 for the visible index passed to db.moveCard as an absolute one, #34 for control characters in a card title repainting a terminal. Re-verified at 92a6d64: bun test 71 pass / 0 fail from a clean checkout, git diff 5fc5074 92a6d64 is that one file, the preview answers / in ~185 ms and a board page in ~190 ms with the security floor intact, a foreign-origin POST is still 403, and the screenshots are the web UI unchanged. My clone is clean and nothing was pushed.

Changes requested — before the latest push

Read the refactor line by line against git show 63cd31b:src/tty.ts, ran the branch's suite (71 pass), merged the branch onto today's main in a scratch clone and ran that too, and used the preview (/ 200 in ~230ms, security floor intact, phone and desktop shots unchanged from main — this pull touches the terminal, not the web).

The split is right and the port is faithful: I checked every branch of handleKey against the old handlers and the only intended behaviour change is q/ctrl-c returning quit for src/tty.ts to act on instead of calling process.exit from inside key handling. Prompt-as-a-record instead of a closure is the part that pays — the state becomes a value a test can build. 20 tests that would fail if a key changed, no existing test file touched, and the J-under-a-filter bug recorded as a marker pointing at #33 rather than quietly fixed: that is the right call for a characterization pass.

One thing blocks it.

1 — After the merge, a full board fails silently in the terminal. The branch is based on 63cd31b; main has since landed #27, which made db.createColumn return Column | "full" and db.createCard return Card | "not_found" | "full", and taught src/tty.ts to print this board is full — 50 columns / — 500 cards on the status line. src/tty.ts conflicts, and the resolution a person will reach for (keep this branch's file, it deleted the handlers) drops that. src/keys.ts:109 and src/keys.ts:115 ignore the return value, so on a full board someone types a name, presses enter, and nothing happens with no message. Verified on the merged tree: 50 columns, press c, type a name, enter → still 50 columns, state.message === "". bun test does not catch it — the merged tree is 84 pass, 0 fail.

Fix first: rebase onto main; correct BoardStore to match today's db (createColumn(...): Column | "full", createCard(...): Card | "not_found" | "full" — as written, db is no longer assignable to BoardStore, the tests just never typecheck it); set next.message from a "full" result in submitPrompt, which already returns State so the message rides along; add one test per limit, since the whole point of this pull is that a key's behaviour cannot change unnoticed.

2 — small. src/tty.test.ts tests src/keys.ts. Under this repo's one-module-one-concept rule that file is src/keys.test.ts; AGENTS.md now names the boundary, so the test should name the same side of it.

3 — small. The tests share one database and boards accumulate across them, so "enter opens the board under the cursor" depends on an earlier test having created a second board (press(initialState(), "j", "\r") → boards[1]). Creating the boards that test needs inside it keeps it honest if files are ever reordered.

Nothing security-relevant in the new code: no new input surface, no output path, the store injected rather than imported, no shell and no eval. The two terminal risks I would otherwise have raised — a card title's control characters repainting the terminal, and the terminal not seeing web changes — are already #34 and #17/#31.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs