@1agh/maude 0.22.2 → 0.23.0

package/plugins/design/dev-server/sync/agent.ts

@@ -0,0 +1,323 @@
+// Per-canvas bidirectional sync agent — Phase 9 Task 4.
+//
+// Wires together the Y.Doc the HocuspocusProvider keeps in sync with the hub
+// and the local on-disk files Claude Code reads + writes:
+//
+//   `.design/<slug>.html`           ←→ Y.Text  (Y_SYNC_TYPES.html)
+//   `.design/_comments/<slug>.json` ←→ Y.Array (Y_TYPES.comments)
+//   `.design/<slug>.annotations.svg`←→ Y.Map.svg (Y_TYPES.annotations)
+//
+// Provider is INJECTED — the agent doesn't import @hocuspocus/provider. This
+// keeps the orchestration testable with an in-memory pair of Y.Docs (no hub
+// process required) and makes the wiring layer (sync/index.ts) responsible
+// for the HocuspocusProvider lifecycle.
+//
+// Flow A — local edit (Claude `Write`, designer ⌘S) → hub:
+//   1. fs.watch fires → fs-mirror debounces 250ms → onRead({bytes, hash})
+//   2. echoGuard.consume(path, hash) returns false (genuine edit)
+//   3. applyHtmlToDoc(doc, str, agentOrigin) — emits Y op
+//   4. HocuspocusProvider broadcasts the op to hub → other peers
+//
+// Flow B — hub broadcasts other peer's edit → us:
+//   1. Provider applies update to doc with NON-agent origin
+//   2. doc.on('update') schedules a 800ms-debounced flush
+//   3. On flush: htmlFromDoc(doc) → echoGuard.record(path, hash) → atomicWrite
+//   4. fs.watch fires → fs-mirror reads → onRead matches the recorded echo
+//      → echoGuard.consume returns true → event dropped (no infinite loop)
+//
+// 800ms quiescence matches the existing Phase 8 collab room flush (DDR-051).
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import type * as Y from 'yjs';
+
+import { atomicWrite } from './atomic-write.ts';
+import {
+  Y_SYNC_TYPES,
+  annotationsFromDoc,
+  applyAnnotationsToDoc,
+  applyCommentsToDoc,
+  applyHtmlToDoc,
+  commentsFromDoc,
+  htmlFromDoc,
+} from './codec.ts';
+import { type EchoGuard, hashBytes } from './echo-guard.ts';
+
+export const DOC_FLUSH_MS = 800;
+
+export interface CanvasSyncPaths {
+  /** Absolute path to <designRoot>/<canvas>.html. */
+  html: string;
+  /** Absolute path to <designRoot>/_comments/<slug>.json. */
+  comments: string;
+  /** Absolute path to <designRoot>/<slug>.annotations.svg. */
+  annotations: string;
+}
+
+export interface CanvasSyncAgentOptions {
+  slug: string;
+  doc: Y.Doc;
+  paths: CanvasSyncPaths;
+  echoGuard: EchoGuard;
+  /** When true, the first reconcile() pushes local disk state up to the doc
+   *  instead of overwriting disk with the doc state. Cleared after first run. */
+  adopt?: boolean;
+  /** Override the 800ms flush. Tests use 0 to flush synchronously. */
+  flushMs?: number;
+  /** Injected for tests — defaults to atomicWrite. */
+  writer?: (path: string, bytes: string | Uint8Array) => void;
+}
+
+export interface CanvasSyncAgent {
+  readonly slug: string;
+  /** Set up the doc.on('update') listener. Idempotent. */
+  start(): void;
+  /**
+   * Reconcile disk ↔ doc once. In adopt mode, disk wins; otherwise doc
+   * (= hub) wins. Call this AFTER the provider's `synced` event.
+   */
+  reconcile(): Promise<void>;
+  /** Apply an fs event (from fs-mirror) to the doc, honoring echo guard. */
+  applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean;
+  /** Force the pending flush timer immediately. */
+  flush(): Promise<void>;
+  /** Stop all timers + listeners. */
+  stop(): void;
+  /** Test/inspection: the origin tag used on agent-applied transactions. */
+  readonly origin: object;
+}
+
+export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncAgent {
+  const { slug, doc, paths, echoGuard } = opts;
+  const flushMs = opts.flushMs ?? DOC_FLUSH_MS;
+  const writer = opts.writer ?? atomicWrite;
+  let adopt = !!opts.adopt;
+
+  const origin = Object.freeze({ agent: 'sync', slug });
+
+  let started = false;
+  let stopped = false;
+  let dirty = false;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Tracks the last-written contents for each path so we don't issue redundant
+  // disk writes when a flush fires but the projection hasn't changed.
+  let lastHtml: string | null = null;
+  let lastComments: string | null = null;
+  let lastAnnotations: string | null = null;
+
+  function onDocUpdate(_update: Uint8Array, updateOrigin: unknown): void {
+    if (stopped) return;
+    // Self-applied (we just synced from disk) — disk is already current.
+    if (updateOrigin === origin) return;
+    scheduleFlush();
+  }
+
+  function scheduleFlush(): void {
+    dirty = true;
+    if (flushMs === 0) {
+      // Synchronous mode for tests — fire on next microtask so the doc
+      // observer has fully run.
+      queueMicrotask(() => {
+        void flush();
+      });
+      return;
+    }
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, flushMs);
+  }
+
+  async function flush(): Promise<void> {
+    if (!dirty || stopped) return;
+    dirty = false;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    try {
+      writeHtmlIfChanged();
+      writeCommentsIfChanged();
+      writeAnnotationsIfChanged();
+    } catch (err) {
+      dirty = true;
+      console.error(`[sync/${slug}] flush failed:`, err);
+    }
+  }
+
+  function writeHtmlIfChanged(): void {
+    const next = htmlFromDoc(doc);
+    if (next === lastHtml) return;
+    const hash = hashBytes(next);
+    echoGuard.record(paths.html, hash);
+    writer(paths.html, next);
+    lastHtml = next;
+  }
+
+  function writeCommentsIfChanged(): void {
+    const next = commentsFromDoc(doc);
+    const serialized = next.length > 0 ? `${JSON.stringify(next, null, 2)}\n` : '';
+    if (serialized === lastComments) return;
+    if (serialized === '') {
+      // Empty comments — don't create an empty file; just remember the state.
+      lastComments = serialized;
+      return;
+    }
+    const hash = hashBytes(serialized);
+    echoGuard.record(paths.comments, hash);
+    writer(paths.comments, serialized);
+    lastComments = serialized;
+  }
+
+  function writeAnnotationsIfChanged(): void {
+    const next = annotationsFromDoc(doc);
+    const value = next ?? '';
+    if (value === lastAnnotations) return;
+    if (value === '') {
+      // Empty annotations — same handling as comments.
+      lastAnnotations = value;
+      return;
+    }
+    const hash = hashBytes(value);
+    echoGuard.record(paths.annotations, hash);
+    writer(paths.annotations, value);
+    lastAnnotations = value;
+  }
+
+  function applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean {
+    if (stopped) return false;
+    // Echo of our own atomicWrite — drop.
+    if (echoGuard.consume(evt.path, evt.hash)) return false;
+
+    const str = bytesToString(evt.bytes);
+    if (evt.path === paths.html) {
+      const changed = applyHtmlToDoc(doc, str, origin);
+      if (changed) lastHtml = htmlFromDoc(doc);
+      return changed;
+    }
+    if (evt.path === paths.comments) {
+      const parsed = tryParseJsonArray(str);
+      if (parsed === null) return false;
+      const changed = applyCommentsToDoc(doc, parsed, origin);
+      if (changed) lastComments = str;
+      return changed;
+    }
+    if (evt.path === paths.annotations) {
+      const changed = applyAnnotationsToDoc(doc, str, origin);
+      if (changed) lastAnnotations = str;
+      return changed;
+    }
+    return false;
+  }
+
+  async function reconcile(): Promise<void> {
+    if (stopped) return;
+    const localHtml = readLocal(paths.html);
+    const localComments = readLocal(paths.comments);
+    const localAnnotations = readLocal(paths.annotations);
+
+    const docHtml = htmlFromDoc(doc);
+    const docComments = commentsFromDoc(doc);
+    const docCommentsStr =
+      docComments.length > 0 ? `${JSON.stringify(docComments, null, 2)}\n` : '';
+    const docAnnotations = annotationsFromDoc(doc) ?? '';
+
+    if (adopt) {
+      // Push local up: doc takes its values from disk. Hub becomes our
+      // canonical view of this canvas. One-shot.
+      if (localHtml !== null) applyHtmlToDoc(doc, localHtml, origin);
+      if (localComments !== null) {
+        const parsed = tryParseJsonArray(localComments);
+        if (parsed !== null) applyCommentsToDoc(doc, parsed, origin);
+      }
+      if (localAnnotations !== null) applyAnnotationsToDoc(doc, localAnnotations, origin);
+      lastHtml = localHtml ?? '';
+      lastComments = localComments ?? '';
+      lastAnnotations = localAnnotations ?? '';
+      adopt = false;
+      return;
+    }
+
+    // Hub-wins (default): overwrite disk from doc when they differ.
+    lastHtml = docHtml;
+    lastComments = docCommentsStr;
+    lastAnnotations = docAnnotations;
+    if (localHtml !== docHtml) {
+      const hash = hashBytes(docHtml);
+      echoGuard.record(paths.html, hash);
+      writer(paths.html, docHtml);
+    }
+    if (docCommentsStr !== '' && localComments !== docCommentsStr) {
+      const hash = hashBytes(docCommentsStr);
+      echoGuard.record(paths.comments, hash);
+      writer(paths.comments, docCommentsStr);
+    }
+    if (docAnnotations !== '' && localAnnotations !== docAnnotations) {
+      const hash = hashBytes(docAnnotations);
+      echoGuard.record(paths.annotations, hash);
+      writer(paths.annotations, docAnnotations);
+    }
+  }
+
+  return {
+    slug,
+    origin,
+    start() {
+      if (started) return;
+      doc.on('update', onDocUpdate);
+      started = true;
+    },
+    reconcile,
+    applyFromFs,
+    flush,
+    stop() {
+      stopped = true;
+      doc.off('update', onDocUpdate);
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+    },
+  };
+}
+
+/* ---------------------------------------------------------------- helpers */
+
+function readLocal(p: string): string | null {
+  if (!existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function bytesToString(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+// Reviver strips dangerous keys at parse time so a malicious hub-pushed
+// payload (or a planted commit) can't seed `__proto__` / `constructor` /
+// `prototype` own-properties into the comment objects yjs subsequently
+// serializes to other peers. Modern V8/Bun block direct Object.prototype
+// pollution at parse, but the reviver also closes the cross-machine
+// propagation surface where an unsafe `for…in` on a peer would re-pollute.
+// DDR-054 §2g (defender M2).
+function tryParseJsonArray(s: string): unknown[] | null {
+  try {
+    const parsed = JSON.parse(s, (key, value) => {
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+        return undefined;
+      }
+      return value;
+    });
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Re-export for the wiring layer to know which shared type holds HTML.
+export { Y_SYNC_TYPES };

package/plugins/design/dev-server/sync/atomic-write.ts

@@ -0,0 +1,103 @@
+// Atomic file writes for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// fs.watch on macOS/Linux fires on rename, so a non-atomic write (open →
+// truncate → write chunks → close) emits multiple watch events with partial
+// content. The agent's echo guard hashes the final content, so a partial-write
+// event would miss the hash match and incorrectly bubble the (truncated) state
+// up to Y.Doc — corrupting the live state.
+//
+// Pattern: open `<path>.tmp.<random-128-bit>` with O_CREAT|O_EXCL ('wx' in
+// Node), write bytes, close, `renameSync` to the final path. POSIX rename is
+// atomic when source + destination are on the same filesystem; the watch sees
+// the final-content-already-present rename event rather than a stream of
+// in-flight chunks. O_EXCL + 128-bit suffix defeats pre-created symlinks on
+// shared-tenant hosts (DDR-054 §2c — closes attacker Chain C + defender L1).
+//
+// File mode 0o600 on the staging file so other tenants on shared hosts can't
+// read in-flight content before the rename.
+//
+// Windows note: rename of a file the watcher has open returns EBUSY. The
+// plan's Task 4 step 4 acknowledges this as a known minor risk for v1.1;
+// the agent treats EBUSY as a transient error and retries once after a 25ms
+// jitter.
+
+import { randomBytes } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const RETRY_DELAY_MS = 25;
+// 'wx' = O_CREAT | O_EXCL — fails if the target already exists, including as
+// a dangling/live symlink. Plus O_TRUNC is implied; mode 0o600 sets owner-only.
+const TMP_OPEN_FLAGS = 'wx' as const;
+const TMP_OPEN_MODE = 0o600;
+
+/**
+ * Write `bytes` to `path` atomically. Returns the absolute path written
+ * (same as input — convenience for chaining).
+ *
+ * Bytes are written via Node's synchronous `openSync` with `O_CREAT|O_EXCL`
+ * (fails on pre-existing tmp / symlink), then `renameSync` moves it into
+ * place. 128-bit random suffix; mode 0o600. On POSIX the rename is atomic;
+ * on Windows there is a small window where the watcher may see a brief gap,
+ * retried once on EBUSY.
+ *
+ * `bytes` accepts string (UTF-8 encoded) or Uint8Array (written verbatim).
+ */
+export function atomicWrite(path: string, bytes: string | Uint8Array): string {
+  // Ensure the parent directory exists. Cheap (mkdirSync recursive is a no-op
+  // when present) and removes the per-canvas burden of creating _comments/
+  // before the agent's first flush.
+  mkdirSync(dirname(path), { recursive: true });
+  // 16 bytes = 32 hex chars = 128 bits. Unforgeable in practice against a
+  // local racer (vs. the prior 32-bit value which was brute-forceable in ms).
+  const suffix = randomBytes(16).toString('hex');
+  const tmp = `${path}.tmp.${suffix}`;
+  let fd: number | null = null;
+  try {
+    fd = openSync(tmp, TMP_OPEN_FLAGS, TMP_OPEN_MODE);
+    const buf = typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : Buffer.from(bytes);
+    writeSync(fd, buf, 0, buf.byteLength, 0);
+    closeSync(fd);
+    fd = null;
+    try {
+      renameSync(tmp, path);
+    } catch (err) {
+      if (isWindowsBusy(err)) {
+        // Brief retry — Windows watcher may hold a handle while reading the
+        // pre-rename target. 25ms is short enough to be invisible to the user
+        // and long enough to clear the typical fs.watch poll interval.
+        const start = Date.now();
+        while (Date.now() - start < RETRY_DELAY_MS) {
+          // Tight loop is OK for 25ms — keeps the call synchronous so callers
+          // can record the echo-guard hash before any fs event fires.
+        }
+        renameSync(tmp, path);
+      } else {
+        throw err;
+      }
+    }
+  } catch (err) {
+    // Best-effort cleanup of the .tmp + fd on failure — don't mask the
+    // original exception with a cleanup error.
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+  return path;
+}
+
+function isWindowsBusy(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const code = (err as { code?: string }).code;
+  return code === 'EBUSY' || code === 'EPERM' || code === 'EACCES';
+}

package/plugins/design/dev-server/sync/codec.ts

@@ -0,0 +1,169 @@
+// Y.Doc ↔ disk codecs for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// The agent shuttles three classes of files between disk and the Y.Doc the
+// HocuspocusProvider holds:
+//
+//   `.design/<canvas>.html`             -> Y.Text     (Y_SYNC_TYPES.html)
+//   `.design/_comments/<slug>.json`     -> Y.Array    (Y_TYPES.comments  — Phase 6)
+//   `.design/<slug>.annotations.svg`    -> Y.Map.svg  (Y_TYPES.annotations — Phase 5)
+//
+// v1.1 design decision (plan §"Key insight"): HTML body is treated as opaque
+// Y.Text rather than structured Y.XmlFragment. Round-trip drift would
+// otherwise cause infinite sync churn — every time we serialize the structured
+// CRDT back to HTML the formatting whitespace would shift and re-enter the
+// system as a new mutation. Structured CRDT (true element-level co-editing) is
+// Phase 10 / v1.2.
+//
+// The "diff-aware" applyHtmlToDoc replaces the Y.Text contents using a
+// longest-common-prefix + suffix elimination so other peers see a minimal
+// op (e.g. "user changed character 42 only"). This isn't a true textual diff
+// (no LCS), but it's drastically cheaper for typical edits than `delete-all +
+// insert-all`, and crucially preserves cursor positions other peers may have
+// in the unchanged regions.
+
+import type * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+
+/**
+ * Y.Doc shared-type names introduced by Task 4. Distinct namespace from
+ * Y_TYPES so existing comments / annotations stay untouched; new fields
+ * land here.
+ */
+export const Y_SYNC_TYPES = {
+  /** The canvas HTML body, as opaque Y.Text. */
+  html: 'html',
+} as const;
+
+/**
+ * Hard caps on hub-pushed content (DDR-054 §2d — closes attacker F7). yjs
+ * has no upstream-enforced size cap; the codec is the consumer's guard.
+ * Mirrors the existing /_api/annotations 1 MB cap (api.ts) so the sync path
+ * doesn't bypass the HTTP-layer guard.
+ */
+export const MAX_HTML_BYTES = 4 * 1024 * 1024;
+export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
+export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
+
+function byteLengthUtf8(s: string): number {
+  return Buffer.byteLength(s, 'utf8');
+}
+
+/* ---------------------------------------------------------------- HTML */
+
+export function htmlFromDoc(doc: Y.Doc): string {
+  return doc.getText(Y_SYNC_TYPES.html).toString();
+}
+
+/**
+ * Apply `next` to the Y.Text inside `doc`. Uses a minimal common-prefix /
+ * common-suffix replace so peers see a small op rather than a full replace.
+ *
+ * Pass `origin` as the transaction origin so a downstream observer can
+ * distinguish self-originated updates from peer/remote ones.
+ */
+export function applyHtmlToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  if (byteLengthUtf8(next) > MAX_HTML_BYTES) {
+    console.warn(
+      `[sync/codec] refusing HTML apply > ${MAX_HTML_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const yText = doc.getText(Y_SYNC_TYPES.html);
+  const current = yText.toString();
+  if (current === next) return false;
+
+  // Find longest common prefix.
+  let prefix = 0;
+  const maxPrefix = Math.min(current.length, next.length);
+  while (prefix < maxPrefix && current.charCodeAt(prefix) === next.charCodeAt(prefix)) {
+    prefix++;
+  }
+  // Find longest common suffix that doesn't overlap the prefix.
+  let suffix = 0;
+  const maxSuffix = Math.min(current.length - prefix, next.length - prefix);
+  while (
+    suffix < maxSuffix &&
+    current.charCodeAt(current.length - 1 - suffix) === next.charCodeAt(next.length - 1 - suffix)
+  ) {
+    suffix++;
+  }
+
+  const deleteLen = current.length - prefix - suffix;
+  const insertStr = next.slice(prefix, next.length - suffix);
+
+  doc.transact(() => {
+    if (deleteLen > 0) yText.delete(prefix, deleteLen);
+    if (insertStr.length > 0) yText.insert(prefix, insertStr);
+  }, origin);
+
+  return true;
+}
+
+/* ---------------------------------------------------------------- comments */
+
+/**
+ * Comments JSON payload — opaque to the codec, just the array of objects the
+ * Y.Array holds.
+ */
+export type CommentsSnapshot = unknown[];
+
+export function commentsFromDoc(doc: Y.Doc): CommentsSnapshot {
+  const arr = doc.getArray(Y_TYPES.comments);
+  return arr.toArray();
+}
+
+export function applyCommentsToDoc(doc: Y.Doc, next: CommentsSnapshot, origin?: unknown): boolean {
+  const arr = doc.getArray(Y_TYPES.comments);
+  // Comments are LWW on the JSON file (the snapshot is the source of truth);
+  // collapse Y.Array to the new state. For v1.1 we just replace wholesale —
+  // structural comment-level merge is deferred along with structured HTML.
+  // Check whether anything actually changed to avoid no-op transactions
+  // (transactions still fire `update` events, which would re-enter the loop).
+  const before = JSON.stringify(arr.toArray());
+  const after = JSON.stringify(next);
+  if (byteLengthUtf8(after) > MAX_COMMENTS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing comments apply > ${MAX_COMMENTS_BYTES} bytes (got ${byteLengthUtf8(after)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  if (before === after) return false;
+
+  doc.transact(() => {
+    if (arr.length > 0) arr.delete(0, arr.length);
+    if (next.length > 0) arr.push(next);
+  }, origin);
+  return true;
+}
+
+/* ---------------------------------------------------------------- annotations */
+
+/** Returns the annotations SVG string, or null if unset. */
+export function annotationsFromDoc(doc: Y.Doc): string | null {
+  const map = doc.getMap<unknown>(Y_TYPES.annotations);
+  const svg = map.get('svg');
+  return typeof svg === 'string' ? svg : null;
+}
+
+export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?: unknown): boolean {
+  if (next !== null && byteLengthUtf8(next) > MAX_ANNOTATIONS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing annotations apply > ${MAX_ANNOTATIONS_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const map = doc.getMap<unknown>(Y_TYPES.annotations);
+  const current = map.get('svg');
+  const currentStr = typeof current === 'string' ? current : null;
+  if (currentStr === next) return false;
+
+  doc.transact(() => {
+    if (next === null || next === '') {
+      map.delete('svg');
+    } else {
+      map.set('svg', next);
+    }
+  }, origin);
+  return true;
+}