@1agh/maude 0.23.0 → 0.24.0

package/plugins/design/dev-server/test/shared-doc-projection.test.ts

@@ -0,0 +1,238 @@
+// Phase 9.2 (DDR-064) Phase C — loop-free disk projection (Tasks 6 + 7).
+//
+// Unit tests for sync/projection.ts in isolation (no runtime / no hub). They
+// pin the contract the shared-doc cutover relies on:
+//   - doc→file projects html/css/meta only (the collab room owns comments +
+//     annotations doc→file — no double-write);
+//   - file→doc imports all five types as a minimal DIFF (never wholesale),
+//     tagged FILE_IMPORT so it doesn't echo back to disk;
+//   - our own doc→file writes are dropped on their fs echo (hash guard);
+//   - a body file edit does NOT clobber concurrent in-doc comments (independent
+//     Y-types — the cross-type no-clobber guarantee);
+//   - an unparseable file is quarantined after 3 strikes (circuit breaker).
+//
+// NB: true char-level merge of CONCURRENT edits to the SAME body region is
+// Phase 10 (structured CRDT). Here the body is opaque Y.Text + prefix/suffix
+// diff: it preserves untouched regions, but a whole-file /design:edit that omits
+// a concurrent browser body edit will still supersede it. Browsers edit
+// comments/annotations (separate types), so that residual is out of Phase C
+// scope by design.
+
+import { describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+import { MAX_HTML_BYTES, applyHtmlToDoc } from '../sync/codec.ts';
+import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+import { ORIGINS } from '../sync/origins.ts';
+import { createDocProjection } from '../sync/projection.ts';
+
+const enc = (s: string) => new TextEncoder().encode(s);
+
+interface Write {
+  path: string;
+  bytes: string;
+}
+
+function makeProjection(paths: {
+  html: string;
+  comments: string;
+  annotations: string;
+  meta?: string;
+  css?: string;
+}) {
+  const doc = new Y.Doc();
+  const writes: Write[] = [];
+  const echoGuard = createEchoGuard();
+  const projection = createDocProjection({
+    slug: 'p',
+    doc,
+    paths,
+    echoGuard,
+    flushMs: 0, // synchronous flush on the next microtask
+    writer: (path, bytes) => writes.push({ path, bytes: bytes.toString() }),
+  });
+  projection.start();
+  return { doc, writes, echoGuard, projection };
+}
+
+const PATHS = {
+  html: '/d/ui/screen.html',
+  comments: '/d/_comments/ui-screen.json',
+  annotations: '/d/ui-screen.annotations.svg',
+  meta: '/d/ui/screen.meta.json',
+  css: '/d/ui/screen.css',
+};
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('projection doc→file (html/css/meta only — room owns comments/annotations)', () => {
+  test('projects html / css / meta on a doc edit', async () => {
+    const { doc, writes, projection } = makeProjection(PATHS);
+    doc.getText('html').insert(0, '<button>hi</button>');
+    doc.getText('css').insert(0, '.b{color:red}');
+    // meta is stored as the canonical SHARED subset (a JSON string in Y.Text).
+    doc.getText('meta').insert(0, JSON.stringify({ title: 'Screen' }));
+    await projection.flush();
+
+    const byPath = Object.fromEntries(writes.map((w) => [w.path, w.bytes]));
+    expect(byPath[PATHS.html]).toBe('<button>hi</button>');
+    expect(byPath[PATHS.css]).toBe('.b{color:red}');
+    expect(JSON.parse(byPath[PATHS.meta])).toMatchObject({ title: 'Screen' });
+    await tick();
+  });
+
+  test('does NOT write comments or annotations doc→file (the room owns those)', async () => {
+    const { doc, writes, projection } = makeProjection(PATHS);
+    doc.getArray(Y_TYPES.comments).push([{ id: 'c1', text: 'hi' }]);
+    doc.getMap(Y_TYPES.annotations).set('svg', '<svg/>');
+    await projection.flush();
+    expect(writes.find((w) => w.path === PATHS.comments)).toBeUndefined();
+    expect(writes.find((w) => w.path === PATHS.annotations)).toBeUndefined();
+  });
+
+  test('never clobbers a non-empty body with an empty doc value (safe reconcile)', async () => {
+    const { writes, projection } = makeProjection(PATHS);
+    // doc html is empty → reconcile must not write an empty file over local.
+    projection.reconcile();
+    expect(writes.find((w) => w.path === PATHS.html)).toBeUndefined();
+  });
+});
+
+describe('projection file→doc (diff-import, all five types, FILE_IMPORT origin)', () => {
+  test('imports an external body edit into the doc', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    const body = '<main>edited</main>';
+    const changed = projection.applyFromFs({
+      path: PATHS.html,
+      bytes: enc(body),
+      hash: hashBytes(body),
+    });
+    expect(changed).toBe(true);
+    expect(doc.getText('html').toString()).toBe(body);
+  });
+
+  test('import is tagged FILE_IMPORT (so the projector does not re-project it)', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    let lastOrigin: unknown;
+    doc.on('update', (_u: Uint8Array, origin: unknown) => {
+      lastOrigin = origin;
+    });
+    const body = '<main>x</main>';
+    projection.applyFromFs({ path: PATHS.html, bytes: enc(body), hash: hashBytes(body) });
+    expect(lastOrigin).toBe(ORIGINS.FILE_IMPORT);
+  });
+
+  test('imports comments + annotations too', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    const comments = JSON.stringify([{ id: 'x', text: 'yo' }]);
+    expect(
+      projection.applyFromFs({
+        path: PATHS.comments,
+        bytes: enc(comments),
+        hash: hashBytes(comments),
+      })
+    ).toBe(true);
+    expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'x', text: 'yo' }]);
+
+    const svg = '<svg><rect/></svg>';
+    expect(
+      projection.applyFromFs({ path: PATHS.annotations, bytes: enc(svg), hash: hashBytes(svg) })
+    ).toBe(true);
+    expect(doc.getMap(Y_TYPES.annotations).get('svg')).toBe(svg);
+  });
+
+  test('body import is a MINIMAL diff — preserves an untouched suffix region', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    doc.getText('html').insert(0, 'HELLO WORLD');
+    // Change only the prefix; the diff must keep " WORLD" in place (prefix/suffix
+    // elimination), not delete-all + insert-all.
+    const next = 'HOWDY WORLD';
+    projection.applyFromFs({ path: PATHS.html, bytes: enc(next), hash: hashBytes(next) });
+    expect(doc.getText('html').toString()).toBe(next);
+    // Cross-check the codec produced a minimal op (the same primitive the
+    // projector uses) — a wholesale replace would not preserve the suffix.
+    const probe = new Y.Doc();
+    probe.getText('html').insert(0, 'HELLO WORLD');
+    expect(applyHtmlToDoc(probe, next, 'x')).toBe(true);
+  });
+});
+
+describe('projection loop-freedom', () => {
+  test('drops the fs echo of our own doc→file write (hash guard)', async () => {
+    const { doc, projection } = makeProjection(PATHS);
+    doc.getText('html').insert(0, '<x/>');
+    await projection.flush();
+    // The fs.watch fires for our own write — same bytes → same hash → dropped,
+    // doc unchanged, no re-import.
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = projection.applyFromFs({
+      path: PATHS.html,
+      bytes: enc('<x/>'),
+      hash: hashBytes('<x/>'),
+    });
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('a body file edit does NOT clobber concurrent in-doc comments (cross-type no-clobber)', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    // Browser added a comment (lives in the comments Y.Array).
+    doc.getArray(Y_TYPES.comments).push([{ id: 'live', text: 'mine' }]);
+    // Concurrently /design:edit rewrites the whole body file.
+    const body = '<main>rewritten by design:edit</main>';
+    projection.applyFromFs({ path: PATHS.html, bytes: enc(body), hash: hashBytes(body) });
+    // Body updated; the concurrent comment SURVIVED (independent Y-type).
+    expect(doc.getText('html').toString()).toBe(body);
+    expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'live', text: 'mine' }]);
+  });
+});
+
+describe('projection hub→disk hardening (security re-audit A2 + A3)', () => {
+  test('A2 — refuses to materialize an oversized (hub-pushed) body to disk', async () => {
+    const { doc, writes, projection } = makeProjection(PATHS);
+    // Simulate a hub raw-update that bypassed the codec import cap: an oversized
+    // body lands directly in the shared doc.
+    doc.getText('html').insert(0, 'x'.repeat(MAX_HTML_BYTES + 1));
+    await projection.flush();
+    // The doc→file lane must refuse it — no disk-fill DoS.
+    expect(writes.find((w) => w.path === PATHS.html)).toBeUndefined();
+  });
+
+  test('A3 — a meta file with __proto__ is imported without polluting Object.prototype', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    const malicious = JSON.stringify({ __proto__: { polluted: 'yes' }, title: 'ok' });
+    projection.applyFromFs({ path: PATHS.meta, bytes: enc(malicious), hash: hashBytes(malicious) });
+    // The dangerous key was stripped at parse time — no prototype pollution and
+    // the stored shared meta carries only the safe key.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+    const stored = doc.getText('meta').toString();
+    expect(stored).not.toContain('__proto__');
+    expect(stored).not.toContain('polluted');
+    expect(stored).toContain('ok');
+  });
+});
+
+describe('projection circuit breaker', () => {
+  test('quarantines an unparseable meta file after 3 strikes (until checksum changes)', () => {
+    const { doc, projection } = makeProjection(PATHS);
+    const broken = '{ not json';
+    const ev = { path: PATHS.meta, bytes: enc(broken), hash: hashBytes(broken) };
+    // First three attempts: parse fails → false, strikes accumulate.
+    expect(projection.applyFromFs(ev)).toBe(false);
+    expect(projection.applyFromFs(ev)).toBe(false);
+    expect(projection.applyFromFs(ev)).toBe(false);
+    // Now quarantined for that hash — still false, but short-circuited.
+    expect(projection.applyFromFs(ev)).toBe(false);
+
+    // A DIFFERENT (valid) payload clears the quarantine and applies.
+    const ok = JSON.stringify({ title: 'Fixed' });
+    expect(projection.applyFromFs({ path: PATHS.meta, bytes: enc(ok), hash: hashBytes(ok) })).toBe(
+      true
+    );
+    expect(doc.getText('meta').toString()).toContain('Fixed');
+  });
+});

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-meta-codec.test.ts

@@ -0,0 +1,123 @@
+// Gap 2 — .meta.json shared-layout sync codec.
+//
+// Artboard layout must propagate as a file diff (one machine moves an artboard →
+// the other's .meta.json layout converges), while each user's pan/zoom
+// (`viewport`) and the security opt-in (`syncable`) stay strictly local. These
+// tests pin that split: applyMetaToDoc stores only the shared subset, and
+// mergeSharedMetaIntoLocal layers it back without trampling local-only keys.
+
+import { describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import {
+  META_LOCAL_KEYS,
+  applyCssToDoc,
+  applyMetaToDoc,
+  cssFromDoc,
+  mergeSharedMetaIntoLocal,
+  metaFromDoc,
+} from '../sync/codec.ts';
+
+describe('Gap 2 — meta codec: shared layout syncs, per-user keys stay local', () => {
+  test('applyMetaToDoc stores ONLY the shared subset (viewport/last_modified/syncable stripped)', () => {
+    const doc = new Y.Doc();
+    const full = JSON.stringify({
+      title: 'Kanban',
+      layout: { 'ab-1': { x: 10, y: 20 } },
+      viewport: { x: 999, y: 888, zoom: 0.5 },
+      last_modified: '2026-01-01T00:00:00Z',
+      syncable: true,
+    });
+    expect(applyMetaToDoc(doc, full)).toBe(true);
+
+    const shared = JSON.parse(metaFromDoc(doc) as string);
+    expect(shared.title).toBe('Kanban');
+    expect(shared.layout).toEqual({ 'ab-1': { x: 10, y: 20 } });
+    // The three per-machine keys never enter the synced doc.
+    expect(shared.viewport).toBeUndefined();
+    expect(shared.last_modified).toBeUndefined();
+    expect(shared.syncable).toBeUndefined();
+  });
+
+  test('applyMetaToDoc is a NO-OP when only per-user keys differ (no churn from panning)', () => {
+    const doc = new Y.Doc();
+    applyMetaToDoc(doc, JSON.stringify({ title: 'X', viewport: { x: 1 } }));
+    // Same shared content, different viewport → must not register a change,
+    // otherwise every pan would emit a sync op.
+    expect(applyMetaToDoc(doc, JSON.stringify({ title: 'X', viewport: { x: 2 } }))).toBe(false);
+  });
+
+  test('mergeSharedMetaIntoLocal takes shared layout, PRESERVES local viewport + syncable', () => {
+    const shared = JSON.stringify({ title: 'Kanban', layout: { 'ab-1': { x: 10, y: 20 } } });
+    const local = JSON.stringify({
+      title: 'Kanban (stale)',
+      layout: { 'ab-1': { x: 0, y: 0 } },
+      viewport: { x: 42, y: 7, zoom: 1.5 },
+      syncable: false,
+      last_modified: 'local-ts',
+    });
+    const merged = JSON.parse(mergeSharedMetaIntoLocal(local, shared) as string);
+    expect(merged.layout).toEqual({ 'ab-1': { x: 10, y: 20 } }); // shared layout won
+    expect(merged.title).toBe('Kanban'); // shared title won
+    expect(merged.viewport).toEqual({ x: 42, y: 7, zoom: 1.5 }); // LOCAL viewport kept
+    expect(merged.syncable).toBe(false); // LOCAL opt-in kept (security invariant)
+    expect(merged.last_modified).toBe('local-ts'); // local timestamp kept
+  });
+
+  test('round-trip: artboard move on A reaches B without touching B viewport / syncable', () => {
+    const aDoc = new Y.Doc();
+    applyMetaToDoc(
+      aDoc,
+      JSON.stringify({
+        title: 'K',
+        layout: { 'ab-1': { x: 100, y: 200 } },
+        viewport: { zoom: 0.5 },
+        syncable: true,
+      })
+    );
+    const shared = metaFromDoc(aDoc) as string;
+
+    const bLocal = JSON.stringify({
+      title: 'K',
+      layout: { 'ab-1': { x: 0, y: 0 } },
+      viewport: { zoom: 2.0 },
+      syncable: false,
+    });
+    const bMerged = JSON.parse(mergeSharedMetaIntoLocal(bLocal, shared) as string);
+    expect(bMerged.layout['ab-1']).toEqual({ x: 100, y: 200 }); // A's move landed on B
+    expect(bMerged.viewport).toEqual({ zoom: 2.0 }); // B's camera untouched
+    expect(bMerged.syncable).toBe(false); // B's opt-in untouched
+  });
+
+  test('a freshly-cloned peer with no local viewport just takes the shared subset', () => {
+    const merged = JSON.parse(
+      mergeSharedMetaIntoLocal('{}', JSON.stringify({ title: 'K', layout: { a: 1 } })) as string
+    );
+    expect(merged).toEqual({ title: 'K', layout: { a: 1 } });
+  });
+
+  test('META_LOCAL_KEYS pins the never-synced set', () => {
+    expect([...META_LOCAL_KEYS].sort()).toEqual(['last_modified', 'syncable', 'viewport']);
+  });
+
+  test('mergeSharedMetaIntoLocal returns null on an unparseable shared payload', () => {
+    expect(mergeSharedMetaIntoLocal('{}', 'not json')).toBeNull();
+  });
+});
+
+describe('Gap 3 — css codec (opaque wholesale text)', () => {
+  test('applyCssToDoc round-trips the css string', () => {
+    const doc = new Y.Doc();
+    expect(cssFromDoc(doc)).toBeNull();
+    const css = '.ka-card { color: red; }\n';
+    expect(applyCssToDoc(doc, css)).toBe(true);
+    expect(cssFromDoc(doc)).toBe(css);
+  });
+
+  test('applyCssToDoc is a no-op when unchanged (loop-safe)', () => {
+    const doc = new Y.Doc();
+    applyCssToDoc(doc, '.x{}');
+    expect(applyCssToDoc(doc, '.x{}')).toBe(false);
+    expect(applyCssToDoc(doc, '.x{ color: blue }')).toBe(true);
+  });
+});