@1agh/maude 0.22.0 → 0.23.0

package/plugins/design/dev-server/sync/codec.ts

@@ -0,0 +1,169 @@
+// Y.Doc ↔ disk codecs for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// The agent shuttles three classes of files between disk and the Y.Doc the
+// HocuspocusProvider holds:
+//
+//   `.design/<canvas>.html`             -> Y.Text     (Y_SYNC_TYPES.html)
+//   `.design/_comments/<slug>.json`     -> Y.Array    (Y_TYPES.comments  — Phase 6)
+//   `.design/<slug>.annotations.svg`    -> Y.Map.svg  (Y_TYPES.annotations — Phase 5)
+//
+// v1.1 design decision (plan §"Key insight"): HTML body is treated as opaque
+// Y.Text rather than structured Y.XmlFragment. Round-trip drift would
+// otherwise cause infinite sync churn — every time we serialize the structured
+// CRDT back to HTML the formatting whitespace would shift and re-enter the
+// system as a new mutation. Structured CRDT (true element-level co-editing) is
+// Phase 10 / v1.2.
+//
+// The "diff-aware" applyHtmlToDoc replaces the Y.Text contents using a
+// longest-common-prefix + suffix elimination so other peers see a minimal
+// op (e.g. "user changed character 42 only"). This isn't a true textual diff
+// (no LCS), but it's drastically cheaper for typical edits than `delete-all +
+// insert-all`, and crucially preserves cursor positions other peers may have
+// in the unchanged regions.
+
+import type * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+
+/**
+ * Y.Doc shared-type names introduced by Task 4. Distinct namespace from
+ * Y_TYPES so existing comments / annotations stay untouched; new fields
+ * land here.
+ */
+export const Y_SYNC_TYPES = {
+  /** The canvas HTML body, as opaque Y.Text. */
+  html: 'html',
+} as const;
+
+/**
+ * Hard caps on hub-pushed content (DDR-054 §2d — closes attacker F7). yjs
+ * has no upstream-enforced size cap; the codec is the consumer's guard.
+ * Mirrors the existing /_api/annotations 1 MB cap (api.ts) so the sync path
+ * doesn't bypass the HTTP-layer guard.
+ */
+export const MAX_HTML_BYTES = 4 * 1024 * 1024;
+export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
+export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
+
+function byteLengthUtf8(s: string): number {
+  return Buffer.byteLength(s, 'utf8');
+}
+
+/* ---------------------------------------------------------------- HTML */
+
+export function htmlFromDoc(doc: Y.Doc): string {
+  return doc.getText(Y_SYNC_TYPES.html).toString();
+}
+
+/**
+ * Apply `next` to the Y.Text inside `doc`. Uses a minimal common-prefix /
+ * common-suffix replace so peers see a small op rather than a full replace.
+ *
+ * Pass `origin` as the transaction origin so a downstream observer can
+ * distinguish self-originated updates from peer/remote ones.
+ */
+export function applyHtmlToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  if (byteLengthUtf8(next) > MAX_HTML_BYTES) {
+    console.warn(
+      `[sync/codec] refusing HTML apply > ${MAX_HTML_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const yText = doc.getText(Y_SYNC_TYPES.html);
+  const current = yText.toString();
+  if (current === next) return false;
+
+  // Find longest common prefix.
+  let prefix = 0;
+  const maxPrefix = Math.min(current.length, next.length);
+  while (prefix < maxPrefix && current.charCodeAt(prefix) === next.charCodeAt(prefix)) {
+    prefix++;
+  }
+  // Find longest common suffix that doesn't overlap the prefix.
+  let suffix = 0;
+  const maxSuffix = Math.min(current.length - prefix, next.length - prefix);
+  while (
+    suffix < maxSuffix &&
+    current.charCodeAt(current.length - 1 - suffix) === next.charCodeAt(next.length - 1 - suffix)
+  ) {
+    suffix++;
+  }
+
+  const deleteLen = current.length - prefix - suffix;
+  const insertStr = next.slice(prefix, next.length - suffix);
+
+  doc.transact(() => {
+    if (deleteLen > 0) yText.delete(prefix, deleteLen);
+    if (insertStr.length > 0) yText.insert(prefix, insertStr);
+  }, origin);
+
+  return true;
+}
+
+/* ---------------------------------------------------------------- comments */
+
+/**
+ * Comments JSON payload — opaque to the codec, just the array of objects the
+ * Y.Array holds.
+ */
+export type CommentsSnapshot = unknown[];
+
+export function commentsFromDoc(doc: Y.Doc): CommentsSnapshot {
+  const arr = doc.getArray(Y_TYPES.comments);
+  return arr.toArray();
+}
+
+export function applyCommentsToDoc(doc: Y.Doc, next: CommentsSnapshot, origin?: unknown): boolean {
+  const arr = doc.getArray(Y_TYPES.comments);
+  // Comments are LWW on the JSON file (the snapshot is the source of truth);
+  // collapse Y.Array to the new state. For v1.1 we just replace wholesale —
+  // structural comment-level merge is deferred along with structured HTML.
+  // Check whether anything actually changed to avoid no-op transactions
+  // (transactions still fire `update` events, which would re-enter the loop).
+  const before = JSON.stringify(arr.toArray());
+  const after = JSON.stringify(next);
+  if (byteLengthUtf8(after) > MAX_COMMENTS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing comments apply > ${MAX_COMMENTS_BYTES} bytes (got ${byteLengthUtf8(after)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  if (before === after) return false;
+
+  doc.transact(() => {
+    if (arr.length > 0) arr.delete(0, arr.length);
+    if (next.length > 0) arr.push(next);
+  }, origin);
+  return true;
+}
+
+/* ---------------------------------------------------------------- annotations */
+
+/** Returns the annotations SVG string, or null if unset. */
+export function annotationsFromDoc(doc: Y.Doc): string | null {
+  const map = doc.getMap<unknown>(Y_TYPES.annotations);
+  const svg = map.get('svg');
+  return typeof svg === 'string' ? svg : null;
+}
+
+export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?: unknown): boolean {
+  if (next !== null && byteLengthUtf8(next) > MAX_ANNOTATIONS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing annotations apply > ${MAX_ANNOTATIONS_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const map = doc.getMap<unknown>(Y_TYPES.annotations);
+  const current = map.get('svg');
+  const currentStr = typeof current === 'string' ? current : null;
+  if (currentStr === next) return false;
+
+  doc.transact(() => {
+    if (next === null || next === '') {
+      map.delete('svg');
+    } else {
+      map.set('svg', next);
+    }
+  }, origin);
+  return true;
+}

package/plugins/design/dev-server/sync/echo-guard.ts

@@ -0,0 +1,108 @@
+// Echo prevention for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// Problem: when the sync agent writes a file from a remote Y.Doc update, the
+// local fs.watch fires immediately afterwards. Naively, that watch event would
+// be interpreted as a user edit, get pushed back to the Y.Doc, broadcast back
+// to every peer (including ourselves), and trigger another write — an infinite
+// echo loop.
+//
+// Solution: before writing a file from a remote-origin update, the agent
+// records `sha256(bytes)` in a small TTL map. When the fs.watch fires for that
+// path, the agent computes sha256 of the on-disk bytes and asks the guard
+// `consume(path, hash)`. If the hash matches a pending entry that hasn't
+// expired, the event is dropped (it's our own write echoing back). If no
+// match, the event is treated as a real user/Claude edit and pushed up to the
+// Y.Doc.
+//
+// Inspired by Syncthing's "weak hash + sequence number" approach (plan Task 4
+// "Pattern" bullet). The expiry window is intentionally short — 1500ms covers
+// realistic fs.watch debounce on macOS / Linux / Windows without holding state
+// long enough to falsely silence genuine user edits that happen to produce the
+// same hash (e.g. typing the same character back).
+
+import { createHash } from 'node:crypto';
+
+export const ECHO_TTL_MS = 1500;
+
+/**
+ * Compute a hex SHA-256 of the given bytes. Stable across platforms; the agent
+ * uses this as the echo-detection fingerprint.
+ */
+export function hashBytes(bytes: Uint8Array | string): string {
+  const hash = createHash('sha256');
+  hash.update(bytes);
+  return hash.digest('hex');
+}
+
+interface PendingEcho {
+  hash: string;
+  expiresAt: number;
+}
+
+export interface EchoGuard {
+  /**
+   * Record that we just wrote `hash` to `path` from a remote-origin update.
+   * The next fs.watch event for that path within ECHO_TTL_MS with a matching
+   * hash will be treated as an echo and dropped.
+   *
+   * Multiple writes to the same path stack as a small per-path queue — useful
+   * when remote updates fire in rapid succession and the fs.watch coalesces
+   * them. consume() pops the oldest matching entry.
+   */
+  record(path: string, hash: string, now?: number): void;
+
+  /**
+   * Returns true if `hash` matches a pending entry for `path` (i.e. this
+   * fs.watch event is the echo of our own write). Pops the entry on match so
+   * a later, genuine user edit producing the same bytes still goes through.
+   */
+  consume(path: string, hash: string, now?: number): boolean;
+
+  /** Drop expired entries. Idempotent. */
+  sweep(now?: number): void;
+
+  /** Test/inspection: count of currently pending entries across all paths. */
+  size(): number;
+}
+
+export function createEchoGuard(ttlMs: number = ECHO_TTL_MS): EchoGuard {
+  const pending = new Map<string, PendingEcho[]>();
+
+  function sweep(now: number = Date.now()): void {
+    for (const [path, queue] of pending) {
+      const alive = queue.filter((e) => e.expiresAt > now);
+      if (alive.length === 0) pending.delete(path);
+      else if (alive.length !== queue.length) pending.set(path, alive);
+    }
+  }
+
+  return {
+    record(path, hash, now = Date.now()) {
+      sweep(now);
+      const expiresAt = now + ttlMs;
+      const queue = pending.get(path) ?? [];
+      queue.push({ hash, expiresAt });
+      pending.set(path, queue);
+    },
+
+    consume(path, hash, now = Date.now()) {
+      sweep(now);
+      const queue = pending.get(path);
+      if (!queue || queue.length === 0) return false;
+      const idx = queue.findIndex((e) => e.hash === hash);
+      if (idx === -1) return false;
+      queue.splice(idx, 1);
+      if (queue.length === 0) pending.delete(path);
+      else pending.set(path, queue);
+      return true;
+    },
+
+    sweep,
+
+    size() {
+      let n = 0;
+      for (const queue of pending.values()) n += queue.length;
+      return n;
+    },
+  };
+}

package/plugins/design/dev-server/sync/fs-mirror.ts

@@ -0,0 +1,160 @@
+// Debounced file reader for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// The dev-server already has a recursive fs.watch (fs-watch.ts) firing
+// `fs:html` / `fs:json` / `fs:any` bus events with ~50ms debounce. That's
+// great for HMR (the browser wants the freshest possible reload), but
+// the sync agent needs a stricter quiet-window: when a user edit drops onto
+// disk in a flurry (Vim's atomic save: rename twice; or a codemod hammering
+// 100 writes in 10ms), we want to react ONCE per quiescent path so the
+// resulting Y.Doc op is the final state, not 100 intermediate ones.
+//
+// FsReader is that layer. Subscribe via `notify(path)`; after the configured
+// quiet window (default 250ms per plan Task 4 step 2) the reader reads bytes
+// from disk, computes a SHA-256, and invokes the per-path handler.
+//
+// Stateless beyond per-path timers — no fs.watch of its own. The agent wires
+// `ctx.bus.on('fs:any', (path) => reader.notify(path))` once at boot.
+
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join as nodeJoin, resolve as nodeResolve, sep as pathSep } from 'node:path';
+
+import { hashBytes } from './echo-guard.ts';
+
+export const DEFAULT_QUIET_MS = 250;
+
+export interface FsReadEvent {
+  /** Path relative to designRoot — same shape the bus emits. */
+  path: string;
+  /** Raw bytes on disk after the quiet window. */
+  bytes: Uint8Array;
+  /** sha256(bytes), hex. Same fingerprint the echo guard records. */
+  hash: string;
+}
+
+export type FsReaderHandler = (evt: FsReadEvent) => void | Promise<void>;
+
+export interface FsReader {
+  /**
+   * Record an fs event for `relPath`. Resets the per-path quiet timer; the
+   * handler fires after `quietMs` of no further notify() calls for the same
+   * path. Passing an absolute path is fine — the reader uses it verbatim when
+   * resolving against the read root.
+   */
+  notify(relPath: string): void;
+
+  /** Number of paths currently waiting on a debounce timer. Test only. */
+  pending(): number;
+
+  /** Force-fire all pending timers immediately. Test only. */
+  flush(): Promise<void>;
+
+  /** Cancel all pending timers and drop subscriptions. */
+  stop(): void;
+}
+
+export interface FsReaderOptions {
+  /** Absolute path the relPath should be resolved against. */
+  rootDir: string;
+  /** Per-path quiet window. Defaults to DEFAULT_QUIET_MS. */
+  quietMs?: number;
+  /** Predicate — if false, the path is ignored. Used by the agent to filter
+   *  to just the file types the sync layer cares about (.html, .json, .svg). */
+  accept: (relPath: string) => boolean;
+  /** Called once per quiescence with bytes + hash. */
+  onRead: FsReaderHandler;
+  /** Called when a file disappeared during the quiet window. */
+  onDeleted?: (relPath: string) => void;
+  /** Path join helper (injected for tests). Defaults to node:path.join. */
+  joinPath?: (a: string, b: string) => string;
+}
+
+export function createFsReader(opts: FsReaderOptions): FsReader {
+  const quiet = opts.quietMs ?? DEFAULT_QUIET_MS;
+  const join = opts.joinPath ?? defaultJoin;
+
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  let stopped = false;
+
+  async function fire(relPath: string): Promise<void> {
+    timers.delete(relPath);
+    if (stopped) return;
+    const abs = join(opts.rootDir, relPath);
+    // Defense-in-depth — confirm the joined path stays under rootDir. The agent's
+    // absolute-path equality check in applyFromFs already constrains the impact,
+    // but adding the guard prevents future-refactor regressions from re-opening
+    // the surface. DDR-054 §2f (defender M1 + attacker F12).
+    const safeRoot = nodeResolve(opts.rootDir);
+    const norm = nodeResolve(abs);
+    if (norm !== safeRoot && !norm.startsWith(safeRoot + pathSep)) {
+      // Silent drop — never read out-of-tree files.
+      return;
+    }
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(abs);
+    } catch (err) {
+      if (isNotFound(err)) {
+        opts.onDeleted?.(relPath);
+        return;
+      }
+      // Best-effort — log and skip; another fs.watch event will re-fire.
+      console.warn('[sync/fs-mirror] read failed for', relPath, '-', describeErr(err));
+      return;
+    }
+    const u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const hash = hashBytes(u8);
+    try {
+      await opts.onRead({ path: relPath, bytes: u8, hash });
+    } catch (err) {
+      console.error('[sync/fs-mirror] handler threw for', relPath, '-', describeErr(err));
+    }
+  }
+
+  return {
+    notify(relPath) {
+      if (stopped) return;
+      // Reject obvious traversal attempts before the timer is even armed.
+      // DDR-054 §2f (defender M1 + attacker F12).
+      if (relPath.includes('..') || isAbsolute(relPath)) return;
+      if (!opts.accept(relPath)) return;
+      const prev = timers.get(relPath);
+      if (prev) clearTimeout(prev);
+      const t = setTimeout(() => {
+        void fire(relPath);
+      }, quiet);
+      timers.set(relPath, t);
+    },
+
+    pending() {
+      return timers.size;
+    },
+
+    async flush() {
+      const paths = Array.from(timers.keys());
+      for (const p of paths) {
+        const t = timers.get(p);
+        if (t) clearTimeout(t);
+      }
+      await Promise.all(paths.map((p) => fire(p)));
+    },
+
+    stop() {
+      stopped = true;
+      for (const t of timers.values()) clearTimeout(t);
+      timers.clear();
+    },
+  };
+}
+
+function defaultJoin(a: string, b: string): string {
+  return nodeJoin(a, b);
+}
+
+function isNotFound(err: unknown): boolean {
+  return !!err && typeof err === 'object' && (err as { code?: string }).code === 'ENOENT';
+}
+
+function describeErr(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/plugins/design/dev-server/sync/hubs-config.ts

@@ -0,0 +1,87 @@
+// Read-only mirror of cli/lib/hubs-config.mjs for the dev-server runtime.
+//
+// The CLI owns writes (`maude design link` adds + removes entries); the
+// dev-server only ever reads. This module deliberately re-implements the
+// reader instead of importing from cli/lib so the Bun-side ts compile chain
+// doesn't pull in the .mjs CLI surface.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+export interface HubRecord {
+  token: string;
+  linkedAt: number;
+}
+
+export interface HubsConfig {
+  hubs: Record<string, HubRecord>;
+}
+
+/** Resolve the on-disk path to hubs.json (matches cli/lib/hubs-config.mjs). */
+export function hubsConfigPath(): string {
+  if (process.env.HUBS_CONFIG_PATH) return process.env.HUBS_CONFIG_PATH;
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
+  return join(base, 'maude', 'hubs.json');
+}
+
+/** Normalize a hub URL — trim trailing slash, lower-case scheme + host. */
+export function normalizeUrl(url: string): string {
+  const u = new URL(url);
+  u.protocol = u.protocol.toLowerCase();
+  u.hostname = u.hostname.toLowerCase();
+  let str = u.toString();
+  if (str.endsWith('/') && u.pathname === '/') str = str.slice(0, -1);
+  return str;
+}
+
+export function loadHubsConfig(): HubsConfig {
+  const path = hubsConfigPath();
+  if (!existsSync(path)) return { hubs: {} };
+  warnIfWorldOrGroupReadable(path);
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.hubs !== 'object' || parsed.hubs === null) {
+      return { hubs: {} };
+    }
+    return parsed;
+  } catch {
+    return { hubs: {} };
+  }
+}
+
+// DDR-054 §2h (attacker F15). The CLI writes hubs.json with mode 0600. If a
+// user later opens the file with an editor that resets permissions, or syncs
+// it from a different host, the dev-server warns once on read. Non-blocking —
+// Windows + funky-umask hosts get a polite nudge rather than a hard refusal.
+let _modeWarnedFor: string | null = null;
+function warnIfWorldOrGroupReadable(path: string): void {
+  if (platform() === 'win32') return; // POSIX-mode semantics don't apply
+  if (_modeWarnedFor === path) return; // warn once per process
+  try {
+    const stats = statSync(path);
+    const mode = stats.mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+      console.warn(
+        `[sync] ${path} is mode ${mode.toString(8)} — recommend 'chmod 600 ${path}' (only owner can read hub tokens).`
+      );
+      _modeWarnedFor = path;
+    }
+  } catch {
+    /* statSync raced with a delete — next read will retry */
+  }
+}
+
+/** Look up a token for `url`. Returns null when no entry exists. */
+export function getHubToken(url: string): string | null {
+  try {
+    const norm = normalizeUrl(url);
+    const cfg = loadHubsConfig();
+    const record = cfg.hubs[norm];
+    return record ? record.token : null;
+  } catch {
+    return null;
+  }
+}