plan-review 1.0.0 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # plan-review
 
-Interactive CLI for reviewing AI-generated markdown plans. Parses plans into sections, renders them in the terminal or browser, collects your comments, and outputs structured feedback.
+Interactive CLI for reviewing AI-generated markdown plans. Parses plans into sections, renders them in the terminal or browser, collects your comments, and outputs structured feedback — back to the AI or your team.
 
 ## Install
 
@@ -8,30 +8,65 @@ Interactive CLI for reviewing AI-generated markdown plans. Parses plans into sec
 npm install -g plan-review
 ```
 
-## Usage
+### Claude Code skill (optional)
+
+If you use Claude Code, install the companion skill so you can say *"review this plan"*:
 
 ```bash
-# Terminal mode (interactive)
-plan-review path/to/plan.md
+plan-review install-skill
+```
+
+## Quick start
+
+```bash
+# Try the included demo plan
+plan-review --browser examples/demo-plan.md
 
-# Browser mode (three-panel review UI)
+# Review your own plan
 plan-review path/to/plan.md --browser
+
+# Pipe feedback directly to Claude
+plan-review path/to/plan.md --browser -o claude
 ```
 
-### Options
+## Browser mode (`--browser`)
+
+![Browser mode demo](https://raw.githubusercontent.com/alvaroaac/plan-review/main/examples/demo-browser.gif)
+
+The browser mode opens a three-panel review UI:
 
 ```
--o, --output <target>   Output target: stdout, clipboard, file, claude
---output-file <path>    Custom output file path (with --output file)
---split-by <strategy>   Force split strategy: heading, separator
---browser               Open browser-based review UI
--V, --version           Show version
--h, --help              Show help
++------------------+----------------------------+------------------+
+|                  |                            |                  |
+|   Table of       |   Rendered markdown        |   Comment        |
+|   Contents       |   with plan metadata       |   Sidebar        |
+|                  |                            |                  |
+|   - Milestone 1  |   ## Task 1.1              |   [Add comment]  |
+|     * Task 1.1 ✓ |                            |                  |
+|     * Task 1.2   |   **Depends on:** 1.0      |   > "Line 3-5"  |
+|   - Milestone 2  |   **Blocks:** 1.2          |   Fix the error  |
+|     * Task 2.1   |                            |   handling here  |
+|                  |   Content with line        |                  |
+|                  |   gutters for anchoring    |   [Submit Review] |
+|                  |   comments to ranges       |                  |
++------------------+----------------------------+------------------+
 ```
 
-If `-o` is omitted, you'll be prompted to choose after the review. Output targets work with both terminal and browser modes (e.g., `--browser -o clipboard`).
+**Line-anchored comments:** Click a line number in the gutter to start a selection. Shift-click another line to select a range. Your comment is anchored to those exact lines.
 
-### Interactive commands
+**Section-level comments:** Click "Add comment to entire section" below any section.
+
+**Auto-save:** Comments are saved as you work. Close the browser, come back later, resume where you left off.
+
+Click "Submit Review" when done — structured feedback is sent back to the CLI.
+
+## Terminal mode (default)
+
+```bash
+plan-review path/to/plan.md
+```
+
+Interactive terminal UI with table of contents, section navigation, and inline commenting. Works over SSH, in CI, anywhere.
 
 | Command | Action |
 |---------|--------|
@@ -43,21 +78,32 @@ If `-o` is omitted, you'll be prompted to choose after the review. Output target
 | *(enter)* | Skip section |
 | *(any text)* | Add comment on current section |
 
-## Review modes
+## Options
 
-### Terminal mode (default)
+```
+-o, --output <target>   Output target: stdout, clipboard, file, claude
+--output-file <path>    Custom output file path (with --output file)
+--split-by <strategy>   Force split strategy: heading, separator
+--fresh                 Skip session resume, start clean review
+--browser               Open browser-based review UI
+-V, --version           Show version
+-h, --help              Show help
+```
 
-Interactive terminal UI with table of contents, section navigation, and inline commenting.
+## The AI feedback loop
 
-### Browser mode (`--browser`)
+The real power is closing the loop between AI-generated plans and human review:
 
-Opens a three-panel review UI in your browser:
+```
+AI writes plan  →  You review with plan-review  →  Feedback pipes to Claude  →  AI revises
+```
 
-- **Left** — Table of contents with section tree and comment indicators
-- **Center** — Rendered markdown content with dependency metadata (plan mode)
-- **Right** — Comment sidebar with add, edit, and delete
+```bash
+# Review in browser, send feedback straight to Claude
+plan-review plan.md --browser -o claude
+```
 
-Add comments on any section, then click "Submit Review" to send your feedback back to the CLI. The server shuts down automatically after submission.
+Your anchored, section-by-section comments become structured input the AI can act on — not a wall of text in a chat message.
 
 ## How it works
 
@@ -87,16 +133,12 @@ Review progress is auto-saved as you work. If you close the terminal or browser
 
 Sessions are stored in `~/.plan-review/sessions/`.
 
-### Commands
-
 ```
 plan-review plan.md --fresh    Skip session resume, start clean
 plan-review sessions           List all saved sessions
 ```
 
-### Manual cleanup
-
-Delete files in `~/.plan-review/sessions/` to remove old sessions.
+Manual cleanup: delete files in `~/.plan-review/sessions/`.
 
 ## License
 

package/dist/browser/index.html

@@ -297,6 +297,11 @@ body {
 .line-inner ol { list-style: decimal; }
 .line-inner blockquote { border-left: 3px solid var(--border); padding-left: 12px; color: var(--text-secondary); margin: 0; }
 .line-inner h3, .line-inner h4 { font-size: 14px; margin: 4px 0; }
+.line-inner table { width: 100%; border-collapse: collapse; margin: 4px 0; font-size: 13px; }
+.line-inner th, .line-inner td { border: 1px solid var(--border); padding: 6px 10px; text-align: left; }
+.line-inner th { background: var(--bg-secondary); font-weight: 600; color: var(--text-primary); }
+.line-inner td { color: var(--text-secondary); }
+.line-inner tr:hover td { background: rgba(0, 173, 181, 0.05); }
 
 .add-section-comment-link {
   display: inline-block;

package/examples/demo-plan.md

@@ -0,0 +1,129 @@
+# User Authentication System — Implementation Plan
+
+**Goal:** Add email/password authentication with session management to the web app.
+
+**Architecture:** Express middleware + bcrypt + JWT tokens + PostgreSQL sessions table. Three milestones: database schema, auth endpoints, session management.
+
+**Tech Stack:** Node.js, Express, PostgreSQL, bcrypt, jsonwebtoken
+
+---
+
+## Milestone 1: Database Foundation
+
+### Task 1.1: Create users table
+
+**Depends On:** (none)
+**Blocks:** 1.2, 2.1, 2.2
+**Related Files:** `src/db/migrations/001_users.sql`, `src/db/schema.ts`
+**Verification:** `npm run migrate && npm test`
+
+Create the users table with the following columns:
+
+| Column | Type | Constraints |
+|--------|------|-------------|
+| id | UUID | PRIMARY KEY, DEFAULT gen_random_uuid() |
+| email | VARCHAR(255) | UNIQUE, NOT NULL |
+| password_hash | VARCHAR(255) | NOT NULL |
+| created_at | TIMESTAMP | DEFAULT NOW() |
+| updated_at | TIMESTAMP | DEFAULT NOW() |
+
+Add an index on `email` for login lookups. The migration should be idempotent (use `IF NOT EXISTS`).
+
+### Task 1.2: Create sessions table
+
+**Depends On:** 1.1
+**Blocks:** 3.1, 3.2
+**Related Files:** `src/db/migrations/002_sessions.sql`, `src/db/schema.ts`
+**Verification:** `npm run migrate && npm test`
+
+Sessions table for server-side session tracking:
+
+- `id` (UUID, primary key)
+- `user_id` (UUID, foreign key → users.id, ON DELETE CASCADE)
+- `token` (VARCHAR, unique, indexed)
+- `expires_at` (TIMESTAMP, NOT NULL)
+- `created_at` (TIMESTAMP, DEFAULT NOW())
+
+Add a cleanup index on `expires_at` for the session pruning job.
+
+---
+
+## Milestone 2: Authentication Endpoints
+
+### Task 2.1: POST /auth/register
+
+**Depends On:** 1.1
+**Blocks:** 2.3
+**Related Files:** `src/routes/auth.ts`, `src/services/user.ts`, `tests/auth.test.ts`
+**Verification:** `npm test -- --grep "register"`
+
+Accepts `{ email, password }`. Validates:
+- Email format (basic regex, no need for RFC 5322 compliance)
+- Password minimum 8 characters
+- Email not already registered (unique constraint handles race conditions)
+
+Hash password with bcrypt (cost factor 12). Return `201 { user: { id, email } }` on success, `400` with validation errors, `409` if email exists.
+
+### Task 2.2: POST /auth/login
+
+**Depends On:** 1.1
+**Blocks:** 2.3
+**Related Files:** `src/routes/auth.ts`, `src/services/auth.ts`, `tests/auth.test.ts`
+**Verification:** `npm test -- --grep "login"`
+
+Accepts `{ email, password }`. Compares against stored bcrypt hash.
+
+On success: create a session (Task 3.1), return `200 { token, expiresAt }`.
+On failure: return `401 { error: "Invalid credentials" }`. Do **not** reveal whether the email exists.
+
+Rate limiting: 5 attempts per email per 15 minutes. Use a simple in-memory counter (Redis in v2).
+
+### Task 2.3: Auth middleware
+
+**Depends On:** 2.1, 2.2
+**Blocks:** 3.2
+**Related Files:** `src/middleware/auth.ts`, `tests/middleware.test.ts`
+**Verification:** `npm test -- --grep "middleware"`
+
+Express middleware that:
+1. Extracts `Authorization: Bearer <token>` header
+2. Looks up session by token
+3. Checks `expires_at > NOW()`
+4. Attaches `req.user = { id, email }` if valid
+5. Returns `401` if missing/invalid/expired
+
+Should be composable: `router.get('/profile', requireAuth, handler)`.
+
+---
+
+## Milestone 3: Session Management
+
+### Task 3.1: Session creation and token generation
+
+**Depends On:** 1.2
+**Blocks:** 3.2
+**Related Files:** `src/services/session.ts`, `tests/session.test.ts`
+**Verification:** `npm test -- --grep "session"`
+
+Generate tokens using `crypto.randomBytes(32).toString('hex')` — not JWT for session tokens (JWTs can't be revoked without a blacklist, defeating the purpose of server-side sessions).
+
+Default expiry: 7 days. Configurable via `SESSION_TTL_HOURS` env var.
+
+### Task 3.2: Session cleanup and logout
+
+**Depends On:** 1.2, 2.3
+**Blocks:** (none)
+**Related Files:** `src/services/session.ts`, `src/routes/auth.ts`, `tests/session.test.ts`
+**Verification:** `npm test -- --grep "logout|cleanup"`
+
+Two features:
+
+**Logout endpoint** — `POST /auth/logout` (requires auth middleware). Deletes the current session row. Returns `204`.
+
+**Cleanup job** — Runs every hour via `setInterval`. Deletes sessions where `expires_at < NOW()`. Log the count of pruned sessions.
+
+```sql
+DELETE FROM sessions WHERE expires_at < NOW();
+```
+
+Consider: should logout invalidate all sessions for the user, or just the current one? Start with current-only. Add "logout everywhere" as a v2 feature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-review",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Interactive CLI for reviewing AI-generated markdown plans",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "examples"
   ],
   "scripts": {
     "build": "tsc && tsc --project tsconfig.browser.json --noEmit && node scripts/build-browser.js",