feat: htmlbin serve — local preview before publish

[utsengar]

Summary

Adds htmlbin serve — a local preview server for HTML and Markdown so iteration happens locally before publishing. Same file in, same artifact out: htmlbin serve out.html → review locally → htmlbin publish out.html. Also gives the CLI a branded help screen.

htmlbin serve <path>     start (file or directory; live-reload on save)
htmlbin serve --status   inspect the running server in this cwd
htmlbin serve --stop     shut it down

Highlights

• One command, file or directory. .html served raw; .md rendered via marked with the same prose tokens as htmlbin.dev. Directory mode shows an mtime-sorted index.
• Chrome matches the production drop viewer-bar. Full-width, Geist sans title, mono meta column, red [local] chip + connection dot. Appended to documentElement (not body) and position: fixed, so it survives user pages with max-width containers, transform, or filter. Body padding-top is extended at mount so content sits below the bar, not behind it.
• publish → link in the bar. Click opens a small popover with htmlbin publish <abs-path> and a Copy command button. No network calls from the server — bar stays passive. Shown only for .html/.htm.
• External client assets. The bar's CSS and JS live at /__hb/client.css and /__hb/client.js, not inline, so pages with Content-Security-Policy: script-src 'self' (and style-src 'self') still load the bar.
• CSS reset resilience. All bar positioning carries !important, so user CSS like * { all: revert !important } can't override it.
• Live reload over SSE, zero client deps. fs.watch with 50ms debounce and a dotfile/node_modules filter (so the state file at .htmlbin/serve.json doesn't fire phantom reloads).
• Symlink-safe. renderDir does a fs.realpath() check to confirm the resolved path is still under the served root; the directory walker uses lstat and skips symlinks.
• Agent-first contract: one JSON object per line on stdout (started, reload, client-connected, idle-shutdown, stopped) when --output json. Lets an agent tail the background process and verify "did my edit reach the browser?" without polling.
• State file at ./.htmlbin/serve.json is the cross-invocation discovery primitive — a later turn can call --status / --stop without parsing logs.
• Auto-detected agent defaults: when CLAUDE_CODE / CURSOR_AGENT / etc. is set in the env, browser auto-open flips off and idle timeout drops from 30 → 5 min.
• Duplicate-start guard with PID liveness check; clean SIGINT / SIGTERM shutdown; ephemeral port by default, --port to override.
• Branded htmlbin --help. Sectioned layout (commands / flags / environment variables / try / learn-more) with an ASCII wordmark, gated on TTY + NO_COLOR so piped output stays plain. htmlbin with no subcommand now lands on this help instead of commander's "missing required command" error. Subcommands keep commander's default per-command help.

New runtime dep: marked.

Files

src/serve/
  index.ts       orchestration (start / status / stop)
  server.ts      http.createServer + SSE broadcast hub + /__hb/* routes
  render.ts      path → response (HTML pass-through, MD render, dir index, 404, realpath/symlink check)
  inject.ts      builds the <link> + <script src> tags appended to served HTML
  client.ts      bar runtime + styles, served as static assets
  template.ts    chrome + prose tokens for content we own (MD, index, 404)
  watcher.ts     fs.watch wrapper with debounce + dotfile filter
  state.ts       .htmlbin/serve.json read/write + PID liveness
  types.ts       ServeOptions, ServeState

src/banner.ts    branded help formatter for the root command
src/bin.ts       registerServeCommand + helpInformation override
src/errors.ts    + serve_already_running / serve_not_running / serve_port_in_use

Stress tests passed

• 100 concurrent SSE clients connected; 50/50 received a reload broadcast
• 20 rapid edits collapse to 1 reload (50ms debounce)
• Atomic save (write-tmp + rename) → exactly 1 reload
• 100 files added in a dir → 2 reloads, server responsive in ~25ms
• Path traversal (../, %2E%2E%2F, double-encoded, null byte) → 404
• Symlink inside the served root pointing at /etc/passwd → 404 (after hardening)
• kill -9 → stale state file is cleared on next start
• Port collision → serve_port_in_use (exit 8)
• serve --stop twice → second returns serve_not_running (exit 7)

Test plan

• htmlbin serve <file.html> — bar renders full-width with [local] chip; edit file → browser reloads
• User HTML content sits below the bar, not behind it (works on pages with and without their own body { padding })
• publish → link opens a popover with htmlbin publish /abs/path + Copy button; click outside or Esc dismisses
• htmlbin serve <file.md> — Markdown renders with chrome at top; no publish button
• htmlbin serve <dir> — index page lists .html/.md sorted by mtime
• htmlbin serve --status / --stop — round-trip with state file at .htmlbin/serve.json
• Duplicate htmlbin serve <path> while one is running → exit 7
• htmlbin serve --output json — one event per line on stdout
• Edit a file → exactly one reload event (state-file write doesn't echo)
• htmlbin (no args) and htmlbin --help show the branded banner in a TTY, plain text when piped
• htmlbin serve --help (and other subcommand --help) still uses commander's default

🤖 Generated with Claude Code