@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/test/sync-migrate-flat-fallback.test.ts

@@ -0,0 +1,98 @@
+// Fix 4 of the 2026-08-10 sync RCA — the one-shot quarantine of pre-fix-5
+// flat fallback twins. The rules under test: a flat body moves ONLY when a
+// grouped twin of the same slug exists; siblings ride along; annotations stay
+// (they serve the surviving twin); a lone flat canvas is somebody's work and
+// never moves; a second run is a no-op; nothing ever throws into boot.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { migrateFlatFallback } from '../sync/migrate-flat-fallback.ts';
+
+let designRoot: string;
+
+beforeEach(() => {
+  designRoot = mkdtempSync(join(tmpdir(), 'migrate-flat-'));
+});
+
+afterEach(() => {
+  rmSync(designRoot, { recursive: true, force: true });
+});
+
+const run = () => migrateFlatFallback({ designRoot, designRel: '.design', log: () => {} });
+
+describe('migrateFlatFallback — quarantine the redundant flat copy, never work', () => {
+  test('a collision pair: the flat copy (+ siblings) moves to _trash, the grouped twin stays', () => {
+    mkdirSync(join(designRoot, 'ui'), { recursive: true });
+    writeFileSync(join(designRoot, 'ui/welcome.tsx'), 'grouped\n');
+    writeFileSync(join(designRoot, 'ui-welcome.tsx'), 'flat stub\n');
+    writeFileSync(join(designRoot, 'ui-welcome.meta.json'), '{}\n');
+    writeFileSync(join(designRoot, 'ui-welcome.css'), '.x{}\n');
+    // Annotations are keyed by the flat slug and serve the SURVIVING twin.
+    writeFileSync(join(designRoot, 'ui-welcome.annotations.svg'), '<svg/>\n');
+
+    const moves = run();
+
+    expect(moves).toHaveLength(1);
+    expect(moves[0].slug).toBe('ui-welcome');
+    expect(moves[0].from).toBe('ui-welcome.tsx');
+    expect(moves[0].keptTwin).toBe('ui/welcome.tsx');
+
+    expect(existsSync(join(designRoot, 'ui/welcome.tsx'))).toBe(true);
+    expect(existsSync(join(designRoot, 'ui-welcome.tsx'))).toBe(false);
+    expect(existsSync(join(designRoot, 'ui-welcome.meta.json'))).toBe(false);
+    expect(existsSync(join(designRoot, 'ui-welcome.css'))).toBe(false);
+    expect(existsSync(join(designRoot, 'ui-welcome.annotations.svg'))).toBe(true);
+
+    const trashed = readdirSync(join(designRoot, moves[0].trashedTo)).sort();
+    expect(trashed).toEqual(['ui-welcome.css', 'ui-welcome.meta.json', 'ui-welcome.tsx']);
+  });
+
+  test('a lone flat canvas has no twin — it is somebody’s work and stays put', () => {
+    writeFileSync(join(designRoot, 'scratch-pad.tsx'), 'mine\n');
+    expect(run()).toEqual([]);
+    expect(existsSync(join(designRoot, 'scratch-pad.tsx'))).toBe(true);
+  });
+
+  test('a grouped file with no flat twin is untouched', () => {
+    mkdirSync(join(designRoot, 'ui'), { recursive: true });
+    writeFileSync(join(designRoot, 'ui/card.tsx'), 'x\n');
+    expect(run()).toEqual([]);
+    expect(existsSync(join(designRoot, 'ui/card.tsx'))).toBe(true);
+  });
+
+  test('the second run is a no-op — the quarantine dir is runtime state the scan skips', () => {
+    mkdirSync(join(designRoot, 'ui'), { recursive: true });
+    writeFileSync(join(designRoot, 'ui/welcome.tsx'), 'grouped\n');
+    writeFileSync(join(designRoot, 'ui-welcome.tsx'), 'flat stub\n');
+
+    expect(run()).toHaveLength(1);
+    expect(run()).toEqual([]);
+    // The quarantined copy is still there — moved, never deleted.
+    const trash = readdirSync(join(designRoot, '_trash'));
+    expect(trash).toHaveLength(1);
+  });
+
+  test('nested twins at any depth count', () => {
+    mkdirSync(join(designRoot, 'ui/2026/social'), { recursive: true });
+    writeFileSync(join(designRoot, 'ui/2026/social/summer-camp.tsx'), 'deep\n');
+    writeFileSync(join(designRoot, 'ui-2026-social-summer-camp.tsx'), 'flat stub\n');
+
+    const moves = run();
+    expect(moves).toHaveLength(1);
+    expect(moves[0].keptTwin).toBe('ui/2026/social/summer-camp.tsx');
+    expect(existsSync(join(designRoot, 'ui/2026/social/summer-camp.tsx'))).toBe(true);
+  });
+
+  test('a missing design root is a quiet no-op, not a throw', () => {
+    expect(
+      migrateFlatFallback({
+        designRoot: join(designRoot, 'does-not-exist'),
+        designRel: '.design',
+        log: () => {},
+      })
+    ).toEqual([]);
+  });
+});

package/apps/studio/test/sync-panel-surface.test.ts

@@ -0,0 +1,90 @@
+// feature-sync-progress-modal — the Sync panel + HUB SYNC chip surface.
+//
+// Source-level assertions (cloud-shell-surfaces style): what these pin is
+// exactly what would regress — someone dropping the linked-only gate (a solo
+// project would get a dock tab that opens onto nothing), rewiring the chip
+// away from the dock helpers (breaking the one-panel-per-side invariant), or
+// the panel inventing sync vocabulary / dropping the a11y live region the
+// CloudBar note established.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const APP = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+const PANEL = readFileSync(join(STUDIO, 'client', 'panels', 'SyncPanel.jsx'), 'utf8');
+
+describe('the Sync panel exists only where a hub link exists', () => {
+  test('sync is a dock panel with a right-side default', () => {
+    expect(APP).toContain("{ id: 'sync', label: 'Sync' }");
+    expect(APP).toMatch(/sync: 'right'/);
+  });
+
+  test('panelAvailable gates sync on a live syncStatus — solo projects get no tab', () => {
+    expect(APP).toContain("if (id === 'sync') return !!syncStatus;");
+  });
+
+  test('the chip toggles through the dock helpers, not a raw setState', () => {
+    // toggleRightPanel keeps the one-panel-per-side invariant; a bare
+    // setSyncPanelOpen(true) here would let Sync render behind an open sibling.
+    expect(APP).toMatch(/onOpenSync=\{syncStatus \? \(\) => toggleRightPanel\('sync'\)/);
+  });
+
+  test('the chip is a real button with pressed-state semantics', () => {
+    expect(APP).toContain('data-testid="open-sync"');
+    expect(APP).toMatch(/aria-pressed=\{syncOpen\}/);
+  });
+
+  test('the span fallback remains for sessions without a handler', () => {
+    // Older wiring / no-handler renders must keep the passive chip rather
+    // than a dead button.
+    expect(APP).toMatch(/onOpenSync \? \(/);
+  });
+});
+
+describe('the Sync panel speaks the presentation vocabulary, safely', () => {
+  test('the header sentence comes from syncPresentation — the one shared rule', () => {
+    expect(PANEL).toContain("from '../../sync/presentation.ts'");
+    expect(PANEL).toContain('syncPresentation(status');
+  });
+
+  test('rows map DocSyncState onto existing words, never new ones', () => {
+    expect(PANEL).toMatch(/pending: 'syncing'/);
+    expect(PANEL).toMatch(/connected: 'synced'/);
+    expect(PANEL).toMatch(/'auth-rejected': 'refused'/);
+  });
+
+  test('every name that reaches the DOM goes through safeName', () => {
+    // Slugs and asset keys are local, but the payload is read back off disk —
+    // bounded text-only rendering is the house rule (DDR-054).
+    expect(PANEL).toContain('import { safeName, syncPresentation }');
+    expect(PANEL).not.toMatch(/dangerouslySetInnerHTML/);
+  });
+
+  test('the live header is a polite status region (the CloudBar a11y pattern)', () => {
+    expect(PANEL).toMatch(/role="status" aria-live="polite"/);
+  });
+
+  test('the asset lane renders from the payload, with the retry promise', () => {
+    expect(PANEL).toContain('data-testid="sync-assets"');
+    expect(PANEL).toContain('retry on the next launch');
+  });
+});
+
+describe('the panel reads the off-disk payload fail-closed (DDR-102 discipline)', () => {
+  test('items, assets and the header counts all pass a readCounts-style gate', () => {
+    // `_sync.json` is JSON.parse with no schema — a partial write or older
+    // producer must degrade to "nothing to show", never crash or print NaN
+    // (security review 2026-08-11, defender W1).
+    expect(PANEL).toContain('function readItems(');
+    expect(PANEL).toContain('function readAssets(');
+    expect(PANEL).toContain('readItems(status?.items)');
+    expect(PANEL).toContain('readAssets(status?.assets)');
+    expect(PANEL).toMatch(/Number\.isInteger/);
+    // The header chip validates the same counts the note fails closed on.
+    expect(PANEL).toMatch(
+      /\[rawDocs\.synced, rawDocs\.pending, rawDocs\.rejected\]\.every\(isCount\)/
+    );
+  });
+});

package/apps/studio/test/sync-path-pull.test.ts

@@ -233,6 +233,69 @@ describe('a peer with an empty design root pulls the project down whole', () =>
   });
 });
 
+describe('boot runs the flat-fallback quarantine BEFORE the scan (fix 4)', () => {
+  test('a pre-fix-5 flat twin is in _trash by the time the runtime settles', async () => {
+    const ctx = makeCtx();
+    mkdirSync(join(ctx.paths.designRoot, 'ui'), { recursive: true });
+    writeFileSync(join(ctx.paths.designRoot, 'ui/welcome.tsx'), 'grouped\n');
+    writeFileSync(join(ctx.paths.designRoot, 'ui-welcome.tsx'), 'flat stub\n');
+    hubListing([]);
+
+    const runtime = createSyncRuntime(ctx, { providerFactory: hubDocProviderFactory({}) });
+    await runtime?.start();
+    await runtime?.stop();
+
+    expect(existsSync(join(ctx.paths.designRoot, 'ui-welcome.tsx'))).toBe(false);
+    expect(existsSync(join(ctx.paths.designRoot, 'ui/welcome.tsx'))).toBe(true);
+    expect(existsSync(join(ctx.paths.designRoot, '_trash'))).toBe(true);
+  });
+});
+
+describe('the stamp race — the path is on the doc BEFORE the handshake (fix 5)', () => {
+  test('a local canvas stamps syncMeta.path before onceSynced, so the hub’s first store sees it', async () => {
+    // The RCA bug: the stamp lived only in the post-reconcile tail, so the
+    // hub's FIRST onDocumentStored saw a bare body, memoised the flat fallback
+    // in its pathIndex, and the real nested path could never win — a stub was
+    // born whose dynamic import failed forever.
+    const ctx = makeCtx();
+    const bodyAbs = join(ctx.paths.designRoot, NESTED_REL);
+    mkdirSync(join(ctx.paths.designRoot, 'ui/2026/social'), { recursive: true });
+    writeFileSync(bodyAbs, BODY);
+    hubListing([]);
+
+    let pathAtHandshake: unknown = 'never-called';
+    const runtime = createSyncRuntime(ctx, {
+      canvases: [
+        {
+          slug: NESTED_SLUG,
+          html: bodyAbs,
+          comments: join(ctx.paths.commentsDir, `${NESTED_SLUG}.json`),
+          annotations: join(ctx.paths.designRoot, `${NESTED_SLUG}.annotations.svg`),
+          meta: bodyAbs.replace(/\.tsx$/, '.meta.json'),
+          css: bodyAbs.replace(/\.tsx$/, '.css'),
+        },
+      ],
+      providerFactory: (args) => {
+        const doc = args.document ?? new Y.Doc();
+        return {
+          document: doc,
+          awareness: new Awareness(doc),
+          async onceSynced() {
+            // What the hub can see by the time the handshake settles — the
+            // stamp must ALREADY be there, not arrive with the reconcile tail.
+            pathAtHandshake = doc.getMap('syncMeta').get('path');
+          },
+          destroy() {},
+        };
+      },
+    });
+    await runtime?.start();
+    await runtime?.stop();
+
+    expect(pathAtHandshake).toBe(NESTED_REL);
+  });
+});
+
 describe("rule 7 governs a path's IDENTITY, not what already lives there", () => {
   test('a pulled canvas never lands on a file that already exists locally', async () => {
     // `scanCanvases` omits a canvas whose `.meta.json` says `syncable: false` —

package/apps/studio/test/sync-presentation.test.ts

@@ -183,3 +183,80 @@ describe('hub-supplied text is untrusted (DDR-054)', () => {
     expect(p?.names).toEqual([]);
   });
 });
+
+describe('zero progress has a deadline — the stalled phase', () => {
+  const NOW = 10 * 60_000; // 10 minutes after the epoch-zero base
+
+  test('connecting past the ceiling with nothing synced becomes stalled, with the move named', () => {
+    const p = syncPresentation(
+      { ...base, state: 'connecting', startedAt: 1, docs: { synced: 0, pending: 73, rejected: 0 } },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('stalled');
+    expect(p?.online).toBe(false);
+    expect(p?.title).toContain('Nothing has synced');
+    expect(p?.next).toContain('Reconnect');
+  });
+
+  test('a fresh connect is NOT stalled — the handshake gets its moment', () => {
+    const p = syncPresentation(
+      { ...base, state: 'connecting', startedAt: 1, docs: { synced: 0, pending: 73, rejected: 0 } },
+      { project: 'alligators', now: 30_000 }
+    );
+    expect(p?.phase).toBe('connecting');
+  });
+
+  test('any progress at all cancels the stall — syncing is not stalling', () => {
+    const p = syncPresentation(
+      { ...base, startedAt: 1, docs: { synced: 1, pending: 72, rejected: 0 } },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('syncing');
+  });
+
+  test('zero known documents past the ceiling also stalls', () => {
+    const p = syncPresentation(
+      { ...base, state: 'connecting', startedAt: 1, docs: { synced: 0, pending: 0, rejected: 0 } },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('stalled');
+  });
+
+  test('an old payload without startedAt can never stall (fail open to connecting)', () => {
+    const p = syncPresentation(
+      { ...base, state: 'connecting' },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('connecting');
+  });
+
+  test('a refusal still outranks a stall — the more specific cause wins', () => {
+    const p = syncPresentation(
+      { ...base, startedAt: 1, docs: { synced: 0, pending: 0, rejected: 73 } },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('refused');
+  });
+
+  test('an unreachable hub still outranks a stall — offline explains itself', () => {
+    const p = syncPresentation(
+      { ...base, state: 'offline', startedAt: 1, docs: { synced: 0, pending: 3, rejected: 0 } },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('offline');
+  });
+
+  test('a garbage startedAt fails open, never into a false alarm', () => {
+    const p = syncPresentation(
+      // biome-ignore lint/suspicious/noExplicitAny: hostile-payload shape test
+      {
+        ...base,
+        state: 'connecting',
+        startedAt: 'yes' as any,
+        docs: { synced: 0, pending: 1, rejected: 0 },
+      },
+      { project: 'alligators', now: NOW }
+    );
+    expect(p?.phase).toBe('connecting');
+  });
+});