ruohki/bbs-md
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: create roadmap (4 phases)

Browse Source
This commit is contained in:
ruohki
2026-02-28 20:35:13 +01:00
parent 05a301ae63
commit 4f6c9bcdc9
3 changed files with 179 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+35 -35
View File
@@ -98,44 +98,44 @@ Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status | | Requirement | Phase | Status |
|-------------|-------|--------| |-------------|-------|--------|
| LIFE-01 | — | Pending | | LIFE-01 | Phase 1 | Pending |
| LIFE-02 | — | Pending | | LIFE-02 | Phase 1 | Pending |
| LIFE-03 | — | Pending | | LIFE-03 | Phase 1 | Pending |
| LIFE-04 | — | Pending | | LIFE-04 | Phase 1 | Pending |
| REND-01 | — | Pending | | CONF-01 | Phase 1 | Pending |
| REND-02 | — | Pending | | SHEL-01 | Phase 1 | Pending |
| REND-03 | — | Pending | | SHEL-02 | Phase 1 | Pending |
| REND-04 | — | Pending | | REND-01 | Phase 2 | Pending |
| REND-05 | — | Pending | | REND-02 | Phase 2 | Pending |
| REND-06 | — | Pending | | REND-03 | Phase 2 | Pending |
| REND-07 | — | Pending | | REND-04 | Phase 2 | Pending |
| REND-08 | — | Pending | | REND-05 | Phase 2 | Pending |
| REND-09 | — | Pending | | REND-06 | Phase 2 | Pending |
| REND-10 | — | Pending | | REND-07 | Phase 2 | Pending |
| NAV-01 | — | Pending | | REND-08 | Phase 2 | Pending |
| NAV-02 | — | Pending | | REND-09 | Phase 2 | Pending |
| NAV-03 | — | Pending | | REND-10 | Phase 2 | Pending |
| NAV-04 | — | Pending | | NAV-05 | Phase 2 | Pending |
| NAV-05 | — | Pending | | NAV-06 | Phase 2 | Pending |
| NAV-06 | — | Pending | | NAV-07 | Phase 2 | Pending |
| NAV-07 | — | Pending | | NAV-08 | Phase 2 | Pending |
| NAV-08 | — | Pending | | NAV-09 | Phase 2 | Pending |
| NAV-09 | — | Pending | | NAV-01 | Phase 3 | Pending |
| NAV-10 | — | Pending | | NAV-02 | Phase 3 | Pending |
| NAV-11 | — | Pending | | NAV-03 | Phase 3 | Pending |
| BBS-01 | — | Pending | | NAV-04 | Phase 3 | Pending |
| BBS-02 | — | Pending | | NAV-10 | Phase 3 | Pending |
| LIVE-01 | — | Pending | | NAV-11 | Phase 3 | Pending |
| LIVE-02 | — | Pending | | BBS-01 | Phase 4 | Pending |
| CONF-01 | — | Pending | | BBS-02 | Phase 4 | Pending |
| SHEL-01 | — | Pending | | LIVE-01 | Phase 4 | Pending |
| SHEL-02 | — | Pending | | LIVE-02 | Phase 4 | Pending |
**Coverage:** **Coverage:**
- v1 requirements: 32 total - v1 requirements: 32 total
- Mapped to phases: 0 - Mapped to phases: 32
- Unmapped: 32 ⚠️ - Unmapped: 0
--- ---
*Requirements defined: 2026-02-28* *Requirements defined: 2026-02-28*
*Last updated: 2026-02-28 after initial definition* *Last updated: 2026-02-28 after roadmap creation*
.planning/ROADMAP.md
+79
View File
@@ -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 | - |
.planning/STATE.md
+65
View File
@@ -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