hunk: Instructions file for Codex

hunk agent notes

purpose

• Terminal-first diff viewer for understanding coding-agent changesets.
• Product target is "modern desktop diff tool in a terminal", not a pager-style TUI.

architecture

workspace map

packages/hunk/                 published CLI, application, and public extension/OpenTUI facades
packages/hunk-vcs/             private dependency-bottom VCS helpers
packages/hunk-{git,jj,sapling}/ private bundled VCS providers
packages/hunk-gh/              private bundled GitHub review extension
packages/session-broker-core/  low-level broker protocol and state
packages/session-broker/       runtime-neutral broker, daemon, auth, and connection lifecycle
packages/session-broker-{bun,node}/ runtime listener adapters
packages/term-video/           private terminal capture tooling
website/                       product/documentation site, not the browser review client

application flow

main.tsx -> app/startup.ts -> app/cli.ts
  -> headless command/history plan returned to main.tsx, or
  -> app plan: extensionBootstrap.ts -> sessionBootstrap.ts -> normalized Changeset / DiffFile[]
     -> main.tsx lazy-loads runInteractiveApp.tsx -> HunkSessionHost -> AppHost -> App
     -> pane/diff planning -> Pierre-backed terminal rows

shared review seam

Terminal, agent/session, broker/protocol, extension, and HTTP/SSE consumers share review semantics. The browser client and UI remain planned. Do not recreate semantic review behavior in a surface:

DiffFile[] -> projectReviewDocument -> ReviewDocumentV1 -> ReviewStore
ReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer -> surface projection

• Model: packages/hunk/src/core/review/{types,document,identity}.ts owns the ordered, JSON-safe document. File order is review/sidebar order; use key (referenced as fileKey elsewhere), contentIdentity, and sourceIdentity (cached source text additionally requires sourceAttested) — not runtime IDs or indexes — across reloads/surfaces.
• Shared derivations: geometry.ts, expansion.ts, anchors.ts, stml.ts, and contentManifest.ts own ranges, gaps, source splitting, note targets/ownership, tag roles, and parity manifests. Consume them; never re-derive those facts in a renderer.
• State: state.ts is semantic state; actions.ts transitions; reducer.ts pure/no-I/O; selectors.ts shared policies; store.ts synchronous observable storage. New cross-surface operations start as intents. Callers supply mutable-note IDs/timestamps; core derives identities.
• Surfaces/publishers: useTerminalReview.ts is the TUI adapter and reviewNoteMapping.ts is terminal-only. Rows, measurement, scrolling, layout, themes, DOM mechanics, and source I/O stay local. useHunkSessionBridge.ts publishes the current terminal session export; registration.ts builds its metadata/initial snapshot and bridge.ts receives agent commands. This broker export is not a full ReviewState mirror.
• Other consumers: Web/API consumers reuse the model, derivations, state, intents, and the producer/protocol tier. Never build a parallel protocol. Keep presentation/client-local state local; host/extension commands need explicit remote capabilities. See docs/browser-review-rebuild.md for the rollout and current boundaries.
• Conformance: test/review-conformance/ has hand-authored semantic fixtures covering every registered core, terminal, producer, broker, protocol, and extension projection. Every new semantic consumer registers its real projection and runs the whole corpus. scripts/quality/source-boundaries.test.ts keeps the seam renderer/platform-free; its Node-debt list is shrink-only and tombstone lists append-only. A repaid seam finding deletes copies, adds a file or banned-symbol tombstone and adversarial fixture, registers consumers, and updates docs/browser-review-seam-audit.md.