Add Phase 1 requirements checklist with NFRs
Consolidates the conversation and ADRs into a checkable Phase 1 requirements document: 66 functional items, 7 NFRs (performance, visual quality, light/dark background support, cross-platform parity), and 3 explicitly out-of-scope items. Stable per-item IDs, status legend, test-suite baseline, and maintenance rules.
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,326 @@
|
||||
# RDBMS Playground — Requirements (Phase 1)
|
||||
|
||||
This document is the **consolidated Phase 1 requirements
|
||||
checklist** for RDBMS Playground. It captures everything the
|
||||
project has committed to so far, derived from the design
|
||||
conversation and the ADRs in `docs/adr/`.
|
||||
|
||||
**Purpose.** Phase 5 verification at every milestone measures
|
||||
delivered work against this checklist. An item not on this list
|
||||
was not promised; an item silently dropped without confirmation
|
||||
is a process failure.
|
||||
|
||||
**Scope.** The list is intentionally coarse — each item is a
|
||||
unit of "satisfied / not satisfied" judgement. When an item is
|
||||
taken up for implementation, it is decomposed further in a
|
||||
backlog (initially in this repo, later in GitHub issues once the
|
||||
repo is pushed).
|
||||
|
||||
## Status legend
|
||||
|
||||
- `[ ]` — open, not yet implemented
|
||||
- `[x]` — satisfied (implemented + tested)
|
||||
- `[~]` — deferred, awaiting an ADR or further design before any
|
||||
implementation
|
||||
- `[-]` — explicitly out of scope (rationale at the bottom)
|
||||
|
||||
## Test baseline
|
||||
|
||||
No test suite exists yet — the repo currently contains only
|
||||
docs. The baseline is therefore "0 passing, 0 failing, 0
|
||||
skipped." Subsequent phases establish the suite and measure
|
||||
against it.
|
||||
|
||||
---
|
||||
|
||||
## Distribution and install
|
||||
|
||||
- [ ] **D1** Cross-platform binaries: Linux, macOS, Windows on
|
||||
x86_64 and aarch64.
|
||||
- [ ] **D2** Single static binary, no runtime dependencies.
|
||||
- [ ] **D3** Released via prebuilt binaries plus Homebrew, Scoop,
|
||||
`winget`, and `cargo binstall`.
|
||||
|
||||
## TUI shell
|
||||
|
||||
- [ ] **S1** Three-region layout: items list (left), output
|
||||
panel (right), input field (bottom).
|
||||
- [ ] **S2** Items list shows tables and per-table indexes;
|
||||
designed to extend to additional element kinds (relations,
|
||||
views, etc.) without restructuring.
|
||||
- [ ] **S3** Output panel renders a visualization of the
|
||||
currently selected item and supports multiple tabs.
|
||||
- [ ] **S4** Hint area below the input field; keyboard-toggleable
|
||||
for inspecting hints about the current input or last error.
|
||||
- [ ] **S5** Mode label and distinct border style on the input
|
||||
field communicate the current input mode at all times.
|
||||
|
||||
## Input field
|
||||
|
||||
- [ ] **I1** Multi-line entry that auto-expands; Ctrl-Enter (or
|
||||
equivalent) submits, plain Enter inserts a newline.
|
||||
- [ ] **I2** Persistent navigable input history (project-scoped,
|
||||
with a global rolling history also available).
|
||||
- [ ] **I3** Tab completion for app commands, DSL keywords, table
|
||||
names, column names, and SQL keywords.
|
||||
- [ ] **I4** Syntax highlighting for both the DSL and SQL.
|
||||
- [ ] **I5** In-flight query/command cancellation (Ctrl-C in the
|
||||
output area or input field).
|
||||
|
||||
## Input modes (per ADR-0003)
|
||||
|
||||
- [ ] **M1** Simple mode is the default. It accepts DSL data
|
||||
commands and the canonical app-level commands; raw SQL is
|
||||
rejected with a friendly hint.
|
||||
- [ ] **M2** Advanced mode accepts SQL plus the canonical
|
||||
app-level commands without any sigil.
|
||||
- [ ] **M3** Prefixing a single line with `:` in simple mode is a
|
||||
one-shot advanced escape (with the prompt label updated). The
|
||||
`mode simple` / `mode advanced` command switches modes
|
||||
persistently.
|
||||
|
||||
## App-level commands (per ADR-0003)
|
||||
|
||||
- [ ] **A1** All canonical app-level commands implemented and
|
||||
available in both modes: `save`, `save as`, `load`, `new`,
|
||||
`export`, `import`, `seed`, `replay`, `undo`, `redo`, `mode`,
|
||||
`help`, `hint`, `quit`.
|
||||
|
||||
## DSL data commands
|
||||
|
||||
- [ ] **C1** Table operations: create / drop / rename.
|
||||
- [ ] **C2** Column operations: add / drop / rename / change
|
||||
type, including the rebuild-table dance behind the scenes
|
||||
where SQLite ALTER cannot do it directly.
|
||||
- [ ] **C3** Schema constraints: primary key (single and
|
||||
compound), foreign key with `ON DELETE` / `ON UPDATE` referential
|
||||
actions, indexes, `NOT NULL`, `UNIQUE`, `CHECK`, `DEFAULT`.
|
||||
- [ ] **C4** Convenience: `create m:n relationship from <T1> to
|
||||
<T2>` produces an auto-named junction table the user can rename;
|
||||
pulls primary keys and FK definitions automatically.
|
||||
- [ ] **C5** Data operations: insert / update / delete via DSL.
|
||||
|
||||
## SQL handling
|
||||
|
||||
- [ ] **Q1** SQL parsed via `sqlparser-rs`; supported subset is
|
||||
defined (specifics deferred to a future ADR).
|
||||
- [ ] **Q2** Non-standard syntax rejected with a clear message
|
||||
pointing at the supported subset.
|
||||
- [ ] **Q3** User-facing simplified types map transparently to
|
||||
SQLite STRICT types in generated DDL.
|
||||
- [~] **Q4** Supported SQL subset specification — design and ADR
|
||||
pending. Q1 cannot be marked satisfied without it.
|
||||
|
||||
## Database backend (per ADR-0002)
|
||||
|
||||
- [ ] **B1** SQLite via `rusqlite`; all tables created `STRICT`;
|
||||
`PRAGMA foreign_keys = ON` per connection.
|
||||
- [ ] **B2** Schema evolution uses the rebuild-table technique
|
||||
internally where SQLite `ALTER TABLE` cannot.
|
||||
- [ ] **B3** Query timeout and cancellation supported (no
|
||||
cartesian-join-of-doom can hang the app).
|
||||
|
||||
## Type system (per ADR-0005)
|
||||
|
||||
- [ ] **T1** All ten user-facing types implemented: `text`,
|
||||
`int`, `real`, `decimal`, `bool`, `date`, `datetime`, `blob`,
|
||||
`serial`, `shortid`.
|
||||
- [ ] **T2** `shortid` generation: base58, 10–12 characters,
|
||||
omits ambiguous characters; generated client-side at insert.
|
||||
- [ ] **T3** Compound primary keys handled end-to-end (DSL,
|
||||
storage, display, FK reference).
|
||||
|
||||
## Visualizations
|
||||
|
||||
- [ ] **V1** Single-element views render in the output pane: a
|
||||
selected table as its structure (columns, types, keys,
|
||||
constraints); a selected relationship as two tables joined by
|
||||
a line.
|
||||
- [ ] **V2** SQL query results render as a dynamic table view in
|
||||
the output pane, with multiple result tabs supported.
|
||||
- [~] **V3** Full ER-diagram export (whole-database graph, viewed
|
||||
outside the TUI) — low priority; design and ADR pending.
|
||||
|
||||
## Project lifecycle (per ADR-0004)
|
||||
|
||||
- [ ] **P1** An auto-named temporary project is created on
|
||||
startup unless a project is specified, and stored in a
|
||||
platform-standard path
|
||||
(e.g. `~/.rdbms-playground/projects/temp-<name>`).
|
||||
- [ ] **P2** `save` elevates a temp project to a named project at
|
||||
a chosen location.
|
||||
- [ ] **P3** Project is always saved as changes occur — there is
|
||||
no manual dirty state.
|
||||
- [ ] **P4** `load` opens a picker listing temp projects with
|
||||
timestamps, with the option to browse to an arbitrary location.
|
||||
- [ ] **P5** `playground.db` is a derived artifact: rebuilt
|
||||
silently when missing, rebuilt with confirmation and a change
|
||||
summary when present (per ADR-0004).
|
||||
|
||||
## Project file format (per ADR-0004)
|
||||
|
||||
- [ ] **F1** `project.yaml` with `version` field carries schema,
|
||||
relationships, and project metadata; `data/<table>.csv` carries
|
||||
table data (UTF-8, header row, RFC 4180).
|
||||
- [ ] **F2** A `.gitignore` template (excluding `playground.db`)
|
||||
is created in each new project.
|
||||
- [ ] **F3** Project file format includes a registered-migrator
|
||||
mechanism so older `version` values load cleanly as the format
|
||||
evolves. (Exercised once `version` increments past 1; the
|
||||
mechanism itself is built in v1.)
|
||||
|
||||
## Undo and replay (per ADR-0006)
|
||||
|
||||
- [ ] **U1** Auto-snapshot before destructive operations into a
|
||||
ring buffer (initial size N=10, tunable).
|
||||
- [ ] **U2** `undo` restores the most recent snapshot; `redo`
|
||||
re-applies; both prompt for confirmation showing the snapshot
|
||||
timestamp and a summary of the changes that will be discarded.
|
||||
- [ ] **U3** `history.log` records every successfully executed
|
||||
command in append-only form.
|
||||
- [ ] **U4** `replay` runs commands from a `history.log` or
|
||||
`.commands` file.
|
||||
|
||||
## Sharing and export (per ADR-0007)
|
||||
|
||||
- [ ] **E1** `export` produces a zip excluding `playground.db`;
|
||||
default filename `YYYYMMDD-<projectname>-export-NN.zip` with a
|
||||
non-clobbering two-digit sequence.
|
||||
- [ ] **E2** User documentation includes sharing recipes for
|
||||
git, email, and direct file transfer.
|
||||
|
||||
## Sample data / seeding
|
||||
|
||||
- [ ] **SD1** `seed <table> [count]` generates plausible fake
|
||||
data; junction tables are seeded with valid foreign-key
|
||||
references drawn from existing parent rows.
|
||||
- [~] **SD2** Detailed seeding rules (per-type generators,
|
||||
locale, determinism, override hooks) — design and ADR pending.
|
||||
|
||||
## Query analysis
|
||||
|
||||
- [ ] **QA1** `EXPLAIN QUERY PLAN` is run on demand for queries;
|
||||
output is rendered as an annotated tree highlighting full
|
||||
scans, index use, and join order.
|
||||
- [~] **QA2** Plan rendering specifics (tree layout, annotation
|
||||
taxonomy, colour scheme) — design and ADR pending.
|
||||
|
||||
## Hints, help, errors
|
||||
|
||||
- [ ] **H1** Friendly error-rewriting layer translates SQLite
|
||||
error messages into learner-friendly equivalents.
|
||||
- [ ] **H2** `hint` provides contextual help for the current
|
||||
input or the most recent error.
|
||||
- [ ] **H3** `help` provides general reference and per-command
|
||||
help.
|
||||
|
||||
## CLI
|
||||
|
||||
- [ ] **L1** Load a project via a positional CLI argument.
|
||||
- [~] **L2** Submit a command alongside project load — deferred,
|
||||
not v1.
|
||||
|
||||
## Tutorials and lessons
|
||||
|
||||
- [~] **TU1** Tutorial / lesson system — design and ADR pending
|
||||
before any implementation. Out of v1 unless an ADR is written.
|
||||
|
||||
## Testing (per ADR-0008)
|
||||
|
||||
- [ ] **TT1** Tier 1: `cargo test` + `proptest` covering
|
||||
pure-logic modules (parser, dispatcher, type mapping, project
|
||||
I/O, snapshot ring buffer, replay log).
|
||||
- [ ] **TT2** Tier 2: Ratatui `TestBackend` + `insta` snapshots
|
||||
for representative views.
|
||||
- [ ] **TT3** Tier 3: synthetic event-loop integration tests
|
||||
covering the user-facing flows in this checklist.
|
||||
- [ ] **TT4** Tier 4: PTY-based end-to-end for the four critical
|
||||
flows named in ADR-0008 (cold launch → DDL → quit; save →
|
||||
reopen; export → import → rebuild; undo after DROP).
|
||||
- [ ] **TT5** CI runs all tiers on Linux, macOS, and Windows on
|
||||
stable Rust.
|
||||
|
||||
## Cross-cutting
|
||||
|
||||
- [ ] **X1** Comprehensive logging via the project's logging
|
||||
infrastructure per `CLAUDE.md` (decision points, parameter
|
||||
values, fallback paths).
|
||||
- [~] **X2** Language: English-only for v1; multi-language is an
|
||||
open question to revisit later.
|
||||
- [~] **X3** Accessibility: TUI screen-reader support is
|
||||
best-effort and not a v1 commitment; revisit if user need
|
||||
emerges.
|
||||
|
||||
---
|
||||
|
||||
## Non-functional requirements
|
||||
|
||||
NFRs are quality bars rather than discrete features. Where a
|
||||
target is measurable, it is stated numerically; where it is
|
||||
necessarily qualitative, the criterion is named and the bar is
|
||||
"reviewer judgement against the criterion."
|
||||
|
||||
- [ ] **NFR-1 Performance — startup.** Cold launch to first
|
||||
rendered frame under 500ms on commodity hardware (developer
|
||||
laptop, mid-range desktop). Measured in CI on the Linux runner
|
||||
as a regression gate.
|
||||
- [ ] **NFR-2 Performance — input latency.** Keystroke-to-render
|
||||
latency under 16ms during normal editing; long-running queries
|
||||
must execute off the UI thread so the interface remains
|
||||
responsive (typing, scrolling, mode switching) while a query is
|
||||
running.
|
||||
- [ ] **NFR-3 Performance — resource footprint.** Idle memory
|
||||
under 50MB on the smallest target platform; no busy-loops; CPU
|
||||
near zero when waiting for input.
|
||||
- [ ] **NFR-4 Visual quality — distinctive design.** Colour
|
||||
palette and typography are deliberate and consistent across
|
||||
views; layout uses Unicode box-drawing and symbols where they
|
||||
add clarity; rendering avoids the generic flat-default look
|
||||
that ships with most TUI frameworks. Criterion: a reviewer can
|
||||
identify the app from a screenshot of any view.
|
||||
- [ ] **NFR-5 Visual quality — colour use.** Colour conveys
|
||||
information rather than decoration: mode indication, query
|
||||
result types (numeric vs text vs null), error severity,
|
||||
syntax highlighting categories. Foreground/background
|
||||
combinations meet WCAG-AA contrast (4.5:1 for normal text)
|
||||
even though we have not committed to broader accessibility.
|
||||
- [ ] **NFR-6 Cross-platform parity.** Behaviour and visual
|
||||
quality are equivalent across Linux, macOS, and Windows on
|
||||
crossterm-supported terminals. Platform-specific divergence
|
||||
(e.g. font fallbacks) is documented, not silently tolerated.
|
||||
- [ ] **NFR-7 Light and dark background support.** The colour
|
||||
scheme remains legible and visually coherent on both light and
|
||||
dark terminal backgrounds. The mechanism (auto-detect via
|
||||
terminal query, explicit user setting, or both) is an
|
||||
implementation choice, but the outcome is non-negotiable: no
|
||||
dark-on-dark or light-on-light readability failures on either
|
||||
background.
|
||||
|
||||
---
|
||||
|
||||
## Explicitly out of scope
|
||||
|
||||
- [-] **N1** Hosted publishing platform — per ADR-0007. Sharing
|
||||
is local-artifact based.
|
||||
- [-] **N2** Real UUID column type — per ADR-0005. The `shortid`
|
||||
type covers the pedagogical need at TUI-friendly width.
|
||||
- [-] **N3** Cross-emulator visual regression coverage — per
|
||||
ADR-0008. Crossterm abstracts terminals adequately; we revisit
|
||||
only if a real regression surfaces.
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
This document is updated whenever:
|
||||
|
||||
- A new requirement is committed to (added as a new item with the
|
||||
next free ID in its section).
|
||||
- A deferred item is taken up (status moves from `[~]` to `[ ]`).
|
||||
- An item is satisfied (status moves to `[x]`, with a reference
|
||||
to the commit, PR, or test that demonstrates it).
|
||||
- An item moves out of scope (status moves to `[-]` with a
|
||||
rationale and a link to the decision).
|
||||
|
||||
IDs are stable: once assigned, they are not reused. Removing a
|
||||
requirement leaves a "withdrawn" entry referencing the decision.
|
||||
Reference in New Issue
Block a user