@1agh/maude 0.22.2 → 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-agent.test.ts

@@ -0,0 +1,278 @@
+// Sync-agent integration tests — Phase 9 Task 4.
+//
+// Uses an in-memory pair of Y.Docs cross-linked via Y.applyUpdate as a stand-in
+// for HocuspocusProvider's transport. The agent under test owns docB; docA
+// represents "another peer talking to the hub". Updates flow:
+//
+//   docA → encode → applyUpdate(docB) → agent observes → write to disk
+//   disk → onRead → applyFromFs → applyHtmlToDoc(docB) → encode → docA
+//
+// This lets us validate the whole bidi loop, echo prevention, and the
+// 100-event stress scenario from the plan without booting a real hub.
+
+import { mkdtempSync, readFileSync, 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 * as Y from 'yjs';
+
+import { type CanvasSyncAgent, createCanvasSyncAgent } from '../sync/agent.ts';
+import { Y_SYNC_TYPES, applyHtmlToDoc, htmlFromDoc } from '../sync/codec.ts';
+import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+import { createFsReader } from '../sync/fs-mirror.ts';
+
+let dir: string;
+let agent: CanvasSyncAgent;
+let docA: Y.Doc;
+let docB: Y.Doc;
+
+function paths() {
+  return {
+    html: join(dir, 'screen.html'),
+    comments: join(dir, '_comments', 'screen.json'),
+    annotations: join(dir, 'screen.annotations.svg'),
+  };
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'sync-agent-'));
+  docA = new Y.Doc();
+  docB = new Y.Doc();
+  // Mirror docA→docB and docB→docA, ignoring transient origin objects from
+  // the transport itself (we use a symbol).
+  const TRANSPORT = Symbol('transport');
+  docA.on('update', (update: Uint8Array, origin: unknown) => {
+    if (origin === TRANSPORT) return;
+    Y.applyUpdate(docB, update, TRANSPORT);
+  });
+  docB.on('update', (update: Uint8Array, origin: unknown) => {
+    if (origin === TRANSPORT) return;
+    Y.applyUpdate(docA, update, TRANSPORT);
+  });
+});
+
+afterEach(() => {
+  agent?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function makeAgent(extra: { adopt?: boolean; flushMs?: number } = {}): CanvasSyncAgent {
+  const a = createCanvasSyncAgent({
+    slug: 'screen',
+    doc: docB,
+    paths: paths(),
+    echoGuard: createEchoGuard(),
+    flushMs: 0, // synchronous flush; the agent uses queueMicrotask
+    ...extra,
+  });
+  a.start();
+  return a;
+}
+
+describe('CanvasSyncAgent — hub → disk (Flow B)', () => {
+  test('writes HTML to disk when other peer mutates the doc', async () => {
+    agent = makeAgent();
+    // Other peer types into docA — propagates to docB via the in-memory
+    // transport, which our agent observes.
+    applyHtmlToDoc(docA, '<button>v1</button>');
+    await agent.flush();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>v1</button>');
+  });
+
+  test('debounces multiple rapid peer edits into one disk write', async () => {
+    agent = makeAgent({ flushMs: 30 });
+    for (let i = 0; i < 10; i++) {
+      applyHtmlToDoc(docA, `<button>v${i}</button>`);
+    }
+    await new Promise((res) => setTimeout(res, 80));
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>v9</button>');
+  });
+
+  test('writes comments JSON when Y.Array changes', async () => {
+    agent = makeAgent();
+    docA.transact(() => {
+      docA.getArray('comments').push([{ id: 'c1', body: 'hello' }]);
+    });
+    await agent.flush();
+
+    const written = JSON.parse(readFileSync(paths().comments, 'utf8'));
+    expect(written).toEqual([{ id: 'c1', body: 'hello' }]);
+  });
+
+  test('writes annotations SVG when Y.Map.svg changes', async () => {
+    agent = makeAgent();
+    docA.transact(() => {
+      docA.getMap('annotations').set('svg', '<svg>annot</svg>');
+    });
+    await agent.flush();
+
+    expect(readFileSync(paths().annotations, 'utf8')).toBe('<svg>annot</svg>');
+  });
+});
+
+describe('CanvasSyncAgent — disk → hub (Flow A)', () => {
+  test('applies disk HTML to doc when applyFromFs is called', () => {
+    agent = makeAgent();
+    const bytes = new TextEncoder().encode('<div>local-edit</div>');
+    const changed = agent.applyFromFs({
+      path: paths().html,
+      bytes,
+      hash: hashBytes(bytes),
+    });
+    expect(changed).toBe(true);
+    expect(htmlFromDoc(docA)).toBe('<div>local-edit</div>');
+  });
+
+  test('parses + applies comments JSON from disk', () => {
+    agent = makeAgent();
+    const snap = [{ id: 'c2' }];
+    const str = `${JSON.stringify(snap, null, 2)}\n`;
+    const bytes = new TextEncoder().encode(str);
+    agent.applyFromFs({ path: paths().comments, bytes, hash: hashBytes(bytes) });
+    expect(docA.getArray('comments').toArray()).toEqual(snap);
+  });
+
+  test('applies annotations SVG from disk', () => {
+    agent = makeAgent();
+    const bytes = new TextEncoder().encode('<svg>x</svg>');
+    agent.applyFromFs({ path: paths().annotations, bytes, hash: hashBytes(bytes) });
+    expect(docA.getMap<string>('annotations').get('svg')).toBe('<svg>x</svg>');
+  });
+
+  test('drops the fs-watch echo of its own atomic write', async () => {
+    agent = makeAgent();
+    // Peer edits → agent writes to disk → echo guard recorded.
+    applyHtmlToDoc(docA, '<button>hi</button>');
+    await agent.flush();
+
+    // Simulate the fs.watch firing for the path we just wrote.
+    const bytes = readFileSync(paths().html);
+    const u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const changed = agent.applyFromFs({
+      path: paths().html,
+      bytes: u8,
+      hash: hashBytes(u8),
+    });
+
+    expect(changed).toBe(false);
+  });
+});
+
+describe('CanvasSyncAgent — cold start reconciliation', () => {
+  test('hub-wins (default): overwrites disk when doc differs', async () => {
+    // Local disk has stale content.
+    writeFileSync(paths().html, '<old>');
+    // Hub state arrives via docA (propagated to docB before reconcile runs).
+    applyHtmlToDoc(docA, '<new>');
+
+    agent = makeAgent();
+    await agent.reconcile();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<new>');
+  });
+
+  test('adopt mode: pushes local disk state up to the doc', async () => {
+    writeFileSync(paths().html, '<button>local</button>');
+    // Hub has stale content.
+    applyHtmlToDoc(docA, '<old-hub>');
+
+    agent = makeAgent({ adopt: true });
+    await agent.reconcile();
+
+    expect(htmlFromDoc(docA)).toBe('<button>local</button>');
+    expect(htmlFromDoc(docB)).toBe('<button>local</button>');
+  });
+
+  test('adopt mode is one-shot — second reconcile is hub-wins', async () => {
+    writeFileSync(paths().html, '<button>local-v1</button>');
+    agent = makeAgent({ adopt: true });
+    await agent.reconcile();
+
+    // Hub changes the value.
+    applyHtmlToDoc(docA, '<button>hub-v2</button>');
+
+    // Disk reverts to a stale local-only state.
+    writeFileSync(paths().html, '<button>local-v3</button>');
+    await agent.reconcile();
+
+    // Hub state won this time.
+    expect(htmlFromDoc(docB)).toBe('<button>hub-v2</button>');
+  });
+
+  test('identical disk + doc states: no disk write', async () => {
+    writeFileSync(paths().html, '<button>same</button>');
+    applyHtmlToDoc(docA, '<button>same</button>');
+
+    agent = makeAgent();
+    let writes = 0;
+    const customAgent = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docB,
+      paths: paths(),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      writer: () => {
+        writes++;
+      },
+    });
+    customAgent.start();
+    await customAgent.reconcile();
+    customAgent.stop();
+
+    expect(writes).toBe(0);
+  });
+});
+
+describe('CanvasSyncAgent — stress: 100 rapid disk writes converge with no echo loop', () => {
+  test('100-event scenario from plan validate', async () => {
+    // Wire up fs-mirror against the temp dir so this looks like the production
+    // flow: file writes → fs.watch → fs-mirror debounce → agent.applyFromFs.
+    agent = makeAgent({ flushMs: 20 });
+
+    const reader = createFsReader({
+      rootDir: dir,
+      quietMs: 15,
+      accept: (p) => p.endsWith('.html'),
+      onRead: async (evt) => {
+        agent.applyFromFs({
+          path: join(dir, evt.path),
+          bytes: evt.bytes,
+          hash: evt.hash,
+        });
+      },
+    });
+
+    // Track how many times the doc transitioned — should be bounded, no echo
+    // loop multiplying it.
+    let docUpdates = 0;
+    docB.on('update', () => {
+      docUpdates++;
+    });
+
+    for (let i = 0; i < 100; i++) {
+      writeFileSync(paths().html, `<button>${i}</button>`);
+      reader.notify('screen.html');
+    }
+
+    // Let everything settle: reader quiet (15ms), agent flush (20ms) + slack.
+    await new Promise((res) => setTimeout(res, 200));
+    await reader.flush();
+    await agent.flush();
+    reader.stop();
+
+    // Doc + disk + peer all converge on the last write.
+    const last = '<button>99</button>';
+    expect(htmlFromDoc(docB)).toBe(last);
+    expect(htmlFromDoc(docA)).toBe(last);
+    expect(readFileSync(paths().html, 'utf8')).toBe(last);
+
+    // Update count must be bounded — strictly < 100 transitions (debounce did
+    // its job) AND < 200 (no echo loop running 2x amplification).
+    expect(docUpdates).toBeLessThan(200);
+    // Also: it should be > 0 — we DID see real syncs.
+    expect(docUpdates).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,63 @@
+// Atomic-write unit tests — Phase 9 Task 4.
+
+import { mkdtempSync, readFileSync, readdirSync, 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 { atomicWrite } from '../sync/atomic-write.ts';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'atomic-write-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('atomicWrite', () => {
+  test('writes UTF-8 string to a new path', () => {
+    const p = join(dir, 'a.html');
+    atomicWrite(p, '<button>hi</button>');
+    expect(readFileSync(p, 'utf8')).toBe('<button>hi</button>');
+  });
+
+  test('writes Uint8Array bytes verbatim', () => {
+    const p = join(dir, 'b.html');
+    const bytes = new TextEncoder().encode('<div>x</div>');
+    atomicWrite(p, bytes);
+    expect(readFileSync(p, 'utf8')).toBe('<div>x</div>');
+  });
+
+  test('overwrites existing files atomically (no partial-write window)', () => {
+    const p = join(dir, 'c.html');
+    writeFileSync(p, 'old');
+    atomicWrite(p, 'new');
+    expect(readFileSync(p, 'utf8')).toBe('new');
+  });
+
+  test('cleans up the .tmp sidecar after a successful write', () => {
+    const p = join(dir, 'd.html');
+    atomicWrite(p, 'final');
+    const leftovers = readdirSync(dir).filter((f) => f.startsWith('d.html.tmp.'));
+    expect(leftovers).toEqual([]);
+  });
+
+  test('rapid sequential writes converge on the last value', () => {
+    const p = join(dir, 'e.html');
+    for (let i = 0; i < 50; i++) {
+      atomicWrite(p, `v${i}`);
+    }
+    expect(readFileSync(p, 'utf8')).toBe('v49');
+    const leftovers = readdirSync(dir).filter((f) => f.startsWith('e.html.tmp.'));
+    expect(leftovers).toEqual([]);
+  });
+
+  test('returns the path it wrote', () => {
+    const p = join(dir, 'f.html');
+    expect(atomicWrite(p, 'x')).toBe(p);
+  });
+});