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
|
## Overview
|
||||||
|
|
||||||
Build a WYSIWYG markdown editor with save functionality consisting of a Go backend and vanilla JavaScript frontend with Tailwind CSS.
|
Build a markdown editor with preview: Go backend + React/TypeScript frontend with Tailwind CSS.
|
||||||
Beyond the listed features, no authentication, user accounts, collaborative editing, or version history are required.
|
|
||||||
|
**Out of scope:** authentication, user accounts, collaborative editing, version history.
|
||||||
|
|
||||||
## Backend (Go)
|
## 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
|
### CLI Flags
|
||||||
- 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 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`)
|
- Markdown editor with live GFM preview
|
||||||
- `--port`: Port number to run the HTTP server on (default: `8080`)
|
- File management: list, create, open, save, delete
|
||||||
- `--host`: Host address to bind to (default: `127.0.0.1`)
|
- Three themes (Dark, Light, System) with switcher
|
||||||
Cobra must generate help text for `--help` and `-h` that includes defaults.
|
- Responsive (desktop + mobile)
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
## Development Environment
|
## Development Environment
|
||||||
|
|
||||||
The repository root contains a `flake.nix` locked to `github:NixOS/nixpkgs/nixos-25.11`.
|
`flake.nix` (locked to `nixos-25.11`) provides: go, gopls, golangci-lint, eslint, nodejs, gnumake, lsof
|
||||||
`nix develop` has already been executed; the resulting shell provides:
|
|
||||||
|
|
||||||
- go, gopls, golangci-lint
|
**Do not modify flake.**
|
||||||
- tailwindcss
|
|
||||||
- gnumake
|
|
||||||
|
|
||||||
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
|
## Milestones
|
||||||
- Minimal dependencies
|
|
||||||
- Clean, maintainable code
|
|
||||||
- Proper error handling
|
|
||||||
|
|
||||||
## 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.).
|
**B1: CLI & Server Setup**
|
||||||
- The test must demonstrate that a markdown file can be created, read, updated, and deleted through the REST endpoints.
|
- Cobra CLI with --data-dir, --port, --host flags
|
||||||
- On start-up the server must log its bound address in the format `listening on <host>:<port>` so evaluators can script against it.
|
- 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:
|
**B3: File Storage**
|
||||||
(1) CLI starts with defaults,
|
- Read/write .md files to disk
|
||||||
(2) CRUD round-trip,
|
- Flat file structure
|
||||||
(3) theme switch & persistence,
|
|
||||||
(4) responsive layout on 320 px and 1920 px,
|
**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