diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 032273f..fe99b0d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -98,44 +98,44 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| LIFE-01 | — | Pending | -| LIFE-02 | — | Pending | -| LIFE-03 | — | Pending | -| LIFE-04 | — | Pending | -| REND-01 | — | Pending | -| REND-02 | — | Pending | -| REND-03 | — | Pending | -| REND-04 | — | Pending | -| REND-05 | — | Pending | -| REND-06 | — | Pending | -| REND-07 | — | Pending | -| REND-08 | — | Pending | -| REND-09 | — | Pending | -| REND-10 | — | Pending | -| NAV-01 | — | Pending | -| NAV-02 | — | Pending | -| NAV-03 | — | Pending | -| NAV-04 | — | Pending | -| NAV-05 | — | Pending | -| NAV-06 | — | Pending | -| NAV-07 | — | Pending | -| NAV-08 | — | Pending | -| NAV-09 | — | Pending | -| NAV-10 | — | Pending | -| NAV-11 | — | Pending | -| BBS-01 | — | Pending | -| BBS-02 | — | Pending | -| LIVE-01 | — | Pending | -| LIVE-02 | — | Pending | -| CONF-01 | — | Pending | -| SHEL-01 | — | Pending | -| SHEL-02 | — | Pending | +| LIFE-01 | Phase 1 | Pending | +| LIFE-02 | Phase 1 | Pending | +| LIFE-03 | Phase 1 | Pending | +| LIFE-04 | Phase 1 | Pending | +| CONF-01 | Phase 1 | Pending | +| SHEL-01 | Phase 1 | Pending | +| SHEL-02 | Phase 1 | Pending | +| REND-01 | Phase 2 | Pending | +| REND-02 | Phase 2 | Pending | +| REND-03 | Phase 2 | Pending | +| REND-04 | Phase 2 | Pending | +| REND-05 | Phase 2 | Pending | +| REND-06 | Phase 2 | Pending | +| REND-07 | Phase 2 | Pending | +| REND-08 | Phase 2 | Pending | +| REND-09 | Phase 2 | Pending | +| REND-10 | Phase 2 | Pending | +| NAV-05 | Phase 2 | Pending | +| NAV-06 | Phase 2 | Pending | +| NAV-07 | Phase 2 | Pending | +| NAV-08 | Phase 2 | Pending | +| NAV-09 | Phase 2 | Pending | +| NAV-01 | Phase 3 | Pending | +| NAV-02 | Phase 3 | Pending | +| NAV-03 | Phase 3 | Pending | +| NAV-04 | Phase 3 | Pending | +| NAV-10 | Phase 3 | Pending | +| NAV-11 | Phase 3 | Pending | +| BBS-01 | Phase 4 | Pending | +| BBS-02 | Phase 4 | Pending | +| LIVE-01 | Phase 4 | Pending | +| LIVE-02 | Phase 4 | Pending | **Coverage:** - v1 requirements: 32 total -- Mapped to phases: 0 -- Unmapped: 32 ⚠️ +- Mapped to phases: 32 +- Unmapped: 0 --- *Requirements defined: 2026-02-28* -*Last updated: 2026-02-28 after initial definition* +*Last updated: 2026-02-28 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..8134446 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,79 @@ +# Roadmap: BBS-MD + +## Overview + +Four phases take this project from a bare Rust scaffold to a fully functional retro BBS markdown vault reader. Phase 1 establishes process safety — the login-shell deployment context means a crash without terminal restoration locks out every SSH user. Phase 2 builds the vault engine and renderer, producing the core content display pipeline. Phase 3 wires up link navigation, back/forward history, and keyboard link cycling, turning the viewer into an actual browser. Phase 4 adds the BBS aesthetic differentiators and live filesystem watching that make the experience feel like a real BBS rather than a generic TUI app. + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [ ] **Phase 1: Safety Foundation** - Process lifecycle safety, shell integration, and configuration +- [ ] **Phase 2: Vault Core and Rendering** - Markdown parsing pipeline and full content display +- [ ] **Phase 3: Navigation and Links** - Link following, back/forward history, link cycling +- [ ] **Phase 4: BBS Polish and Live Content** - Retro aesthetic, filesystem watching, directory listing + +## Phase Details + +### Phase 1: Safety Foundation +**Goal**: The app launches as a login shell, handles crashes and disconnects without locking out users, and reads its configuration +**Depends on**: Nothing (first phase) +**Requirements**: LIFE-01, LIFE-02, LIFE-03, LIFE-04, SHEL-01, SHEL-02, CONF-01 +**Success Criteria** (what must be TRUE): + 1. When the app panics, the SSH session returns to a usable terminal state instead of leaving it broken + 2. When a user disconnects via SSH (SIGHUP) or the process is killed (SIGTERM), the app exits cleanly without corrupting the terminal + 3. The app reads vault path and theme settings from bbs.toml and applies them on launch + 4. The app exits cleanly when the user presses q or Ctrl+C, restoring the terminal + 5. The app starts correctly when invoked as a login shell (argv[0] may have a leading dash) +**Plans**: TBD + +### Phase 2: Vault Core and Rendering +**Goal**: Users can read a markdown document — all standard constructs render correctly and content is scrollable +**Depends on**: Phase 1 +**Requirements**: REND-01, REND-02, REND-03, REND-04, REND-05, REND-06, REND-07, REND-08, REND-09, REND-10, NAV-05, NAV-06, NAV-07, NAV-08, NAV-09 +**Success Criteria** (what must be TRUE): + 1. User sees headers (H1-H6), bold, italic, inline code, fenced code blocks, lists, blockquotes, horizontal rules, and image placeholders rendered with distinct visual styling + 2. User sees GFM tables rendered with aligned columns + 3. User lands on index.md when the app starts; when index.md is missing, a readable error page is shown instead of a crash + 4. User can scroll content longer than the terminal with j/k, arrow keys, and PgUp/PgDn + 5. User sees keyboard hints in the status bar, box-drawing borders on panels, and a CGA-era retro color theme; the layout reflows correctly when the terminal is resized +**Plans**: TBD + +### Phase 3: Navigation and Links +**Goal**: Users can browse the vault by following links and navigating back and forward through their history +**Depends on**: Phase 2 +**Requirements**: NAV-01, NAV-02, NAV-03, NAV-04, NAV-10, NAV-11 +**Success Criteria** (what must be TRUE): + 1. User can press Enter on a highlighted wiki-link (`[[Page Name]]`) to navigate to that document + 2. User can press Enter on a highlighted standard markdown link (`[text](path.md)`) to navigate to that document + 3. User can press Backspace or a back key to return to the previous document, and then press a forward key to return to where they were + 4. User can Tab-cycle between links on a page to select and follow them without using a mouse + 5. User sees their current location (breadcrumb) in the status bar +**Plans**: TBD + +### Phase 4: BBS Polish and Live Content +**Goal**: The app feels like a real BBS — the index page has an ANSI art header, pages show last-updated timestamps, a vault directory is browsable, and content updates live without restarting +**Depends on**: Phase 3 +**Requirements**: BBS-01, BBS-02, LIVE-01, LIVE-02 +**Success Criteria** (what must be TRUE): + 1. The index.md page displays an ANSI art splash screen header + 2. Each page shows the file's last-modified timestamp + 3. When a markdown file in the vault is modified on disk, the currently displayed page auto-refreshes without the user doing anything + 4. User can navigate to a vault-wide directory listing showing all available documents +**Plans**: TBD + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Safety Foundation | 0/TBD | Not started | - | +| 2. Vault Core and Rendering | 0/TBD | Not started | - | +| 3. Navigation and Links | 0/TBD | Not started | - | +| 4. BBS Polish and Live Content | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..cf698de --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,65 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-02-28) + +**Core value:** Users can connect via SSH and seamlessly browse a vault of linked markdown documents with retro BBS aesthetics +**Current focus:** Phase 1 - Safety Foundation + +## Current Position + +Phase: 1 of 4 (Safety Foundation) +Plan: 0 of TBD in current phase +Status: Ready to plan +Last activity: 2026-02-28 — Roadmap created + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: - +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- Pre-Phase 1: Verify `edition = "2024"` compiles before changing to 2021 — leave it if `cargo build` succeeds +- Pre-Phase 1: Use pulldown-cmark event-based approach for markdown parsing (not comrak) +- Pre-Phase 1: No tokio/async runtime — synchronous event loop only +- Pre-Phase 2: Choose wiki-link parsing strategy before implementation (regex pre-pass vs post-parse interception) + +### Pending Todos + +None yet. + +### Blockers/Concerns + +- **LIFE**: Panic hook and SIGHUP handling are highest priority — must land before any feature code +- **REND**: Verify ratatui 0.30 custom Widget trait signature before building BBS widgets (changed between 0.28 and 0.29) +- **NAV**: Path traversal via wiki-links must be addressed in Phase 3 link resolver — canonicalize and prefix-check every resolved path +- **LIVE**: notify 8.x API must be verified at integration time; watch only current file (not full vault) to avoid inotify exhaustion + +## Session Continuity + +Last session: 2026-02-28 +Stopped at: Roadmap created, ready to plan Phase 1 +Resume file: None