@1agh/maude 0.60.2 → 0.60.3

package/apps/studio/http.ts

@@ -1194,6 +1194,28 @@ export function createHttp(
   const gitJson = (r: { status: number; json: unknown }) =>
     Response.json(r.json, { status: r.status, headers: { 'Cache-Control': 'no-store' } });
 
+  /**
+   * A refused `/_api/sync/*` call, in the shape the Sync panel can actually
+   * render: `{ ok: false, reason, detail }`.
+   *
+   * The panel falls back to a fixed string when a response carries no `detail`,
+   * so every plain-text refusal on these routes surfaced as the same causeless
+   * "Resync could not start." — the failure the 2026-08-13 report ends on. The
+   * gate decisions are untouched; only the answer is.
+   *
+   * The `detail` is written for a person and names no request internals: which
+   * origin or host was presented is in the server log, where it is diagnostic,
+   * not in a body a canvas iframe could read back.
+   */
+  const syncRefusal = (reason: 'cross-origin' | 'untrusted-host', what: string): Response => {
+    console.warn(`[sync] ${reason} request to a sync control route — refused.`);
+    const detail =
+      reason === 'cross-origin'
+        ? `${what} from Maude itself, not from inside a canvas.`
+        : `${what} from the Maude app or this machine's own browser tab.`;
+    return gitJson({ status: 403, json: { ok: false, reason, detail } });
+  };
+
   // Shared by /_api/export and /_api/export-jobs — build the exportJobs.enqueue()
   // args from a validated request body. `inspect.state` is the live `_active.json`;
   // readers narrow to the resolver's subset locally so the export pipeline doesn't
@@ -2476,10 +2498,19 @@ export function createHttp(
     // the person's own hub, and a way to spend their rate-limit budget.
     '/_api/sync/resync': async (req: Request) => {
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
-      if (!sameOriginWrite(req))
-        return new Response('cross-origin write rejected', { status: 403 });
+      // REFUSALS ANSWER IN JSON, WITH A REASON.
+      //
+      // These were plain-text 403s, so the panel — which reads `json.detail` and
+      // falls back to a fixed string — rendered every one of them as "Resync
+      // could not start.", a sentence naming no cause and offering no next step.
+      // A person hitting the gate legitimately (a canvas iframe, a stale tab,
+      // the wrong host) got the same six words as a person hitting a bug, and
+      // neither could tell which they had. The GATES are unchanged: what a
+      // refusal SAYS is not a security property, and saying nothing was never
+      // protecting anything.
+      if (!sameOriginWrite(req)) return syncRefusal('cross-origin', 'Resync must be started');
       if (!isTrustedRequestHost(req))
-        return new Response('local request required', { status: 403 });
+        return syncRefusal('untrusted-host', 'Resync must be started');
       const control = ctx.syncControl;
       if (!control) {
         return gitJson({
@@ -2507,10 +2538,9 @@ export function createHttp(
       // is. Safe by construction — uploads are idempotent and the hub writes
       // temp-then-rename, so no half-written asset can survive this.
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
-      if (!sameOriginWrite(req))
-        return new Response('cross-origin write rejected', { status: 403 });
+      if (!sameOriginWrite(req)) return syncRefusal('cross-origin', 'Cancelling must be started');
       if (!isTrustedRequestHost(req))
-        return new Response('local request required', { status: 403 });
+        return syncRefusal('untrusted-host', 'Cancelling must be started');
       const cancelled = ctx.syncControl?.current?.()?.cancelAssetSweep() ?? false;
       return gitJson({ status: 200, json: { ok: true, cancelled } });
     },

package/apps/studio/server.ts

@@ -685,6 +685,17 @@ ctx.bus.on('fs:json', (rel: string) => {
 // Connect starts syncing instead of printing "restart the studio server".
 const syncRuntime = createSyncSupervisor(ctx, collab ? { registry: collab.registry } : {});
 ctx.syncControl = syncRuntime;
+// A linked project that had NOTHING syncable at boot asks for one cycle the
+// moment it gains its first canvas — see the zero-canvas branch in
+// `sync/index.ts`. The runtime cannot cycle itself (the supervisor owns the
+// serialization), so it asks and this answers. Refused while a cycle is already
+// in flight, exactly like the Resync button.
+ctx.bus.on('sync:needs-restart', () => {
+  if (syncRuntime.busy()) return;
+  void syncRuntime.restart().catch((err) => {
+    console.error('[sync] first-canvas restart failed:', err);
+  });
+});
 try {
   await syncRuntime.start();
 } catch (err) {

package/apps/studio/sync/asset-push.ts

@@ -192,6 +192,36 @@ function extOf(name: string): string {
  * `system/<ds>/assets/`, …) and collects the asset-extension files inside it.
  * Skips runtime-state (`_*`), `.git`, `node_modules`. Missing root → [].
  */
+/**
+ * Would `listPushableAssets` have returned this designRoot-relative path?
+ *
+ * The cheap, no-disk half of the same rule, for deciding whether an `fs:any`
+ * event is worth a sweep. It must not drift from the walk below — the two are
+ * kept adjacent for that reason — but it is deliberately CONSERVATIVE where it
+ * cannot be sure: a `false` here means an asset silently never uploads until
+ * the next boot, which is the bug this predicate exists to end, so anything
+ * shaped like an asset under an `assets/` directory answers true and lets the
+ * sweep itself decide.
+ */
+export function isPushableAssetRel(rel: string): boolean {
+  if (typeof rel !== 'string' || !rel) return false;
+  const norm = rel.replace(/\\/g, '/');
+  if (norm.length > MAX_REL_LEN) return false;
+  const parts = norm.split('/');
+  if (parts.length < 2 || parts.length > MAX_SEGMENTS) return false;
+  let insideAssets = false;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const seg = parts[i];
+    if (seg.startsWith('_') || seg === '.git' || seg === 'node_modules') return false;
+    if (!SEGMENT.test(seg)) return false;
+    if (seg === 'assets') insideAssets = true;
+  }
+  if (!insideAssets) return false;
+  const name = parts[parts.length - 1];
+  if (name.startsWith('_') || !SEGMENT.test(name)) return false;
+  return ASSET_EXTS.has(extOf(name));
+}
+
 export function listPushableAssets(designRoot: string): string[] {
   const out: string[] = [];
   // Walk the tree; once inside an `assets` dir, collect asset files below it.

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

@@ -119,6 +119,16 @@ export interface ConnectionMonitor {
    *  `reason` (feature-sync-progress-modal) is the classification for an
    *  auth-rejected doc — our own vocabulary, ignored for other states. */
   noteDocState(slug: string, state: DocSyncState, reason?: string): void;
+  /**
+   * Drop every trace of a slug — its doc state, its rejection reason and its
+   * provider status.
+   *
+   * The counterpart to `noteDocState` for a canvas the runtime has RELEASED
+   * (deleted on disk, or moved out of a synced group). Without it a released
+   * canvas stays in the item list as a row that can never settle, and its stale
+   * provider status keeps voting in the session's online/offline derivation.
+   */
+  forgetDoc(slug: string): void;
   /** DDR-102 — real sync activity for a slug (reconcile done, hub-pushed flush
    *  applied): bumps `lastSyncAt` to now. */
   noteSyncActivity(slug: string): void;
@@ -422,6 +432,19 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       emit();
     },
 
+    forgetDoc(slug) {
+      if (stopped) return;
+      // A released canvas must leave the counters, not linger as a `pending` row
+      // nothing will ever settle. `providerStatuses` is keyed by the same slug
+      // (see `noteProviderStatus`'s `providerId`), so it is dropped here too —
+      // otherwise a deleted canvas's last known status would keep voting in
+      // `deriveState` forever and could hold the whole session in `offline`.
+      const had = docStates.delete(slug);
+      docReasons.delete(slug);
+      const hadStatus = providerStatuses.delete(slug);
+      if (had || hadStatus) emit();
+    },
+
     noteSyncActivity(slug) {
       if (stopped) return;
       lastSyncAt = now();

package/apps/studio/sync/discovery.ts

@@ -0,0 +1,139 @@
+// Continuous canvas discovery — the decision half.
+//
+// THE BUG THIS EXISTS TO END. `createSyncRuntime.start()` enumerated a project
+// exactly once: `scanCanvases` for the local disk, `GET /api/documents` for the
+// hub, then one provider per canvas. After that loop nothing could join the
+// runtime. A canvas created a second later — by the person, by `/design:new`,
+// by a peer, by `git checkout` — was invisible to sync until the whole runtime
+// was cycled (the Resync button, or an app restart).
+//
+// That read as a one-way sync, and the asymmetry was an artifact of WHO
+// restarts. A desktop app is relaunched constantly, so a canvas made there
+// eventually got picked up; a cloud cell is a container that stays up for days,
+// so a canvas made there never did — no provider, therefore no Hocuspocus
+// document, therefore not even a NAME in the listing the desktop polls. The
+// same missing mechanism, one end of it just failed more visibly.
+//
+// WHY A FULL RESCAN RATHER THAN A DELTA. `canvas-list-watch.ts` already emits
+// `canvas-list-update` with a `rel` and a `slug`, and it would be easy to build
+// a descriptor from them. That file's own comment forbids it, and it is right:
+// those values are ATTACKER-CONTROLLED (an agent-authored or `git checkout`-
+// authored filename), and a descriptor is a set of paths the runtime then reads
+// and writes. So the event is treated as a NUDGE ONLY — the authoritative set is
+// recomputed by the same `scanCanvases` boot uses, and this module just diffs
+// the result. A rescan also gets rename, move, a flipped `syncable: false` and a
+// newly-declared canvas group right, all of which a single-path delta gets wrong.
+
+/** What changed between the runtime's current membership and a fresh scan. */
+export interface CanvasSetDiff {
+  /** Slugs present in the scan that the runtime has not attached. */
+  added: string[];
+  /** Slugs the runtime holds that the scan no longer offers. */
+  removed: string[];
+}
+
+/**
+ * Diff a fresh scan against what the runtime currently owns.
+ *
+ * `attached` is the runtime's live membership (agents + projections), NOT the
+ * boot set — a canvas pulled down from the hub mid-session is attached and must
+ * therefore not be re-added on the next rescan.
+ *
+ * PULLED CANVASES ARE NEVER "REMOVED" BY THIS. A canvas that arrived from the
+ * hub may legitimately be absent from a local scan for a moment (its body is
+ * written after the handshake), and dropping it would tear down the provider
+ * that is in the middle of materialising it. The caller passes those slugs in
+ * `keep` and they are excluded from `removed` — being on the hub is reason
+ * enough to stay attached.
+ */
+export function diffCanvasSet(
+  attached: Iterable<string>,
+  scanned: Iterable<string>,
+  keep: Iterable<string> = []
+): CanvasSetDiff {
+  const have = new Set(attached);
+  const want = new Set(scanned);
+  const pinned = new Set(keep);
+  const added: string[] = [];
+  const removed: string[] = [];
+  for (const slug of want) if (!have.has(slug)) added.push(slug);
+  for (const slug of have) if (!want.has(slug) && !pinned.has(slug)) removed.push(slug);
+  added.sort();
+  removed.sort();
+  return { added, removed };
+}
+
+export interface RescanScheduler {
+  /** Ask for a rescan. Coalesces every call inside the debounce window. */
+  schedule(): void;
+  /** Run now, awaiting any rescan already in flight. Test seam. */
+  flush(): Promise<void>;
+  stop(): void;
+}
+
+export interface RescanSchedulerOptions {
+  debounceMs: number;
+  run: () => Promise<void>;
+  setTimer?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  clearTimer?: (h: ReturnType<typeof setTimeout>) => void;
+  /** Reported failures — never thrown, a rescan that failed must not kill sync. */
+  onError?: (err: unknown) => void;
+}
+
+/**
+ * Debounce + serialize the rescans.
+ *
+ * Both properties are load-bearing, for different reasons. DEBOUNCE: creating a
+ * canvas writes a `.tsx` and then a `.meta.json`, and a `git checkout` touches
+ * hundreds of files — one scan per quiet window, not per write. SERIALIZE: two
+ * overlapping rescans would each diff against a membership the other is
+ * changing, and both would try to adopt the same slug.
+ *
+ * Mirrors `canvas-list-watch.ts`'s own chain-and-debounce shape deliberately, so
+ * the two watchers are reviewable side by side rather than being two different
+ * answers to one question.
+ */
+export function createRescanScheduler(opts: RescanSchedulerOptions): RescanScheduler {
+  const setTimer = opts.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+  let pending: ReturnType<typeof setTimeout> | null = null;
+  let chain: Promise<void> = Promise.resolve();
+  let stopped = false;
+
+  const runOnce = async (): Promise<void> => {
+    if (stopped) return;
+    try {
+      await opts.run();
+    } catch (err) {
+      opts.onError?.(err);
+    }
+  };
+
+  function enqueue(): Promise<void> {
+    chain = chain.then(runOnce, runOnce);
+    return chain;
+  }
+
+  return {
+    schedule() {
+      if (stopped) return;
+      if (pending) clearTimer(pending);
+      pending = setTimer(() => {
+        pending = null;
+        void enqueue();
+      }, opts.debounceMs);
+    },
+    flush() {
+      if (pending) {
+        clearTimer(pending);
+        pending = null;
+      }
+      return enqueue();
+    },
+    stop() {
+      stopped = true;
+      if (pending) clearTimer(pending);
+      pending = null;
+    },
+  };
+}