mnfst-run 1.0.20 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnfst-run",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Zero-dependency dev server for Manifest projects",
   "type": "module",
   "bin": {

package/serve.mjs

@@ -31,6 +31,15 @@
  *                       panel already shows the page, so a second browser tab
  *                       is just noise. Put `--no-open` in an LLM preview's
  *                       launch config to guarantee suppression.
+ *   --attach            Supervised/agent mode (e.g. an LLM preview panel that
+ *                       assigns a port and tracks the process it spawns). Never
+ *                       starts a SECOND dev server for a project already running:
+ *                       if a server for this root exists on another port, it
+ *                       binds the assigned port and reverse-proxies to that real
+ *                       server (live reload included); if it's already on the
+ *                       assigned port it just attaches; otherwise it starts one
+ *                       normally. Let the supervisor pick the port (no --port;
+ *                       it's read from PORT). Pair with `--no-open`.
  *   --list              Print all mnfst-run servers currently running on this
  *                       machine and exit.
  *
@@ -43,7 +52,9 @@
  *                     sources and updates Alpine store reactively (no reload)
  *   other           → full page reload
  */
-import { createServer, get as httpGet }  from 'http';
+import { createServer, get as httpGet, request as httpRequest }  from 'http';
+import { request as httpsRequest } from 'https';
+import { connect as tlsConnect } from 'tls';
 import {
   readFileSync, statSync, watch,
   existsSync, writeFileSync, unlinkSync,
@@ -152,9 +163,10 @@ const LIVE_RELOAD_SCRIPT = `<script>
 // by the host. See the Appwrite setup doc for the full pattern.
 function loadEnvFile(rootDir) {
   const envPath = join(rootDir, '.env');
-  if (!existsSync(envPath)) return { public: {}, private: [] };
+  if (!existsSync(envPath)) return { public: {}, private: [], privateValues: {} };
   const publicEnv = {};
   const privateNames = [];
+  const privateValues = {};   // server-side only — NEVER injected into window.env
   try {
     const text = readFileSync(envPath, 'utf8');
     for (const line of text.split(/\r?\n/)) {
@@ -170,12 +182,12 @@ function loadEnvFile(rootDir) {
         value = value.slice(1, -1);
       }
       if (key.startsWith('PUBLIC_')) publicEnv[key] = value;
-      else privateNames.push(key);
+      else { privateNames.push(key); privateValues[key] = value; }
     }
   } catch (error) {
     console.warn('[mnfst-run] Failed to parse .env:', error.message);
   }
-  return { public: publicEnv, private: privateNames };
+  return { public: publicEnv, private: privateNames, privateValues };
 }
 
 // Build a `<script>window.env = {…};</script>` tag from the public env map.
@@ -226,6 +238,12 @@ let openBrowserEnabled = !(
 );
 
 let listMode = false;
+// --attach: supervised/agent mode (e.g. Claude Code's preview panel). Guarantees
+// a live server in the FOREGROUND on the requested --port: if that exact port is
+// already serving this root, stay attached to it (don't exit) instead of bailing;
+// a separate server the user started on another port is left alone. Never writes
+// or deletes the running-server registry, so it can't clobber the user's entry.
+let attachMode = false;
 
 for (let i = 0; i < args.length; i++) {
   if ((args[i] === '--port' || args[i] === '-p') && args[i + 1]) { port = parseInt(args[++i], 10); continue; }
@@ -233,6 +251,7 @@ for (let i = 0; i < args.length; i++) {
   if (args[i] === '--idle-shutdown' && args[i + 1]) { idleShutdownSec = parseInt(args[++i], 10); continue; }
   if (args[i] === '--no-open') { openBrowserEnabled = false; continue; }
   if (args[i] === '--open')    { openBrowserEnabled = true;  continue; }
+  if (args[i] === '--attach') { attachMode = true; continue; }
   if (args[i] === '--list' || args[i] === '-l') { listMode = true; continue; }
   if (!args[i].startsWith('-')) dir = args[i];
 }
@@ -341,13 +360,87 @@ if (listMode) {
 }
 
 const root = resolve(process.cwd(), dir);
+const EDIT_ENABLED = process.argv.includes('--edit') || process.env.MNFST_EDIT === '1';   // gates /__edit/save (edit-plugin source write-back, authoring only)
 
 // Load .env from the serving root (if present) and pre-build the inject
 // script. Kept as a single string so serveFile doesn't re-stringify on every
 // HTML response. Empty string when no public vars exist — the injection step
 // becomes a no-op for projects whose .env holds only server-side secrets.
-const { public: publicEnv, private: privateEnvNames } = loadEnvFile(root);
-const envInjectScript = buildEnvInjectScript(publicEnv);
+const { public: publicEnv, private: privateEnvNames, privateValues: privateEnv } = loadEnvFile(root);
+// Appwrite dev proxy: when APPWRITE_PROXY_TARGET is set (server-side .env), the
+// dev server proxies /_appwrite/* to that Appwrite origin so the session cookie
+// is FIRST-PARTY on localhost. Cross-origin Appwrite Cloud blocks the third-party
+// session cookie, and some endpoints (e.g. Presences) don't honour the
+// X-Fallback-Cookies workaround the SDK uses for the others — so user-scoped
+// calls land as the anonymous "guests" role. Proxying makes Appwrite same-origin
+// and fixes it uniformly (HTTP + Realtime WebSocket).
+const APPWRITE_PROXY_TARGET = (process.env.APPWRITE_PROXY_TARGET || privateEnv.APPWRITE_PROXY_TARGET || '').trim();
+const APPWRITE_PROXY_PREFIX = '/_appwrite';
+
+let envInjectScript = buildEnvInjectScript(publicEnv);
+if (APPWRITE_PROXY_TARGET) {
+  // Point the Appwrite endpoint at the same-origin proxy. Computed in the browser
+  // from location.origin so it's port-independent (auto-port safe) and prod-safe
+  // (production sets PUBLIC_APPWRITE_ENDPOINT to the real/custom domain instead).
+  envInjectScript += `<script>window.env=Object.assign(window.env||{},{PUBLIC_APPWRITE_ENDPOINT:location.origin+'${APPWRITE_PROXY_PREFIX}/v1'});</script>`;
+}
+
+
+// --- Turnkey AI relay (gates the same-origin /_ai/chat route) ---------------
+// Reads the optional `ai` block from manifest.json and the LLM key from .env
+// (server-side only). When the `ai` block is present, the dev server hosts the
+// relay so a chat adapter can POST to `/_ai/chat` with no separate proxy, no
+// CORS, and no key in the browser. No key → MOCK replies (try keyless); add the
+// key for real. The same path is served by managed Manifest hosting in prod.
+const aiConfig = (() => {
+  try { return JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8')).ai || null; }
+  catch { return null; }
+})();
+const aiKey = process.env.ANTHROPIC_API_KEY || privateEnv.ANTHROPIC_API_KEY || '';
+if (publicEnv.PUBLIC_ANTHROPIC_API_KEY) {
+  // The one footgun: a PUBLIC_-prefixed LLM key would ship to every visitor.
+  console.warn('[mnfst-run] ⚠ PUBLIC_ANTHROPIC_API_KEY is injected into the BROWSER and exposes your key to every visitor. Rename it to ANTHROPIC_API_KEY (no PUBLIC_ prefix) — the dev server uses it server-side via /_ai/chat.');
+}
+if (aiConfig) {
+  console.log(`[mnfst-run] AI relay on /_ai/chat — provider=${aiConfig.provider || 'anthropic'} model=${aiConfig.model || 'claude-haiku-4-5'} mode=${aiKey ? 'REAL' : 'MOCK (no ANTHROPIC_API_KEY)'}`);
+}
+
+function aiSse(res, o) { res.write(`event: ${o.type}\ndata: ${JSON.stringify(o)}\n\n`); }
+function streamMockAi(res) {
+  res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+  aiSse(res, { type: 'message_start', message: { id: 'mock', role: 'assistant' } });
+  aiSse(res, { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } });
+  const text = "Here's a **mock** reply from the in-server relay:\n\n- no separate proxy\n- the key stays server-side\n- add `ANTHROPIC_API_KEY` to `.env` for real Claude\n\n```js\nconst turnkey = true;\n```";
+  const chunks = text.match(/\S+\s*/g) || [text];
+  let i = 0;
+  const tick = setInterval(() => {
+    if (i >= chunks.length) { clearInterval(tick); aiSse(res, { type: 'content_block_stop', index: 0 }); aiSse(res, { type: 'message_delta', delta: { stop_reason: 'end_turn' }, usage: { output_tokens: chunks.length } }); aiSse(res, { type: 'message_stop' }); res.end(); return; }
+    aiSse(res, { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: chunks[i++] } });
+  }, 45);
+  res.on('close', () => clearInterval(tick));
+}
+async function streamRealAi(res, payload) {
+  const upstream = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': aiKey, 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify({
+      model: payload.model || aiConfig.model || 'claude-haiku-4-5',
+      max_tokens: payload.max_tokens || aiConfig.maxTokens || 1024,
+      stream: true,
+      system: payload.system || aiConfig.system || undefined,
+      messages: payload.messages || []
+    })
+  });
+  if (!upstream.ok) {
+    const body = await upstream.text();
+    res.writeHead(upstream.status, { 'Content-Type': 'text/event-stream' });
+    aiSse(res, { type: 'error', error: { message: `upstream ${upstream.status}: ${body.slice(0, 300)}` } });
+    return res.end();
+  }
+  res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
+  for await (const chunk of upstream.body) res.write(chunk);   // passthrough — exact Anthropic SSE
+  res.end();
+}
 const publicCount = Object.keys(publicEnv).length;
 if (publicCount > 0) {
   console.log(`Loaded ${publicCount} PUBLIC_ env var(s) into window.env`);
@@ -362,13 +455,26 @@ if (privateEnvNames.length > 0) {
   );
 }
 
-// Dedup: if a server is already serving this exact root, point the user at
-// it (and open the browser, since that's what they were going to do anyway).
+const label = dir === '.' ? basename(process.cwd()) : dir.replace(/\\/g, '/');
+
+// If a server is already serving this exact root, REUSE it — never start a
+// second dev server for the same project.
+//   - manual use: print the URL and exit.
+//   - --attach (supervisor, e.g. Claude Code's preview panel): the panel only
+//     uses a server on the port it assigned us, and can't point at a server it
+//     didn't spawn. So if the existing server is on OUR port, just attach; if
+//     it's on a different port, bind our port and reverse-proxy to it — the
+//     existing server stays the only real dev server (file-watch, live reload),
+//     and the proxy is a thin pass-through the panel can track.
 const existing = await findRunningServer(root);
 if (existing) {
+  if (attachMode) {
+    if (existing.port === port) attachToExisting(existing.port);  // already on our port — just keep alive
+    else startProxy(port, existing.port);                          // bridge our port → the real server
+    await new Promise(() => {});       // block here — never fall through and start a duplicate
+  }
   const url = `http://localhost:${existing.port}`;
-  const label0 = dir === '.' ? basename(process.cwd()) : dir.replace(/\\/g, '/');
-  console.log(`\n${label0} already running at ${url} (pid ${existing.pid})\n`);
+  console.log(`\n${label} already running at ${url} (pid ${existing.pid})\n`);
   // Open the browser anyway — matches the experience of starting fresh.
   // (Skipped under --no-open / Claude Code, where the preview panel is the browser.)
   if (openBrowserEnabled) {
@@ -468,6 +574,297 @@ function isFile(p) {
   try { return statSync(p).isFile(); } catch { return false; }
 }
 
+// Reorder a data file's rows/items to match `order` (array of ids). CSV (tabular,
+// header with an `id` column) or JSON (array of {id}). Ids not in `order` keep their
+// relative order at the end. Returns true if written. Used by /__edit/save (spike).
+function reorderDataFile(file, order) {
+  const ext = extname(file).toLowerCase();
+  const text = readFileSync(file, 'utf8');
+  const ord = (order || []).map(String);
+  if (ext === '.json') {
+    const data = JSON.parse(text);
+    if (!Array.isArray(data)) return false;
+    const byId = new Map(data.map(it => [String(it.id), it]));
+    const next = ord.map(id => byId.get(id)).filter(Boolean);
+    data.forEach(it => { if (!ord.includes(String(it.id))) next.push(it); });
+    writeFileSync(file, JSON.stringify(next, null, 2) + (text.endsWith('\n') ? '\n' : ''));
+    return true;
+  }
+  if (ext === '.csv') {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(/\r?\n/);
+    const trailing = lines.length && lines[lines.length - 1] === '';
+    if (trailing) lines.pop();
+    if (lines.length < 2) return false;
+    const header = lines[0];
+    const idIdx = header.split(',').map(s => s.trim().toLowerCase()).indexOf('id');
+    if (idIdx < 0) return false;
+    const rows = lines.slice(1);
+    const idOf = (r) => (r.split(',')[idIdx] || '').trim();   // id col is simple (unquoted); full row line preserved
+    const byId = new Map(rows.map(r => [idOf(r), r]));
+    const next = ord.map(id => byId.get(id)).filter(Boolean);
+    rows.forEach(r => { if (!ord.includes(idOf(r))) next.push(r); });
+    writeFileSync(file, [header, ...next].join(eol) + (trailing ? eol : ''));
+    return true;
+  }
+  return false;
+}
+
+// Quote-aware CSV line split + cell quoting (so editing an early column doesn't corrupt
+// a later quoted field with commas).
+function parseCsvLine(line) {
+  const out = []; let cur = '', q = false;
+  for (let i = 0; i < line.length; i++) { const ch = line[i]; if (q) { if (ch === '"') { if (line[i + 1] === '"') { cur += '"'; i++; } else q = false; } else cur += ch; } else { if (ch === ',') { out.push(cur); cur = ''; } else if (ch === '"') q = true; else cur += ch; } }
+  out.push(cur); return out;
+}
+const csvCell = (v) => /[",\n]/.test(v) ? '"' + String(v).replace(/"/g, '""') + '"' : String(v);
+// Data-value write-back (local CSV/JSON cell). Cloud sources are not files → caller should
+// persist via $x.<source>.$update(id,{field}) instead.
+function writeDataValue(p, manifest) {
+  const src = (manifest.data || {})[p.source], rel = typeof src === 'string' ? src : null;
+  if (!rel) return { kind: 'data-val', source: p.source, status: 'skipped', reason: 'not a file source (cloud → use $x.$update)' };
+  const file = safeResolve(rel); if (!file || !isFile(file)) return { kind: 'data-val', source: p.source, status: 'error', reason: `file not found: ${rel}` };
+  const ext = extname(file).toLowerCase(), text = readFileSync(file, 'utf8');
+  if (ext === '.json') {
+    const data = JSON.parse(text); if (!Array.isArray(data)) return { kind: 'data-val', source: p.source, status: 'error', reason: 'JSON is not an array' };
+    const rec = data.find(r => String(r.id) === String(p.id)); if (!rec) return { kind: 'data-val', source: p.source, status: 'error', reason: `id ${p.id} not found` };
+    rec[p.field] = p.value; writeFileSync(file, JSON.stringify(data, null, 2) + (text.endsWith('\n') ? '\n' : ''));
+    return { kind: 'data-val', source: p.source, id: p.id, field: p.field, status: 'written', file: basename(file) };
+  }
+  if (ext === '.csv') {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n', lines = text.split(/\r?\n/);
+    const trailing = lines.length && lines[lines.length - 1] === ''; if (trailing) lines.pop();
+    if (lines.length < 2) return { kind: 'data-val', source: p.source, status: 'error', reason: 'empty CSV' };
+    const header = parseCsvLine(lines[0]).map(h => h.trim().toLowerCase());
+    const idIdx = header.indexOf('id'), fIdx = header.indexOf(String(p.field).toLowerCase());
+    if (idIdx < 0 || fIdx < 0) return { kind: 'data-val', source: p.source, status: 'error', reason: `column not found (id/${p.field})` };
+    let hit = false;
+    const rows = lines.slice(1).map(line => { const cells = parseCsvLine(line); if (String(cells[idIdx]).trim() === String(p.id)) { cells[fIdx] = p.value; hit = true; return cells.map(csvCell).join(','); } return line; });
+    if (!hit) return { kind: 'data-val', source: p.source, status: 'error', reason: `id ${p.id} not found` };
+    writeFileSync(file, [lines[0], ...rows].join(eol) + (trailing ? eol : ''));
+    return { kind: 'data-val', source: p.source, id: p.id, field: p.field, status: 'written', file: basename(file) };
+  }
+  return { kind: 'data-val', source: p.source, status: 'error', reason: `unsupported ext ${ext}` };
+}
+
+// --- Dependency-free HTML region editor (spike) ---
+// packages/run is zero-dep by design, so instead of pulling in an HTML parser we do a
+// small tag-aware scan: find the element carrying x-edit="<key>", depth-match its close,
+// and splice. Robust for authored Manifest source (well-formed); not a general parser.
+const escapeReg = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function tagEnd(html, from) {            // from = index of '<'; returns index of the unquoted '>'
+  let q = null;
+  for (let i = from + 1; i < html.length; i++) {
+    const ch = html[i];
+    if (q) { if (ch === q) q = null; }
+    else if (ch === '"' || ch === "'") q = ch;
+    else if (ch === '>') return i;
+  }
+  return -1;
+}
+function matchingClose(html, tag, from) {   // depth-match </tag> accounting for nested same-name tags
+  const re = new RegExp(`<(/?)${escapeReg(tag)}(?=[\\s/>])`, 'gi');
+  re.lastIndex = from;
+  let depth = 1, m;
+  while ((m = re.exec(html))) {
+    if (m[1] === '/') { depth--; if (depth === 0) { const gt = html.indexOf('>', m.index); return { start: m.index, end: gt + 1 }; } }
+    else { const ge = tagEnd(html, m.index); if (ge >= 0) { if (html[ge - 1] !== '/') depth++; re.lastIndex = ge; } }
+  }
+  return null;
+}
+function locateEditEl(html, key) {          // element whose x-edit*-named attr value === key
+  const m = new RegExp(`x-edit[.\\w-]*\\s*=\\s*(?:"${escapeReg(key)}"|'${escapeReg(key)}')`).exec(html);
+  if (!m) return null;
+  const openStart = html.lastIndexOf('<', m.index); if (openStart < 0) return null;
+  const nameM = /^<([a-zA-Z][\w-]*)/.exec(html.slice(openStart)); if (!nameM) return null;
+  const openEnd = tagEnd(html, openStart); if (openEnd < 0) return null;
+  const innerStart = openEnd + 1;
+  const cl = matchingClose(html, nameM[1], innerStart); if (!cl) return null;
+  return { tag: nameM[1], openStart, openEnd, innerStart, innerEnd: cl.start };
+}
+function setAttr(openTag, name, value) {    // replace or insert an attribute in an opening-tag string
+  const val = `"${String(value).replace(/"/g, '&quot;')}"`;
+  const re = new RegExp(`(\\s${escapeReg(name)}\\s*=\\s*)(?:"[^"]*"|'[^']*')`);
+  if (re.test(openTag)) return openTag.replace(re, `$1${val}`);
+  return openTag.replace(/\s*\/?>$/, m => ` ${name}=${val}${m}`);
+}
+// Static per-node ops + reorder — surgical source edits (no whole-innerHTML replacement).
+function navInRegion(html, loc, path) {
+  let node = { innerStart: loc.innerStart, innerEnd: loc.innerEnd };
+  for (const i of path.split('.').map(Number)) { node = childAt(html, node.innerStart, node.innerEnd, i); if (!node) return null; }
+  return node;
+}
+function serverStaticKey(html, child) {   // mirror the client's staticKey (tag + first 24 text chars)
+  const text = html.slice(child.innerStart, child.innerEnd).replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim().slice(0, 24);
+  return child.tag.toUpperCase() + ':' + text;
+}
+function writeStaticOps(file, key, edits, order) {
+  for (const ed of (edits || [])) {                      // re-read+re-locate each (offsets shift after writes)
+    let html = readFileSync(file, 'utf8');
+    const loc = locateEditEl(html, key); if (!loc) return { region: key, status: 'error', reason: `x-edit="${key}" not found in ${basename(file)}` };
+    const node = ed.path === '' ? { tagStart: loc.openStart, openEnd: loc.openEnd, innerStart: loc.innerStart, innerEnd: loc.innerEnd } : navInRegion(html, loc, ed.path);
+    if (!node) continue;
+    const openTag = html.slice(node.tagStart, node.openEnd + 1);
+    if (ed.prop === 'text') html = html.slice(0, node.innerStart) + ed.value + html.slice(node.innerEnd);
+    else if (ed.prop === 'class') html = html.slice(0, node.tagStart) + setAttr(openTag, 'class', ed.value) + html.slice(node.openEnd + 1);
+    else if (ed.prop === 'style') html = html.slice(0, node.tagStart) + setAttr(openTag, 'style', ed.value) + html.slice(node.openEnd + 1);
+    writeFileSync(file, html);
+  }
+  let reordered = false;
+  if (order && order.length) {
+    let html = readFileSync(file, 'utf8'); const loc = locateEditEl(html, key);
+    if (loc) {
+      const kids = []; let n = 0, c;
+      while ((c = childAt(html, loc.innerStart, loc.innerEnd, n++))) kids.push(c);
+      const byKey = {}; kids.forEach(k => { byKey[serverStaticKey(html, k)] = k; });
+      const seq = order.map(k => byKey[k]).filter(Boolean);
+      if (seq.length === kids.length && seq.length) {
+        const reassembled = seq.map(k => html.slice(k.tagStart, k.closeEnd)).join('\n          ');
+        html = html.slice(0, kids[0].tagStart) + reassembled + html.slice(kids[kids.length - 1].closeEnd);
+        writeFileSync(file, html); reordered = true;
+      }
+    }
+  }
+  return { region: key, status: 'written', file: basename(file), edits: (edits || []).length, reordered };
+}
+function writeStaticRegion(file, key, innerHTML, style) {
+  let html = readFileSync(file, 'utf8');
+  const loc = locateEditEl(html, key);
+  if (!loc) return { region: key, status: 'error', reason: `x-edit="${key}" not found in ${basename(file)}` };
+  let openTag = html.slice(loc.openStart, loc.openEnd + 1);
+  if (style) openTag = setAttr(openTag, 'style', style);
+  html = html.slice(0, loc.openStart) + openTag + '\n' + (innerHTML || '') + '\n' + html.slice(loc.innerEnd);
+  writeFileSync(file, html);
+  return { region: key, status: 'written', file: basename(file) };
+}
+// Structural navigation for component-file edits (dependency-free).
+const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const escapeText = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+function childAt(html, from, to, idx) {           // nth element child within [from,to), skipping comments/text
+  let i = from, count = 0;
+  while (i < to) {
+    const lt = html.indexOf('<', i); if (lt < 0 || lt >= to) return null;
+    if (html.startsWith('<!--', lt)) { const e = html.indexOf('-->', lt); i = e < 0 ? to : e + 3; continue; }
+    if (html[lt + 1] === '/') { i = html.indexOf('>', lt) + 1; continue; }
+    const nameM = /^<([a-zA-Z][\w-]*)/.exec(html.slice(lt)); if (!nameM) { i = lt + 1; continue; }
+    const tag = nameM[1], openEnd = tagEnd(html, lt); if (openEnd < 0) return null;
+    const selfClose = html[openEnd - 1] === '/' || VOID_TAGS.has(tag.toLowerCase());
+    let innerStart = openEnd + 1, innerEnd = innerStart, closeEnd = openEnd + 1;
+    if (!selfClose) { const cl = matchingClose(html, tag, innerStart); if (!cl) return null; innerEnd = cl.start; closeEnd = cl.end; }
+    if (count === idx) return { tag, tagStart: lt, openEnd, innerStart, innerEnd, closeEnd };
+    count++; i = closeEnd;
+  }
+  return null;
+}
+function navigateToNode(html, path) {             // path indices are relative to the component's first top-level element ('' = the root itself)
+  let node = childAt(html, 0, html.length, 0); if (!node) return null;
+  if (!path) return node;
+  for (const i of path.split('.').map(Number)) { node = childAt(html, node.innerStart, node.innerEnd, i); if (!node) return null; }
+  return node;
+}
+function resolveComponentFile(manifest, name) {
+  const all = [...(manifest.preloadedComponents || []), ...(manifest.components || [])];
+  return all.find(p => String(p).split('/').pop().replace('.html', '') === name) || null;
+}
+
+// Theme var write: rewrite (or append) a single `--var: value;` in the target CSS file.
+// Scoped vars carry their file (data-edit-theme-file); global vars fall back to the
+// standard theme file. Surgical — rewrites the existing declaration in place, else
+// appends into the first :root{} block, else creates one.
+const DEFAULT_THEME_FILE = 'styles/core/manifest.theme.css';
+function writeThemeVar(p) {
+  if (!/^--[\w-]+$/.test(p.var || '')) return { region: p.var, status: 'error', reason: 'bad var name' };
+  const rel = (p.file || DEFAULT_THEME_FILE).replace(/^\//, '');
+  const file = safeResolve('/' + rel);
+  if (!file) return { region: p.var, status: 'error', reason: `path outside root: ${rel}` };
+  let css = isFile(file) ? readFileSync(file, 'utf8') : '';
+  const decl = `${p.var}: ${p.value};`;
+  const declRe = new RegExp(`(${escapeReg(p.var)}\\s*:)[^;]*;`);
+  if (declRe.test(css)) css = css.replace(declRe, `$1 ${p.value};`);              // rewrite in place
+  else if (/:root\s*[^{]*\{/.test(css)) css = css.replace(/(:root\s*[^{]*\{)/, `$1\n    ${decl}`);   // append into :root
+  else css = `:root {\n    ${decl}\n}\n${css}`;                                    // create :root
+  writeFileSync(file, css);
+  return { region: `${p.scope ? p.scope + ':' : ''}${p.var}`, status: 'written', file: rel };
+}
+const modParamIn = (openTag, attr) => { const m = openTag.match(new RegExp(escapeReg(attr) + `\\s*=\\s*("[^"]*"|'[^']*')`)); if (!m) return null; const mm = m[1].slice(1, -1).match(/\$modify\(['"]([\w-]+)['"]\)/); return mm ? mm[1] : null; };
+const allModifyParams = (html) => { const s = new Set(); let m; const re = /\$modify\(['"]([\w-]+)['"]\)/g; while ((m = re.exec(html))) s.add(m[1]); return [...s]; };
+const removeAttr = (openTag, name) => openTag.replace(new RegExp(`\\s${escapeReg(name)}\\s*=\\s*(?:"[^"]*"|'[^']*')`, 'g'), '');
+const classOf = (openTag) => { const m = openTag.match(/\sclass\s*=\s*("[^"]*"|'[^']*')/); return m ? m[1].slice(1, -1) : ''; };
+
+// Component edits, per node (structural path), per prop (text|class), routed by scope.
+//   main     → edit the component source literal/class (affects every instance)
+//   instance → set the $modify instance attr; AUTO-PROMOTE a plain node first
+//              (text → x-text="$modify('p_…') ?? 'orig'"; class → :class="$modify('c_…') ?? 'orig'")
+//   reverts  → remove the instance's $modify attrs so it falls back to the component default
+function writeComponentEdits(p, manifest) {
+  const compRel = resolveComponentFile(manifest, p.component);
+  if (!compRel) return { region: p.region, status: 'error', reason: `component '${p.component}' not registered` };
+  const compFile = safeResolve(compRel);
+  if (!compFile || !isFile(compFile)) return { region: p.region, status: 'error', reason: `component file not found: ${compRel}` };
+  const indexFile = join(root, 'index.html'), instanceAttrs = {}, removeNames = new Set(), applied = [];
+  for (const ed of (p.edits || [])) {
+    const prop = ed.prop || 'text';
+    let html = readFileSync(compFile, 'utf8');
+    const node = navigateToNode(html, ed.path);
+    if (!node) { applied.push({ path: ed.path, status: 'not-found' }); continue; }
+    let openTag = html.slice(node.tagStart, node.openEnd + 1);
+    const seg = ed.path === '' ? 'root' : ed.path.replace(/\./g, '_');
+
+    if (prop === 'class') {
+      const param = modParamIn(openTag, ':class');
+      if (p.scope === 'main') { writeFileSync(compFile, html.slice(0, node.tagStart) + setAttr(openTag, 'class', ed.value) + html.slice(node.openEnd + 1)); applied.push({ path: ed.path, prop, status: 'main' }); }
+      else if (param) { instanceAttrs[param] = ed.value; applied.push({ path: ed.path, prop, status: 'instance', param }); }
+      else { const name = 'c_' + seg; writeFileSync(compFile, html.slice(0, node.tagStart) + setAttr(openTag, ':class', `$modify('${name}') ?? '${classOf(openTag).replace(/'/g, "\\'")}'`) + html.slice(node.openEnd + 1)); instanceAttrs[name] = ed.value; applied.push({ path: ed.path, prop, status: 'promoted', param: name }); }
+      continue;
+    }
+
+    // text — value is innerHTML; may contain nested elements (<i>/<br>), bound via x-html.
+    const hasMarkup = /<[a-z!\/][\s\S]*>/i.test(ed.value);
+    const param = modParamIn(openTag, 'x-html') || modParamIn(openTag, 'x-text');
+    if (p.scope === 'main') {
+      if (param) writeFileSync(compFile, html.slice(0, node.tagStart) + openTag.replace(/((?:\?\?|\|\|)\s*)(['"]).*?\2/, `$1'${ed.value.replace(/'/g, "\\'")}'`) + html.slice(node.openEnd + 1));
+      else writeFileSync(compFile, html.slice(0, node.innerStart) + ed.value + html.slice(node.innerEnd));   // raw HTML literal
+      applied.push({ path: ed.path, prop, status: 'main' });
+    } else if (param) {
+      if (hasMarkup && /\sx-text\s*=/.test(openTag) && !/\sx-html\s*=/.test(openTag)) { writeFileSync(compFile, html.slice(0, node.tagStart) + openTag.replace(/\sx-text(\s*=)/, ' x-html$1') + html.slice(node.openEnd + 1)); }
+      instanceAttrs[param] = ed.value; applied.push({ path: ed.path, prop, status: 'instance', param });
+    } else {                                        // PROMOTE: x-html if rich, else x-text
+      const name = 'p_' + seg, bind = hasMarkup ? 'x-html' : 'x-text';
+      const orig = html.slice(node.innerStart, node.innerEnd).trim().replace(/'/g, "\\'");
+      writeFileSync(compFile, html.slice(0, node.tagStart) + setAttr(openTag, bind, `$modify('${name}') ?? '${orig}'`) + html.slice(node.openEnd + 1));
+      instanceAttrs[name] = ed.value; applied.push({ path: ed.path, prop, status: 'promoted', param: name, bind });
+    }
+  }
+  if (p.scope === 'instance' && (p.reverts || []).length) {
+    const html = readFileSync(compFile, 'utf8');
+    for (const rp of p.reverts) {
+      if (rp === '*') { allModifyParams(html).forEach(n => removeNames.add(n)); applied.push({ path: '*', status: 'revert-all' }); continue; }
+      const node = navigateToNode(html, rp); if (!node) continue;
+      const openTag = html.slice(node.tagStart, node.openEnd + 1);
+      [modParamIn(openTag, 'x-text'), modParamIn(openTag, 'x-html'), modParamIn(openTag, ':class')].forEach(n => { if (n) removeNames.add(n); });
+      applied.push({ path: rp, status: 'reverted' });
+    }
+  }
+  const inst = (Object.keys(instanceAttrs).length || removeNames.size) ? writeComponentInstance(indexFile, p.region, instanceAttrs, [...removeNames]) : null;
+  return { region: p.region, status: 'written', scope: p.scope, file: basename(compFile), applied, instance: inst && inst.status };
+}
+function writeComponentInstance(file, key, overrides, removals) {
+  let html = readFileSync(file, 'utf8');
+  const loc = locateEditEl(html, key);
+  if (!loc) return { region: key, status: 'error', reason: `x-edit="${key}" not found in ${basename(file)}` };
+  const inner = html.slice(loc.innerStart, loc.innerEnd);
+  const cm = /<x-[\w-]+/.exec(inner);   // first component instance in the region
+  if (!cm) return { region: key, status: 'error', reason: 'no <x-*> instance in region' };
+  const instStart = loc.innerStart + cm.index, instEnd = tagEnd(html, instStart);
+  if (instEnd < 0) return { region: key, status: 'error', reason: 'malformed instance tag' };
+  let openTag = html.slice(instStart, instEnd + 1);
+  for (const [k, v] of Object.entries(overrides || {})) openTag = setAttr(openTag, k, v);
+  for (const name of (removals || [])) openTag = removeAttr(openTag, name);
+  html = html.slice(0, instStart) + openTag + html.slice(instEnd + 1);
+  writeFileSync(file, html);
+  return { region: key, status: 'written', file: basename(file), applied: Object.keys(overrides || {}), removed: removals || [] };
+}
+
 // Resolve a request path against `root` and refuse anything that escapes.
 // `path.join` does NOT prevent `..` traversal — `join('/a/b', '/../../etc/passwd')`
 // returns `/etc/passwd`. Use `path.resolve` + an explicit prefix check.
@@ -542,6 +939,75 @@ function isLocalOrigin(origin, port) {
 }
 
 // --- HTTP server ---
+// --- Appwrite dev proxy (see APPWRITE_PROXY_TARGET above) ---
+
+// Rewrite upstream Set-Cookie so the session cookie is storable + sent on
+// http://localhost: drop Domain (defaults to our host), drop Secure (we're http),
+// and downgrade SameSite=None → Lax (None requires Secure, which we just removed).
+function rewriteAppwriteSetCookie(values) {
+  return (Array.isArray(values) ? values : [values]).map(v => v
+    .replace(/;\s*Domain=[^;]*/ig, '')
+    .replace(/;\s*Secure\b/ig, '')
+    .replace(/;\s*SameSite=None/ig, '; SameSite=Lax'));
+}
+
+// /_appwrite/v1/account?x → /v1/account?x  (strip our prefix, keep path + query)
+function appwriteUpstreamPath(reqUrl, urlPath) {
+  const search = reqUrl.includes('?') ? reqUrl.slice(reqUrl.indexOf('?')) : '';
+  return urlPath.slice(APPWRITE_PROXY_PREFIX.length) + search;
+}
+
+function proxyAppwriteHttp(req, res, urlPath) {
+  let u;
+  try { u = new URL(APPWRITE_PROXY_TARGET); } catch { res.writeHead(502); res.end('bad APPWRITE_PROXY_TARGET'); return; }
+  const headers = { ...req.headers, host: u.host };
+  delete headers.connection;
+  // Force cookie-only auth. Appwrite emits X-Fallback-Cookies (because the
+  // forwarded Origin looks cross-origin) and the SDK then replays it on every
+  // request — but the Presences endpoint REJECTS any request carrying the
+  // fallback, even with a valid session cookie present. Strip it both ways so
+  // the real first-party cookie (which the proxy makes same-origin) is used.
+  delete headers['x-fallback-cookies'];
+  const transport = u.protocol === 'https:' ? httpsRequest : httpRequest;
+  const upstream = transport({
+    protocol: u.protocol, hostname: u.hostname,
+    port: u.port || (u.protocol === 'https:' ? 443 : 80),
+    method: req.method, path: appwriteUpstreamPath(req.url, urlPath), headers,
+  }, (up) => {
+    const outHeaders = { ...up.headers };
+    delete outHeaders.connection; delete outHeaders['transfer-encoding'];
+    delete outHeaders['x-fallback-cookies']; // keep the SDK out of localStorage-fallback mode
+    if (up.headers['set-cookie']) outHeaders['set-cookie'] = rewriteAppwriteSetCookie(up.headers['set-cookie']);
+    res.writeHead(up.statusCode || 502, outHeaders);
+    up.pipe(res);
+  });
+  upstream.on('error', (e) => { try { res.writeHead(502, { 'Content-Type': 'text/plain' }); res.end('appwrite proxy error: ' + e.message); } catch { /* client gone */ } });
+  req.pipe(upstream);
+}
+
+// Raw WebSocket tunnel for Appwrite Realtime (wss). Replays the HTTP upgrade over
+// a TLS socket to the upstream and pipes both ways; the browser's first-party
+// localhost cookie rides the upgrade headers, so realtime auth works too.
+function proxyAppwriteWs(req, socket, head, urlPath) {
+  let u;
+  try { u = new URL(APPWRITE_PROXY_TARGET); } catch { socket.destroy(); return; }
+  const upstream = tlsConnect({ host: u.hostname, port: u.port || 443, servername: u.hostname }, () => {
+    const headers = { ...req.headers, host: u.host };
+    delete headers['x-fallback-cookies']; // cookie-only auth (see HTTP proxy)
+    let handshake = `${req.method} ${appwriteUpstreamPath(req.url, urlPath)} HTTP/1.1\r\n`;
+    for (const [k, v] of Object.entries(headers)) {
+      (Array.isArray(v) ? v : [v]).forEach(val => { handshake += `${k}: ${val}\r\n`; });
+    }
+    handshake += '\r\n';
+    upstream.write(handshake);
+    if (head && head.length) upstream.write(head);
+    upstream.pipe(socket);
+    socket.pipe(upstream);
+  });
+  upstream.on('error', () => socket.destroy());
+  socket.on('error', () => upstream.destroy());
+}
+
 const server = createServer((req, res) => {
   const urlPath = decodeURIComponent(req.url.split('?')[0]);
 
@@ -555,6 +1021,13 @@ const server = createServer((req, res) => {
     return;
   }
 
+  // Appwrite dev proxy — forward to the configured Appwrite origin so the
+  // session cookie is first-party (see APPWRITE_PROXY_TARGET).
+  if (APPWRITE_PROXY_TARGET && urlPath.startsWith(APPWRITE_PROXY_PREFIX + '/')) {
+    proxyAppwriteHttp(req, res, urlPath);
+    return;
+  }
+
   // Identity endpoint: lets `mnfst-run` (and `--list`) confirm that a server
   // on a registered port really is OUR server for the expected root, not
   // some unrelated process that happened to inherit a recycled PID/port.
@@ -628,6 +1101,60 @@ const server = createServer((req, res) => {
     return;
   }
 
+  // Edit-plugin B-side write-back (SPIKE, dev-only). POST + same-origin. Currently
+  // handles the `data` regime: reorder the source CSV/JSON for a registered data
+  // source. static/component regimes are reported unsupported (need an HTML parser).
+  // Turnkey AI relay — same-origin chat proxy; key held server-side, never in
+  // the browser. Inert (404) unless manifest.json has an `ai` block. No key →
+  // mock stream so keyless dev works; add ANTHROPIC_API_KEY to .env for real.
+  if (urlPath === '/_ai/chat') {
+    if (!aiConfig) { res.writeHead(404); res.end(); return; }
+    if (req.method !== 'POST') { res.writeHead(405, { 'Allow': 'POST' }); res.end(); return; }
+    if (listenPort && !isLocalOrigin(req.headers.origin, listenPort)) { res.writeHead(403); res.end(); return; }
+    let raw = '';
+    req.on('data', c => { raw += c; if (raw.length > 25e6) req.destroy(); });   // 25MB cap (attachments)
+    req.on('end', async () => {
+      let payload = {}; try { payload = raw ? JSON.parse(raw) : {}; } catch { res.writeHead(400); res.end('bad json'); return; }
+      try { if (aiKey) await streamRealAi(res, payload); else streamMockAi(res); }
+      catch (e) { try { res.writeHead(500); res.end(String(e && e.message || e)); } catch (_) {} }
+    });
+    return;
+  }
+
+  if (urlPath === '/__edit/save') {
+    if (!EDIT_ENABLED) { res.writeHead(404); res.end(); return; }   // opt-in (--edit / MNFST_EDIT=1): source write-back is authoring-only
+    if (req.method !== 'POST') { res.writeHead(405, { 'Allow': 'POST' }); res.end(); return; }
+    if (listenPort && !isLocalOrigin(req.headers.origin, listenPort)) { res.writeHead(403); res.end(); return; }
+    let raw = '';
+    req.on('data', c => { raw += c; if (raw.length > 1e6) req.destroy(); });
+    req.on('end', () => {
+      let patches; try { patches = JSON.parse(raw); } catch { res.writeHead(400); res.end('bad json'); return; }
+      if (!Array.isArray(patches)) patches = [patches];
+      let manifest = {}; try { manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8')); } catch {}
+      const indexFile = join(root, 'index.html');
+      const results = patches.map(p => {
+        try {
+          if (p.kind === 'data') {
+            const src = (manifest.data || {})[p.source];
+            const rel = typeof src === 'string' ? src : null;
+            if (!rel) return { region: p.region, status: 'error', reason: `data source '${p.source}' is not a plain file path` };
+            const file = safeResolve(rel);
+            if (!file || !isFile(file)) return { region: p.region, status: 'error', reason: `file not found: ${rel}` };
+            return { region: p.region, status: reorderDataFile(file, p.order) ? 'written' : 'noop', file: rel };
+          }
+          if (p.kind === 'data-val') return writeDataValue(p, manifest);
+          if (p.kind === 'static') return writeStaticOps(indexFile, p.region, p.edits, p.order);
+          if (p.kind === 'component') return writeComponentEdits(p, manifest);
+          if (p.kind === 'theme') return writeThemeVar(p);
+          return { region: p.region, status: 'skipped', reason: `unknown kind ${p.kind}` };
+        } catch (e) { return { region: p.region, status: 'error', reason: e.message }; }
+      });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ results }));
+    });
+    return;
+  }
+
   const exact = safeResolve(urlPath);
   if (exact && isFile(exact)) return serveFile(res, exact);
 
@@ -644,8 +1171,7 @@ const server = createServer((req, res) => {
 });
 
 // --- Auto-port ---
-// Human-readable label: the dir arg as given, or the cwd folder name if serving '.'
-const label = dir === '.' ? basename(process.cwd()) : dir.replace(/\\/g, '/');
+// (`label` is defined earlier, before the reuse/dedup check.)
 
 function openBrowser(url) {
   const cmd = process.platform === 'win32' ? `start ${url}`
@@ -654,6 +1180,82 @@ function openBrowser(url) {
   exec(cmd);
 }
 
+// Whether THIS process owns the running-server registry entry for `root`.
+// Stays false in --attach mode (we never claim the entry), so the exit handler
+// can't delete an entry belonging to the user's own server for the same root.
+let weOwnServer = false;
+
+// --attach: the requested port is already serving this root. Stay in the
+// foreground so the supervising preview panel keeps tracking this process,
+// without owning the server — never touch its registry; just re-probe and exit
+// once it goes away.
+function attachToExisting(p) {
+  const url = `http://localhost:${p}`;
+  console.log(`\n${label} already running at ${url} — attached.\n`);
+  if (openBrowserEnabled) openBrowser(url);
+  watchUpstream(p);
+}
+
+// Exit once the server we're bridging/attached to goes away — we're only a
+// pass-through, so there's nothing to serve without it.
+function watchUpstream(upstreamPort) {
+  setInterval(async () => {
+    const id = await probeIdentity(upstreamPort);
+    if (!id || id.root !== root) {
+      console.log('\nmnfst-run: the server it was bridging has stopped — exiting.\n');
+      process.exit(0);
+    }
+  }, 5000);
+}
+
+// --attach: a real dev server for this root is already running on `upstreamPort`,
+// but the preview panel can only use a server on the port it assigned us
+// (`listenPort`). Bind that port and transparently reverse-proxy every request
+// to the real server — including the live-reload SSE stream — so the existing
+// server stays the ONE dev server and the panel still works. We don't own a
+// server, so we never touch the registry.
+function startProxy(listenPort, upstreamPort) {
+  const proxy = createServer((creq, cres) => {
+    // Rewrite host/origin to the upstream so its loopback host + same-origin
+    // checks pass (the client speaks to us on listenPort, the server on upstream).
+    const headers = { ...creq.headers, host: `localhost:${upstreamPort}` };
+    if (headers.origin) headers.origin = `http://localhost:${upstreamPort}`;
+    if (headers.referer) {
+      headers.referer = headers.referer.split(`localhost:${listenPort}`).join(`localhost:${upstreamPort}`);
+    }
+    const preq = httpRequest(
+      { host: '127.0.0.1', port: upstreamPort, method: creq.method, path: creq.url, headers },
+      (pres) => {
+        cres.writeHead(pres.statusCode || 502, pres.headers);
+        pres.pipe(cres);   // stream — keeps SSE (text/event-stream) flowing live
+      },
+    );
+    preq.on('error', () => { try { cres.writeHead(502); cres.end('mnfst-run proxy: upstream unavailable'); } catch { /* client gone */ } });
+    creq.pipe(preq);
+  });
+  proxy.on('error', (err) => {
+    console.error(`mnfst-run: could not bind proxy port ${listenPort}: ${err.code || err.message}`);
+    process.exit(1);
+  });
+  proxy.listen(listenPort, '127.0.0.1', () => {
+    console.log(
+      `\n${label} already running at http://localhost:${upstreamPort} — ` +
+      `bridged to http://localhost:${listenPort} for the preview panel.\n`,
+    );
+  });
+  watchUpstream(upstreamPort);
+}
+
+// Appwrite Realtime (WebSocket) proxy — same first-party-cookie rationale as the
+// HTTP proxy. Without it, switching the endpoint to the proxy would break realtime.
+if (APPWRITE_PROXY_TARGET) {
+  server.on('upgrade', (req, socket, head) => {
+    const p = (req.url || '').split('?')[0];
+    if (p.startsWith(APPWRITE_PROXY_PREFIX + '/')) proxyAppwriteWs(req, socket, head, p);
+    else socket.destroy();
+  });
+}
+
 function tryListen(p, attempt = 0) {
   if (attempt > 20) {
     console.error('mnfst-run: could not find a free port after 20 attempts.');
@@ -667,14 +1269,28 @@ function tryListen(p, attempt = 0) {
   const onListening = () => {
     server.removeListener('error', onError);
     const url = `http://localhost:${p}`;
+    // A successful fresh bind means WE are the server for this root — register it
+    // (so a later manual `mnfst-run` for the same project reuses it instead of
+    // starting another). In --attach we only reach here when nothing was already
+    // running, so there's no entry to clobber.
     writeRegistry(root, p);
+    weOwnServer = true;
     console.log(`\n${label} running at ${url}\n`);
     if (openBrowserEnabled) openBrowser(url);
   };
   const onError = err => {
     server.removeListener('listening', onListening);
-    if (err.code === 'EADDRINUSE') tryListen(p + 1, attempt + 1);
-    else throw err;
+    if (err.code !== 'EADDRINUSE') { throw err; }
+    // Under --attach, if the requested port is already OUR project, attach to it
+    // (stay alive) rather than spawn a duplicate on the next port up.
+    if (attachMode && attempt === 0) {
+      probeIdentity(p).then((id) => {
+        if (id && id.root === root) attachToExisting(p);
+        else tryListen(p + 1, attempt + 1);
+      });
+      return;
+    }
+    tryListen(p + 1, attempt + 1);
   };
   server.once('listening', onListening);
   server.once('error', onError);
@@ -684,10 +1300,11 @@ function tryListen(p, attempt = 0) {
   server.listen(p, '127.0.0.1');
 }
 
-// Clean up the registry entry on graceful exit. process.exit() (used by
-// idle-shutdown) fires 'exit'; SIGINT/SIGTERM are translated into a
-// process.exit so the same path runs for Ctrl+C and `kill <pid>`.
-process.on('exit', () => removeRegistry(root));
+// Clean up the registry entry on graceful exit — but only if we actually own it
+// (never in --attach mode, where the entry may belong to the user's server).
+// process.exit() (used by idle-shutdown) fires 'exit'; SIGINT/SIGTERM are
+// translated into a process.exit so the same path runs for Ctrl+C and `kill`.
+process.on('exit', () => { if (weOwnServer) removeRegistry(root); });
 process.on('SIGINT',  () => process.exit(0));
 process.on('SIGTERM', () => process.exit(0));