@1agh/maude 0.20.0 → 0.21.0

package/plugins/design/dev-server/collab/ai-activity.ts

@@ -0,0 +1,127 @@
+// Phase 8 Task 4 — AI activity tracking with heartbeat-based TTL.
+//
+// `/design:edit` (or any external slash command driving Claude work) POSTs to
+// /_api/ai/start when it begins editing a canvas, pings /_api/ai/heartbeat
+// every 10 seconds, and POSTs /_api/ai/end on normal completion. The server
+// maintains an in-memory map keyed by canvas file path, broadcasts changes
+// over the inspector WS bus so every open client renders a yellow "Claude is
+// editing this canvas" banner.
+//
+// Why not Awareness — Awareness is the y-protocols channel for connected
+// peers. The AI is not a connected peer (it lives in a slash command, not a
+// browser tab) and the banner has to reach BOTH collab and inspector clients,
+// not just the per-canvas Y.Doc room. A separate bus event keeps the model
+// honest: AI activity is a server-managed projection, not a peer state.
+//
+// 30-second grace TTL — if the slash command crashes (no /end POST) the
+// banner auto-clears 30 s after the last heartbeat. A janitor runs every 5 s
+// and broadcasts cleared state if the entry expired.
+
+import type { Context } from '../context.ts';
+
+const HEARTBEAT_GRACE_MS = 30_000;
+const JANITOR_INTERVAL_MS = 5_000;
+
+export interface AiActivityEntry {
+  file: string;
+  author: string;
+  startedAt: number;
+  lastHeartbeat: number;
+}
+
+export interface AiActivity {
+  /** Begin tracking AI work on a canvas. Idempotent — replaces any prior. */
+  start(file: string, author: string): AiActivityEntry;
+  /** Refresh the lastHeartbeat timestamp. Returns null if no entry. */
+  heartbeat(file: string): AiActivityEntry | null;
+  /** Explicit end — clears immediately on normal completion. */
+  end(file: string): boolean;
+  /** Read the live state — used by the GET /_api/ai endpoint. */
+  list(): AiActivityEntry[];
+  /** Check one canvas — used by the bus broadcaster. */
+  get(file: string): AiActivityEntry | null;
+  /** Tear down the janitor (server shutdown). */
+  stop(): void;
+}
+
+export function createAiActivity(ctx: Context, now: () => number = Date.now): AiActivity {
+  const entries = new Map<string, AiActivityEntry>();
+  let janitor: ReturnType<typeof setInterval> | null = null;
+
+  function broadcast(file: string, entry: AiActivityEntry | null) {
+    ctx.bus.emit('ai-activity', { file, entry });
+  }
+
+  function expired(entry: AiActivityEntry, t: number): boolean {
+    return t - entry.lastHeartbeat > HEARTBEAT_GRACE_MS;
+  }
+
+  function start(file: string, author: string): AiActivityEntry {
+    const t = now();
+    const entry: AiActivityEntry = {
+      file,
+      author,
+      startedAt: entries.get(file)?.startedAt ?? t,
+      lastHeartbeat: t,
+    };
+    entries.set(file, entry);
+    broadcast(file, entry);
+    ensureJanitor();
+    return entry;
+  }
+
+  function heartbeat(file: string): AiActivityEntry | null {
+    const entry = entries.get(file);
+    if (!entry) return null;
+    entry.lastHeartbeat = now();
+    broadcast(file, entry);
+    return entry;
+  }
+
+  function end(file: string): boolean {
+    if (!entries.has(file)) return false;
+    entries.delete(file);
+    broadcast(file, null);
+    if (entries.size === 0 && janitor) {
+      clearInterval(janitor);
+      janitor = null;
+    }
+    return true;
+  }
+
+  function list(): AiActivityEntry[] {
+    return Array.from(entries.values());
+  }
+
+  function get(file: string): AiActivityEntry | null {
+    return entries.get(file) ?? null;
+  }
+
+  function ensureJanitor() {
+    if (janitor || typeof setInterval === 'undefined') return;
+    janitor = setInterval(() => {
+      const t = now();
+      for (const [file, entry] of entries) {
+        if (expired(entry, t)) {
+          entries.delete(file);
+          broadcast(file, null);
+        }
+      }
+      if (entries.size === 0 && janitor) {
+        clearInterval(janitor);
+        janitor = null;
+      }
+    }, JANITOR_INTERVAL_MS);
+  }
+
+  function stop(): void {
+    if (janitor) {
+      clearInterval(janitor);
+      janitor = null;
+    }
+  }
+
+  return { start, heartbeat, end, list, get, stop };
+}
+
+export { HEARTBEAT_GRACE_MS, JANITOR_INTERVAL_MS };

package/plugins/design/dev-server/collab/git-lifecycle.ts

@@ -0,0 +1,124 @@
+// Phase 8 Task 7 — `.git/HEAD` watcher. On branch switch (`git checkout`) or
+// pull mid-session, force-snapshot every dirty Y.Doc to its on-disk JSON form
+// BEFORE prompting peers to reload. Order matters per DDR-051 §3:
+//
+//   1. Synchronously flush every dirty room → JSON via registry.flushAll().
+//   2. THEN broadcast a `git-lifecycle` bus event with the new HEAD ref.
+//   3. Clients render a non-modal "Repo state changed — reload to sync?"
+//      banner; on confirm they call location.reload() and the next mount
+//      seeds the Y.Doc from the (now branch-current) JSON.
+//
+// Without step 1, the reload prompt can fire while in-flight edits are still
+// buffered in the 800 ms debounce window — the user's "reload" click then
+// silently discards them. Force-snapshot is the cheap escape valve: pay the
+// full sync cost once at branch-switch time.
+
+import { existsSync, readFileSync, watch } from 'node:fs';
+import path from 'node:path';
+
+import type { Context } from '../context.ts';
+import type { Registry } from './registry.ts';
+
+export interface GitLifecycle {
+  /** Stop the underlying watcher (server shutdown). */
+  stop(): void;
+}
+
+interface GitLifecycleEvent {
+  reason: 'head-changed';
+  head: string;
+  prevHead: string | null;
+  ts: number;
+}
+
+const HEAD_DEBOUNCE_MS = 250;
+
+export function createGitLifecycle(ctx: Context, registry: Registry): GitLifecycle {
+  const gitDir = path.join(ctx.paths.repoRoot, '.git');
+  const headPath = path.join(gitDir, 'HEAD');
+
+  if (!existsSync(headPath)) {
+    // Not a git repo — no lifecycle to watch. Quietly no-op so the dev-server
+    // still works inside scratch / templated projects.
+    return { stop: () => {} };
+  }
+
+  let prevHead: string | null = readHeadSafe(headPath);
+  let debounce: ReturnType<typeof setTimeout> | null = null;
+  let watcher: ReturnType<typeof watch> | null = null;
+  let stopped = false;
+
+  async function onChange() {
+    if (stopped) return;
+    const next = readHeadSafe(headPath);
+    if (next === null) return; // transient mid-write read; ignore
+    if (next === prevHead) return;
+    const old = prevHead;
+    prevHead = next;
+
+    // STEP 1 — synchronous JSON flush BEFORE the prompt. Awaiting is critical;
+    // the broadcast must NOT race ahead of the disk write.
+    try {
+      await registry.flushAll();
+    } catch (err) {
+      console.error('[git-lifecycle] flushAll failed:', err);
+    }
+
+    // STEP 2 — broadcast. Clients render a reload prompt; user confirms → reload.
+    const evt: GitLifecycleEvent = {
+      reason: 'head-changed',
+      head: next,
+      prevHead: old,
+      ts: Date.now(),
+    };
+    ctx.bus.emit('git-lifecycle', evt);
+  }
+
+  function schedule() {
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      debounce = null;
+      void onChange();
+    }, HEAD_DEBOUNCE_MS);
+  }
+
+  try {
+    // Watch the HEAD file directly. fs.watch on .git/HEAD fires on every
+    // checkout (git rewrites the file with the new ref) and on pull (when
+    // git updates HEAD to a new commit via the `update-ref` path). Some
+    // filesystems / git implementations fire spurious events on packfile
+    // operations too — the readHead diff above filters noise.
+    watcher = watch(headPath, { persistent: false }, () => schedule());
+  } catch (err) {
+    console.warn(
+      '[git-lifecycle] failed to watch .git/HEAD:',
+      err instanceof Error ? err.message : err
+    );
+  }
+
+  function stop() {
+    stopped = true;
+    if (debounce) {
+      clearTimeout(debounce);
+      debounce = null;
+    }
+    if (watcher) {
+      try {
+        watcher.close();
+      } catch {
+        /* ignore */
+      }
+      watcher = null;
+    }
+  }
+
+  return { stop };
+}
+
+function readHeadSafe(headPath: string): string | null {
+  try {
+    return readFileSync(headPath, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}

package/plugins/design/dev-server/collab/index.ts

@@ -0,0 +1,47 @@
+// Public surface of the collab module. Bundles the registry + persistence
+// wiring so ws.ts + server.ts don't need to know about the internal split.
+
+import type { Api } from '../api.ts';
+import type { Context } from '../context.ts';
+
+import { Y_TYPES, createPersistence } from './persistence.ts';
+import { type Registry, createRegistry } from './registry.ts';
+
+export { Y_TYPES };
+export type { Registry } from './registry.ts';
+export type { Room, RoomConn } from './room.ts';
+export type { CollabConn } from './protocol.ts';
+
+export interface Collab {
+  registry: Registry;
+}
+
+/**
+ * Build the collab subsystem for this server instance. One registry +
+ * persistence binding per dev-server boot. The registry is also the surface
+ * the git-lifecycle path will call to force-snapshot dirty rooms (Phase 8
+ * Task 7).
+ */
+export function createCollab(ctx: Context, api: Api): Collab {
+  // Inverse of api.fileSlug — we have the URL slug, need the canonical
+  // repo-relative path the api expects. The current fileSlug() is destructive
+  // (loses the extension + the designRel prefix), so we round-trip by
+  // scanning loadAllComments — cheap enough at room-open time, and a fresh
+  // canvas with no comments yet just returns null (an empty Y.Doc is correct
+  // in that case).
+  //
+  // Task 3 will tighten this to a slug -> file lookup table maintained from
+  // the index/file-tree state so we don't need to read every JSON file.
+  async function fileForSlug(slug: string): Promise<string | null> {
+    const all = await api.loadAllComments();
+    for (const [file] of Object.entries(all)) {
+      if (api.fileSlug(file) === slug) return file;
+    }
+    return null;
+  }
+
+  const persistence = createPersistence({ ctx, api, fileForSlug });
+  const registry = createRegistry(persistence);
+
+  return { registry };
+}

package/plugins/design/dev-server/collab/persistence.ts

@@ -0,0 +1,123 @@
+// DDR-051 persistence wiring — bridges Room callbacks to the existing JSON
+// snapshots (Phase 6 _comments/<slug>.json) + Phase 5 annotations.svg + the
+// new `.ydoc.bin` cache under _state/<slug>.ydoc.bin.
+
+import path from 'node:path';
+
+import * as Y from 'yjs';
+
+import type { Api } from '../api.ts';
+import type { Context } from '../context.ts';
+import { type RoomCallbacks, ensureStateDir } from './room.ts';
+
+/**
+ * Y.Doc shared-type names. Frozen on Task 1 so client + server agree even
+ * before they're populated. Task 3 added `comments`; Task 5 adds `annotations`
+ * (a Y.Map holding the SVG string under the `svg` key — LWW shape, mirrors
+ * the current /_api/annotations PUT semantics).
+ */
+export const Y_TYPES = {
+  comments: 'comments',
+  annotations: 'annotations',
+  presentation: 'presentation',
+} as const;
+
+export interface PersistenceDeps {
+  ctx: Context;
+  api: Api;
+  /**
+   * Resolve a canvas slug back to the repo-relative `file` path the api
+   * expects. The collab WS sends slugs (URL-safe), the comments path
+   * round-trips through Api.fileSlug. Persistence callers may also call
+   * `noteFile(file)` to populate the lookup table — server-side write paths
+   * (comments + annotations) call this so the room can locate the canvas
+   * even when no prior JSON file existed.
+   */
+  fileForSlug: (slug: string) => Promise<string | null>;
+  /** Best-effort cache primer — see fileForSlug above. */
+  noteFile?: (file: string) => void;
+}
+
+/**
+ * Build the RoomCallbacks the registry plugs into createRoom().
+ *
+ * persistJson now serializes BOTH `comments` (Y.Array) and `annotations`
+ * (Y.Map → `svg` string) back to their existing on-disk formats. Each is
+ * skipped when the Y type is empty / unset — the JSON file stays whatever
+ * the prior legacy write produced.
+ */
+export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
+  const { ctx, api, fileForSlug } = deps;
+  const stateDir = ensureStateDir(ctx.paths.designRoot);
+
+  function ydocBinPath(slug: string): string {
+    return path.join(stateDir, `${slug}.ydoc.bin`);
+  }
+
+  async function readBinary(slug: string): Promise<Uint8Array | null> {
+    try {
+      const file = Bun.file(ydocBinPath(slug));
+      if (!(await file.exists())) return null;
+      const buf = await file.arrayBuffer();
+      return new Uint8Array(buf);
+    } catch {
+      return null;
+    }
+  }
+
+  async function seed(slug: string, doc: Y.Doc): Promise<void> {
+    // Step 1 — try the binary cache.
+    const binary = await readBinary(slug);
+    if (binary && binary.byteLength > 0) {
+      Y.applyUpdate(doc, binary);
+      return;
+    }
+
+    // Step 2 — seed each Y type from its existing on-disk source.
+    const file = await fileForSlug(slug);
+    if (!file) return;
+
+    const [comments, svg] = await Promise.all([
+      api.loadCommentsForFile(file),
+      api.loadAnnotations(file),
+    ]);
+
+    if (comments.length === 0 && !svg) return;
+
+    doc.transact(() => {
+      if (comments.length > 0) {
+        const arr = doc.getArray<unknown>(Y_TYPES.comments);
+        arr.push(comments);
+      }
+      if (svg && typeof svg === 'string') {
+        const map = doc.getMap<string>(Y_TYPES.annotations);
+        map.set('svg', svg);
+      }
+    }, 'seed');
+  }
+
+  async function persistJson(slug: string, doc: Y.Doc): Promise<void> {
+    const file = await fileForSlug(slug);
+    if (!file) return;
+
+    // Comments — Y.Array projection back to JSON.
+    const arr = doc.getArray(Y_TYPES.comments);
+    if (arr.length > 0) {
+      const list = arr.toArray() as Parameters<Api['saveCommentsForFile']>[1];
+      await api.saveCommentsForFile(file, list);
+    }
+
+    // Annotations — Y.Map.svg → annotations.svg file. Task 5.
+    const map = doc.getMap<unknown>(Y_TYPES.annotations);
+    const svg = map.get('svg');
+    if (typeof svg === 'string' && svg) {
+      await api.saveAnnotations(file, svg);
+    }
+  }
+
+  async function persistBinary(slug: string, state: Uint8Array): Promise<void> {
+    await Bun.write(ydocBinPath(slug), state);
+  }
+
+  return { seed, persistJson, persistBinary };
+}

package/plugins/design/dev-server/collab/protocol.ts

@@ -0,0 +1,108 @@
+// y-websocket binary protocol — message routing for the collab WS.
+//
+// Mirrors the reference implementation in y-websocket/bin/utils.js (140 lines),
+// adapted to Bun's native ServerWebSocket. Two message types per the y-protocols
+// spec: 0 = sync (Y.Doc state), 1 = awareness (cursors / presence). Both ride a
+// varint framing of (messageType, payload).
+//
+// The functions are pure transport — Y.Doc lifecycle + persistence + room
+// registry live in `room.ts` and `registry.ts`.
+
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
+import * as awarenessProtocol from 'y-protocols/awareness';
+import * as syncProtocol from 'y-protocols/sync';
+import type * as Y from 'yjs';
+
+export const MESSAGE_SYNC = 0;
+export const MESSAGE_AWARENESS = 1;
+
+export interface CollabConn {
+  /** Push a frame to this single peer. */
+  send(payload: Uint8Array): void;
+}
+
+/**
+ * Encode the initial sync handshake (sync step 1) + current awareness state for
+ * a freshly connected peer. The peer replies with sync step 2 (their missing
+ * updates) which we hand back to `handleMessage`.
+ */
+export function encodeHandshake(doc: Y.Doc, awareness: awarenessProtocol.Awareness): Uint8Array[] {
+  const frames: Uint8Array[] = [];
+
+  const sync = encoding.createEncoder();
+  encoding.writeVarUint(sync, MESSAGE_SYNC);
+  syncProtocol.writeSyncStep1(sync, doc);
+  frames.push(encoding.toUint8Array(sync));
+
+  const states = awareness.getStates();
+  if (states.size > 0) {
+    const aw = encoding.createEncoder();
+    encoding.writeVarUint(aw, MESSAGE_AWARENESS);
+    encoding.writeVarUint8Array(
+      aw,
+      awarenessProtocol.encodeAwarenessUpdate(awareness, Array.from(states.keys()))
+    );
+    frames.push(encoding.toUint8Array(aw));
+  }
+
+  return frames;
+}
+
+/** Encode a sync update frame (broadcast after a Y.Doc local update). */
+export function encodeSyncUpdate(update: Uint8Array): Uint8Array {
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, MESSAGE_SYNC);
+  syncProtocol.writeUpdate(encoder, update);
+  return encoding.toUint8Array(encoder);
+}
+
+/** Encode an awareness update frame (broadcast after applyAwarenessUpdate). */
+export function encodeAwarenessFrame(
+  awareness: awarenessProtocol.Awareness,
+  changedClients: number[]
+): Uint8Array {
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, MESSAGE_AWARENESS);
+  encoding.writeVarUint8Array(
+    encoder,
+    awarenessProtocol.encodeAwarenessUpdate(awareness, changedClients)
+  );
+  return encoding.toUint8Array(encoder);
+}
+
+/**
+ * Decode and dispatch one incoming binary frame. Returns an optional reply
+ * frame the caller MUST send back to the originating peer (sync step 2 from
+ * the server, in response to the peer's sync step 1).
+ *
+ * `conn` is the origin token threaded into awarenessProtocol so the awareness
+ * registry can attribute states to the right peer.
+ */
+export function handleMessage(
+  payload: Uint8Array,
+  doc: Y.Doc,
+  awareness: awarenessProtocol.Awareness,
+  conn: CollabConn
+): Uint8Array | null {
+  const decoder = decoding.createDecoder(payload);
+  const messageType = decoding.readVarUint(decoder);
+
+  switch (messageType) {
+    case MESSAGE_SYNC: {
+      const encoder = encoding.createEncoder();
+      encoding.writeVarUint(encoder, MESSAGE_SYNC);
+      // readSyncMessage applies the peer's update to the doc and writes the
+      // response (sync step 2 / sync step 2 ack) into encoder.
+      syncProtocol.readSyncMessage(decoder, encoder, doc, conn);
+      if (encoding.length(encoder) > 1) return encoding.toUint8Array(encoder);
+      return null;
+    }
+    case MESSAGE_AWARENESS: {
+      awarenessProtocol.applyAwarenessUpdate(awareness, decoding.readVarUint8Array(decoder), conn);
+      return null;
+    }
+    default:
+      return null;
+  }
+}

package/plugins/design/dev-server/collab/registry.ts

@@ -0,0 +1,110 @@
+// Per-server registry of active collab rooms.
+//
+// Rooms are lazy: created on first connection for a given slug, retained while
+// any peer is connected, torn down (with a final flush) when the last peer
+// disconnects. The registry is also the surface the git-lifecycle handler will
+// call into (Phase 8 Task 7) to force-snapshot every dirty room before a reload
+// prompt — see DDR-051 §3.
+
+import { Y_TYPES } from './persistence.ts';
+import type { Room, RoomCallbacks } from './room.ts';
+import { createRoom } from './room.ts';
+
+export interface Registry {
+  /** Get-or-create. Reuses an existing room for the same slug. */
+  get(slug: string): Room;
+  /** Existence check — returns the live room if any, else null. NEVER creates. */
+  peek(slug: string): Room | null;
+  /**
+   * Phase 8 Task 3 bridge — inspector-channel writes (REST `/_api/comments*`
+   * or the legacy WS comments-add path) call this so the live Y.Array sees
+   * the change and broadcasts it to collab peers. No-op when no room is
+   * live; the next cold open will seed from the freshly-written JSON anyway.
+   *
+   * `comments` is the post-mutation JSON list (the same shape persistJson
+   * writes back). We replace the Y.Array contents wholesale inside a
+   * transaction tagged `'inspector-write'` so the doc.update broadcaster
+   * downstreams it to peers but skips the in-flight debounce loop.
+   */
+  syncRoomFromComments(slug: string, comments: readonly unknown[]): void;
+  /**
+   * Phase 8 Task 5 bridge — same shape as syncRoomFromComments but for the
+   * `annotations` Y.Map. The PUT /_api/annotations endpoint passes the
+   * post-write SVG; the room replaces `Y.Map.svg` so collab peers see the
+   * updated stroke set without waiting for a cold-open re-seed.
+   */
+  syncRoomFromAnnotations(slug: string, svg: string): void;
+  /** Flush every dirty room synchronously. DDR-051 branch-switch path. */
+  flushAll(): Promise<void>;
+  /** Tear down everything (e.g. on server shutdown). */
+  destroyAll(): Promise<void>;
+  /** Tear down a single room when its last peer leaves. */
+  drop(slug: string): Promise<void>;
+  /** Test/introspection. */
+  size(): number;
+}
+
+export function createRegistry(callbacks: RoomCallbacks): Registry {
+  const rooms = new Map<string, Room>();
+
+  function get(slug: string): Room {
+    let room = rooms.get(slug);
+    if (!room) {
+      room = createRoom(slug, callbacks);
+      rooms.set(slug, room);
+    }
+    return room;
+  }
+
+  function peek(slug: string): Room | null {
+    return rooms.get(slug) ?? null;
+  }
+
+  function syncRoomFromComments(slug: string, comments: readonly unknown[]): void {
+    const room = rooms.get(slug);
+    if (!room) return;
+    room.doc.transact(() => {
+      const arr = room.doc.getArray<unknown>(Y_TYPES.comments);
+      if (arr.length > 0) arr.delete(0, arr.length);
+      if (comments.length > 0) arr.push(comments as unknown[]);
+    }, 'inspector-write');
+  }
+
+  function syncRoomFromAnnotations(slug: string, svg: string): void {
+    const room = rooms.get(slug);
+    if (!room) return;
+    room.doc.transact(() => {
+      const map = room.doc.getMap<string>(Y_TYPES.annotations);
+      map.set('svg', svg);
+    }, 'inspector-write');
+  }
+
+  async function flushAll(): Promise<void> {
+    await Promise.all(Array.from(rooms.values(), (r) => r.flush()));
+  }
+
+  async function drop(slug: string): Promise<void> {
+    const room = rooms.get(slug);
+    if (!room) return;
+    if (room.size() > 0) return; // still active, leave it
+    rooms.delete(slug);
+    await room.destroy();
+  }
+
+  async function destroyAll(): Promise<void> {
+    const all = Array.from(rooms.values());
+    rooms.clear();
+    await Promise.all(all.map((r) => r.destroy()));
+  }
+
+  return {
+    get,
+    peek,
+    syncRoomFromComments,
+    syncRoomFromAnnotations,
+    flushAll,
+    destroyAll,
+    drop,
+    size: () => rooms.size,
+  };
+}