tmk241/mim
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

NS10 slice: Build PTY-backed browser terminal harness #69

New Issue
Closed
opened 2026-06-21 14:50:34 +00:00 by tmk241 · 1 comment
tmk241 commented 2026-06-21 14:50:34 +00:00
Owner
Copy Link
Copy Source

OBJECTIVE: Add the first deterministic mim terminal E2E harness: launch the compiled editor under a pseudo-terminal, render it in a real browser-terminal surface, drive input, and produce screenshot/text artifacts from one local build command.

AUTHORITY: Parent #65; PRODUCT.md server-side terminal editor boundary; REQUIREMENTS.md req: testing/001-004, session/001-004, input/001-002, ui/001; AGENTS.md verification rules.

AGENT AUTHORITY:

  • Delivery authority: local-commit
  • Tracker authority: this issue may be commented and closed when acceptance passes; comment parent #65 with the completion receipt.
  • Handoff state: committed clean, tracker commented/closed.

PARENT: #65 NS10 via explicit parent link and parent checklist.

SCOPE: build.zig; a small test-support harness under src/ or test-support/; browser terminal fixture/page if needed; PTY spawn/drive code; artifact output path under zig-cache or /tmp only.

BOUNDARIES:

  • No cloud/browser service.
  • No native iOS automation.
  • No runtime product config, plugins, package managers, or hidden installers.
  • Do not attempt full behavior matrix here; prove one thin browser-terminal path end-to-end.

REGRESSION CLASS: catches harness-level blind spots where unit/headless tests pass but a real PTY/browser terminal shows raw-mode skew, missing chrome, broken raw key delivery, or missing artifacts.

EVIDENCE ARTIFACTS: browser screenshot, browser/terminal text transcript, PTY input/output log or equivalent, scenario command receipt, and artifact path report.

REQUIREMENT IMPACT: requires authority attention because terminal-e2e becomes a durable verification obligation; implementer should cite existing REQUIREMENTS.md testing/session/input/ui anchors and update requirement authority if the new command becomes canonical.

ACCEPTANCE:

  • A documented command, preferably zig build terminal-e2e, builds mim, starts it under a PTY, renders through a browser terminal implementation, sends a small input script, and exits deterministically.
  • The harness captures at least one screenshot artifact and one text/DOM/transcript artifact.
  • The initial scenario proves no diagonal CRLF skew, visible line-number gutter, visible cursor/chrome, and successful recognition of at least one raw key event.
  • Failure output points at artifact paths and includes enough terminal text to diagnose the problem.
  • Existing zig build, zig build test, and zig build v1-smoke remain green.

VERIFICATION:

  • zig build terminal-e2e
  • zig build test
  • zig build
  • redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md

BLOCKERS: none.

SLICE_CONTRACT:
objective: Create the minimum PTY + browser terminal E2E harness and command.
authority: #65, PRODUCT.md, REQUIREMENTS.md testing/session/input/ui rows.
acceptance: one browser-terminal scenario drives mim and captures screenshot + transcript artifacts that catch CRLF/chrome/raw-key regressions.
verification: zig build terminal-e2e plus canonical build/test gates.
non_goals: full matrix, cloud browser, native iOS automation, runtime config/plugin surfaces.
blockers: none.

OBJECTIVE: Add the first deterministic `mim` terminal E2E harness: launch the compiled editor under a pseudo-terminal, render it in a real browser-terminal surface, drive input, and produce screenshot/text artifacts from one local build command. AUTHORITY: Parent #65; PRODUCT.md server-side terminal editor boundary; REQUIREMENTS.md req: testing/001-004, session/001-004, input/001-002, ui/001; AGENTS.md verification rules. AGENT AUTHORITY: - Delivery authority: local-commit - Tracker authority: this issue may be commented and closed when acceptance passes; comment parent #65 with the completion receipt. - Handoff state: committed clean, tracker commented/closed. PARENT: #65 NS10 via explicit parent link and parent checklist. SCOPE: build.zig; a small test-support harness under src/ or test-support/; browser terminal fixture/page if needed; PTY spawn/drive code; artifact output path under zig-cache or /tmp only. BOUNDARIES: - No cloud/browser service. - No native iOS automation. - No runtime product config, plugins, package managers, or hidden installers. - Do not attempt full behavior matrix here; prove one thin browser-terminal path end-to-end. REGRESSION CLASS: catches harness-level blind spots where unit/headless tests pass but a real PTY/browser terminal shows raw-mode skew, missing chrome, broken raw key delivery, or missing artifacts. EVIDENCE ARTIFACTS: browser screenshot, browser/terminal text transcript, PTY input/output log or equivalent, scenario command receipt, and artifact path report. REQUIREMENT IMPACT: requires authority attention because `terminal-e2e` becomes a durable verification obligation; implementer should cite existing REQUIREMENTS.md testing/session/input/ui anchors and update requirement authority if the new command becomes canonical. ACCEPTANCE: - A documented command, preferably `zig build terminal-e2e`, builds `mim`, starts it under a PTY, renders through a browser terminal implementation, sends a small input script, and exits deterministically. - The harness captures at least one screenshot artifact and one text/DOM/transcript artifact. - The initial scenario proves no diagonal CRLF skew, visible line-number gutter, visible cursor/chrome, and successful recognition of at least one raw key event. - Failure output points at artifact paths and includes enough terminal text to diagnose the problem. - Existing `zig build`, `zig build test`, and `zig build v1-smoke` remain green. VERIFICATION: - `zig build terminal-e2e` - `zig build test` - `zig build` - `redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md` BLOCKERS: none. SLICE_CONTRACT: objective: Create the minimum PTY + browser terminal E2E harness and command. authority: #65, PRODUCT.md, REQUIREMENTS.md testing/session/input/ui rows. acceptance: one browser-terminal scenario drives mim and captures screenshot + transcript artifacts that catch CRLF/chrome/raw-key regressions. verification: `zig build terminal-e2e` plus canonical build/test gates. non_goals: full matrix, cloud browser, native iOS automation, runtime config/plugin surfaces. blockers: none.
tmk241 added the sliceready-for-agent labels 2026-06-21 14:50:34 +00:00
tmk241 commented 2026-06-21 15:18:08 +00:00
Author
Owner
Copy Link
Copy Source

Implemented and committed #69 as 70e6418 Add PTY terminal E2E harness.

What changed:

  • Added zig build terminal-e2e.
  • Added tools/terminal_e2e.py, a stdlib-only PTY harness that launches the compiled mim binary through a pseudo-terminal.
  • Drives one raw-key/chrome/CRLF scenario: type what is up, use mobile-safe Space n, save, quit.
  • Writes ignored artifacts under .zig-cache/terminal-e2e/raw-key-chrome-crlf/:
    • raw.bin
    • visible-controls.txt with visible CR/LF/ESC/control glyphs
    • transcript.txt semantic terminal grid
    • screenshot.svg browser-viewable screenshot artifact
    • terminal.html browser-viewable terminal page linking the SVG
  • Assertions catch saved-buffer mismatch, missing gutter, missing cursor marker, Space-n/mode failure, echoed ^[, and overwide terminal lines.

Verification:

  • zig build terminal-e2e
  • zig build test
  • zig build
  • zig build v1-smoke
  • zig build run -- --help
  • redgate list /opt/repositories/mim/REQUIREMENTS.md
  • redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md

Notes:

  • This is the walking skeleton requested by #69. It produces browser-viewable HTML/SVG artifacts from a real PTY transcript without adding external browser dependencies. Later NS10 slices can extend or replace this with a real browser engine if/when the repo adopts that dependency.
Implemented and committed #69 as `70e6418 Add PTY terminal E2E harness`. What changed: - Added `zig build terminal-e2e`. - Added `tools/terminal_e2e.py`, a stdlib-only PTY harness that launches the compiled `mim` binary through a pseudo-terminal. - Drives one raw-key/chrome/CRLF scenario: type `what is up`, use mobile-safe `Space n`, save, quit. - Writes ignored artifacts under `.zig-cache/terminal-e2e/raw-key-chrome-crlf/`: - `raw.bin` - `visible-controls.txt` with visible CR/LF/ESC/control glyphs - `transcript.txt` semantic terminal grid - `screenshot.svg` browser-viewable screenshot artifact - `terminal.html` browser-viewable terminal page linking the SVG - Assertions catch saved-buffer mismatch, missing gutter, missing cursor marker, Space-n/mode failure, echoed `^[`, and overwide terminal lines. Verification: - `zig build terminal-e2e` - `zig build test` - `zig build` - `zig build v1-smoke` - `zig build run -- --help` - `redgate list /opt/repositories/mim/REQUIREMENTS.md` - `redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md` Notes: - This is the walking skeleton requested by #69. It produces browser-viewable HTML/SVG artifacts from a real PTY transcript without adding external browser dependencies. Later NS10 slices can extend or replace this with a real browser engine if/when the repo adopts that dependency.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
goal
Issue has a Pi goal contract
 northstar
Parent outcome for v1 product work
 ready-for-agent
Scoped and unblocked for agent implementation
 slice
Executable vertical child issue
No Label ready-for-agent slice
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
tmk241
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: tmk241/mim#69
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?