sitedrift 0.1.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,112 @@
+# sitedrift for agents
+
+sitedrift compares a local site with production and keeps a shared review-note
+channel for humans and AI tools. Prefer the packaged MCP server. Use the JSON CLI
+only when the host cannot run MCP.
+
+## Fast path
+
+1. Install once: `npm install --global sitedrift`
+2. In the project, create `sitedrift.config.json`:
+
+   ```json
+   {
+     "dev": "http://localhost:4321",
+     "live": "https://example.com",
+     "open": true
+   }
+   ```
+
+3. Start the app: `sitedrift`
+4. Configure the AI host to run:
+
+   ```json
+   {
+     "command": "sitedrift-mcp",
+     "args": []
+   }
+   ```
+
+   No global install: use `"command": "npx"` and
+   `"args": ["-y", "sitedrift", "mcp"]`.
+
+   Common one-command setup:
+
+   ```bash
+   codex mcp add sitedrift -- sitedrift-mcp
+   claude mcp add sitedrift -- sitedrift-mcp
+   ```
+
+   For Cursor and other JSON-configured hosts, put this in the host's MCP
+   configuration under `mcpServers`:
+
+   ```json
+   {
+     "sitedrift": {
+       "command": "sitedrift-mcp",
+       "args": []
+     }
+   }
+   ```
+
+## Agent workflow
+
+1. Call `sitedrift_context` first. Do not guess the URLs or active session.
+2. Inspect the requested route in the viewer or with the host's browser tools.
+3. Call `sitedrift_notes_list` before adding notes to avoid duplicates.
+4. Add one concrete finding per `sitedrift_note_add` call. Always provide
+   `route`; provide `side` when the issue belongs specifically to DEV or LIVE.
+5. Re-list notes after code changes. Resolve only findings you verified.
+6. Remove or clear notes only when the user explicitly requests it.
+
+Hosted Cloudflare preview deployments are a different mode: their notes are
+browser-local and intentionally unavailable to MCP. Use browser inspection for
+those URLs. Do not claim that a hosted note was shared with an agent or written
+to the project.
+
+## MCP tools
+
+- `sitedrift_context`: active targets, viewer URL, and capabilities.
+- `sitedrift_notes_list`: shared findings.
+- `sitedrift_note_add`: add one actionable finding.
+- `sitedrift_note_resolve`: mark a verified finding complete.
+- `sitedrift_note_reopen`: reopen a regressed or incomplete finding.
+- `sitedrift_note_remove`: permanently remove one finding.
+- `sitedrift_notes_clear`: permanently remove all findings.
+- `sitedrift_setup`: return install, config, HTTPS, and MCP setup instructions.
+
+Default port is `4178`. Pass `port` to every tool when the user runs another
+session port.
+
+## CLI fallback
+
+```bash
+sitedrift context
+sitedrift notes list
+sitedrift notes add "CTA differs" --route /pricing --side live --author agent
+sitedrift notes resolve <id>
+```
+
+All CLI output is JSON. The MCP server communicates over stdio and writes no
+logs to stdout.
+
+## HTTPS
+
+Loopback HTTP is normally sufficient. When the compared site requires HTTPS:
+
+```bash
+sitedrift --setup-https
+sitedrift --https
+```
+
+## Security
+
+sitedrift accepts loopback hosts only. The control API uses a random bearer
+token stored in `~/.sitedrift/sessions/<port>.json` with mode `0600`. DEV and
+LIVE render on separate origins. Never expose sitedrift through a public proxy.
+
+The optional Cloudflare Pages addon is intentionally public-preview safe: it is
+installed only on non-production builds, exposes only `/__sitedrift/*`, permits
+only `GET` and `HEAD`, allowlists one configured live origin, and sandboxes both
+frames without same-origin authority. Production output and existing API
+Functions are unchanged.

package/README.md

@@ -5,15 +5,11 @@ that frames your local site and production **side-by-side on the same route**,
 locked to the same scroll — then overlays them in `difference` mode so the only
 things that light up are the pixels that actually changed.
 
-```
-┌─────────────── sitedrift ───────────────┐
-│  DEV  ▸ /pricing      200   LIVE ▸ /pricing 200 │
-│ ┌───────────┐ │ ┌───────────┐  Overlay ▸ Diff   │
-│ │  $19      │ │ │  $29      │  ≠ meta           │
-│ │ [Start…]  │ │ │ [Get…]    │  ✓ author notes   │
-│ └───────────┘ │ └───────────┘                   │
-└──────────────────────────────────────────┘
-```
+<p align="center">
+  <img src="docs/images/sitedrift-split.jpg" alt="sitedrift comparing a redesigned local product page with production" width="100%">
+</p>
+
+<p align="center"><strong>Same route. Same scroll. Every change visible.</strong></p>
 
 ---
 
@@ -39,6 +35,108 @@ npm i -g sitedrift
 sitedrift /pricing -d http://localhost:4321 -l https://example.com -o
 ```
 
+For a project you use repeatedly, add `sitedrift.config.json`:
+
+```json
+{
+  "dev": "http://localhost:4321",
+  "live": "https://example.com",
+  "author": "joe",
+  "open": true
+}
+```
+
+Configuration precedence is **flag > environment > project file > default**.
+The file is discovered from the current directory upward; `--config <file>`
+selects one explicitly.
+
+### HTTPS
+
+The default (`http://127.0.0.1`) just works — loopback is a browser "secure
+context", so you usually need nothing. When you do want HTTPS:
+
+```bash
+sitedrift --setup-https   # one-time: generate + trust a local cert
+sitedrift --https         # serve over HTTPS from then on
+```
+
+`--setup-https` uses [mkcert](https://github.com/FiloSottile/mkcert) if it's
+installed — that gives a **locally-trusted cert with zero browser warnings**. If
+mkcert isn't found it falls back to an `openssl` self-signed cert and prints the
+one command to trust it on your OS. Already have a cert? Skip all of this and
+pass `--cert <file> --key <file>`.
+
+### Cloudflare preview deployments
+
+Turn every non-production Cloudflare Pages deployment into a compact sitedrift
+review URL. The deployment opens its own preview in DEV Solo mode and can switch
+to Split, Overlay, or Diff against the configured production site.
+
+Install sitedrift and run the wrapper after your static build:
+
+```json
+{
+  "scripts": {
+    "build": "astro build && sitedrift cloudflare --dir dist --live https://example.com"
+  },
+  "devDependencies": {
+    "sitedrift": "^0.3.0"
+  }
+}
+```
+
+Add one scoped Pages Function:
+
+```ts
+// functions/__sitedrift/[[path]].ts
+export { onRequest } from 'sitedrift/cloudflare';
+```
+
+That is the entire integration. On Cloudflare Pages, the wrapper activates only
+when `CF_PAGES=1` and `CF_PAGES_BRANCH` is not `main`. Production builds are
+left unchanged. Use `--production-branch <name>` when production is another
+branch.
+
+Hosted proxies are read-only (`GET`/`HEAD`), sandboxed without same-origin
+authority, and fixed to the configured live origin. Review notes stay in that
+browser's `localStorage`; they are not sent to an API, shared with agents, or
+written to disk. Existing application Functions keep their original routes.
+
+---
+
+## See the whole review loop
+
+The included example compares a fictional Northstar release candidate against
+production. It uses realistic release drift: primary CTA, metric values, and a
+release badge change while the underlying layout stays aligned.
+
+<table>
+  <tr>
+    <td width="50%">
+      <img src="docs/images/sitedrift-diff.jpg" alt="Difference overlay showing only changed pixels">
+      <br><strong>Pixel difference</strong><br>
+      Overlay both pages and light up only what changed.
+    </td>
+    <td width="50%">
+      <img src="docs/images/sitedrift-collaboration.jpg" alt="Review drawer with notes from a human and an AI agent">
+      <br><strong>Human + AI review channel</strong><br>
+      Share route-specific findings through the viewer, CLI, or MCP.
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="docs/images/sitedrift-mobile.jpg" alt="sitedrift Solo mode on a narrow mobile viewport" width="360">
+  <br><strong>Focused mobile review</strong><br>
+  Narrow screens default to Solo; Swap flips between DEV and LIVE.
+</p>
+
+Rebuild these screenshots from the deterministic local showcase:
+
+```bash
+npm run docs:screenshots
+```
+
 ---
 
 ## What it does
@@ -59,7 +157,10 @@ sitedrift /pricing -d http://localhost:4321 -l https://example.com -o
   file the viewer polls every 4s, so a teammate or an AI coding session can leave
   notes that appear live. Click a note to jump to its route, copy a per-note
   deep link, dock or float the drawer, and **Send to vault** or export Markdown.
-- **No dependencies.** Node standard library only.
+- **No runtime dependencies.** Node standard library only.
+- **Deploy-preview mode for Cloudflare Pages.** Preview branches can carry the
+  compact comparison toolbar without changing production output or application
+  API routes.
 
 ### Keyboard
 
@@ -82,7 +183,6 @@ Shortcuts work whether focus is in the viewer chrome or inside either pane.
 ## Options
 
 Every option is a CLI flag, and also reads a `SITEDRIFT_<NAME>` env var.
-Precedence is **flag > env > default**.
 
 | Flag | Env | Default | Purpose |
 |---|---|---|---|
@@ -91,36 +191,85 @@ Precedence is **flag > env > default**.
 | `-p, --port <n>` | `SITEDRIFT_PORT` | `4178` | Listen port. |
 | `--host <addr>` | `SITEDRIFT_HOST` | `127.0.0.1` | Bind address. |
 | `-o, --open` | — | off | Open the viewer in your browser. |
-| `--http` | — | — | Force plain HTTP (ignore `--cert`/`--key`). |
-| `--cert <file>` / `--key <file>` | `SITEDRIFT_CERT` / `_KEY` | — | If both set, serve over HTTPS. |
+| `--https` | — | off | Serve HTTPS with an auto cert (mkcert if present, else openssl). |
+| `--setup-https` | — | — | One-time: generate + trust a local cert, then exit. |
+| `--http` | — | — | Force plain HTTP (the default; overrides `--https`). |
+| `--cert <file>` / `--key <file>` | `SITEDRIFT_CERT` / `_KEY` | — | Bring your own cert; if both set, serve over HTTPS. |
 | `--notes <file>` | `SITEDRIFT_NOTES` | `$TMPDIR/sitedrift-notes.json` | Shared review-notes file. |
 | `--brand <text>` | `SITEDRIFT_BRAND` | — | Strip `\| <text>` from titles in pane headers. |
 | `--author <name>` | `SITEDRIFT_AUTHOR` | `you` | Byline for notes added in the viewer. |
 | `--vault <dir>` | `SITEDRIFT_VAULT` | — | Enable **Send to vault** (writes the review markdown here). |
+| `--config <file>` | — | discovered | Read project configuration from JSON. |
 
 A positional `[path]` (e.g. `sitedrift /pricing`) sets the initial route.
 `-h, --help` and `-v, --version` do what you'd expect.
 
+### AI and automation
+
+The running process writes a private mode-`0600` descriptor under
+`~/.sitedrift/sessions/`. The npm package includes a zero-dependency stdio MCP
+server and an `AGENTS.md` operating guide.
+
+Configure an MCP host with:
+
+```json
+{
+  "command": "sitedrift-mcp",
+  "args": []
+}
+```
+
+Codex and Claude Code can register it directly:
+
+```bash
+codex mcp add sitedrift -- sitedrift-mcp
+claude mcp add sitedrift -- sitedrift-mcp
+```
+
+Without a global install:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "sitedrift", "mcp"]
+}
+```
+
+Agents call `sitedrift_context` first, then use the note tools to share findings
+with the user. The server also exposes `sitedrift://guide`, a `review_route`
+prompt, and `sitedrift_setup` for install/config/HTTPS guidance.
+
+For hosts without MCP, use the JSON CLI instead of scraping the viewer or
+constructing authenticated requests:
+
+```bash
+sitedrift context
+sitedrift notes list
+sitedrift notes add "CTA differs" --route /pricing --side live --author codex
+sitedrift notes resolve <id>
+sitedrift notes reopen <id>
+sitedrift notes remove <id>
+sitedrift notes clear
+```
+
+Commands print JSON and return non-zero on failure. They work over HTTP or local
+HTTPS without an agent-specific SDK.
+
 ### HTTP endpoints
 
 | Route | Purpose |
 |---|---|
 | `GET /` | The viewer. |
 | `GET /health` | `{ dev, live, version }`. |
-| `GET /notes` · `POST /notes` | Read / mutate notes (`op: add\|remove\|toggle\|clear`). |
+| `GET /api/v1/session` | Authenticated session context and capabilities. |
+| `GET /api/v1/notes` · `POST /api/v1/notes` | Authenticated note list / operations. |
 | `GET /notes.md` | Notes as a Markdown checklist. |
-| `POST /notes/save` | Write the notes markdown into `--vault`. |
+| `POST /api/v1/notes/save` | Write notes markdown into `--vault`. |
 | `GET /icon.svg` | The app mark / favicon. |
-| `GET /__dev/*` · `GET /__live/*` | Proxied origins. |
-
-`POST /notes` requires `Content-Type: application/json`, so a cross-origin page
-can't forge a no-preflight write. Add a note from anywhere:
+| frame ports: `GET /__dev/*` · `GET /__live/*` | Isolated proxied origins. |
 
-```bash
-curl -X POST localhost:4178/notes -H 'content-type: application/json' \
-  -d '{"op":"add","text":"H1 on /about is larger on LIVE",
-       "author":"claude","route":"/about","side":"live"}'
-```
+The control API requires the per-session bearer token. The CLI commands above
+are the supported machine interface.
 
 Most viewer state (route, layout, scroll mode, focus) is mirrored into the URL
 query string, so a link reproduces the exact view.
@@ -131,12 +280,26 @@ query string, so a link reproduces the exact view.
 
 The proxy strips `Content-Security-Policy`, `X-Frame-Options`, and the
 Cross-Origin-{Embedder,Opener,Resource}-Policy headers so production can be
-framed next to dev. That is safe **only on loopback**:
+framed next to dev.
 
-- It binds to `127.0.0.1` unless you override `--host`. **Do not** bind it to a
-  public interface or put it behind a public proxy.
+- Only loopback hosts are accepted, and Host headers are validated.
+- The viewer/control API uses `--port`; DEV and LIVE frames use `--port + 1`
+  and `--port + 2`, so neither page can inspect the other.
+- Framed pages communicate through a narrow `postMessage` bridge and cannot
+  access the viewer DOM, bearer token, notes API, or vault endpoint.
 - Treat the notes file as plaintext shared scratch space.
 
+## Development
+
+```bash
+npm test
+npm run test:e2e:visual
+npm run test:e2e:visual:update   # intentionally accept visual changes
+```
+
+The visual suite uses deterministic origins and checked-in Chromium baselines
+for desktop split, narrow Solo, difference overlay, and the notes drawer.
+
 ## Limitations
 
 - **URL rewriting is regex-based**, tuned for static sites (e.g. Astro builds).