docs: update specification to use TypeScript frontend
- Replace 'Vanilla JavaScript' with 'TypeScript' in frontend requirements - Update flake.nix to use nodejs package instead of tailwindcss - Clarify testing requirements to cover both frontend and backend - Fix punctuation in evaluation checklist
This commit is contained in:
175
SPEC.md
175
SPEC.md
@@ -2,117 +2,100 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Build a WYSIWYG markdown editor with save functionality consisting of a Go backend and vanilla JavaScript frontend with Tailwind CSS.
|
||||
Beyond the listed features, no authentication, user accounts, collaborative editing, or version history are required.
|
||||
Build a markdown editor with preview: Go backend + React/TypeScript frontend with Tailwind CSS.
|
||||
|
||||
**Out of scope:** authentication, user accounts, collaborative editing, version history.
|
||||
|
||||
## Backend (Go)
|
||||
|
||||
### Requirements
|
||||
- Standard HTTP server + Cobra for CLI
|
||||
- CRUD REST API for markdown files
|
||||
- Store files on disk (flat structure, `.md` files only)
|
||||
- Errors return 4xx/5xx + JSON with `error` field
|
||||
- Comprehensive logging using logrus
|
||||
|
||||
- Use Go with standard HTTP server
|
||||
- Use Cobra library for CLI argument parsing
|
||||
- Implement CRUD operations for markdown files:
|
||||
- Create: Add new markdown files
|
||||
- Read: Retrieve/View markdown files
|
||||
- Update: Edit existing markdown files
|
||||
- Delete: Remove markdown files
|
||||
- Store markdown files on disk in a specified directory
|
||||
- The server must handle concurrent requests safely; the last successful write wins
|
||||
- Markdown file names are case-sensitive and must end in `.md`. Illegal characters for the current OS must be rejected with 400 Bad Request
|
||||
- Directory structure under `--data-dir` is flat: every `.md` file is a sibling; sub-directories are ignored
|
||||
### CLI Flags
|
||||
|
||||
### CLI Options
|
||||
- `--data-dir`: Storage path (default: `./data`)
|
||||
- `--port`: Server port (default: `8080`)
|
||||
- `--host`: Bind address (default: `127.0.0.1`)
|
||||
|
||||
The application must support the following CLI flags:
|
||||
## Frontend (React + TypeScript + Tailwind)
|
||||
|
||||
- `--data-dir`: Path to the directory where markdown files will be stored (default: `./data`)
|
||||
- `--port`: Port number to run the HTTP server on (default: `8080`)
|
||||
- `--host`: Host address to bind to (default: `127.0.0.1`)
|
||||
Cobra must generate help text for `--help` and `-h` that includes defaults.
|
||||
|
||||
### API Implementation
|
||||
|
||||
- Design and implement appropriate REST endpoints for CRUD operations
|
||||
- Handle error responses appropriately
|
||||
- Validate inputs appropriately
|
||||
- Any operation that fails must return an HTTP 4xx/5xx code and a JSON body containing at least an `error` string
|
||||
|
||||
## Frontend (Vanilla JavaScript + Tailwind CSS)
|
||||
|
||||
### Requirements
|
||||
|
||||
- Vanilla JavaScript (no frameworks)
|
||||
- Tailwind CSS for styling
|
||||
- Single-page application interface
|
||||
- No build step except running the Tailwind CLI once to generate the CSS file; runtime must work in a current Chrome/Edge/Firefox without polyfills
|
||||
|
||||
### Features
|
||||
|
||||
#### Markdown Editor
|
||||
|
||||
- Split-view or toggleable view with:
|
||||
- Edit pane: Textarea for markdown input
|
||||
- Preview pane: Rendered markdown preview
|
||||
- Real-time preview updates
|
||||
- Render markdown with GitHub-Flavored-Markdown (GFM) semantics
|
||||
|
||||
#### Theme Support
|
||||
|
||||
Three theme modes:
|
||||
|
||||
- **Dark**: Dark color scheme
|
||||
- **Light**: Light color scheme
|
||||
- **System**: Follows system preference
|
||||
|
||||
Theme switching requirements:
|
||||
|
||||
- Auto-detect system preference on load (prefers-color-scheme)
|
||||
- Manual theme switcher with three options: Dark, Light, System
|
||||
- Persist theme preference in localStorage under the key `wysiwyg-theme`
|
||||
- Update theme immediately when changed
|
||||
- Respect system theme changes when in "System" mode
|
||||
|
||||
#### File Management UI
|
||||
|
||||
- List all markdown files
|
||||
- Create new files
|
||||
- Open existing files for editing
|
||||
- Save changes
|
||||
- Delete files
|
||||
|
||||
#### Responsive Design
|
||||
|
||||
- Works on desktop and mobile
|
||||
- Responsive layout using Tailwind classes
|
||||
- Markdown editor with live GFM preview
|
||||
- File management: list, create, open, save, delete
|
||||
- Three themes (Dark, Light, System) with switcher
|
||||
- Responsive (desktop + mobile)
|
||||
|
||||
## Development Environment
|
||||
|
||||
The repository root contains a `flake.nix` locked to `github:NixOS/nixpkgs/nixos-25.11`.
|
||||
`nix develop` has already been executed; the resulting shell provides:
|
||||
`flake.nix` (locked to `nixos-25.11`) provides: go, gopls, golangci-lint, eslint, nodejs, gnumake, lsof
|
||||
|
||||
- go, gopls, golangci-lint
|
||||
- tailwindcss
|
||||
- gnumake
|
||||
**Do not modify flake.**
|
||||
|
||||
You must not modify the flake or add packages outside this environment.
|
||||
## Testing (TDD)
|
||||
|
||||
## General Requirements
|
||||
- **All tests must pass**
|
||||
- Single command to run tests
|
||||
- Backend: demonstrate CRUD round-trip + static asset serving
|
||||
- Frontend: verify core functionality
|
||||
|
||||
- No database - use file system
|
||||
- Minimal dependencies
|
||||
- Clean, maintainable code
|
||||
- Proper error handling
|
||||
## Milestones
|
||||
|
||||
## Testing & Observability
|
||||
### Backend (6 milestones)
|
||||
|
||||
- Provide at least one automated test (unit, integration, or end-to-end) that can be run with a single command (`go test`, `make test`, etc.).
|
||||
- The test must demonstrate that a markdown file can be created, read, updated, and deleted through the REST endpoints.
|
||||
- On start-up the server must log its bound address in the format `listening on <host>:<port>` so evaluators can script against it.
|
||||
**B1: CLI & Server Setup**
|
||||
- Cobra CLI with --data-dir, --port, --host flags
|
||||
- HTTP server with basic routing
|
||||
|
||||
## Evaluation Checklist
|
||||
**B2: CRUD API**
|
||||
- REST endpoints for markdown files (GET, POST, PUT, DELETE)
|
||||
- JSON error responses (4xx/5xx)
|
||||
|
||||
Evaluation will check:
|
||||
(1) CLI starts with defaults,
|
||||
(2) CRUD round-trip,
|
||||
(3) theme switch & persistence,
|
||||
(4) responsive layout on 320 px and 1920 px,
|
||||
**B3: File Storage**
|
||||
- Read/write .md files to disk
|
||||
- Flat file structure
|
||||
|
||||
**B4: Logging**
|
||||
- Comprehensive logrus logging for all operations
|
||||
|
||||
**B5: Static Assets**
|
||||
- Serve frontend build files
|
||||
|
||||
**B6: Backend Tests**
|
||||
- CRUD round-trip tests
|
||||
- Static asset serving tests
|
||||
|
||||
### Frontend (6 milestones)
|
||||
|
||||
**F1: Project Setup**
|
||||
- React + TypeScript + Tailwind configured
|
||||
|
||||
**F2: File Management UI**
|
||||
- List, create, open, save, delete markdown files
|
||||
|
||||
**F3: Editor & Preview**
|
||||
- Markdown editor with live GFM preview
|
||||
|
||||
**F4: Theme System**
|
||||
- Dark/Light/System themes
|
||||
- Theme switcher and persistence
|
||||
|
||||
**F5: Responsive Design**
|
||||
- Works at 320px and 1920px
|
||||
|
||||
**F6: Frontend Tests**
|
||||
- Core functionality tests (editor, file operations, themes)
|
||||
|
||||
### Integration (1 milestone)
|
||||
|
||||
**I1: End-to-end**
|
||||
- Full CRUD workflow test from frontend to backend
|
||||
|
||||
## Evaluation
|
||||
|
||||
1. CLI starts with defaults
|
||||
2. CRUD works end-to-end
|
||||
3. Static assets are properly served
|
||||
4. Theme switch & persistence
|
||||
5. Responsive at 320px and 1920px
|
||||
|
||||
Reference in New Issue
Block a user