@1agh/maude 0.22.2 → 0.23.0

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