diff --git a/SPEC.md b/SPEC.md index b4e08f8..cc22433 100644 --- a/SPEC.md +++ b/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 :` 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 diff --git a/flake.nix b/flake.nix index 3933bbd..d7a68dd 100644 --- a/flake.nix +++ b/flake.nix @@ -27,7 +27,9 @@ go gopls golangci-lint - tailwindcss + + nodejs + eslint gnumake lsof ];