@1agh/maude 0.22.2 → 0.24.0

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

@@ -0,0 +1,165 @@
+// Codec unit tests — Phase 9 Task 4.
+//
+// Verify Y.Doc <-> disk round-trips for the three classes of files the sync
+// agent shuttles: HTML body, comments JSON, annotations SVG.
+
+import { describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+import {
+  Y_SYNC_TYPES,
+  annotationsFromDoc,
+  applyAnnotationsToDoc,
+  applyCommentsToDoc,
+  applyHtmlToDoc,
+  commentsFromDoc,
+  htmlFromDoc,
+} from '../sync/codec.ts';
+
+describe('HTML codec', () => {
+  test('htmlFromDoc returns empty string for a fresh doc', () => {
+    const doc = new Y.Doc();
+    expect(htmlFromDoc(doc)).toBe('');
+  });
+
+  test('applyHtmlToDoc → htmlFromDoc round-trip', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<button>hello</button>');
+    expect(htmlFromDoc(doc)).toBe('<button>hello</button>');
+  });
+
+  test('applyHtmlToDoc with identical content is a no-op', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<button>hi</button>');
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = applyHtmlToDoc(doc, '<button>hi</button>');
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('applyHtmlToDoc emits a minimal op via common prefix + suffix', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<button class="cta">Click</button>');
+
+    // Yjs requires `event.changes.delta` to be read inside the observer.
+    let inserts = '';
+    let deletes = 0;
+    const yText = doc.getText(Y_SYNC_TYPES.html);
+    yText.observe((evt) => {
+      for (const d of evt.changes.delta) {
+        if (typeof d.insert === 'string') inserts += d.insert;
+        if (typeof d.delete === 'number') deletes += d.delete;
+      }
+    });
+
+    applyHtmlToDoc(doc, '<button class="cta">Tap</button>');
+    expect(htmlFromDoc(doc)).toBe('<button class="cta">Tap</button>');
+
+    // The change is "Click" → "Tap". With shared prefix
+    // `<button class="cta">` and shared suffix `</button>`, the delta should
+    // only touch the middle.
+    expect(inserts).toBe('Tap');
+    expect(deletes).toBe('Click'.length);
+  });
+
+  test('applyHtmlToDoc handles complete replace (no shared prefix)', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, 'aaaa');
+    applyHtmlToDoc(doc, 'bbbb');
+    expect(htmlFromDoc(doc)).toBe('bbbb');
+  });
+
+  test('applyHtmlToDoc tags transaction with origin', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, 'seed');
+
+    let observedOrigin: unknown = 'unset';
+    doc.on('update', (_update: Uint8Array, origin: unknown) => {
+      observedOrigin = origin;
+    });
+
+    const myOrigin = { id: 'sync-agent' };
+    applyHtmlToDoc(doc, 'changed', myOrigin);
+    expect(observedOrigin).toBe(myOrigin);
+  });
+});
+
+describe('Comments codec', () => {
+  test('commentsFromDoc returns empty array for a fresh doc', () => {
+    expect(commentsFromDoc(new Y.Doc())).toEqual([]);
+  });
+
+  test('applyCommentsToDoc → commentsFromDoc round-trip', () => {
+    const doc = new Y.Doc();
+    const snap = [{ id: 'c1', body: 'hi' }];
+    applyCommentsToDoc(doc, snap);
+    expect(commentsFromDoc(doc)).toEqual(snap);
+  });
+
+  test('applyCommentsToDoc with identical content is a no-op', () => {
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1' }]);
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = applyCommentsToDoc(doc, [{ id: 'c1' }]);
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('applyCommentsToDoc replaces existing entries on disk-wins update', () => {
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1' }, { id: 'c2' }]);
+    applyCommentsToDoc(doc, [{ id: 'c3' }]);
+    expect(commentsFromDoc(doc)).toEqual([{ id: 'c3' }]);
+  });
+
+  test('comments share Y_TYPES.comments name with Phase 6 persistence', () => {
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1' }]);
+    // The Phase 6 persistence layer reads from this name directly.
+    expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'c1' }]);
+  });
+});
+
+describe('Annotations codec', () => {
+  test('annotationsFromDoc returns null for a fresh doc', () => {
+    expect(annotationsFromDoc(new Y.Doc())).toBeNull();
+  });
+
+  test('applyAnnotationsToDoc → annotationsFromDoc round-trip', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg></svg>');
+    expect(annotationsFromDoc(doc)).toBe('<svg></svg>');
+  });
+
+  test('applyAnnotationsToDoc with null clears the entry', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg></svg>');
+    applyAnnotationsToDoc(doc, null);
+    expect(annotationsFromDoc(doc)).toBeNull();
+  });
+
+  test('applyAnnotationsToDoc with identical content is a no-op', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg></svg>');
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = applyAnnotationsToDoc(doc, '<svg></svg>');
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('annotations share Y_TYPES.annotations name with Phase 5 persistence', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg>x</svg>');
+    expect(doc.getMap<string>(Y_TYPES.annotations).get('svg')).toBe('<svg>x</svg>');
+  });
+});

package/plugins/design/dev-server/test/sync-connection-state.test.ts

@@ -0,0 +1,146 @@
+// Connection-state machine tests — Phase 9 Task 8 (hub-down offline mode).
+//
+// Drives the monitor with injected timers + clock so transitions are
+// deterministic without real wall-clock waits.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type SyncStatusSnapshot, createConnectionMonitor } from '../sync/connection-state.ts';
+
+/** A controllable timer queue: setTimer enqueues, advance() fires due timers. */
+function fakeClock() {
+  let nowMs = 1_000_000;
+  let nextId = 1;
+  const timers = new Map<number, { fireAt: number; cb: () => void }>();
+  return {
+    now: () => nowMs,
+    setTimer: (cb: () => void, ms: number) => {
+      const id = nextId++;
+      timers.set(id, { fireAt: nowMs + ms, cb });
+      return id as unknown as ReturnType<typeof setTimeout>;
+    },
+    clearTimer: (h: ReturnType<typeof setTimeout>) => {
+      timers.delete(h as unknown as number);
+    },
+    /** Advance virtual time by `ms`, firing every timer whose deadline passed. */
+    advance(ms: number) {
+      nowMs += ms;
+      for (const [id, t] of [...timers.entries()].sort((a, b) => a[1].fireAt - b[1].fireAt)) {
+        if (t.fireAt <= nowMs) {
+          timers.delete(id);
+          t.cb();
+        }
+      }
+    },
+  };
+}
+
+function makeMonitor(overrides = {}) {
+  const clock = fakeClock();
+  const changes: SyncStatusSnapshot[] = [];
+  const monitor = createConnectionMonitor({
+    graceMs: 30_000,
+    escalateMs: 24 * 60 * 60 * 1000,
+    flashMs: 3_000,
+    now: clock.now,
+    setTimer: clock.setTimer,
+    clearTimer: clock.clearTimer,
+    onChange: (s) => changes.push(s),
+    ...overrides,
+  });
+  return { clock, changes, monitor };
+}
+
+describe('connection monitor', () => {
+  test('starts online and stays online when the provider connects', () => {
+    const { monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    expect(monitor.snapshot().state).toBe('online');
+  });
+
+  test('disconnect → stays connecting during grace, goes offline after graceMs', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    monitor.noteProviderStatus('p1', 'disconnected');
+    // Inside the grace window — no offline yet (transient blips don't flash UI).
+    expect(monitor.snapshot().state).toBe('connecting');
+    clock.advance(29_000);
+    expect(monitor.snapshot().state).toBe('connecting');
+    clock.advance(2_000); // total 31s > 30s grace
+    expect(monitor.snapshot().state).toBe('offline');
+    expect(monitor.snapshot().offlineSince).not.toBeNull();
+  });
+
+  test('reconnect inside grace cancels the offline transition', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    monitor.noteProviderStatus('p1', 'disconnected');
+    clock.advance(10_000);
+    monitor.noteProviderStatus('p1', 'connected');
+    expect(monitor.snapshot().state).toBe('online');
+    clock.advance(60_000); // grace timer must have been cancelled
+    expect(monitor.snapshot().state).toBe('online');
+  });
+
+  test('queues local edits while offline, resets on reconnect with a green flash', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    monitor.noteProviderStatus('p1', 'disconnected');
+    clock.advance(31_000);
+    expect(monitor.snapshot().state).toBe('offline');
+
+    monitor.noteLocalEdit();
+    monitor.noteLocalEdit();
+    monitor.noteLocalEdit();
+    expect(monitor.snapshot().queuedOps).toBe(3);
+
+    monitor.noteProviderStatus('p1', 'connected');
+    const snap = monitor.snapshot();
+    expect(snap.state).toBe('online');
+    expect(snap.queuedOps).toBe(0);
+    expect(snap.flash).toBe('synced');
+
+    clock.advance(3_500); // flashMs elapses
+    expect(monitor.snapshot().flash).toBeNull();
+  });
+
+  test('does not count edits made while online toward the queue', () => {
+    const { monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    monitor.noteLocalEdit();
+    expect(monitor.snapshot().queuedOps).toBe(0);
+  });
+
+  test('escalates to offline-long after escalateMs offline', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    monitor.noteProviderStatus('p1', 'disconnected');
+    clock.advance(31_000);
+    expect(monitor.snapshot().state).toBe('offline');
+    clock.advance(24 * 60 * 60 * 1000 + 1_000);
+    expect(monitor.snapshot().state).toBe('offline-long');
+  });
+
+  test('aggregates multiple providers: any connected ⇒ online', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteProviderStatus('a', 'connected');
+    monitor.noteProviderStatus('b', 'connected');
+    // b drops, a still up → stays online (aggregate sees a connected).
+    monitor.noteProviderStatus('b', 'disconnected');
+    expect(monitor.snapshot().state).toBe('online');
+    // a drops too → grace, then offline.
+    monitor.noteProviderStatus('a', 'disconnected');
+    clock.advance(31_000);
+    expect(monitor.snapshot().state).toBe('offline');
+  });
+
+  test('stop() cancels pending timers (no late transitions)', () => {
+    const { clock, changes, monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connected');
+    monitor.noteProviderStatus('p1', 'disconnected');
+    monitor.stop();
+    const before = changes.length;
+    clock.advance(60_000);
+    expect(changes.length).toBe(before); // no offline transition fired
+  });
+});

package/plugins/design/dev-server/test/sync-echo-guard.test.ts

@@ -0,0 +1,96 @@
+// Echo-guard unit tests — Phase 9 Task 4.
+
+import { describe, expect, test } from 'bun:test';
+
+import { ECHO_TTL_MS, createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+
+describe('hashBytes', () => {
+  test('stable hex SHA-256 of bytes', () => {
+    expect(hashBytes('hello')).toBe(
+      '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+    );
+  });
+
+  test('matches across string + Uint8Array inputs', () => {
+    const buf = new TextEncoder().encode('hello');
+    expect(hashBytes(buf)).toBe(hashBytes('hello'));
+  });
+});
+
+describe('createEchoGuard', () => {
+  test('record + consume same hash returns true (echo dropped)', () => {
+    const g = createEchoGuard();
+    g.record('a.html', 'h1');
+    expect(g.consume('a.html', 'h1')).toBe(true);
+    // Entry was popped — second consume of the same hash is a fresh match.
+    expect(g.consume('a.html', 'h1')).toBe(false);
+  });
+
+  test('consume with non-matching hash returns false (real edit)', () => {
+    const g = createEchoGuard();
+    g.record('a.html', 'h1');
+    expect(g.consume('a.html', 'different-hash')).toBe(false);
+    // Original entry stays available for matching.
+    expect(g.consume('a.html', 'h1')).toBe(true);
+  });
+
+  test('consume on path with no pending entries returns false', () => {
+    const g = createEchoGuard();
+    expect(g.consume('a.html', 'whatever')).toBe(false);
+  });
+
+  test('expires entries past TTL', () => {
+    const g = createEchoGuard(100);
+    g.record('a.html', 'h1', 0);
+    // Same instant — still valid.
+    expect(g.consume('a.html', 'h1', 50)).toBe(true);
+
+    g.record('a.html', 'h2', 0);
+    // Past TTL — expired, not consumed.
+    expect(g.consume('a.html', 'h2', 200)).toBe(false);
+  });
+
+  test('per-path isolation', () => {
+    const g = createEchoGuard();
+    g.record('a.html', 'h1');
+    g.record('b.html', 'h2');
+    expect(g.consume('a.html', 'h2')).toBe(false);
+    expect(g.consume('b.html', 'h1')).toBe(false);
+    expect(g.consume('a.html', 'h1')).toBe(true);
+    expect(g.consume('b.html', 'h2')).toBe(true);
+  });
+
+  test('stacked writes — N record() calls allow N consume() matches', () => {
+    const g = createEchoGuard();
+    g.record('a.html', 'h1');
+    g.record('a.html', 'h1');
+    g.record('a.html', 'h1');
+    expect(g.consume('a.html', 'h1')).toBe(true);
+    expect(g.consume('a.html', 'h1')).toBe(true);
+    expect(g.consume('a.html', 'h1')).toBe(true);
+    expect(g.consume('a.html', 'h1')).toBe(false);
+  });
+
+  test('sweep removes expired entries idempotently', () => {
+    const g = createEchoGuard(100);
+    g.record('a.html', 'h1', 0);
+    g.record('b.html', 'h2', 0);
+    expect(g.size()).toBe(2);
+    g.sweep(50);
+    expect(g.size()).toBe(2);
+    g.sweep(200);
+    expect(g.size()).toBe(0);
+    // Double-sweep is fine.
+    g.sweep(300);
+    expect(g.size()).toBe(0);
+  });
+
+  test('default TTL is ECHO_TTL_MS', () => {
+    const g = createEchoGuard();
+    g.record('a.html', 'h1', 0);
+    expect(g.consume('a.html', 'h1', ECHO_TTL_MS - 1)).toBe(true);
+
+    g.record('a.html', 'h2', 0);
+    expect(g.consume('a.html', 'h2', ECHO_TTL_MS + 1)).toBe(false);
+  });
+});

package/plugins/design/dev-server/test/sync-fs-mirror.test.ts

@@ -0,0 +1,182 @@
+// fs-mirror unit tests — Phase 9 Task 4.
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { hashBytes } from '../sync/echo-guard.ts';
+import { createFsReader } from '../sync/fs-mirror.ts';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'fs-mirror-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const ACCEPT_ALL = () => true;
+
+describe('createFsReader', () => {
+  test('reads file bytes + hash after the quiet window', async () => {
+    writeFileSync(join(dir, 'a.html'), 'hello');
+    const events: { path: string; bytes: Uint8Array; hash: string }[] = [];
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 10,
+      accept: ACCEPT_ALL,
+      onRead: (e) => {
+        events.push(e);
+      },
+    });
+    r.notify('a.html');
+    await new Promise((res) => setTimeout(res, 50));
+
+    expect(events.length).toBe(1);
+    expect(events[0].path).toBe('a.html');
+    expect(new TextDecoder().decode(events[0].bytes)).toBe('hello');
+    expect(events[0].hash).toBe(hashBytes('hello'));
+    r.stop();
+  });
+
+  test('debounces rapid notify() calls on the same path', async () => {
+    writeFileSync(join(dir, 'b.html'), 'v0');
+    const events: { path: string; hash: string }[] = [];
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 30,
+      accept: ACCEPT_ALL,
+      onRead: (e) => {
+        events.push({ path: e.path, hash: e.hash });
+      },
+    });
+    // 5 notify calls within 5ms should collapse to one read.
+    for (let i = 0; i < 5; i++) r.notify('b.html');
+    expect(r.pending()).toBe(1);
+    await new Promise((res) => setTimeout(res, 80));
+    expect(events.length).toBe(1);
+    r.stop();
+  });
+
+  test('reads the latest disk content after the quiet window (not stale)', async () => {
+    const p = join(dir, 'c.html');
+    writeFileSync(p, 'old');
+    const events: string[] = [];
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 20,
+      accept: ACCEPT_ALL,
+      onRead: (e) => {
+        events.push(new TextDecoder().decode(e.bytes));
+      },
+    });
+    r.notify('c.html');
+    // Update the file BEFORE the quiet window elapses — the read should see
+    // the new content.
+    writeFileSync(p, 'new');
+    await new Promise((res) => setTimeout(res, 50));
+    expect(events).toEqual(['new']);
+    r.stop();
+  });
+
+  test('per-path isolation — different paths debounce independently', async () => {
+    writeFileSync(join(dir, 'd.html'), 'a');
+    writeFileSync(join(dir, 'e.html'), 'b');
+    const paths: string[] = [];
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 10,
+      accept: ACCEPT_ALL,
+      onRead: (e) => {
+        paths.push(e.path);
+      },
+    });
+    r.notify('d.html');
+    r.notify('e.html');
+    expect(r.pending()).toBe(2);
+    await new Promise((res) => setTimeout(res, 50));
+    expect(paths.sort()).toEqual(['d.html', 'e.html']);
+    r.stop();
+  });
+
+  test('accept() filter rejects paths before any timer fires', async () => {
+    writeFileSync(join(dir, 'skipme.css'), 'x');
+    let fired = false;
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 10,
+      accept: (p) => p.endsWith('.html'),
+      onRead: () => {
+        fired = true;
+      },
+    });
+    r.notify('skipme.css');
+    expect(r.pending()).toBe(0);
+    await new Promise((res) => setTimeout(res, 50));
+    expect(fired).toBe(false);
+    r.stop();
+  });
+
+  test('onDeleted fires when the file is gone by the time the timer pops', async () => {
+    writeFileSync(join(dir, 'goner.html'), 'bye');
+    const deleted: string[] = [];
+    const reads: string[] = [];
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 20,
+      accept: ACCEPT_ALL,
+      onRead: (e) => {
+        reads.push(e.path);
+      },
+      onDeleted: (p) => {
+        deleted.push(p);
+      },
+    });
+    r.notify('goner.html');
+    rmSync(join(dir, 'goner.html'));
+    await new Promise((res) => setTimeout(res, 60));
+    expect(deleted).toEqual(['goner.html']);
+    expect(reads).toEqual([]);
+    r.stop();
+  });
+
+  test('stop() cancels pending timers', async () => {
+    writeFileSync(join(dir, 'h.html'), 'x');
+    let fired = false;
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 20,
+      accept: ACCEPT_ALL,
+      onRead: () => {
+        fired = true;
+      },
+    });
+    r.notify('h.html');
+    r.stop();
+    await new Promise((res) => setTimeout(res, 50));
+    expect(fired).toBe(false);
+  });
+
+  test('flush() fires all pending timers immediately', async () => {
+    writeFileSync(join(dir, 'i.html'), 'x');
+    writeFileSync(join(dir, 'j.html'), 'y');
+    const reads: string[] = [];
+    const r = createFsReader({
+      rootDir: dir,
+      quietMs: 10000, // long enough that the test would time out without flush
+      accept: ACCEPT_ALL,
+      onRead: (e) => {
+        reads.push(e.path);
+      },
+    });
+    r.notify('i.html');
+    r.notify('j.html');
+    await r.flush();
+    expect(reads.sort()).toEqual(['i.html', 'j.html']);
+    r.stop();
+  });
+});