@1agh/maude 0.55.0 → 0.57.0

package/apps/studio/test/sync-connect-honesty.test.ts

@@ -0,0 +1,114 @@
+// A connect that has not connected must never read as synced.
+//
+// THE FALSIFIER. Written against the pre-fix pipeline and expected to FAIL
+// there — that failure is the evidence that the status signal is optimistic by
+// construction, not merely rendered late. If it ever passes without the
+// monitor changing, the premise of this whole change was wrong and the fix
+// should be dropped rather than the assertion softened.
+//
+// Reported as "vyskočí modal, pak vidím jen syncing canvases, ale reálně se nic
+// nestane": the user was told the truth about an intention and read it as a
+// result.
+//
+// The two monitor-level defects it pins:
+//   1. the monitor is BORN `online` — before a socket exists, before a token is
+//      accepted, before a byte moves. Every surface keys off that value.
+//   2. `docs.synced` can only ever rise — a hub that dies leaves the last count
+//      frozen on screen forever, indistinguishable from a healthy one.
+//
+// The surface-level defects (one connected provider out of many reading green,
+// and the status bar ignoring `docs` entirely) are pinned in
+// `sync-presentation.test.ts`, because they live in the presentation rule
+// rather than in the state machine.
+
+import { describe, expect, test } from 'bun:test';
+
+import { createConnectionMonitor, type SyncStatusSnapshot } from '../sync/connection-state.ts';
+
+/**
+ * The rule the shipped status bar applies (`app.jsx` syncSlot, pre-fix):
+ * green dot and the word "synced" whenever `state` is `online`.
+ *
+ * Reproduced verbatim rather than imported, so this test measures what a USER
+ * sees and cannot be quietly satisfied by editing the surface.
+ */
+function readsAsSynced(snap: SyncStatusSnapshot): boolean {
+  return snap.state === 'online' || snap.flash === 'synced';
+}
+
+function makeMonitor() {
+  const nowMs = 1_000_000;
+  const timers = new Map<number, { fireAt: number; cb: () => void }>();
+  let nextId = 1;
+  const monitor = createConnectionMonitor({
+    now: () => nowMs,
+    setTimer: (cb, ms) => {
+      const id = nextId++;
+      timers.set(id, { fireAt: nowMs + ms, cb });
+      return id as unknown as ReturnType<typeof setTimeout>;
+    },
+    clearTimer: (h) => {
+      timers.delete(h as unknown as number);
+    },
+  });
+  return { monitor };
+}
+
+describe('a connect that has not connected', () => {
+  test('does not read as synced at t=0', () => {
+    // The instant after Connect: the runtime started, providers exist on paper,
+    // nothing has handshaken. This is precisely the moment the user is staring
+    // at the note, and the moment the old pipeline claimed success.
+    const { monitor } = makeMonitor();
+    expect(readsAsSynced(monitor.snapshot())).toBe(false);
+  });
+
+  test('does not read as synced while every document is still pending', () => {
+    const { monitor } = makeMonitor();
+    for (const slug of ['ui-home', 'ui-about', 'ui-welcome']) {
+      monitor.noteDocState(slug, 'pending');
+    }
+    const snap = monitor.snapshot();
+    expect(snap.docs).toEqual({ synced: 0, pending: 3, rejected: 0 });
+    expect(readsAsSynced(snap)).toBe(false);
+  });
+
+  test('does not read as synced when the hub refuses every document', () => {
+    // A rotated credential: providers reach the hub, the hub says no. Nothing
+    // is syncing, and the count that would say so must not claim otherwise.
+    const { monitor } = makeMonitor();
+    for (const slug of ['ui-home', 'ui-about']) {
+      monitor.noteDocState(slug, 'auth-rejected');
+    }
+    expect(monitor.snapshot().docs).toEqual({ synced: 0, pending: 0, rejected: 2 });
+  });
+});
+
+describe('a connect that stops being connected', () => {
+  test('docs.synced falls when the providers drop', () => {
+    // Today nothing demotes a connected document, so a hub that dies leaves
+    // "3 synced" on screen indefinitely — the most convincing possible lie,
+    // because it was true a moment ago.
+    const { monitor } = makeMonitor();
+    for (const slug of ['a', 'b', 'c']) {
+      monitor.noteProviderStatus(slug, 'connected');
+      monitor.noteDocState(slug, 'connected');
+    }
+    expect(monitor.snapshot().docs?.synced).toBe(3);
+
+    for (const slug of ['a', 'b', 'c']) monitor.noteProviderStatus(slug, 'disconnected');
+
+    const snap = monitor.snapshot();
+    expect(snap.docs?.synced).toBe(0);
+    expect(snap.docs?.pending).toBe(3);
+  });
+
+  test('a refusal is not transient — a dropped provider cannot launder it', () => {
+    // `auth-rejected` outranks a disconnect: the hub gave an answer, and losing
+    // the socket does not turn that answer back into "still trying".
+    const { monitor } = makeMonitor();
+    monitor.noteDocState('a', 'auth-rejected');
+    monitor.noteProviderStatus('a', 'disconnected');
+    expect(monitor.snapshot().docs).toEqual({ synced: 0, pending: 0, rejected: 1 });
+  });
+});

package/apps/studio/test/sync-connection-state.test.ts

@@ -52,12 +52,26 @@ function makeMonitor(overrides = {}) {
 }
 
 describe('connection monitor', () => {
-  test('starts online and stays online when the provider connects', () => {
+  test('starts connecting, and goes online when the provider connects', () => {
+    // The seed used to be `online` — success asserted before a socket existed.
+    // See `sync-connect-honesty.test.ts` for why that mattered to a user.
     const { monitor } = makeMonitor();
+    expect(monitor.snapshot().state).toBe('connecting');
     monitor.noteProviderStatus('p1', 'connected');
     expect(monitor.snapshot().state).toBe('online');
   });
 
+  test('a link nobody answers still escalates to offline', () => {
+    // The seed change must not create a state that waits forever: a provider
+    // that only ever reports 'connecting' has to reach the offline banner on
+    // the same grace clock as a link that dropped after being live.
+    const { clock, monitor } = makeMonitor();
+    monitor.noteProviderStatus('p1', 'connecting');
+    expect(monitor.snapshot().state).toBe('connecting');
+    clock.advance(30_000);
+    expect(monitor.snapshot().state).toBe('offline');
+  });
+
   test('disconnect → stays connecting during grace, goes offline after graceMs', () => {
     const { clock, monitor } = makeMonitor();
     monitor.noteProviderStatus('p1', 'connected');
@@ -212,3 +226,33 @@ describe('connection monitor — per-doc states (DDR-102)', () => {
     expect(monitor.snapshot().lastSyncAt).toBe((first as number) + 10_000);
   });
 });
+
+describe('what this run pulled down', () => {
+  // This field was `remoteGap`, "what the project has that this machine does
+  // not" — and it was recorded AFTER the pull, so it named exactly the
+  // canvases that had just arrived. `_sync.json` was observed listing two
+  // documents that were sitting on disk. The name now matches the fact.
+  test('records the canvases that arrived, with a true count', () => {
+    const { monitor } = makeMonitor();
+    monitor.notePulled(['ui-welcome', 'ui-how-to']);
+    expect(monitor.snapshot().pulled).toEqual({
+      names: ['ui-welcome', 'ui-how-to'],
+      count: 2,
+    });
+  });
+
+  test('a run that pulled nothing says nothing', () => {
+    const { monitor } = makeMonitor();
+    monitor.notePulled([]);
+    expect(monitor.snapshot().pulled).toBeUndefined();
+  });
+
+  test('the name list is capped but the count is not — a cap must not falsify a number', () => {
+    // Hub-controlled payload size (same reasoning as rejectedSlugs).
+    const { monitor } = makeMonitor();
+    monitor.notePulled(Array.from({ length: 50 }, (_, i) => `ui-${i}`));
+    const pulled = monitor.snapshot().pulled;
+    expect(pulled?.names).toHaveLength(20);
+    expect(pulled?.count).toBe(50);
+  });
+});

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

@@ -0,0 +1,185 @@
+// The one rule both sync surfaces read — see sync/presentation.ts.
+//
+// Pins the two SURFACE defects that the monitor-level falsifier
+// (`sync-connect-honesty.test.ts`) deliberately leaves alone:
+//   - a link with refusals reading green, because the old status bar keyed off
+//     `state` and never looked at `docs` at all;
+//   - the status bar and the connect note being able to disagree, because they
+//     were two rules over one payload.
+//
+// Every row of the plan's states/copy table gets a case, and each asserts the
+// state names a NEXT ACTION where one exists — the user's explicit ask.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type SyncStatusLike, syncPresentation } from '../sync/presentation.ts';
+
+const base: SyncStatusLike = {
+  state: 'online',
+  queuedOps: 0,
+  lastSyncAt: null,
+  offlineSince: null,
+  flash: null,
+  updatedAt: 0,
+};
+
+const at = (over: SyncStatusLike) =>
+  syncPresentation({ ...base, ...over }, { project: 'alligators' });
+
+describe('nothing to say', () => {
+  test('an unlinked project has no hub status', () => {
+    expect(syncPresentation({ linked: false })).toBeNull();
+    expect(syncPresentation(null)).toBeNull();
+  });
+});
+
+describe('the states a person passes through', () => {
+  test('connecting — no document has settled yet', () => {
+    const p = at({ state: 'connecting', docs: { synced: 0, pending: 3, rejected: 0 } });
+    expect(p?.phase).toBe('connecting');
+    expect(p?.online).toBe(false);
+    expect(p?.title).toContain('Connecting to alligators');
+  });
+
+  test('syncing — visible progress, with a real count', () => {
+    const p = at({ docs: { synced: 40, pending: 35, rejected: 0 } });
+    expect(p?.phase).toBe('syncing');
+    expect(p?.online).toBe(false);
+    expect(p?.label).toBe('40/75');
+    expect(p?.title).toContain('40 of 75');
+  });
+
+  test('synced — and names what arrived, without telling you to open it', () => {
+    const p = at({
+      docs: { synced: 75, pending: 0, rejected: 0 },
+      pulled: { names: ['ui-welcome', 'ui-how-to'], count: 2 },
+    });
+    expect(p?.phase).toBe('synced');
+    expect(p?.online).toBe(true);
+    expect(p?.title).toContain('2 came down');
+    // Names the fact; the decision to open hub-authored TSX stays the person's.
+    expect(p?.next).toContain('new to this machine');
+    expect(p?.next).not.toContain('Open one');
+    expect(p?.names).toEqual(['ui-welcome', 'ui-how-to']);
+  });
+
+  test('synced with nothing pulled has no next action — because there is none', () => {
+    const p = at({ docs: { synced: 5, pending: 0, rejected: 0 } });
+    expect(p?.phase).toBe('synced');
+    expect(p?.next).toBeNull();
+  });
+});
+
+describe('the states that used to read green', () => {
+  test('a hub that refuses everything is not synced', () => {
+    // THE surface defect: `state` is 'online' (a socket exists, the hub is
+    // reachable) while every document's edits go nowhere. The old status bar
+    // showed a green dot and the word "synced" here.
+    const p = at({ state: 'online', docs: { synced: 0, pending: 0, rejected: 75 } });
+    expect(p?.phase).toBe('refused');
+    expect(p?.online).toBe(false);
+    expect(p?.label).toBe('75 refused');
+    expect(p?.next).toContain('Reconnect');
+  });
+
+  test('a partial refusal is reported, not averaged away', () => {
+    const p = at({ state: 'online', docs: { synced: 72, pending: 0, rejected: 3 } });
+    expect(p?.phase).toBe('refused');
+    expect(p?.title).toContain('3 of 75');
+  });
+
+  test('an unreachable hub outranks a stale count', () => {
+    const p = at({ state: 'offline', queuedOps: 4, docs: { synced: 75, pending: 0, rejected: 0 } });
+    expect(p?.phase).toBe('offline');
+    expect(p?.online).toBe(false);
+    expect(p?.label).toBe('offline · 4 ↑');
+    expect(p?.next).toContain('resumes by itself');
+  });
+});
+
+describe('payloads that predate the counts', () => {
+  test('an old payload falls back to state without inventing document facts', () => {
+    const p = at({ state: 'online', docs: undefined });
+    expect(p?.phase).toBe('synced');
+    expect(p?.title).not.toContain('canvas');
+  });
+
+  test('a linked project with zero known documents reads as connecting, not synced', () => {
+    const p = at({ state: 'online', docs: { synced: 0, pending: 0, rejected: 0 } });
+    expect(p?.phase).toBe('connecting');
+    expect(p?.online).toBe(false);
+  });
+
+  test('nothing syncable keeps its own honest copy and names the move', () => {
+    const p = syncPresentation({ notSyncable: true, tsxCount: 4, reason: 'No canvases yet.' });
+    expect(p?.phase).toBe('nothing-syncable');
+    expect(p?.label).toBe('0 syncable · 4 tsx');
+    expect(p?.next).toContain('Create a canvas');
+  });
+});
+
+describe('a payload it cannot read is not a payload that says everything is fine', () => {
+  // `/_sync-status` returns JSON.parse of `_sync.json` with NO schema, so the
+  // input here is whatever is on disk — a partial write, an older producer, a
+  // newer one. `synced` used to be the fall-through, which made the reassuring
+  // answer the only reachable one for every shape not recognised.
+  test('an empty docs object does not render as "all NaN canvases", green', () => {
+    const p = at({ state: 'online', docs: {} as never });
+    expect(p?.phase).not.toBe('synced');
+    expect(p?.online).toBe(false);
+    expect(p?.title).not.toContain('NaN');
+  });
+
+  test('negative, fractional and non-numeric counts all fail closed', () => {
+    for (const docs of [
+      { synced: 5, pending: -5, rejected: 0 },
+      { synced: 1, pending: null, rejected: 0 },
+      { synced: 1.5, pending: 0, rejected: 0 },
+      { synced: '75', pending: 0, rejected: 0 },
+    ] as never[]) {
+      const p = at({ state: 'online', docs });
+      expect(p?.online).toBe(false);
+      expect(p?.phase).not.toBe('synced');
+    }
+  });
+
+  test('an absent docs field is still the old-payload path, not "unreadable"', () => {
+    // Absent and malformed are different facts and must not collapse.
+    const p = at({ state: 'online', docs: undefined });
+    expect(p?.phase).toBe('synced');
+  });
+
+  test('a wild pulled count cannot reach the sentence', () => {
+    const p = at({
+      docs: { synced: 1, pending: 0, rejected: 0 },
+      pulled: { names: [], count: 1e9 } as never,
+    });
+    expect(p?.title).not.toContain('1000000000');
+  });
+});
+
+describe('hub-supplied text is untrusted (DDR-054)', () => {
+  test('counts come first and names are capped in number', () => {
+    const p = at({
+      state: 'online',
+      docs: { synced: 0, pending: 0, rejected: 9 },
+      rejectedSlugs: ['a', 'b', 'c', 'd', 'e'],
+    });
+    expect(p?.names).toHaveLength(3);
+    // The label a hostile name could otherwise dominate carries no name at all.
+    expect(p?.label).toBe('9 refused');
+  });
+
+  test('a long project name cannot run away with the sentence', () => {
+    const p = syncPresentation(
+      { ...base, docs: { synced: 1, pending: 0, rejected: 0 } },
+      { project: 'x'.repeat(500) }
+    );
+    expect(p?.title.length).toBeLessThan(200);
+  });
+
+  test('names survive being absent or empty', () => {
+    const p = at({ state: 'online', docs: { synced: 0, pending: 0, rejected: 2 } });
+    expect(p?.names).toEqual([]);
+  });
+});

package/apps/studio/test/sync-remote-docs.test.ts

@@ -0,0 +1,171 @@
+// The gap between what a project HOLDS and what this machine carries.
+//
+// Regression cover for the reported "Open in Maude does nothing": the desktop
+// synced 72/72 and was accurate about the wrong set — three canvases lived only
+// on the hub and no local counter could ever show it.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  describeRemoteDiff,
+  diffRemoteDocs,
+  fetchRemoteDocs,
+  pullTargets,
+  slugFromDocName,
+} from '../sync/remote-docs.ts';
+
+const okFetch = (documents: unknown) =>
+  (async () =>
+    new Response(JSON.stringify({ documents }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })) as unknown as typeof fetch;
+
+describe('fetchRemoteDocs', () => {
+  test('reads the hub listing', async () => {
+    const docs = await fetchRemoteDocs(
+      'https://hub.example',
+      't',
+      okFetch([{ name: 'ui-welcome', bytes: 2931 }])
+    );
+    expect(docs).toEqual([{ name: 'ui-welcome', bytes: 2931 }]);
+  });
+
+  test('carries the token as a bearer, and strips a trailing slash', async () => {
+    let seenUrl = '';
+    let seenAuth = '';
+    const spy = (async (url: string, init: RequestInit) => {
+      seenUrl = String(url);
+      seenAuth = String((init.headers as Record<string, string>).authorization);
+      return new Response(JSON.stringify({ documents: [] }), { status: 200 });
+    }) as unknown as typeof fetch;
+    await fetchRemoteDocs('https://hub.example/', 'tok123', spy);
+    expect(seenUrl).toBe('https://hub.example/api/documents');
+    expect(seenAuth).toBe('Bearer tok123');
+  });
+
+  test('an unreachable or old hub yields null, never a throw', async () => {
+    // Load-bearing: sync must proceed when the listing cannot be had. A hub
+    // without the route (404) must not degrade into a failed sync.
+    const boom = (async () => {
+      throw new Error('offline');
+    }) as unknown as typeof fetch;
+    expect(await fetchRemoteDocs('https://h', 't', boom)).toBeNull();
+
+    const notFound = (async () => new Response('nope', { status: 404 })) as unknown as typeof fetch;
+    expect(await fetchRemoteDocs('https://h', 't', notFound)).toBeNull();
+
+    const junk = (async () =>
+      new Response(JSON.stringify({ documents: 'not-an-array' }), {
+        status: 200,
+      })) as unknown as typeof fetch;
+    expect(await fetchRemoteDocs('https://h', 't', junk)).toBeNull();
+  });
+});
+
+describe('diffRemoteDocs', () => {
+  test('names the canvases this machine can never receive', () => {
+    // The reported case, in miniature.
+    const diff = diffRemoteDocs(
+      ['ui-home', 'ui-about'],
+      [
+        { name: 'ui-home', bytes: 1 },
+        { name: 'ui-about', bytes: 1 },
+        { name: 'ui-welcome', bytes: 2931 },
+      ]
+    );
+    expect(diff.shared).toEqual(['ui-about', 'ui-home']);
+    expect(diff.hubOnly.map((d) => d.name)).toEqual(['ui-welcome']);
+    expect(diff.localOnly).toEqual([]);
+    expect(diff.reachable).toBe(true);
+  });
+
+  test('a canvas created here but not yet pushed is localOnly, not a gap', () => {
+    const diff = diffRemoteDocs(['ui-new'], []);
+    expect(diff.localOnly).toEqual(['ui-new']);
+    expect(diff.hubOnly).toEqual([]);
+  });
+
+  test('an unreachable hub reports NOT reachable rather than a false gap', () => {
+    // Reporting every local canvas as "hub-only missing" would be worse than
+    // saying nothing — it would invent an alarm out of a network blip.
+    const diff = diffRemoteDocs(['ui-home'], null);
+    expect(diff.reachable).toBe(false);
+    expect(diff.hubOnly).toEqual([]);
+  });
+
+  test('compares WIRE names — a namespaced hub vs flat local is a real mismatch', () => {
+    // If a caller passed raw slugs against a namespaced hub, everything would
+    // look missing on both sides. The diff reports exactly that rather than
+    // papering over it, because it IS the doc-identity bug (DDR-192 §5).
+    const diff = diffRemoteDocs(['ui-home'], [{ name: 'ws/acme/main/ui-home', bytes: 1 }]);
+    expect(diff.shared).toEqual([]);
+    expect(diff.hubOnly.map((d) => d.name)).toEqual(['ws/acme/main/ui-home']);
+    expect(diff.localOnly).toEqual(['ui-home']);
+  });
+});
+
+describe('describeRemoteDiff', () => {
+  test('says what is missing, with names', () => {
+    const msg = describeRemoteDiff(
+      diffRemoteDocs(
+        [],
+        [
+          { name: 'ui-welcome', bytes: 1 },
+          { name: 'ui-how_to_use_maude', bytes: 1 },
+        ]
+      )
+    );
+    expect(msg).toContain('2 canvases');
+    expect(msg).toContain('ui-welcome');
+  });
+
+  test('stays quiet when there is nothing to report', () => {
+    expect(describeRemoteDiff(diffRemoteDocs(['a'], [{ name: 'a', bytes: 1 }]))).toBeNull();
+    expect(describeRemoteDiff(diffRemoteDocs(['a'], null))).toBeNull();
+  });
+});
+
+describe('pulling hub-only documents down', () => {
+  const join = (...p: string[]) => p.join('/');
+  const resolve = (p: string) => p.replace(/\/\.\//g, '/');
+
+  test('maps a flat and a namespaced doc name to the same slug', () => {
+    expect(slugFromDocName('ui-welcome')).toBe('ui-welcome');
+    expect(slugFromDocName('ws/acme/main/ui-welcome')).toBe('ui-welcome');
+  });
+
+  test('lands hub-only canvases flat under the design root', () => {
+    const targets = pullTargets(
+      [
+        { name: 'ui-welcome', bytes: 1 },
+        { name: 'ws/acme/main/ui-home', bytes: 1 },
+      ],
+      '/p/.design',
+      join,
+      resolve,
+      '/'
+    );
+    expect(targets.map((t) => t.bodyAbs)).toEqual([
+      '/p/.design/ui-welcome.tsx',
+      '/p/.design/ui-home.tsx',
+    ]);
+    // The wire name is kept — the provider must open the document the HUB has,
+    // not a name re-derived from the local path.
+    expect(targets[1].docName).toBe('ws/acme/main/ui-home');
+  });
+
+  test('a document NAME can never write outside the design root', () => {
+    // Hub-controlled input, last point before a create. Dots are refused
+    // outright, so traversal cannot even form a candidate path.
+    const evil = [
+      { name: '../../etc/passwd', bytes: 1 },
+      { name: '..', bytes: 1 },
+      { name: 'ui/../../escape', bytes: 1 },
+      { name: 'a b', bytes: 1 },
+      { name: '', bytes: 1 },
+      { name: 'x'.repeat(500), bytes: 1 },
+    ];
+    expect(pullTargets(evil, '/p/.design', join, resolve, '/')).toEqual([]);
+  });
+});