@myrtilleio/redline 0.1.0

package/src/store.js

@@ -0,0 +1,544 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { createHash, randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { formatMarkdown } from './format.js';
+import { combineChecks, diffFingerprints } from './guards.js';
+import { renderTaste, tasteEntry } from './taste.js';
+
+const VERDICTS = new Set(['good', 'fix', 'idea']);
+const MAX_POINTS = 4000;
+
+function str(v, max) {
+  return typeof v === 'string' ? v.slice(0, max) : undefined;
+}
+
+function num(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function rect(r) {
+  return r && typeof r === 'object' ? { x: num(r.x), y: num(r.y), w: num(r.w), h: num(r.h) } : undefined;
+}
+
+function target(t) {
+  if (!t || typeof t !== 'object' || typeof t.selector !== 'string') return undefined;
+  const styles = {};
+  if (t.styles && typeof t.styles === 'object') {
+    for (const [k, v] of Object.entries(t.styles).slice(0, 20)) if (typeof v === 'string') styles[k.slice(0, 40)] = v.slice(0, 200);
+  }
+  return {
+    selector: t.selector.slice(0, 500),
+    html: str(t.html, 300),
+    text: str(t.text, 200),
+    rect: rect(t.rect),
+    styles,
+  };
+}
+
+function paths(list) {
+  if (!Array.isArray(list)) return undefined;
+  let budget = MAX_POINTS;
+  return list
+    .filter(Array.isArray)
+    .slice(0, 20)
+    .map((path) => {
+      const kept = path.slice(0, Math.max(budget, 0)).map((p) => [num(p && p[0]), num(p && p[1])]);
+      budget -= kept.length;
+      return kept;
+    });
+}
+
+function stroke(s) {
+  if (!s || !Array.isArray(s.paths)) return undefined;
+  return {
+    paths: paths(s.paths), // page coordinates
+    local: paths(s.local), // relative to the target's top-left, so the mark follows it through layout changes
+    width: Math.min(Math.max(num(s.width) || 4, 1), 40),
+  };
+}
+
+const CSS_PROP = /^-?[a-z][a-z-]{1,40}$/;
+
+// A live edit the reviewer made on the page: exact before → after values.
+function edits(e) {
+  if (!e || typeof e !== 'object') return undefined;
+  const props = (Array.isArray(e.props) ? e.props : [])
+    .filter((p) => p && CSS_PROP.test(p.prop) && typeof p.to === 'string')
+    .slice(0, 30)
+    .map((p) => ({ prop: p.prop, from: str(p.from, 200) || '', to: p.to.slice(0, 200) }));
+  const text = e.text && typeof e.text.to === 'string' ? { from: str(e.text.from, 2000) || '', to: e.text.to.slice(0, 2000) } : undefined;
+  if (!props.length && !text) return undefined;
+  return { scope: e.scope === 'all' ? 'all' : 'element', selector: str(e.selector, 500), props, text };
+}
+
+const ASSET_PATH = /^(assets|shots)\/[\w.-]{1,80}$/;
+
+function references(list) {
+  if (!Array.isArray(list)) return undefined;
+  const out = list
+    .filter((r) => r && ASSET_PATH.test(r.path))
+    .slice(0, 6)
+    .map((r) => ({ path: r.path, name: str(r.name, 120) || '' }));
+  return out.length ? out : undefined;
+}
+
+// Page state to restore before a screenshot: which controls to switch on/off.
+function replay(list) {
+  if (!Array.isArray(list)) return undefined;
+  return list
+    .filter((r) => r && typeof r.selector === 'string' && typeof r.state === 'string')
+    .slice(0, 8)
+    .map((r) => ({ selector: r.selector.slice(0, 500), state: r.state.slice(0, 20) }));
+}
+
+/** Keep only known fields, with size limits, from client-supplied input. */
+function clean(input, existing) {
+  const a = { ...(existing || {}) };
+  if (input.kind === 'note' || input.kind === 'stroke') a.kind = input.kind;
+  if (VERDICTS.has(input.verdict)) a.verdict = input.verdict;
+  if (typeof input.comment === 'string') a.comment = input.comment.slice(0, 5000);
+  if (Array.isArray(input.tags)) a.tags = input.tags.filter((t) => typeof t === 'string').slice(0, 12).map((t) => t.slice(0, 40));
+  if (typeof input.page === 'string') a.page = input.page.slice(0, 500);
+  if ('target' in input) a.target = target(input.target);
+  if (Array.isArray(input.covers)) a.covers = input.covers.map(target).filter(Boolean).slice(0, 6);
+  if ('stroke' in input) a.stroke = stroke(input.stroke);
+  // A drawn box: an area of the target, in px from its top-left (scaled with it later).
+  if ('region' in input) a.region = input.region && typeof input.region === 'object' ? { x: num(input.region.x), y: num(input.region.y), w: num(input.region.w), h: num(input.region.h) } : undefined;
+  if (input.anchor && typeof input.anchor === 'object') a.anchor = { dx: num(input.anchor.dx), dy: num(input.anchor.dy) };
+  if (input.viewport) a.viewport = { w: num(input.viewport.w), h: num(input.viewport.h) };
+  if (Array.isArray(input.uiState)) a.uiState = input.uiState.filter((t) => typeof t === 'string').slice(0, 8).map((t) => t.slice(0, 80));
+  if (typeof input.quote === 'string') a.quote = input.quote.slice(0, 300);
+  if (typeof input.url === 'string') a.url = input.url.slice(0, 500);
+  if ('edits' in input) a.edits = edits(input.edits);
+  // Which section of the page the mark is in (captured by the overlay).
+  if (input.section && typeof input.section === 'object' && typeof input.section.selector === 'string') {
+    a.section = { selector: input.section.selector.slice(0, 500), heading: str(input.section.heading, 120) || '' };
+  }
+  // A reply from the reviewer, appended to the conversation.
+  if (typeof input.reply === 'string' && input.reply.trim()) {
+    a.thread = [...(a.thread || []), { by: 'you', text: input.reply.trim().slice(0, 5000), at: new Date().toISOString() }];
+  }
+  if ('arrow' in input) a.arrow = input.arrow && target(input.arrow.from) && target(input.arrow.to) ? { from: target(input.arrow.from), to: target(input.arrow.to) } : undefined;
+  if ('references' in input) a.references = references(input.references);
+  if (Array.isArray(input.uiReplay)) a.uiReplay = replay(input.uiReplay);
+  if (input.request && typeof input.request === 'object') {
+    const n = Math.round(num(input.request.variants));
+    a.request = n >= 2 && n <= 5 ? { variants: n } : undefined;
+  } else if (input.request === null) a.request = undefined;
+  if ('chosen' in input) a.chosen = typeof input.chosen === 'string' && /^[A-E]$/.test(input.chosen) ? input.chosen : undefined;
+  if (input.status === 'open' || input.status === 'resolved') a.status = input.status;
+  // Turn-taking: a mark is a draft until sent; the reviewer accepts a fix, or redoes it.
+  if (typeof input.draft === 'boolean') input.draft ? (a.draft = true) : delete a.draft;
+  if (typeof input.accepted === 'boolean') input.accepted ? (a.accepted = true) : delete a.accepted;
+  if (typeof input.resolution === 'string') a.resolution = input.resolution.slice(0, 2000);
+  if ('afterTarget' in input) a.afterTarget = typeof input.afterTarget === 'string' && input.afterTarget ? input.afterTarget.slice(0, 500) : undefined;
+  return a;
+}
+
+// Forget a guard so a new baseline is taken (the look that's approved now).
+function dropGuard(a) {
+  delete a.guard;
+  if (a.shotSigs) for (const k of Object.keys(a.shotSigs)) if (k.startsWith('guard-')) delete a.shotSigs[k];
+}
+
+export class Store {
+  constructor(dir) {
+    this.dir = dir;
+    this.file = join(dir, 'feedback.json');
+    this.briefFile = join(dir, 'FEEDBACK.md');
+    this.queue = Promise.resolve();
+    this.roundsQueue = Promise.resolve();
+    this.tasteQueue = Promise.resolve();
+  }
+
+  async all() {
+    try {
+      const data = JSON.parse(await readFile(this.file, 'utf8'));
+      return Array.isArray(data.annotations) ? data.annotations : [];
+    } catch (err) {
+      if (err.code === 'ENOENT') return [];
+      throw err;
+    }
+  }
+
+  async list(page) {
+    const all = await this.all();
+    return page ? all.filter((a) => a.page === page) : all;
+  }
+
+  async get(id) {
+    return (await this.all()).find((a) => a.id === id);
+  }
+
+  // Serialize read-modify-write cycles so concurrent requests can't drop edits.
+  mutate(fn) {
+    const run = this.queue.then(async () => {
+      const list = await this.all();
+      const result = await fn(list);
+      await this.write(list);
+      return result;
+    });
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  async write(list) {
+    await mkdir(this.dir, { recursive: true });
+    const tmp = `${this.file}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify({ version: 1, annotations: list }, null, 2) + '\n');
+    await rename(tmp, this.file);
+    await writeFile(this.briefFile, formatMarkdown(list, { cli: true, rounds: (await this.rounds()).rounds, taste: await this.taste() }));
+  }
+
+  create(input) {
+    return this.mutate((list) => {
+      const now = new Date().toISOString();
+      const a = clean(input);
+      a.id = 'a_' + randomBytes(4).toString('hex');
+      // Undoing a delete restores the item under its old number, if that's still free.
+      const wanted = Number.isInteger(input.n) && input.n > 0 && !list.some((x) => x.n === input.n);
+      a.n = wanted ? input.n : list.reduce((m, x) => Math.max(m, x.n || 0), 0) + 1;
+      a.kind ||= 'note';
+      a.verdict ||= 'idea';
+      a.page ||= '/';
+      a.comment ||= '';
+      a.status = 'open';
+      a.createdAt = now;
+      a.updatedAt = now;
+      list.push(a);
+      return a;
+    });
+  }
+
+  async update(id, patch) {
+    const judgments = [];
+    const a = await this.mutate((list) => {
+      const i = list.findIndex((a) => a.id === id);
+      if (i < 0) return undefined;
+      const prev = list[i];
+      const a = clean(patch, prev);
+      // Reopening keeps what was already tried, so the agent doesn't repeat it.
+      if (patch.status === 'open' && prev.status === 'resolved') {
+        if (prev.resolution) a.history = [...(prev.history || []), prev.resolution];
+        delete a.resolution;
+        delete a.accepted;
+      }
+      // The reviewer's judgments: each one is remembered (the taste ledger), and
+      // counted for the round the item was sent in (first-pass accept rate).
+      const reply = typeof patch.reply === 'string' ? patch.reply.trim() : '';
+      if (patch.sendBack === true) {
+        // An approval that changed goes back to the agent as a keep: restore it.
+        judgments.push(tasteEntry('sent-back', prev, { diff: prev.guard && prev.guard.now && prev.guard.now.diff }));
+        // With the agent now: it stops asking for a check until the next round's guard run.
+        if (a.guard) a.guard = { ...a.guard, sentBack: true };
+      } else if (patch.accepted === true && !prev.accepted) {
+        judgments.push(tasteEntry('accepted', prev));
+        // An accepted fix is guarded as it looks now; a keep stays guarded as first approved.
+        if (prev.verdict !== 'good') dropGuard(a);
+      } else if (patch.status === 'open' && prev.status === 'resolved' && patch.draft === true) {
+        judgments.push(tasteEntry('redo', prev, { reply }));
+      }
+      if (patch.rebaseline === true && a.guard) {
+        judgments.push(tasteEntry('new-look', prev, { diff: a.guard.now && a.guard.now.diff }));
+        dropGuard(a);
+      }
+      // Gone from the page on purpose: stop guarding it.
+      if (patch.unguard === true) a.guard = { off: true, at: new Date().toISOString() };
+      // Live content (a feed, a date, a carousel): from now on, watch its look, not its words and images.
+      if (patch.dynamic === true) {
+        a.guardIgnore = ['text'];
+        dropGuard(a);
+      }
+      a.updatedAt = new Date().toISOString();
+      list[i] = a;
+      return a;
+    });
+    if (a && judgments.length) {
+      // Counted first, so TASTE.md (rendered when the judgment is remembered) has the new rate.
+      for (const j of judgments) if ((j.kind === 'accepted' || j.kind === 'redo') && a.round) await this.tally(a.round, j.kind);
+      await this.remember(judgments);
+    }
+    return a;
+  }
+
+  /** `target`: a selector for the "after" screenshot when the fix restructured the markup. */
+  async resolve(id, note, target) {
+    const a = await this.update(id, { status: 'resolved', resolution: note || '', afterTarget: target || null });
+    if (a && note) return this.agentSays(id, note, 'resolved');
+    return a;
+  }
+
+  /** The agent answers in an item's conversation. */
+  agentSays(id, text, tag) {
+    return this.mutate((list) => {
+      const a = list.find((x) => x.id === id || String(x.n) === String(id).replace(/^#/, ''));
+      if (!a) throw Object.assign(new Error(`no feedback item ${id}`), { status: 404 });
+      a.thread = [...(a.thread || []), { by: 'agent', text: String(text).slice(0, 5000), at: new Date().toISOString(), ...(tag ? { tag } : {}) }];
+      a.updatedAt = new Date().toISOString();
+      return a;
+    });
+  }
+
+  // ------------------------------------------------------------ rounds
+  // Review happens in turns. The reviewer's marks are drafts until they press
+  // Send, which hands them to the agent as round N. The agent fixes them, then
+  // closes the round with a short report. The reviewer accepts each fix or asks
+  // for a redo, which becomes a draft for the next round.
+
+  roundsFile() {
+    return join(this.dir, 'rounds.json');
+  }
+
+  async rounds() {
+    try {
+      return JSON.parse(await readFile(this.roundsFile(), 'utf8'));
+    } catch {
+      return { rounds: [] };
+    }
+  }
+
+  async writeRounds(data) {
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(this.roundsFile(), JSON.stringify(data, null, 2) + '\n');
+  }
+
+  /** Send every draft to the agent as the next round. Returns the round, or null if nothing to send. */
+  async send() {
+    const data = await this.rounds();
+    const n = (data.rounds.at(-1)?.n || 0) + 1;
+    const count = await this.mutate((list) => {
+      let c = 0;
+      for (const a of list) {
+        if (a.draft) {
+          delete a.draft;
+          // Every round it was sent in, so a round's report still shows what happened to it then.
+          a.rounds = [...(a.rounds || (a.round ? [a.round] : [])), n];
+          a.round = n;
+          c++;
+        }
+      }
+      return c;
+    });
+    if (!count) return null;
+    const round = { n, sentAt: new Date().toISOString(), count };
+    await this.mutateRounds((d) => d.rounds.push(round));
+    // Green marks are the clearest statement of taste there is: remember them.
+    const kept = (await this.all()).filter((a) => a.round === n && a.verdict === 'good' && !a.history && !(a.guard && a.guard.sentBack));
+    if (kept.length) await this.remember(kept.map((a) => tasteEntry('keep', a)));
+    await this.mutate(() => {}); // refresh the brief with the round header
+    return round;
+  }
+
+  /** Serialized read-modify-write of rounds.json. */
+  mutateRounds(fn) {
+    const run = this.roundsQueue.then(async () => {
+      const data = await this.rounds();
+      const result = await fn(data);
+      await this.writeRounds(data);
+      return result;
+    });
+    this.roundsQueue = run.catch(() => {});
+    return run;
+  }
+
+  /** The round the agent owes an answer to: sent and not yet closed with a report. */
+  async pendingRound() {
+    const last = (await this.rounds()).rounds.at(-1);
+    return last && !last.returnedAt ? last : null;
+  }
+
+  /**
+   * Block until the reviewer has sent a round the agent hasn't closed yet, and return it;
+   * right away if one is already waiting. Resolves null when `timeoutMs` passes (0 = never)
+   * or `signal` aborts. Polls rounds.json because the review server that records the Send
+   * usually runs in another process.
+   */
+  async waitForRound({ timeoutMs = 0, signal, pollMs = 1000, onTick } = {}) {
+    const until = timeoutMs > 0 ? Date.now() + timeoutMs : Infinity;
+    for (;;) {
+      const round = await this.pendingRound();
+      if (round) return round;
+      if (signal?.aborted || Date.now() >= until) return null;
+      await new Promise((ok) => {
+        const t = setTimeout(done, Math.min(pollMs, Math.max(until - Date.now(), 0)));
+        function done() {
+          clearTimeout(t);
+          signal?.removeEventListener('abort', done);
+          ok();
+        }
+        signal?.addEventListener('abort', done, { once: true });
+      });
+      onTick?.();
+    }
+  }
+
+  /** Count a judgment for round `n`: accepted first time, or sent back for a redo. */
+  tally(n, kind) {
+    return this.mutateRounds((data) => {
+      const r = data.rounds.find((x) => x.n === n);
+      const key = kind === 'accepted' ? 'accepted' : 'redone';
+      if (r) r[key] = (r[key] || 0) + 1;
+    });
+  }
+
+  // ------------------------------------------------------------ taste
+  // Every judgment the reviewer makes (keep, accept, redo, send back, keep the new
+  // look) is appended to taste.json and rendered as TASTE.md. It is never pruned by
+  // `clear`: it's what the agent should know about this reviewer, round after round.
+
+  async taste() {
+    try {
+      const data = JSON.parse(await readFile(join(this.dir, 'taste.json'), 'utf8'));
+      return Array.isArray(data.entries) ? data.entries : [];
+    } catch {
+      return [];
+    }
+  }
+
+  remember(entries) {
+    const run = this.tasteQueue.then(async () => {
+      const all = [...(await this.taste()), ...entries.filter(Boolean)].slice(-500);
+      await mkdir(this.dir, { recursive: true });
+      await writeFile(join(this.dir, 'taste.json'), JSON.stringify({ version: 1, entries: all }, null, 2) + '\n');
+      await writeFile(join(this.dir, 'TASTE.md'), renderTaste(all, (await this.rounds()).rounds));
+    });
+    this.tasteQueue = run.catch(() => {});
+    return run;
+  }
+
+  /** The agent closes the current round: what it did, how it reads the page, and at most a few questions. */
+  async finishRound({ summary = '', reading = '', questions = [] } = {}) {
+    const round = await this.mutateRounds((data) => {
+      const round = data.rounds.at(-1);
+      if (!round) throw Object.assign(new Error('no round has been sent yet'), { status: 400 });
+      return Object.assign(round, {
+        returnedAt: new Date().toISOString(),
+        summary: String(summary).slice(0, 2000),
+        reading: String(reading).slice(0, 2000),
+        questions: (Array.isArray(questions) ? questions : []).slice(0, 3).map((q) => ({ text: String(q).slice(0, 500) })),
+      });
+    });
+    await this.mutate(() => {});
+    return round;
+  }
+
+  /** The reviewer answers the round report: corrects the agent's reading, answers its questions. */
+  async answerRound(n, { readingCorrection, answers } = {}) {
+    const round = await this.mutateRounds((data) => {
+      const round = data.rounds.find((r) => r.n === Number(n));
+      if (!round) throw Object.assign(new Error(`no round ${n}`), { status: 404 });
+      if (typeof readingCorrection === 'string') round.readingCorrection = readingCorrection.slice(0, 2000);
+      if (Array.isArray(answers)) (round.questions || []).forEach((q, i) => typeof answers[i] === 'string' && (q.answer = answers[i].slice(0, 1000)));
+      return round;
+    });
+    await this.mutate(() => {});
+    // What the page is for, in the reviewer's words, belongs with their taste.
+    if (round.readingCorrection) await this.remember([{ kind: 'reading', at: new Date().toISOString(), round: round.n, reply: round.readingCorrection }]);
+    return round;
+  }
+
+  remove(id) {
+    return this.mutate((list) => {
+      const i = list.findIndex((a) => a.id === id);
+      if (i < 0) return false;
+      list.splice(i, 1);
+      return true;
+    });
+  }
+
+  /** Save an uploaded image (data: URL) under assets/, named by content hash. */
+  async saveAsset(dataUrl) {
+    const m = /^data:image\/(png|jpeg|webp|gif);base64,([A-Za-z0-9+/=]+)$/.exec(dataUrl || '');
+    if (!m) throw Object.assign(new Error('expected a PNG, JPEG, WebP or GIF data URL'), { status: 400 });
+    const buf = Buffer.from(m[2], 'base64');
+    if (buf.length > 8 * 1024 * 1024) throw Object.assign(new Error('image larger than 8 MB'), { status: 413 });
+    const name = createHash('sha1').update(buf).digest('hex').slice(0, 16) + '.' + (m[1] === 'jpeg' ? 'jpg' : m[1]);
+    await mkdir(join(this.dir, 'assets'), { recursive: true });
+    await writeFile(join(this.dir, 'assets', name), buf);
+    return `assets/${name}`;
+  }
+
+  /**
+   * Record a screenshot (written by the shot service); `sig` says what it shows,
+   * `box` where the item's element sits in it (so the overlay can line it up with the page).
+   */
+  setShot(id, key, path, sig, box) {
+    return this.mutate((list) => {
+      const a = list.find((x) => x.id === id);
+      if (!a) return undefined;
+      a.shots = { ...(a.shots || {}), [key]: path };
+      a.shotSigs = { ...(a.shotSigs || {}), [key]: sig };
+      if (box) a.shotBoxes = { ...(a.shotBoxes || {}), [key]: box };
+      return a;
+    });
+  }
+
+  /** An approval's baseline: its screenshot and fingerprint as approved. */
+  /**
+   * An approval's baseline: its screenshot and fingerprint as approved, at the width it
+   * was approved at, or (`width` = MOBILE) on a phone. Not on the page at phone width
+   * (a desktop-only element): nothing to guard there, and that is remembered.
+   */
+  setGuardBase(id, path, fp, sig, box, width) {
+    return this.mutate((list) => {
+      const a = list.find((x) => x.id === id);
+      if (!a || (!fp && !width)) return a;
+      const base = fp ? { shot: path, fp, box, at: new Date().toISOString() } : null;
+      a.guard = { ...(a.guard || {}) };
+      if (width) a.guard.mobile = base ? { base } : { skip: true };
+      else a.guard.base = base;
+      a.shotSigs = { ...(a.shotSigs || {}), [width ? `guard-base@${width}` : 'guard-base']: sig };
+      return a;
+    });
+  }
+
+  /** The approval as it is now, compared with its baseline. `fp` null: it's gone from the page. */
+  setGuardCheck(id, path, fp, sig, width) {
+    return this.mutate((list) => {
+      const a = list.find((x) => x.id === id);
+      const slot = a && a.guard && (width ? a.guard.mobile : a.guard);
+      if (!slot || !slot.base) return a;
+      const diff = diffFingerprints(slot.base.fp, fp, { ignore: a.guardIgnore });
+      slot.check = { shot: path || undefined, at: new Date().toISOString(), status: !fp ? 'missing' : diff.length ? 'changed' : 'held', diff };
+      // One verdict for the approval, across the widths it's guarded at.
+      a.guard.now = combineChecks(a.guard);
+      delete a.guard.sentBack;
+      a.shotSigs = { ...(a.shotSigs || {}), [width ? `guard-now@${width}` : 'guard-now']: sig };
+      return a;
+    });
+  }
+
+  /**
+   * The agent's options for an item: CSS (`&` stands for the item's element) and/or
+   * replacement inner HTML, shown to the reviewer as switchable previews.
+   */
+  proposeVariants(id, variants) {
+    return this.mutate((list) => {
+      const a = list.find((x) => x.id === id || String(x.n) === String(id).replace(/^#/, ''));
+      if (!a) throw Object.assign(new Error(`no feedback item ${id}`), { status: 404 });
+      if (!Array.isArray(variants) || !variants.length) throw Object.assign(new Error('variants must be a non-empty array'), { status: 400 });
+      a.variants = variants.slice(0, 5).map((v, i) => ({
+        key: 'ABCDE'[i],
+        label: str(v && v.label, 80) || `Option ${'ABCDE'[i]}`,
+        css: str(v && v.css, 20000) || '',
+        html: str(v && v.html, 50000) || '',
+        note: str(v && v.note, 500) || '',
+      }));
+      a.chosen = undefined;
+      a.status = 'open';
+      a.updatedAt = new Date().toISOString();
+      return a;
+    });
+  }
+
+  /** Remove annotations matching `pred`; returns how many were removed. */
+  prune(pred) {
+    return this.mutate((list) => {
+      const keep = list.filter((a) => !pred(a));
+      const removed = list.length - keep.length;
+      list.splice(0, list.length, ...keep);
+      return removed;
+    });
+  }
+}

package/src/sync.js

@@ -0,0 +1,126 @@
+// Sync a project to your Redline account (opt-in: `redline proxy … --cloud`), so the
+// hosted MCP server can hand your rounds to an agent running anywhere.
+//
+// This machine stays the source of truth. Up: whenever the notes change, one snapshot
+// of the project (items, rounds, taste and the agent's brief) plus any new screenshots.
+// Down: what the agent asked the hosted MCP to do (resolve, reply, close the round…),
+// applied here with the very same tools the local MCP server uses, then synced back up.
+import { readFile, stat } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { formatMarkdown } from './format.js';
+import { createMcpHandler } from './mcp.js';
+
+const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
+
+export function startSync({ store, storeDir, server, key, project, log = () => {} }) {
+  const base = `${server}/api/v1/sync/${encodeURIComponent(project)}`;
+  const headers = { 'x-api-key': key };
+  const tools = createMcpHandler({ storeDir });
+  let stopped = false;
+  let lastSig = '';
+  let uploaded = null; // screenshot paths the account already has
+  let pushing = null;
+  let dirty = false;
+
+  // What changed locally, cheaply: the store's files' sizes and times.
+  async function signature() {
+    const parts = [];
+    for (const f of ['feedback.json', 'rounds.json', 'taste.json']) {
+      const s = await stat(join(storeDir, f)).catch(() => null);
+      parts.push(s ? `${s.size}:${s.mtimeMs}` : '-');
+    }
+    return parts.join('|');
+  }
+
+  async function push() {
+    const [items, rounds, taste] = await Promise.all([store.all(), store.rounds(), store.taste()]);
+    const open = items.filter((a) => a.status !== 'resolved');
+    const brief = formatMarkdown(open, { rounds: rounds.rounds, taste }).replace(/\n## /, '\n\n## ');
+    if (!uploaded) {
+      const res = await fetch(base, { headers });
+      if (!res.ok) throw new Error(`sync refused (${res.status}): ${(await res.json().catch(() => ({}))).message || ''}`);
+      uploaded = new Set((await res.json()).shots || []);
+    }
+    // Screenshots and reference images first, so the brief never points at a missing one.
+    const paths = new Set();
+    for (const a of items) {
+      for (const p of Object.values(a.shots || {})) paths.add(p);
+      for (const r of a.references || []) if (r.path) paths.add(r.path);
+    }
+    for (const p of paths) {
+      if (uploaded.has(p) || !MIME[extname(p).toLowerCase()]) continue;
+      const bytes = await readFile(join(storeDir, p)).catch(() => null);
+      if (!bytes || bytes.length > 4 * 1024 * 1024) continue;
+      const res = await fetch(`${base}/shot?path=${encodeURIComponent(p)}`, { method: 'PUT', headers: { ...headers, 'content-type': MIME[extname(p).toLowerCase()] }, body: bytes });
+      if (res.ok) uploaded.add(p);
+    }
+    const res = await fetch(base, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: JSON.stringify({ items, rounds, taste, brief }),
+    });
+    if (!res.ok) throw new Error(`sync refused (${res.status})`);
+  }
+
+  // One push at a time; a change during a push means one more right after.
+  async function pushSoon() {
+    if (pushing) return void (dirty = true);
+    pushing = (async () => {
+      do {
+        dirty = false;
+        try {
+          await push();
+        } catch (err) {
+          log(`cloud sync: ${err.message}`);
+        }
+      } while (dirty && !stopped);
+    })();
+    await pushing;
+    pushing = null;
+  }
+
+  async function watch() {
+    while (!stopped) {
+      const sig = await signature();
+      if (sig !== lastSig) {
+        lastSig = sig;
+        await pushSoon();
+      }
+      await new Promise((ok) => setTimeout(ok, 700));
+    }
+  }
+
+  // The agent's requests from the hosted MCP, applied here.
+  async function commands() {
+    let after = 0;
+    while (!stopped) {
+      try {
+        const res = await fetch(`${base}/commands?after=${after}`, { headers, signal: AbortSignal.timeout(35_000) });
+        if (!res.ok) throw new Error(`commands refused (${res.status})`);
+        for (const c of (await res.json()).commands || []) {
+          after = Math.max(after, c.id);
+          const out = await tools.handle({ jsonrpc: '2.0', id: c.id, method: 'tools/call', params: { name: c.tool, arguments: c.arguments || {} } });
+          const r = out && out.result;
+          const text = (r && r.content && r.content.map((x) => x.text).filter(Boolean).join('\n')) || '';
+          const ok = !!r && !r.isError;
+          await pushSoon(); // the change, up before the agent hears it's done
+          await fetch(`${base}/commands`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({ id: c.id, ok, result: { text }, error: ok ? undefined : text }) });
+          log(`cloud: the agent's ${c.tool} ${ok ? 'applied' : 'failed'}`);
+        }
+      } catch (err) {
+        if (stopped) break;
+        log(`cloud sync: ${err.message}; retrying`);
+        await new Promise((ok) => setTimeout(ok, 3000));
+      }
+    }
+  }
+
+  watch();
+  commands();
+  return {
+    stop() {
+      stopped = true;
+    },
+    flush: () => pushSoon(),
+  };
+}