@1agh/maude 0.60.2 → 0.60.4

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;
+    },
+  };
+}

package/apps/studio/sync/file-membership.ts

@@ -0,0 +1,290 @@
+// The file plane's WHOLE membership policy — one positive classifier.
+//
+// Sync's unit used to be a canvas, and a file travelled iff some canvas
+// claimed it by name. A fresh link of a real project delivered 79/79 canvases
+// and lost 103 files — the design system's assets, its token stylesheets,
+// `_brand-css.ts` (→ `TypeError: Importing a module script failed`), both
+// docs (RCA: issue-fresh-link-gets-canvases-but-not-the-design-system). Every
+// fix so far added a per-file-kind lane; the growth was the bug. This module
+// replaces the taxonomy: membership in the manifest-driven file plane
+// (Plane B) is decided HERE, positively, and nowhere else.
+//
+// BREAKER's honest test, from the binding debate
+// (kg: maude/sync-two-plane-manifest-architecture): "That manifest collapses
+// into whole-folder with extra steps — if the classifier ends up as
+// everything-except-the-exclusion-regex, I have paid a manifest complexity
+// for zero safety. The honest test before building: can the team enumerate
+// the versioned classes POSITIVELY?" This module IS that enumeration:
+//
+//   canvas-owned   → Plane A (the per-canvas Yjs CRDT docs), NEVER Plane B.
+//                    A canvas body (`.tsx` inside a canvas group) and its
+//                    named sidecars (`.meta.json`, the same-named sibling
+//                    `.css`, `.annotations.svg`). Plane disjointness is
+//                    enforced at the SOURCE — these never enter a manifest —
+//                    and tested, because a second transport under a CRDT lane
+//                    is how a converged edit gets clobbered by a stale copy.
+//   inert-media    → images / fonts / video / audio / svg. Flows freely.
+//   companion-text → css / md. Flows freely.
+//   code-module    → ts / tsx / js / mjs outside canvas bodies. Flows ONLY
+//                    through the owner-hub gate: the receiver admits it when
+//                    its STORED hub record says `role === 'owner'` (or the
+//                    hub is the loopback cell pairing) — never on a
+//                    hub-supplied claim.
+//   never          → `config.json` at the design root (it names the hub URL
+//                    and the canvas groups — a synced config is a hub
+//                    rewriting its own trust anchors), everything the DDR-115
+//                    runtime-state taxonomy matches, and EVERYTHING not
+//                    positively claimed above. Default-closed: an extension
+//                    not listed here does not travel.
+//
+// THE RECEIVER RE-VALIDATES EVERY PATH (ATTACKER's invariant, same debate):
+// a hub-supplied `class` field is a hint for reporting, never authority —
+// each side classifies against its OWN tree and config before a byte moves.
+//
+// ⚠ MIRRORED in `apps/hub/src/file-membership.mjs` (the doc-namespace
+// precedent). The hub image installs frozen against its own bun.lock and must
+// not reach into apps/studio, so the logic is duplicated rather than shared,
+// and the two are pinned to each other by
+// `test/sync-file-membership.test.ts`, which imports the hub's `.mjs` and
+// asserts both agree over an adversarial corpus. Change one, change the other.
+//
+// ⚠ FOURTH COPY, WITH A TRIPWIRE. `isRuntimeStateRel` below replicates
+// `git/service.ts` `isMaudeRuntimeState` instead of importing it — importing
+// would drag the git surface into the hub mirror's parity story. Three copies
+// of the DDR-115 list already exist (git/service.ts, cli/lib/
+// gitignore-block.mjs, the repo .gitignore) and they have drifted silently
+// before; this copy is pinned by a test that imports BOTH and asserts
+// agreement on a fixture list, which turns the drift into a unit-testable
+// bug. The debate accepted the 4th copy knowingly, on that condition.
+
+/** A `canvasGroups[]` entry, as loose as the config actually is — mirrors
+ *  `canvas-path.ts`'s `CanvasGroupLike` (declared locally so this module,
+ *  like its hub mirror, is dependency-free). */
+export interface CanvasGroupLike {
+  path?: string;
+}
+
+export type FileClass = 'canvas-owned' | 'inert-media' | 'companion-text' | 'code-module' | 'never';
+
+/** The classes the file plane actually carries. `canvas-owned` is Plane A's;
+ *  `never` is nobody's. */
+export const FILE_PLANE_CLASSES = ['inert-media', 'companion-text', 'code-module'] as const;
+export type FilePlaneClass = (typeof FILE_PLANE_CLASSES)[number];
+
+export function isFilePlaneClass(c: FileClass): c is FilePlaneClass {
+  return c === 'inert-media' || c === 'companion-text' || c === 'code-module';
+}
+
+/** Max relative-path length (matches the hub's checkout shape cap). */
+export const MAX_REL_LEN = 512;
+
+/** Max designRoot-relative depth (matches the hub's 8-segment cap). */
+export const MAX_SEGMENTS = 8;
+
+// The positive extension enumerations. Everything is lowercase; the lookup
+// lowercases first — a DS legitimately ships `…P1020428.JPG`.
+const INERT_MEDIA_EXTS = new Set([
+  'png',
+  'jpg',
+  'jpeg',
+  'webp',
+  'gif',
+  'avif',
+  'svg',
+  'mp4',
+  'webm',
+  'mov',
+  'm4v',
+  'mp3',
+  'wav',
+  'm4a',
+  'aac',
+  'ogg',
+  'woff2',
+  'woff',
+  'ttf',
+  'otf',
+]);
+const COMPANION_TEXT_EXTS = new Set(['css', 'md', 'srt']);
+const CODE_MODULE_EXTS = new Set(['ts', 'tsx', 'js', 'mjs']);
+
+/**
+ * Maude's OWN sidecar vocabulary, positively enumerated by full suffix —
+ * never bare `.json` (that stays default-closed; a manifest must not be able
+ * to land arbitrary json, least of all a config). Found by the Task-12
+ * acceptance run on the real alligators tree: `assets/<sha8>.photo.json`
+ * (non-destructive photo edits) and `assets/<sha8>.audio.json` are versioned
+ * content (DDR-115 does not ignore them), and without a lane the second
+ * machine silently loses every photo edit — the exact bug class this module
+ * exists to end.
+ */
+const COMPANION_SIDECAR_SUFFIXES = ['.photo.json', '.audio.json'];
+
+/**
+ * A DIRECTORY segment must start alphanumeric — the same rule as the hub's
+ * `checkoutRelShape`, and the rule that keeps every `_*` runtime DIRECTORY
+ * (`_history/`, `_untrusted/`, `_trash/`, …) out structurally, before the
+ * explicit runtime-state check even runs.
+ */
+const DIR_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+
+/**
+ * The FINAL segment may additionally start with `_` — this is the one
+ * deliberate relaxation over `checkoutRelShape`, and the reason the paired
+ * refusal below (`isRuntimeStateRel`) lands in the same module, same commit:
+ * real versioned FILES like `_brand-css.ts` and `preview/_layout.css` start
+ * with an underscore, and refusing the underscore wholesale is exactly the
+ * DDR-115 shape accident that left them laneless. A leading dot stays
+ * refused — `.DS_Store` and dotfiles are not project content.
+ */
+const FILE_SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9 ._-]*$/;
+
+/**
+ * Maude's own per-machine runtime state — the DDR-115 taxonomy, replicated
+ * byte-for-byte from `git/service.ts` `isMaudeRuntimeState` (see the 4th-copy
+ * tripwire note in the header; the parity test imports both and asserts
+ * agreement). These never travel in EITHER direction, no matter what their
+ * extension says.
+ */
+export function isRuntimeStateRel(p: string): boolean {
+  return (
+    /(^|\/)_(?:server|active|sync|preflight|locator|export-history|generate-history)(?:\.[A-Za-z0-9_-]{1,64})?\.json$/.test(
+      p
+    ) ||
+    /(^|\/)_server\.(?:lock|log)$/.test(p) ||
+    /(^|\/)_(?:history|trash|draw|photo|smoke|reports|canvas-state|state|chat|comments|untrusted|export-jobs)(?:\/|$)/.test(
+      p
+    ) ||
+    /(^|\/)\.kgai(?:\/|$)/.test(p)
+  );
+}
+
+export interface ClassifyOptions {
+  /** Declared canvas groups. Absent ⇒ the same `['system', 'ui']` default the
+   *  canvas-path receiver uses — the two halves of sync must agree on what a
+   *  group is, or a body one lane owns leaks into the other. */
+  canvasGroups?: readonly CanvasGroupLike[];
+  /**
+   * Presence probe over the SAME tree `rel` came from. Powers the ONE
+   * sibling-dependent split: a `.css` inside a canvas group is canvas-owned
+   * when `<same-name>.tsx` exists (it is that canvas's Yjs css lane), and
+   * companion-text when it does not (`brand.css`, `_layout.css` — the RCA's
+   * missing stylesheets). This cannot be decided from the path alone, and
+   * both misreadings are wrong: "all group css is canvas-owned" re-loses the
+   * RCA's five files, "all group css flows" double-transports a CRDT lane.
+   * Absent ⇒ companion-text (the flowing side) — safe because every RECEIVER
+   * passes its own disk probe and re-refuses what its tree shows is a
+   * sidecar.
+   */
+  hasFile?: (rel: string) => boolean;
+}
+
+/**
+ * Classify one designRoot-relative path. Total: every input gets a class, and
+ * every malformed input gets `never` — shape refusal and policy refusal are
+ * deliberately the same answer, so no caller can tell them apart and leak an
+ * oracle.
+ *
+ * Shape gates (all refusals → `never`): relative, `/`-separated, ≤ 8
+ * segments, ≤ 512 chars, no `..`/`.`/empty segment, no backslash, no drive
+ * letter, no control characters, no trailing-space segment, no
+ * `node_modules`, directory segments start alphanumeric, the final segment
+ * may start with `_`.
+ */
+export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): FileClass {
+  const parts = relShape(rel);
+  if (parts === null) return 'never';
+
+  // The design root's own `config.json` names the linked hub and the canvas
+  // groups — a peer that syncs it hands naming authority to the hub.
+  if (rel === 'config.json') return 'never';
+  if (isRuntimeStateRel(rel)) return 'never';
+
+  const last = parts[parts.length - 1] ?? '';
+  const lowerLast = last.toLowerCase();
+  const lowerRel = rel.toLowerCase();
+  const inGroup = normalizedGroups(opts.canvasGroups).some((g) =>
+    lowerRel.startsWith(`${g.toLowerCase()}/`)
+  );
+
+  if (inGroup) {
+    // The canvas body and its NAMED sidecars — Plane A's, by construction.
+    if (lowerLast.endsWith('.tsx')) return 'canvas-owned';
+    if (lowerLast.endsWith('.meta.json')) return 'canvas-owned';
+    if (lowerLast.endsWith('.annotations.svg')) return 'canvas-owned';
+    if (lowerLast.endsWith('.css') && opts.hasFile) {
+      const sibling = `${rel.slice(0, -'.css'.length)}.tsx`;
+      if (opts.hasFile(sibling)) return 'canvas-owned';
+    }
+  }
+
+  if (COMPANION_SIDECAR_SUFFIXES.some((s) => lowerLast.endsWith(s))) return 'companion-text';
+
+  const dot = lowerLast.lastIndexOf('.');
+  const ext = dot < 0 ? '' : lowerLast.slice(dot + 1);
+  if (INERT_MEDIA_EXTS.has(ext)) return 'inert-media';
+  if (COMPANION_TEXT_EXTS.has(ext)) return 'companion-text';
+  if (CODE_MODULE_EXTS.has(ext)) return 'code-module';
+
+  // Default-closed. Not an error — the answer.
+  return 'never';
+}
+
+/**
+ * The shape gate alone — true when `rel` could name a project file at all.
+ *
+ * Exposed for surfaces that must parse BEFORE they can classify: the hub's
+ * PUT route parses the URL before it knows the checkout's canvas groups, and
+ * a parse-stage refusal there is final (the request falls through), so it may
+ * refuse only what NO configuration could ever admit — the shape.
+ */
+export function isProjectFileShape(rel: string): boolean {
+  return relShape(rel) !== null;
+}
+
+/** The segment shape rules alone — split parts, or null on refusal. */
+function relShape(rel: unknown): string[] | null {
+  if (typeof rel !== 'string' || rel.length === 0 || rel.length > MAX_REL_LEN) return null;
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing them is the point.
+  if (/[\u0000-\u001f\u007f]/.test(rel)) return null;
+  if (rel.startsWith('/') || rel.includes('\\') || /^[A-Za-z]:/.test(rel)) return null;
+  const parts = rel.split('/');
+  if (parts.length > MAX_SEGMENTS) return null;
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i] ?? '';
+    if (!p || p === '.' || p === '..') return null;
+    if (p === 'node_modules') return null;
+    if (/ $/.test(p)) return null;
+    if (!(i === parts.length - 1 ? FILE_SEGMENT : DIR_SEGMENT).test(p)) return null;
+  }
+  return parts;
+}
+
+/**
+ * Declared group paths, normalised — the same semantics (and the same
+ * `['system', 'ui']` fallback) as `canvas-path.ts`'s private helper, re-typed
+ * here because this module must load dependency-free in the hub's plain-Node
+ * runtime through its `.mjs` mirror.
+ */
+function normalizedGroups(canvasGroups?: readonly CanvasGroupLike[]): string[] {
+  const out: string[] = [];
+  for (const g of canvasGroups ?? []) {
+    const p = normalizeGroup(g?.path);
+    if (p && !out.includes(p)) out.push(p);
+  }
+  return out.length > 0 ? out : ['system', 'ui'];
+}
+
+/** One group path, or null when unusable as a containment prefix (stricter is
+ *  the safe direction — an escaping group is dropped, not clamped). */
+function normalizeGroup(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  const p = raw.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+  if (!p) return null;
+  if (/^[A-Za-z]:/.test(p)) return null;
+  for (const part of p.split('/')) {
+    if (!part || part === '.' || part === '..') return null;
+    if (!/^[A-Za-z0-9_-][A-Za-z0-9 _-]*(?![\s\S])/.test(part)) return null;
+  }
+  return p;
+}