@1agh/maude 0.60.2 → 0.60.4

package/apps/studio/test/sync-two-peer-discovery.test.ts

@@ -0,0 +1,343 @@
+// Two peers, one hub — the reported bug, end to end, in both directions.
+//
+// The unit tests in `sync-attach-incremental.test.ts` pin each half against a
+// stub. This one puts TWO REAL RUNTIMES on one shared hub and asks the question
+// the user actually asked: if somebody makes a canvas over there, does it show
+// up over here, live, without anyone restarting anything?
+//
+// Both directions are the same code — the cell runs the same runtime the
+// desktop does — so a test that only checked one would prove half of nothing.
+// The reported asymmetry (desktop→cloud "worked", cloud→desktop never did) was
+// never about direction: it was about which end happens to restart.
+//
+// WHAT IS ASSERTED. Not `size()`, which a runtime can inflate by opening a
+// provider it never connects. The peer's CONTENT has to arrive, its later edits
+// have to keep flowing, and the awareness bridge — the thing behind cursors —
+// has to be attached for the canvas that was discovered, not merely for the
+// ones that existed at boot.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import type { Context, DevServerConfig } from '../context.ts';
+import { createBus } from '../context.ts';
+import type { AwarenessRegistry } from '../sync/index.ts';
+import { createSyncRuntime, type SyncProvider, type SyncRuntime } from '../sync/index.ts';
+
+const HUB = 'https://hub.example.com';
+
+let root: string;
+let cfgPathEnv: string | undefined;
+let realFetch: typeof fetch;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'two-peer-'));
+  cfgPathEnv = process.env.HUBS_CONFIG_PATH;
+  process.env.HUBS_CONFIG_PATH = join(root, 'hubs.json');
+  writeFileSync(
+    process.env.HUBS_CONFIG_PATH,
+    JSON.stringify({ hubs: { [HUB]: { token: 'mau_test', linkedAt: 1 } } })
+  );
+  chmodSync(process.env.HUBS_CONFIG_PATH, 0o600);
+  realFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  if (cfgPathEnv === undefined) delete process.env.HUBS_CONFIG_PATH;
+  else process.env.HUBS_CONFIG_PATH = cfgPathEnv;
+  rmSync(root, { recursive: true, force: true });
+});
+
+/**
+ * One hub both peers connect to.
+ *
+ * Holds a Y.Doc per documentName and relays between every connection attached
+ * to it. Each connection carries its OWN origin symbol, so an update that
+ * arrives from peer A reaches peer B and is not echoed back to A — the property
+ * a single shared symbol would silently break, leaving a test that passes
+ * because nothing ever moved.
+ *
+ * It also answers `GET /api/documents` from the same map, which is the whole
+ * point: the listing is what a peer can learn about a canvas it has never seen,
+ * and it can only ever name documents somebody actually opened.
+ */
+function makeHub() {
+  const docs = new Map<string, Y.Doc>();
+
+  function docFor(name: string): Y.Doc {
+    let d = docs.get(name);
+    if (!d) {
+      d = new Y.Doc();
+      docs.set(name, d);
+    }
+    return d;
+  }
+
+  function factory() {
+    return (args: { documentName: string; document?: Y.Doc }): SyncProvider => {
+      const hubDoc = docFor(args.documentName);
+      const local = args.document ?? new Y.Doc();
+      const conn = Symbol('conn');
+      // Initial state transfer, both ways — a real handshake converges the two
+      // sides before `onceSynced` resolves, and the cold-start reconcile the
+      // runtime runs afterwards depends on that having happened.
+      Y.applyUpdate(local, Y.encodeStateAsUpdate(hubDoc), conn);
+      Y.applyUpdate(hubDoc, Y.encodeStateAsUpdate(local), conn);
+      const onLocal = (u: Uint8Array, origin: unknown) => {
+        if (origin === conn) return;
+        Y.applyUpdate(hubDoc, u, conn);
+      };
+      const onHub = (u: Uint8Array, origin: unknown) => {
+        if (origin === conn) return;
+        Y.applyUpdate(local, u, conn);
+      };
+      local.on('update', onLocal);
+      hubDoc.on('update', onHub);
+      return {
+        document: local,
+        awareness: new Awareness(local),
+        async onceSynced() {},
+        destroy() {
+          local.off('update', onLocal);
+          hubDoc.off('update', onHub);
+        },
+      };
+    };
+  }
+
+  /** `GET /api/documents` — names only, exactly like the real route. */
+  function serveListing(): void {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      if (String(input).endsWith('/api/documents')) {
+        return new Response(
+          JSON.stringify({ documents: [...docs.keys()].map((name) => ({ name, bytes: 1 })) }),
+          { status: 200, headers: { 'content-type': 'application/json' } }
+        );
+      }
+      return new Response('nope', { status: 404 });
+    }) as typeof fetch;
+  }
+
+  return {
+    factory,
+    serveListing,
+    docs,
+    bodyOf: (n: string) => docFor(n).getText('html').toString(),
+  };
+}
+
+/** A peer: its own disk, its own context, its own runtime. */
+function makePeer(name: string) {
+  const repoRoot = join(root, name);
+  const designRoot = join(repoRoot, 'design');
+  mkdirSync(join(designRoot, 'ui'), { recursive: true });
+  mkdirSync(join(designRoot, '_comments'), { recursive: true });
+  const linkedHub: DevServerConfig['linkedHub'] = { url: HUB, linkedAt: 1 };
+  const ctx = {
+    // The sandbox split is active — the gate `.tsx` sync is coupled to
+    // (9.1-B). TSX is the real canvas format, and it is also where the pulled
+    // body lands: `fallbackCanvasPath` always resolves to `.tsx`, so a test
+    // written against `.html` would assert a file that correctly never exists.
+    canvasOrigin: 'http://canvas.localhost:9',
+    cfg: {
+      name,
+      projectLabel: null,
+      designRoot: 'design',
+      canvasGroups: [{ label: 'Canvases', path: 'ui' }],
+      rootClass: 'app',
+      themeDefault: 'dark',
+      tokensCssRel: 'system/colors.css',
+      teamAccentDefault: null,
+      handoffTargets: [],
+      newCanvasDir: 'ui',
+      newComponentDir: 'ui/components',
+      linkedHub,
+      _source: 'defaults',
+    },
+    projectLabel: name,
+    paths: {
+      repoRoot,
+      designRel: 'design',
+      designRoot,
+      serverInfoFile: join(designRoot, '_server.json'),
+      activeFile: join(designRoot, '_active.json'),
+      commentsDir: join(designRoot, '_comments'),
+      canvasStateDir: join(designRoot, '_canvas-state'),
+      historyDir: join(designRoot, '_history'),
+      tokensUrlRel: 'design/system/colors.css',
+      systemDirRel: 'system',
+    },
+    bus: createBus(),
+  } as Context;
+
+  /** Which slugs got a hub-awareness bridge — the cursor lane, per canvas. */
+  const bridged: string[] = [];
+  const registry: AwarenessRegistry = {
+    attachHubAwareness(slug) {
+      bridged.push(slug);
+      return () => {};
+    },
+  };
+
+  return {
+    ctx,
+    bridged,
+    registry,
+    /** A canvas the way a real one exists: a `.tsx` body plus the sidecar that
+     *  opts it into sync (Lock 1 — a hub must never be able to flip it). */
+    write(canvas: string, body: string) {
+      writeFileSync(join(designRoot, 'ui', `${canvas}.tsx`), body);
+      writeFileSync(
+        join(designRoot, 'ui', `${canvas}.meta.json`),
+        JSON.stringify({ syncable: true })
+      );
+    },
+    read(canvas: string) {
+      return readFileSync(join(designRoot, 'ui', `${canvas}.tsx`), 'utf8');
+    },
+  };
+}
+
+/** Settle both the fs reader's quiet window and the doc round-trips. */
+const settle = (ms = 450) => new Promise((res) => setTimeout(res, ms));
+
+describe('two peers on one hub', () => {
+  let runtimes: (SyncRuntime | null)[] = [];
+  afterEach(async () => {
+    for (const r of runtimes) await r?.stop();
+    runtimes = [];
+  });
+
+  test('a canvas created on peer A reaches peer B — no restart on either side', async () => {
+    const hub = makeHub();
+    const a = makePeer('a');
+    const b = makePeer('b');
+    // Both start with the same one canvas, so neither is in the special
+    // empty-project path and the only variable is the NEW one.
+    a.write('home', '<main>home</main>');
+    b.write('home', '<main>home</main>');
+    hub.serveListing();
+
+    const ra = createSyncRuntime(a.ctx, { providerFactory: hub.factory(), registry: a.registry });
+    const rb = createSyncRuntime(b.ctx, { providerFactory: hub.factory(), registry: b.registry });
+    runtimes = [ra, rb];
+    await ra?.start();
+    await rb?.start();
+    await settle(50);
+
+    expect(ra?.size()).toBe(1);
+    expect(rb?.size()).toBe(1);
+
+    // ── A makes a canvas. Nobody restarts anything. ──────────────────────
+    a.write('newidea', '<section>made on A</section>');
+    a.ctx.bus.emit('canvas-list-update', { action: 'added', rel: 'ui/newidea.tsx' });
+    await ra?.rescanNow();
+    await settle();
+
+    // It is on the hub — which on a cell is the step that used to be missing
+    // entirely, and is why the other side could not even learn the name.
+    expect(hub.bodyOf('ui-newidea')).toBe('<section>made on A</section>');
+
+    // ── B has never heard of it. It polls, and pulls it down. ────────────
+    await rb?.pullRemoteNow();
+    await settle();
+
+    expect(rb?.size()).toBe(2);
+    expect(b.read('newidea')).toBe('<section>made on A</section>');
+    // The cursor lane is attached for the canvas that ARRIVED, not just the
+    // ones that existed at boot — "no cursor in the new canvas" was half the
+    // report.
+    expect(b.bridged).toContain('ui-newidea');
+  });
+
+  test('the discovered canvas keeps syncing — it is live, not a one-shot copy', async () => {
+    const hub = makeHub();
+    const a = makePeer('a');
+    const b = makePeer('b');
+    a.write('home', '<main>home</main>');
+    b.write('home', '<main>home</main>');
+    hub.serveListing();
+
+    const ra = createSyncRuntime(a.ctx, { providerFactory: hub.factory(), registry: a.registry });
+    const rb = createSyncRuntime(b.ctx, { providerFactory: hub.factory(), registry: b.registry });
+    runtimes = [ra, rb];
+    await ra?.start();
+    await rb?.start();
+
+    a.write('shared', '<p>v1</p>');
+    await ra?.rescanNow();
+    await settle();
+    await rb?.pullRemoteNow();
+    await settle();
+    expect(b.read('shared')).toBe('<p>v1</p>');
+
+    // A edits it again, well after the discovery. This is the difference
+    // between "it appeared" and "it syncs".
+    a.write('shared', '<p>v2 — edited after discovery</p>');
+    a.ctx.bus.emit('fs:any', 'ui/shared.tsx');
+    // Long enough for the whole chain: A's fs quiet window, the doc round-trip,
+    // and B's agent debouncing its doc→file write. Three debounces, not one.
+    await settle(1500);
+
+    expect(hub.bodyOf('ui-shared')).toBe('<p>v2 — edited after discovery</p>');
+    expect(b.read('shared')).toBe('<p>v2 — edited after discovery</p>');
+  });
+
+  test('the other direction is the same code — B creates, A discovers', async () => {
+    const hub = makeHub();
+    const a = makePeer('a');
+    const b = makePeer('b');
+    a.write('home', '<main>home</main>');
+    b.write('home', '<main>home</main>');
+    hub.serveListing();
+
+    const ra = createSyncRuntime(a.ctx, { providerFactory: hub.factory(), registry: a.registry });
+    const rb = createSyncRuntime(b.ctx, { providerFactory: hub.factory(), registry: b.registry });
+    runtimes = [ra, rb];
+    await ra?.start();
+    await rb?.start();
+
+    b.write('fromb', '<article>made on B</article>');
+    await rb?.rescanNow();
+    await settle();
+    await ra?.pullRemoteNow();
+    await settle();
+
+    expect(a.read('fromb')).toBe('<article>made on B</article>');
+    expect(ra?.size()).toBe(2);
+    expect(a.bridged).toContain('ui-fromb');
+  });
+
+  test('a canvas each, made at the same time, and both sides end up with both', async () => {
+    // The case a one-directional fix passes and a real one has to survive:
+    // neither peer is "the server", and each has something the other lacks.
+    const hub = makeHub();
+    const a = makePeer('a');
+    const b = makePeer('b');
+    a.write('home', '<main>home</main>');
+    b.write('home', '<main>home</main>');
+    hub.serveListing();
+
+    const ra = createSyncRuntime(a.ctx, { providerFactory: hub.factory(), registry: a.registry });
+    const rb = createSyncRuntime(b.ctx, { providerFactory: hub.factory(), registry: b.registry });
+    runtimes = [ra, rb];
+    await ra?.start();
+    await rb?.start();
+
+    a.write('alpha', '<p>alpha</p>');
+    b.write('beta', '<p>beta</p>');
+    await Promise.all([ra?.rescanNow(), rb?.rescanNow()]);
+    await settle();
+    await Promise.all([ra?.pullRemoteNow(), rb?.pullRemoteNow()]);
+    await settle();
+
+    expect(a.read('beta')).toBe('<p>beta</p>');
+    expect(b.read('alpha')).toBe('<p>alpha</p>');
+    expect(ra?.size()).toBe(3);
+    expect(rb?.size()).toBe(3);
+  });
+});

package/apps/studio/whats-new.json

@@ -1,6 +1,24 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "continuous-sync-discovery",
+      "version": "0.60.3",
+      "date": "2026-08-13",
+      "kind": "fix",
+      "title": "A new canvas shows up everywhere, on its own",
+      "summary": "Make a canvas in the cloud and it arrives on your desktop; make one on your desktop and it is live in the cloud, with cursors, straight away. Until now each side only looked for new canvases when it started up, so whichever end you had not restarted lately simply never saw them.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "cloud-keeps-its-images",
+      "version": "0.60.3",
+      "date": "2026-08-13",
+      "kind": "fix",
+      "title": "Your cloud project keeps its images",
+      "summary": "After the cloud moved your project between machines, photographs could come back as grey boxes and the only fix was re-uploading everything from your laptop. The cloud now restores those files itself, from the copy it already had.",
+      "surface": "design-ui"
+    },
     {
       "id": "sync-resync-button",
       "version": "0.60.0",

package/cli/commands/doctor.mjs

@@ -25,6 +25,11 @@ import { stdin, stdout } from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from '../lib/argv.mjs';
 import { lintConfig } from '../lib/config-lint.mjs';
+import {
+  describeGitignoreDrift,
+  findGitignoreDrift,
+  removeGitignoreDrift,
+} from '../lib/gitignore-drift.mjs';
 import { getHub } from '../lib/hubs-config.mjs';
 import { checkAll } from '../lib/preflight.mjs';
 import { detectQualityGates, detectStack } from '../lib/stack-detect.mjs';
@@ -172,6 +177,25 @@ export async function run({ args, pkgRoot }) {
     }
   }
 
+  // ── Gitignore drift: is git dropping VERSIONED design content? ───────────
+  // The one failure mode nothing else can see. A rule OUTSIDE the
+  // `# maude:begin`/`# maude:end` markers is invisible to the block writer, so
+  // a stale `.design/*.annotations.svg` — hand-copied years ago from a planning
+  // doc that predates DDR-115 — silently keeps every draw layer out of git
+  // while both UIs render it happily. See `lib/gitignore-drift.mjs`.
+  const gitignoreFsPath = resolve(repoRoot, '.gitignore');
+  const designRel = (() => {
+    try {
+      const dcfg = JSON.parse(readFileSync(designFsPath, 'utf8'));
+      return typeof dcfg.designRoot === 'string' && dcfg.designRoot ? dcfg.designRoot : '.design';
+    } catch {
+      return '.design';
+    }
+  })();
+  const gitignoreDrift = existsSync(gitignoreFsPath)
+    ? findGitignoreDrift(readFileSync(gitignoreFsPath, 'utf8'), designRel)
+    : [];
+
   // ── Summary ─────────────────────────────────────────────────────────────
   const hardDepsMissing = Object.values(depsByPlugin)
     .filter((r) => r.summary)
@@ -184,21 +208,44 @@ export async function run({ args, pkgRoot }) {
     schemaErrors,
     driftCount,
     qualityAdditions: additionsCount,
-    healthy: hardDepsMissing === 0 && schemaErrors === 0,
+    gitignoreDrift: gitignoreDrift.length,
+    // A HARD failure, not a warning. Every other doctor finding is about
+    // configuration that is merely suboptimal; this one means work the person
+    // can see on screen is not in their repository and will not survive a fresh
+    // clone. Silence about that is how it went unnoticed for a whole project.
+    healthy: hardDepsMissing === 0 && schemaErrors === 0 && gitignoreDrift.length === 0,
   };
 
   if (jsonMode) {
     process.stdout.write(
-      `${JSON.stringify({ deps: depsByPlugin, config: configReport, design: designReport, summary }, null, 2)}\n`
+      `${JSON.stringify(
+        {
+          deps: depsByPlugin,
+          config: configReport,
+          design: designReport,
+          gitignore: { path: gitignoreFsPath, designRel, drift: gitignoreDrift },
+          summary,
+        },
+        null,
+        2
+      )}\n`
     );
     process.exit(summary.healthy ? 0 : 1);
   }
 
-  printReport({ depsByPlugin, configReport, designReport, summary });
+  printReport({ depsByPlugin, configReport, designReport, gitignoreDrift, summary });
 
   // ── Fix path ────────────────────────────────────────────────────────────
   if (fix) {
-    await applyFixes({ repoRoot, configFsPath, depsByPlugin, configReport });
+    await applyFixes({
+      repoRoot,
+      configFsPath,
+      depsByPlugin,
+      configReport,
+      gitignoreFsPath,
+      gitignoreDrift,
+      designRel,
+    });
   } else if (!summary.healthy) {
     process.stdout.write(
       '\nRun with --fix to: install missing deps (prompt per item), drop unknown keys, apply detected drift, add missing quality gates. Existing user values are NEVER overwritten.\n'
@@ -249,7 +296,7 @@ function usage() {
 `;
 }
 
-function printReport({ depsByPlugin, configReport, designReport, summary }) {
+function printReport({ depsByPlugin, configReport, designReport, gitignoreDrift, summary }) {
   process.stdout.write('maude doctor\n\n');
   for (const [name, env] of Object.entries(depsByPlugin)) {
     process.stdout.write(`  Dependencies (plugins/${name}):\n`);
@@ -340,6 +387,20 @@ function printReport({ depsByPlugin, configReport, designReport, summary }) {
     process.stdout.write('\n');
   }
 
+  // Gitignore drift — git is dropping content DDR-115 calls versioned.
+  if (gitignoreDrift?.length) {
+    process.stdout.write('  Gitignore (.gitignore):\n');
+    for (const line of describeGitignoreDrift(gitignoreDrift)) {
+      process.stdout.write(`    ✗ ${line}\n`);
+    }
+    process.stdout.write(
+      '    These rules sit OUTSIDE the `# maude:begin`/`# maude:end` block, so\n' +
+        '    re-running the writer cannot correct them. Work you can see in the UI\n' +
+        '    is not in your repository and will not survive a fresh clone.\n' +
+        '    `maude doctor --fix` removes exactly these lines, and nothing else.\n\n'
+    );
+  }
+
   const parts = [];
   if (summary.hardDepsMissing) parts.push(`${summary.hardDepsMissing} hard dep missing`);
   if (summary.schemaErrors)
@@ -350,11 +411,23 @@ function printReport({ depsByPlugin, configReport, designReport, summary }) {
     parts.push(
       `${summary.qualityAdditions} quality addition${summary.qualityAdditions === 1 ? '' : 's'}`
     );
+  if (summary.gitignoreDrift)
+    parts.push(
+      `${summary.gitignoreDrift} gitignore rule${summary.gitignoreDrift === 1 ? '' : 's'} dropping versioned content`
+    );
   if (parts.length === 0) parts.push('all clear');
   process.stdout.write(`  Summary: ${parts.join(', ')}.\n`);
 }
 
-async function applyFixes({ repoRoot, configFsPath, depsByPlugin, configReport }) {
+async function applyFixes({
+  repoRoot,
+  configFsPath,
+  depsByPlugin,
+  configReport,
+  gitignoreFsPath,
+  gitignoreDrift,
+  designRel,
+}) {
   let configChanged = false;
 
   // ── Config edits ───────────────────────────────────────────────────────
@@ -461,6 +534,68 @@ async function applyFixes({ repoRoot, configFsPath, depsByPlugin, configReport }
     }
   }
 
+  // ── Gitignore drift ─────────────────────────────────────────────────────
+  //
+  // The ONE fix in this command that edits a file the user hand-wrote, so it is
+  // the one that asks. Everything else `--fix` does is additive or confined to
+  // generated regions; this deletes lines from somebody's `.gitignore`. The
+  // prompt names each line, and a non-TTY (CI, a scripted spawn) is a decline —
+  // never an assumed yes.
+  if (gitignoreDrift?.length && gitignoreFsPath && existsSync(gitignoreFsPath)) {
+    process.stdout.write('\n--- Gitignore rules dropping VERSIONED design content ---\n');
+    for (const line of describeGitignoreDrift(gitignoreDrift)) {
+      process.stdout.write(`  ${line}\n`);
+    }
+    if (!stdin.isTTY) {
+      process.stdout.write(
+        '  skipped — non-interactive stdin. Re-run in a terminal, or delete the lines above by hand.\n'
+      );
+    } else {
+      const rl = createInterface({ input: stdin, output: stdout });
+      const ans = await rl.question(
+        `  Remove ${gitignoreDrift.length === 1 ? 'this line' : `these ${gitignoreDrift.length} lines`} from .gitignore? [y/N] `
+      );
+      rl.close();
+      if (/^y(es)?$/i.test((ans || '').trim())) {
+        // DELETE ONLY WHAT WAS SHOWN, FROM THE TEXT IT WAS SHOWN FROM.
+        //
+        // `removeGitignoreDrift` deletes by LINE NUMBER, and its contract says
+        // those numbers must come from a scan of the same text — otherwise the
+        // numbers mean something else. The scan happens near the top of this
+        // command; the write happens here, after the report, after every
+        // per-dependency install (which shells out and can run for minutes) and
+        // after this prompt. In a Syncthing tree with concurrent sessions —
+        // which is exactly where this repo lives — that gap is long enough for
+        // the file to change, and the failure mode is silently deleting a line
+        // the person never saw and never approved. A `.gitignore` line can be
+        // the one keeping `.env` out of a commit.
+        //
+        // So: re-read, re-derive, and proceed only if the approved lines are
+        // still exactly where they were. Anything else is a re-run, not a guess.
+        const now = readFileSync(gitignoreFsPath, 'utf8');
+        const stillThere = findGitignoreDrift(now, designRel);
+        const approved = new Map(gitignoreDrift.map((d) => [d.line, d.text]));
+        const unchanged =
+          stillThere.length === approved.size &&
+          stillThere.every((d) => approved.get(d.line) === d.text);
+        if (!unchanged) {
+          process.stdout.write(
+            '  ✗ .gitignore changed while this was waiting for an answer — nothing removed.\n' +
+              '    Re-run `maude doctor --fix` to see the current state.\n'
+          );
+        } else {
+          writeFileSync(gitignoreFsPath, removeGitignoreDrift(now, stillThere), 'utf8');
+          process.stdout.write(
+            '  ✓ removed. The files are still untracked until you `git add` them —\n' +
+              '    `git status` will now show them for the first time.\n'
+          );
+        }
+      } else {
+        process.stdout.write('  skipped.\n');
+      }
+    }
+  }
+
   // Use the actually-changed state to decide on re-run hint.
   void repoRoot;
 }