sitedrift 0.1.0 → 0.3.0

package/src/mcp.mjs

@@ -0,0 +1,324 @@
+import { readVersion } from './cli.mjs';
+import { requestSession } from './agent.mjs';
+import { readSession } from './session.mjs';
+
+const PROTOCOL_VERSIONS = new Set([
+  '2024-11-05',
+  '2025-03-26',
+  '2025-06-18',
+  '2025-11-25',
+]);
+const LATEST_PROTOCOL_VERSION = '2025-11-25';
+
+const TOOLS = [
+  {
+    name: 'sitedrift_context',
+    title: 'Get sitedrift session context',
+    description: 'Get the active DEV/LIVE targets, viewer URL, capabilities, and session metadata. Call this first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        port: { type: 'integer', minimum: 1, maximum: 65533, default: 4178 },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'sitedrift_notes_list',
+    title: 'List review notes',
+    description: 'List the current shared visual-review notes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        port: { type: 'integer', minimum: 1, maximum: 65533, default: 4178 },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'sitedrift_note_add',
+    title: 'Add a review note',
+    description: 'Add one concrete visual finding for the user or another agent.',
+    inputSchema: {
+      type: 'object',
+      required: ['text'],
+      properties: {
+        text: { type: 'string', minLength: 1, maxLength: 2000 },
+        route: { type: 'string', default: '/' },
+        side: { type: ['string', 'null'], enum: ['dev', 'live', null] },
+        author: { type: 'string', default: 'agent' },
+        port: { type: 'integer', minimum: 1, maximum: 65533, default: 4178 },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  },
+  ...['resolve', 'reopen', 'remove'].map((action) => ({
+    name: `sitedrift_note_${action}`,
+    title: `${action[0].toUpperCase()}${action.slice(1)} a review note`,
+    description: `${action[0].toUpperCase()}${action.slice(1)} one shared review note by ID.`,
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'string', minLength: 1 },
+        port: { type: 'integer', minimum: 1, maximum: 65533, default: 4178 },
+      },
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: action === 'remove',
+      idempotentHint: action !== 'remove',
+      openWorldHint: false,
+    },
+  })),
+  {
+    name: 'sitedrift_notes_clear',
+    title: 'Clear all review notes',
+    description: 'Delete every note in the active review session. Use only when the user explicitly requests it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        port: { type: 'integer', minimum: 1, maximum: 65533, default: 4178 },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: 'sitedrift_setup',
+    title: 'Get setup instructions',
+    description: 'Return the shortest install, project configuration, launch, HTTPS, and MCP-client setup instructions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dev: { type: 'string', description: 'Local development origin.' },
+        live: { type: 'string', description: 'Production origin.' },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+];
+
+function jsonResult(value) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    structuredContent: value,
+  };
+}
+
+function setupInstructions(args = {}) {
+  const dev = args.dev || 'http://localhost:4321';
+  const live = args.live || 'https://example.com';
+  return {
+    install: 'npm install --global sitedrift',
+    configFile: 'sitedrift.config.json',
+    config: { dev, live, open: true },
+    launch: 'sitedrift',
+    https: ['sitedrift --setup-https', 'sitedrift --https'],
+    mcp: {
+      command: 'sitedrift-mcp',
+      alternative: 'npx -y sitedrift mcp',
+      config: { command: 'sitedrift-mcp', args: [] },
+    },
+    firstTool: 'sitedrift_context',
+    guide: 'Read the packaged AGENTS.md or the sitedrift://guide MCP resource.',
+  };
+}
+
+function noteOperation(name, args) {
+  if (name === 'sitedrift_note_add') {
+    return {
+      op: 'add',
+      text: args.text,
+      route: args.route || '/',
+      side: args.side || null,
+      author: args.author || 'agent',
+    };
+  }
+  if (name === 'sitedrift_notes_clear') return { op: 'clear' };
+  return { op: name.replace('sitedrift_note_', ''), id: args.id };
+}
+
+async function callTool(name, args = {}) {
+  if (name === 'sitedrift_setup') return setupInstructions(args);
+  const session = readSession(args.port || 4178);
+  if (name === 'sitedrift_context') return requestSession(session, '/api/v1/session');
+  if (name === 'sitedrift_notes_list') return requestSession(session, '/api/v1/notes');
+  if (!TOOLS.some((tool) => tool.name === name)) throw new Error(`Unknown tool: ${name}`);
+  return requestSession(session, '/api/v1/notes', {
+    method: 'POST',
+    body: JSON.stringify(noteOperation(name, args)),
+  });
+}
+
+function guideText() {
+  return `# sitedrift agent workflow
+
+1. Call sitedrift_context before doing review work.
+2. Use the returned viewer URL and DEV/LIVE targets as the source of truth.
+3. Record one concrete issue per sitedrift_note_add call. Include the route and side.
+4. Re-list notes before changing code and after verification.
+5. Resolve a note only after verifying the fix; remove notes only when explicitly asked.
+6. If no session is running, call sitedrift_setup and help the user create sitedrift.config.json, then launch sitedrift.
+
+The MCP server never receives browser credentials and only talks to a loopback sitedrift session using its private mode-0600 descriptor.`;
+}
+
+function promptResult(args = {}) {
+  const route = args.route || '/';
+  return {
+    description: 'Review one route with sitedrift and leave actionable shared notes.',
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `Review ${route} with sitedrift. Call sitedrift_context first, inspect DEV and LIVE, add one specific note per discrepancy, avoid duplicates, and resolve notes only after verification.`,
+      },
+    }],
+  };
+}
+
+export async function handleMcpRequest(message) {
+  const { id, method, params = {} } = message;
+  if (method === 'notifications/initialized' || method === 'notifications/cancelled') return null;
+  if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };
+  if (method === 'initialize') {
+    const requested = params.protocolVersion;
+    if (requested && !PROTOCOL_VERSIONS.has(requested)) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: {
+          code: -32602,
+          message: 'Unsupported protocol version',
+          data: { supported: [...PROTOCOL_VERSIONS], requested },
+        },
+      };
+    }
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: requested || LATEST_PROTOCOL_VERSION,
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        serverInfo: { name: 'sitedrift', version: readVersion() },
+        instructions: 'Call sitedrift_context first. If no session is running, call sitedrift_setup.',
+      },
+    };
+  }
+  if (method === 'tools/list') return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+  if (method === 'tools/call') {
+    try {
+      return { jsonrpc: '2.0', id, result: jsonResult(await callTool(params.name, params.arguments)) };
+    } catch (error) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{ type: 'text', text: error.message }],
+          isError: true,
+        },
+      };
+    }
+  }
+  if (method === 'resources/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        resources: [
+          { uri: 'sitedrift://guide', name: 'Agent guide', mimeType: 'text/markdown' },
+          { uri: 'sitedrift://session', name: 'Active session', mimeType: 'application/json' },
+          { uri: 'sitedrift://notes', name: 'Review notes', mimeType: 'application/json' },
+        ],
+      },
+    };
+  }
+  if (method === 'resources/read') {
+    try {
+      let text;
+      let mimeType = 'application/json';
+      if (params.uri === 'sitedrift://guide') {
+        text = guideText();
+        mimeType = 'text/markdown';
+      } else {
+        const session = readSession(4178);
+        const pathname = params.uri === 'sitedrift://session'
+          ? '/api/v1/session'
+          : params.uri === 'sitedrift://notes'
+            ? '/api/v1/notes'
+            : null;
+        if (!pathname) throw new Error(`Unknown resource: ${params.uri}`);
+        text = JSON.stringify(await requestSession(session, pathname), null, 2);
+      }
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { contents: [{ uri: params.uri, mimeType, text }] },
+      };
+    } catch (error) {
+      return { jsonrpc: '2.0', id, error: { code: -32002, message: error.message } };
+    }
+  }
+  if (method === 'prompts/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        prompts: [{
+          name: 'review_route',
+          title: 'Review a route',
+          description: 'Compare one route and record actionable findings.',
+          arguments: [{ name: 'route', description: 'Route to review, such as /pricing.', required: false }],
+        }],
+      },
+    };
+  }
+  if (method === 'prompts/get') {
+    if (params.name !== 'review_route') {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown prompt: ${params.name}` } };
+    }
+    return { jsonrpc: '2.0', id, result: promptResult(params.arguments) };
+  }
+  return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
+}
+
+async function processMessage(message) {
+  if (Array.isArray(message)) {
+    const responses = (await Promise.all(message.map(handleMcpRequest))).filter(Boolean);
+    return responses.length ? responses : null;
+  }
+  return handleMcpRequest(message);
+}
+
+export function runMcpServer(input = process.stdin, output = process.stdout) {
+  let buffer = '';
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      Promise.resolve()
+        .then(() => JSON.parse(line))
+        .then(processMessage)
+        .then((response) => {
+          if (response) output.write(`${JSON.stringify(response)}\n`);
+        })
+        .catch((error) => {
+          output.write(`${JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32700, message: error.message },
+          })}\n`);
+        });
+    }
+  });
+}

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,80 @@
+import { send } from './http.mjs';
+import { frameBridge, rewriteRootPaths } from './frame-content.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 targetFor(side, pathname, search) {
+    const base = side === 'dev' ? devBase : liveBase;
+    const relative = pathname.replace(new RegExp(`^/__${side}`), '') || '/';
+    return new URL(`${relative}${search}`, `${base.href}/`);
+  }
+
+  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 = frameBridge(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);
+}