docs(01-02): complete terminal safety primitives plan
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
---
|
||||
phase: 01-safety-foundation
|
||||
plan: 02
|
||||
subsystem: terminal
|
||||
tags: [rust, ratatui, crossterm, signal-hook, atomic-bool, panic-hook, raw-mode]
|
||||
|
||||
# Dependency graph
|
||||
requires: []
|
||||
provides:
|
||||
- "src/terminal.rs: init_terminal(), restore_terminal(), install_panic_hook(), Term type alias"
|
||||
- "src/signals.rs: SignalFlags, register_signals(), init_logging() stub"
|
||||
affects:
|
||||
- 01-03
|
||||
- all future phases (terminal safety envelope)
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added:
|
||||
- "ratatui::crossterm (via re-export — crossterm is a transitive dependency)"
|
||||
- "signal-hook 0.4.3 (direct dependency, already in Cargo.toml)"
|
||||
patterns:
|
||||
- "main screen buffer with Viewport::Fullscreen instead of alternate screen"
|
||||
- "let _ = for all cleanup operations in restore and panic hook"
|
||||
- "AtomicBool polling for signal handling without async runtime"
|
||||
- "take_hook + set_hook for panic hook chaining"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- src/terminal.rs
|
||||
- src/signals.rs
|
||||
modified:
|
||||
- src/main.rs
|
||||
|
||||
key-decisions:
|
||||
- "Use ratatui::crossterm re-export instead of direct crossterm dependency (avoids version conflicts)"
|
||||
- "SIGINT not registered via signal-hook — handled via crossterm key events for double-press Ctrl+C (Plan 03)"
|
||||
- "restore_terminal() never calls ratatui::restore() — that would call LeaveAlternateScreen which was never entered"
|
||||
|
||||
patterns-established:
|
||||
- "Cleanup-safe pattern: every operation in restore_terminal() and panic hook uses let _ ="
|
||||
- "No unwrap() or ? in panic hook — double-panic prevention"
|
||||
- "Viewport::Fullscreen for main screen BBS immersive mode"
|
||||
|
||||
requirements-completed: [LIFE-01, LIFE-02, LIFE-03, LIFE-04]
|
||||
|
||||
# Metrics
|
||||
duration: 3min
|
||||
completed: 2026-02-28
|
||||
---
|
||||
|
||||
# Phase 1 Plan 02: Terminal Safety Primitives Summary
|
||||
|
||||
**Main-screen BBS terminal with panic recovery hook, SIGHUP/SIGTERM AtomicBool flag registration, and broken-pipe-safe cleanup using ratatui::crossterm re-export**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~3 min
|
||||
- **Started:** 2026-02-28T20:10:36Z
|
||||
- **Completed:** 2026-02-28T20:12:58Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 3
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Terminal initializes on the main screen buffer (not alternate screen) with raw mode — immersive BBS feel where TUI output persists in scroll history after exit
|
||||
- Panic hook restores terminal state before printing a BBS-themed user message, then delegates to original hook for sysop details (journald/SSH log)
|
||||
- SIGHUP and SIGTERM register a shared AtomicBool flag for event loop polling; SIGINT deliberately excluded to enable double-press Ctrl+C via crossterm key events in Plan 03
|
||||
- All cleanup paths (restore_terminal, panic hook) use `let _ =` on every operation — no double-panic risk
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Terminal init/restore and panic hook** - `b258b6d` (feat)
|
||||
2. **Task 2: Signal handling and logging stub** - `966b47e` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `src/terminal.rs` - init_terminal() (main screen, raw mode, Viewport::Fullscreen), restore_terminal() (let _ = pattern), install_panic_hook() (BBS message + original hook delegation), Term type alias
|
||||
- `src/signals.rs` - SignalFlags struct, register_signals() (SIGHUP + SIGTERM only), should_terminate() poll method, init_logging() Phase 1 stub
|
||||
- `src/main.rs` - Added `mod signals;` and `mod terminal;` declarations
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- Used `ratatui::crossterm` re-export path instead of adding crossterm as a direct dependency. Crossterm is a transitive dependency only; using the re-export avoids version conflicts and keeps Cargo.toml minimal.
|
||||
- SIGINT is NOT registered via signal-hook. The double-press Ctrl+C state machine (SHEL-01) will use crossterm key events (`KeyCode::Char('c') + KeyModifiers::CONTROL`) in the event loop — registering SIGINT twice causes double-handling.
|
||||
- `restore_terminal()` never calls `ratatui::restore()`. That function calls `LeaveAlternateScreen` unconditionally, which corrupts the terminal since we never entered the alternate screen.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Used ratatui::crossterm re-export instead of bare crossterm import**
|
||||
- **Found during:** Task 1 (terminal.rs build verification)
|
||||
- **Issue:** `use crossterm::...` failed to compile — crossterm is a transitive dependency not listed in Cargo.toml directly. Compiler error: "use of unresolved module or unlinked crate `crossterm`" with hint pointing to `ratatui::crossterm`
|
||||
- **Fix:** Changed all `crossterm::` imports to `ratatui::crossterm::` re-export path. Also updated the inlined `execute!` calls inside the panic hook closure to use the fully-qualified `ratatui::crossterm::` path.
|
||||
- **Files modified:** src/terminal.rs
|
||||
- **Verification:** `cargo build` succeeds
|
||||
- **Committed in:** b258b6d (Task 1 commit)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (1 blocking import error)
|
||||
**Impact on plan:** Necessary fix — imports must resolve for compilation. Using re-export path is semantically identical and more robust against version mismatches.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None beyond the crossterm import deviation documented above.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Terminal safety envelope is complete: all exit paths (panic, signal, normal quit) restore the terminal correctly
|
||||
- `install_panic_hook()` should be called first in main() before any terminal init
|
||||
- `register_signals()` returns a `SignalFlags` whose `should_terminate()` method the Plan 03 event loop will poll at the top of each iteration
|
||||
- `init_terminal()` and `restore_terminal()` are ready for Plan 03 integration into the application entry point
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- src/terminal.rs: FOUND
|
||||
- src/signals.rs: FOUND
|
||||
- 01-02-SUMMARY.md: FOUND
|
||||
- Commit b258b6d (Task 1): FOUND
|
||||
- Commit 966b47e (Task 2): FOUND
|
||||
|
||||
---
|
||||
*Phase: 01-safety-foundation*
|
||||
*Completed: 2026-02-28*
|
||||
Reference in New Issue
Block a user