sitedrift 0.1.0 → 0.2.0

package/src/notes.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Review notes are a JSON file the server reads/mutates and the viewer polls,
+// making it a shared channel between humans and AI sessions.
+export function createNotes({ notesFile, author }) {
+  function load() {
+    try {
+      const data = JSON.parse(fs.readFileSync(notesFile, 'utf8'));
+      if (Array.isArray(data)) return data;
+      return Array.isArray(data.notes) ? data.notes : [];
+    } catch {
+      return [];
+    }
+  }
+
+  function save(notes) {
+    fs.mkdirSync(path.dirname(notesFile), { recursive: true });
+    const tmp = `${notesFile}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(notes, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, notesFile);
+  }
+
+  function id() {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+  }
+
+  function markdown(notes) {
+    if (!notes.length) return '# sitedrift review notes\n\n_No notes yet._\n';
+    const lines = ['# sitedrift review notes', ''];
+    for (const note of notes) {
+      const box = note.done ? '[x]' : '[ ]';
+      const where = [note.route && note.route !== '/' ? note.route : '', note.side ? note.side.toUpperCase() : '']
+        .filter(Boolean).join(' ');
+      const tag = where ? ` _(${where})_` : '';
+      lines.push(`- ${box} **${note.author || 'note'}:** ${note.text}${tag}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  function applyOp(op) {
+    let notes = load();
+    if (op.op === 'add' && op.text) {
+      const text = String(op.text).slice(0, 2000);
+      const rawRoute = String(op.route || '/').slice(0, 2048);
+      const route = rawRoute.startsWith('/') ? rawRoute : `/${rawRoute}`;
+      const who = String(op.author || author || 'note').slice(0, 24);
+      const side = op.side === 'dev' || op.side === 'live' ? op.side : null;
+      // Skip an identical open note so repeated `--note` seeding doesn't pile up.
+      const duplicate = notes.some((note) => !note.done
+        && note.text === text && note.route === route && note.author === who && note.side === side);
+      if (!duplicate) {
+        notes.push({ id: id(), text, author: who, route, side, done: false, ts: Date.now() });
+        if (notes.length > 1000) notes = notes.slice(-1000);
+      }
+    } else if (op.op === 'remove') {
+      if (!notes.some((note) => note.id === op.id)) throw new Error(`Unknown note id: ${op.id}`);
+      notes = notes.filter((note) => note.id !== op.id);
+    } else if (op.op === 'toggle' || op.op === 'resolve' || op.op === 'reopen') {
+      const found = notes.some((note) => note.id === op.id);
+      if (!found) throw new Error(`Unknown note id: ${op.id}`);
+      notes = notes.map((note) => {
+        if (note.id !== op.id) return note;
+        const done = op.op === 'toggle' ? !note.done : op.op === 'resolve';
+        return { ...note, done };
+      });
+    } else if (op.op === 'clear') {
+      notes = [];
+    } else {
+      throw new Error(`Unknown notes operation: ${op.op || '(missing)'}`);
+    }
+    save(notes);
+    return notes;
+  }
+
+  return { load, save, markdown, applyOp };
+}

package/src/proxy.mjs

@@ -0,0 +1,146 @@
+import { send } from './http.mjs';
+
+// Reverse-proxies the two origins under /__dev/* and /__live/*, rewriting
+// root-relative URLs so both sites render framed side-by-side. Deliberately
+// strips framing/isolation headers — safe for loopback development only.
+export function createProxy({ devBase, liveBase }) {
+  function bridge(side) {
+    const script = `(() => {
+      const side=${JSON.stringify(side)};
+      let linked=false, mirror=false;
+      const send=(type,data={})=>parent.postMessage({source:'sitedrift-frame',side,type,...data},'*');
+      const root=()=>document.scrollingElement||document.documentElement;
+      const route=()=>location.pathname.replace(/^\\/__${side}/,'')+location.search+location.hash||'/';
+      const snapshot=()=>{
+        const q=(s)=>document.querySelector(s);
+        const imgs=[...document.querySelectorAll('img')];
+        const title=(document.title||'').trim();
+        const description=q('meta[name="description"]')?.content?.trim()||'';
+        const canonical=q('link[rel="canonical"]')?.href||'';
+        const checks=[
+          ['Title present',!!title],['Title 30–60 chars',title.length>=30&&title.length<=60,title.length+''],
+          ['Meta description',!!description],['Description 70–160',description.length>=70&&description.length<=160,description.length+''],
+          ['Exactly one H1',document.querySelectorAll('h1').length===1,document.querySelectorAll('h1').length+' found'],
+          ['Canonical link',!!q('link[rel="canonical"]')],['Viewport meta',!!q('meta[name="viewport"]')],
+          ['html lang',!!document.documentElement.lang],['Open Graph title',!!q('meta[property="og:title"]')],
+          ['Open Graph image',!!q('meta[property="og:image"]')],
+          ['Not noindex',!(q('meta[name="robots"]')?.content||'').toLowerCase().includes('noindex')],
+          ['Favicon',!!q('link[rel~="icon"]')],
+          ['Images have alt',imgs.every((img)=>img.hasAttribute('alt')),imgs.filter((img)=>!img.hasAttribute('alt')).length+' missing']
+        ].map(([label,ok,note])=>({label,ok,note}));
+        send('ready',{route:route(),meta:{title,description,canonical,heading:q('h1')?.textContent?.trim()||'',
+          siteName:q('meta[property="og:site_name"]')?.content?.trim()||'',icon:q('link[rel~="icon"]')?.href||'',checks}});
+        send('scroll',{y:scrollY,max:Math.max(0,root().scrollHeight-innerHeight)});
+      };
+      addEventListener('message',(event)=>{
+        const msg=event.data||{};
+        if(msg.source!=='sitedrift-parent'||msg.side!==side)return;
+        if(msg.type==='settings'){linked=!!msg.linked;mirror=!!msg.mirror;document.documentElement.style.scrollBehavior='auto';}
+        if(msg.type==='scroll'){root().scrollTop=msg.y;}
+        if(msg.type==='reload')location.reload();
+      });
+      addEventListener('scroll',()=>send('scroll',{y:scrollY,max:Math.max(0,root().scrollHeight-innerHeight)}),{passive:true});
+      addEventListener('wheel',(event)=>{if(!linked||!event.deltaY)return;event.preventDefault();send('wheel',{delta:event.deltaY,mode:event.deltaMode,height:innerHeight,y:scrollY});},{passive:false,capture:true});
+      addEventListener('keydown',(event)=>{
+        const typing=/^(INPUT|TEXTAREA|SELECT)$/.test(event.target.tagName)||event.target.isContentEditable;
+        if(!typing&&!event.metaKey&&!event.ctrlKey&&!event.altKey&&['r','s','0','/','o','d'].includes(event.key.toLowerCase())){
+          event.preventDefault();send('key',{key:event.key.toLowerCase()});return;
+        }
+        if(linked&&!typing&&!event.metaKey&&!event.ctrlKey&&!event.altKey)send('key',{key:event.key,shift:event.shiftKey,y:scrollY,height:innerHeight,max:Math.max(0,root().scrollHeight-innerHeight)});
+      },true);
+      addEventListener('click',(event)=>{
+        if(!mirror||event.defaultPrevented||event.button!==0||event.metaKey||event.ctrlKey||event.shiftKey||event.altKey)return;
+        const link=event.target.closest('a[href]');if(!link||link.target==='_blank'||link.hasAttribute('download'))return;
+        const url=new URL(link.href,location.href);if(url.origin!==location.origin||!url.pathname.startsWith('/__'+side))return;
+        event.preventDefault();send('navigate',{route:url.pathname.slice(('/__'+side).length)||'/'});
+      },true);
+      addEventListener('DOMContentLoaded',snapshot,{once:true});if(document.readyState!=='loading')snapshot();
+    })();`;
+    return `<script>${script.replace(/<\//g, '<\\/')}</script>`;
+  }
+
+  function targetFor(side, pathname, search) {
+    const base = side === 'dev' ? devBase : liveBase;
+    const relative = pathname.replace(new RegExp(`^/__${side}`), '') || '/';
+    return new URL(`${relative}${search}`, `${base.href}/`);
+  }
+
+  function rewriteRootPaths(body, side) {
+    const prefix = `/__${side}`;
+    return body
+      .replace(/(\b(?:href|src|action|poster)=["'])\/(?!\/)/gi, `$1${prefix}/`)
+      .replace(/\bsrcset=(["'])(.*?)\1/gi, (attribute, quote, value) => {
+        const rewritten = value.replace(/(^|,\s*)\/(?!\/)/g, `$1${prefix}/`);
+        return `srcset=${quote}${rewritten}${quote}`;
+      })
+      .replace(/url\((["']?)\/(?!\/)/gi, `url($1${prefix}/`)
+      .replace(/(["'`])\/(@(?:id|vite|fs)\/|_astro\/)/g, `$1${prefix}/$2`);
+  }
+
+  async function proxy(req, res, side, requestUrl) {
+    const target = targetFor(side, requestUrl.pathname, requestUrl.search);
+    const headers = { ...req.headers, host: target.host };
+    delete headers['accept-encoding'];
+    delete headers.connection;
+
+    try {
+      const upstream = await fetch(target, {
+        method: req.method,
+        headers,
+        redirect: 'manual',
+      });
+      const responseHeaders = {};
+      upstream.headers.forEach((value, key) => {
+        if (![
+          'content-encoding',
+          'content-length',
+          'content-security-policy',
+          'content-security-policy-report-only',
+          'cross-origin-embedder-policy',
+          'cross-origin-opener-policy',
+          'cross-origin-resource-policy',
+          'transfer-encoding',
+          'x-frame-options',
+        ].includes(key)) {
+          responseHeaders[key] = value;
+        }
+      });
+      responseHeaders['cache-control'] = 'no-store';
+
+      const location = upstream.headers.get('location');
+      if (location) {
+        const redirected = new URL(location, target);
+        if (redirected.origin === target.origin) {
+          responseHeaders.location = `/__${side}${redirected.pathname}${redirected.search}${redirected.hash}`;
+        }
+      }
+
+      const type = upstream.headers.get('content-type') || '';
+      // Rewrite markup/CSS/JS always; rewrite JSON only on the dev side (Vite
+      // manifests) so live API payloads with path-like strings aren't corrupted.
+      const rewritable = /text\/html|text\/css|javascript/.test(type)
+        || (side === 'dev' && /application\/json/.test(type));
+      if (rewritable) {
+        let body = rewriteRootPaths(await upstream.text(), side);
+        if (/text\/html/.test(type)) {
+          const injected = bridge(side);
+          body = body.includes('</head>') ? body.replace('</head>', `${injected}</head>`) : `${injected}${body}`;
+        }
+        res.writeHead(upstream.status, responseHeaders);
+        res.end(body);
+        return;
+      }
+
+      res.writeHead(upstream.status, responseHeaders);
+      res.end(Buffer.from(await upstream.arrayBuffer()));
+    } catch (error) {
+      send(
+        res,
+        502,
+        `Could not load ${target.href}\n\n${error.message}\n\nStart the dev server with: site dev`,
+      );
+    }
+  }
+
+  return { proxy };
+}

package/src/server.mjs

@@ -0,0 +1,171 @@
+import http from 'node:http';
+import https from 'node:https';
+import fs from 'node:fs';
+
+import { send, readBody } from './http.mjs';
+import { createNotes } from './notes.mjs';
+import { createProxy } from './proxy.mjs';
+import { assets, renderViewer, VIEWER_VERSION } from './viewer.mjs';
+
+function sendAsset(res, body, type) {
+  if (!body) return send(res, 404, 'not found');
+  res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'max-age=86400' });
+  res.end(body);
+}
+
+function json(res, status, body) {
+  send(res, status, JSON.stringify(body), 'application/json; charset=utf-8');
+}
+
+function authorized(req, session) {
+  const auth = req.headers.authorization || '';
+  if (auth !== `Bearer ${session.token}`) return false;
+  const referer = req.headers.referer || '';
+  if (!referer) return true;
+  try {
+    const pathname = new URL(referer).pathname;
+    return !pathname.startsWith('/__dev') && !pathname.startsWith('/__live');
+  } catch {
+    return false;
+  }
+}
+
+export function createServer(config, tls, session, { control = true, side: frameSide } = {}) {
+  const { devBase, liveBase, vaultDir } = config;
+  const notes = createNotes(config);
+  const { proxy } = createProxy(config);
+
+  const handler = async (req, res) => {
+    try {
+      const hostname = new URL(`http://${req.headers.host}`).hostname.replace(/^\[|\]$/g, '');
+      if (hostname !== config.host) {
+        send(res, 421, 'misdirected request');
+        return;
+      }
+    } catch {
+      send(res, 400, 'invalid host');
+      return;
+    }
+    const requestUrl = new URL(req.url || '/', `http://${config.host}:${config.port}`);
+    const { pathname } = requestUrl;
+
+    const isNotes = pathname === '/notes' || pathname === '/api/v1/notes';
+    const isSave = pathname === '/notes/save' || pathname === '/api/v1/notes/save';
+
+    if (!control && frameSide && !pathname.startsWith(`/__${frameSide}`)) {
+      const referer = req.headers.referer || '';
+      if (referer.includes(`/__${frameSide}/`)) {
+        requestUrl.pathname = `/__${frameSide}${pathname}`;
+        await proxy(req, res, frameSide, requestUrl);
+      } else {
+        send(res, 404, 'not found');
+      }
+      return;
+    }
+
+    if (!control && !pathname.startsWith('/__dev') && !pathname.startsWith('/__live')) {
+      const referer = req.headers.referer || '';
+      if (referer.includes('/__dev/')) {
+        requestUrl.pathname = `/__dev${pathname}`;
+        await proxy(req, res, 'dev', requestUrl);
+      } else if (referer.includes('/__live/')) {
+        requestUrl.pathname = `/__live${pathname}`;
+        await proxy(req, res, 'live', requestUrl);
+      } else {
+        send(res, 404, 'not found');
+      }
+    } else if (pathname === '/health') {
+      send(res, 200, JSON.stringify({
+        dev: devBase.href.replace(/\/$/, ''),
+        live: liveBase.href.replace(/\/$/, ''),
+        version: VIEWER_VERSION,
+      }), 'application/json; charset=utf-8');
+    } else if (pathname === '/api/v1/session') {
+      if (!authorized(req, session)) {
+        json(res, 401, { error: 'unauthorized' });
+      } else {
+        json(res, 200, {
+          session: {
+            version: session.version,
+            url: session.url,
+            dev: session.dev,
+            live: session.live,
+            notesFile: session.notesFile,
+            startedAt: session.startedAt,
+          },
+          capabilities: ['notes:list', 'notes:add', 'notes:resolve', 'notes:reopen', 'notes:remove', 'notes:clear'],
+          notes: notes.load(),
+        });
+      }
+    } else if (isNotes) {
+      if (!authorized(req, session)) {
+        json(res, 401, { error: 'unauthorized' });
+        return;
+      }
+      if (req.method === 'GET') {
+        json(res, 200, { notes: notes.load() });
+      } else if (req.method === 'POST') {
+        // Require a JSON content-type so cross-origin writes need a preflight the
+        // server (no CORS headers) will fail — closes the text/plain CSRF path.
+        if (!(req.headers['content-type'] || '').includes('application/json')) {
+          json(res, 415, { error: 'notes require Content-Type: application/json' });
+        } else {
+          try {
+            const op = JSON.parse((await readBody(req)) || '{}');
+            json(res, 200, { notes: notes.applyOp(op) });
+          } catch (error) {
+            json(res, 400, { error: error.message });
+          }
+        }
+      } else {
+        send(res, 405, 'method not allowed');
+      }
+    } else if (pathname === '/notes.md') {
+      send(res, 200, notes.markdown(notes.load()), 'text/markdown; charset=utf-8');
+    } else if (isSave) {
+      if (!authorized(req, session)) {
+        json(res, 401, { error: 'unauthorized' });
+        return;
+      }
+      if (req.method !== 'POST') {
+        send(res, 405, 'method not allowed');
+      } else if (!vaultDir) {
+        json(res, 400, { ok: false, error: 'no vault configured' });
+      } else {
+        try {
+          const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-');
+          const file = `${vaultDir}/sitedrift-review-${stamp}.md`;
+          fs.writeFileSync(file, notes.markdown(notes.load()));
+          json(res, 200, { ok: true, path: file });
+        } catch (error) {
+          json(res, 500, { ok: false, error: error.message });
+        }
+      }
+    } else if (pathname === '/icon.svg') {
+      sendAsset(res, assets.icon, 'image/svg+xml; charset=utf-8');
+    } else if (pathname === '/viewer.css') {
+      sendAsset(res, assets.css, 'text/css; charset=utf-8');
+    } else if (pathname === '/viewer.js') {
+      sendAsset(res, assets.js, 'text/javascript; charset=utf-8');
+    } else if (pathname.startsWith('/__dev')) {
+      await proxy(req, res, 'dev', requestUrl);
+    } else if (pathname.startsWith('/__live')) {
+      await proxy(req, res, 'live', requestUrl);
+    } else {
+      // A resource requested by a proxied page (no /__side prefix) is routed by
+      // its referer; everything else is the viewer shell.
+      const referer = req.headers.referer || '';
+      if (referer.includes('/__dev/')) {
+        requestUrl.pathname = `/__dev${pathname}`;
+        await proxy(req, res, 'dev', requestUrl);
+      } else if (referer.includes('/__live/')) {
+        requestUrl.pathname = `/__live${pathname}`;
+        await proxy(req, res, 'live', requestUrl);
+      } else {
+        send(res, 200, renderViewer(config, session), 'text/html; charset=utf-8');
+      }
+    }
+  };
+
+  return tls ? https.createServer(tls, handler) : http.createServer(handler);
+}

package/src/session.mjs

@@ -0,0 +1,53 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SESSION_DIR = path.join(os.homedir(), '.sitedrift', 'sessions');
+
+export function sessionFile(port) {
+  return path.join(SESSION_DIR, `${port}.json`);
+}
+
+export function createSession(config, scheme) {
+  const token = crypto.randomBytes(32).toString('base64url');
+  const host = config.host.includes(':') ? `[${config.host}]` : config.host;
+  const url = `${scheme}://${host}:${config.port}`;
+  const frameUrls = {
+    dev: `${scheme}://${host}:${config.port + 1}`,
+    live: `${scheme}://${host}:${config.port + 2}`,
+  };
+  const session = {
+    version: 1,
+    pid: process.pid,
+    url,
+    frameUrls,
+    token,
+    dev: config.devBase.href.replace(/\/$/, ''),
+    live: config.liveBase.href.replace(/\/$/, ''),
+    notesFile: config.notesFile,
+    startedAt: new Date().toISOString(),
+  };
+  return session;
+}
+
+export function writeSession(config, session) {
+  fs.mkdirSync(SESSION_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(sessionFile(config.port), JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+
+export function removeSession(config) {
+  try {
+    const file = sessionFile(config.port);
+    const current = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (current.pid === process.pid) fs.unlinkSync(file);
+  } catch {}
+}
+
+export function readSession(port) {
+  try {
+    return JSON.parse(fs.readFileSync(sessionFile(port), 'utf8'));
+  } catch {
+    throw new Error(`No running sitedrift session found on port ${port}.`);
+  }
+}

package/src/tls.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// Cached auto-generated cert lives here so --https is instant after the first run
+// and a mkcert-trusted CA only has to be installed once.
+const CERT_DIR = path.join(os.homedir(), '.sitedrift');
+const CERT_FILE = path.join(CERT_DIR, 'localhost.pem');
+const KEY_FILE = path.join(CERT_DIR, 'localhost-key.pem');
+const HOSTS = ['localhost', '127.0.0.1', '::1'];
+
+function have(cmd, probe) {
+  try {
+    return !spawnSync(cmd, [probe], { stdio: 'ignore' }).error;
+  } catch {
+    return false;
+  }
+}
+const hasMkcert = () => have('mkcert', '-CAROOT');
+const hasOpenssl = () => have('openssl', 'version');
+
+function generateWithMkcert(quiet) {
+  const stdio = quiet ? 'ignore' : 'inherit';
+  // -install is idempotent; first run may prompt for the OS trust store.
+  spawnSync('mkcert', ['-install'], { stdio });
+  const r = spawnSync('mkcert', ['-cert-file', CERT_FILE, '-key-file', KEY_FILE, ...HOSTS], { stdio });
+  if (r.status !== 0) throw new Error('mkcert failed to generate a certificate.');
+}
+
+function generateWithOpenssl() {
+  const san = HOSTS.map((h) => (/^[\d.:]+$/.test(h) ? `IP:${h}` : `DNS:${h}`)).join(',');
+  const r = spawnSync('openssl', [
+    'req', '-x509', '-newkey', 'rsa:2048', '-nodes',
+    '-keyout', KEY_FILE, '-out', CERT_FILE,
+    '-days', '825', '-subj', '/CN=localhost',
+    '-addext', `subjectAltName=${san}`,
+  ], { stdio: 'ignore' });
+  if (r.status !== 0) throw new Error('openssl failed to generate a certificate.');
+}
+
+const NO_TOOL = new Error(
+  'sitedrift --https needs `mkcert` (recommended) or `openssl`.\n'
+  + '  Install mkcert for zero-warning HTTPS: https://github.com/FiloSottile/mkcert#installation\n'
+  + '  (macOS: brew install mkcert · then run: sitedrift --setup-https)\n'
+  + '  Or bring your own cert: sitedrift --cert <file> --key <file>',
+);
+
+// Returns { certFile, keyFile, source, trusted }. `source` is cache | mkcert | openssl.
+function ensureCert({ quiet = true, force = false } = {}) {
+  fs.mkdirSync(CERT_DIR, { recursive: true });
+  if (!force && fs.existsSync(CERT_FILE) && fs.existsSync(KEY_FILE)) {
+    return { certFile: CERT_FILE, keyFile: KEY_FILE, source: 'cache', trusted: true };
+  }
+  if (hasMkcert()) {
+    generateWithMkcert(quiet);
+    return { certFile: CERT_FILE, keyFile: KEY_FILE, source: 'mkcert', trusted: true };
+  }
+  if (hasOpenssl()) {
+    generateWithOpenssl();
+    return { certFile: CERT_FILE, keyFile: KEY_FILE, source: 'openssl', trusted: false };
+  }
+  throw NO_TOOL;
+}
+
+function trustSteps(certFile) {
+  const steps = {
+    darwin: `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${certFile}"`,
+    linux: `sudo cp "${certFile}" /usr/local/share/ca-certificates/sitedrift.crt && sudo update-ca-certificates`,
+    win32: `certutil -addstore -f ROOT "${certFile}"`,
+  };
+  const here = steps[process.platform];
+  return here
+    ? `Trust it on this machine:\n   ${here}\n   (or just click through the browser warning each run)`
+    : 'Your browser will warn once — click Advanced → Proceed, or trust the cert in your OS store.';
+}
+
+// Used by the server: resolve { cert, key } buffers, or null for plain HTTP.
+export function resolveTls(config) {
+  if (config.certFile && config.keyFile) {
+    return { cert: fs.readFileSync(config.certFile), key: fs.readFileSync(config.keyFile) };
+  }
+  if (config.https) {
+    const c = ensureCert({ quiet: true });
+    if (c.source === 'openssl') {
+      console.log('sitedrift: generated a self-signed cert (browser will warn).');
+      console.log('  For zero warnings: sitedrift --setup-https  (needs mkcert)\n');
+    }
+    return { cert: fs.readFileSync(c.certFile), key: fs.readFileSync(c.keyFile) };
+  }
+  return null;
+}
+
+// Used by `sitedrift --setup-https`: generate + trust, with guided output.
+export function setupHttps() {
+  console.log('sitedrift — HTTPS setup\n');
+  if (hasMkcert()) {
+    console.log('Found mkcert — generating a locally-trusted certificate.\n');
+    const c = ensureCert({ quiet: false, force: true });
+    console.log(`\n✓ Local CA installed and trusted cert written:\n   ${c.certFile}`);
+    console.log('\nStart with HTTPS (no browser warning):\n   sitedrift --https');
+    return 0;
+  }
+  if (hasOpenssl()) {
+    console.log('mkcert not found — using openssl for a self-signed cert.');
+    console.log('Tip: `brew install mkcert` gives zero-warning HTTPS instead.\n');
+    const c = ensureCert({ quiet: false, force: true });
+    console.log(`✓ Self-signed cert written:\n   ${c.certFile}\n`);
+    console.log(trustSteps(c.certFile));
+    console.log('\nThen start: sitedrift --https');
+    return 0;
+  }
+  console.error(NO_TOOL.message);
+  return 1;
+}

package/src/viewer.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+
+// Bumped when the viewer assets change; busts the ?v= cache and reported in
+// /health so the `site compare` wrapper knows when to restart the server.
+export const VIEWER_VERSION = 28;
+
+function readAsset(path) {
+  try {
+    return fs.readFileSync(new URL(path, import.meta.url), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// Loaded once at startup — the viewer is static; only the config blob is per-run.
+export const assets = {
+  html: readAsset('../assets/viewer.html'),
+  css: readAsset('../assets/viewer.css'),
+  js: readAsset('../assets/viewer.js'),
+  icon: readAsset('../assets/icon.svg'),
+};
+
+export function renderViewer({ devBase, liveBase, brand, author, vaultDir }, session) {
+  const config = JSON.stringify({
+    dev: devBase.href.replace(/\/$/, ''),
+    live: liveBase.href.replace(/\/$/, ''),
+    brand,
+    author,
+    vault: !!vaultDir,
+    token: session.token,
+    api: '/api/v1',
+    frameOrigins: session.frameUrls,
+  }).replace(/</g, '\\u003c');
+
+  return assets.html
+    .replaceAll('__VERSION__', String(VIEWER_VERSION))
+    .replace('__CONFIG__', config);
+}