@1agh/maude 0.15.0

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+// Dev-server entry. Bun.serve + native WebSocket + per-platform standalone
+// binary distribution (DDR-009, DDR-013, DDR-015).
+//
+// Process layout:
+//   createContext()  -> repo root, config, paths, pub/sub bus
+//   createApi(ctx)   -> comments / canvas-state / index / system data
+//   createInspect()  -> active-canvas tracking + HTML injection
+//   createWs()       -> Bun.serve native WS handler
+//   createHttp()     -> route table + fall-through fetch
+//   createFsWatch()  -> recursive fs.watch -> bus -> WS broadcast
+//
+// Single Bun.serve instance owns both HTTP routes and the WS upgrade. Nothing
+// else binds to a port. The orchestrator (slash commands) reads _server.json
+// to detect a live instance and avoid duplicate boots.
+
+import { spawn } from 'node:child_process';
+
+import { createApi } from './api.ts';
+import { createContext } from './context.ts';
+import { createFsWatch } from './fs-watch.ts';
+import { createHttp } from './http.ts';
+import { createInspect } from './inspect.ts';
+import { startHeapWatch } from './mem.ts';
+import { createWs } from './ws.ts';
+
+const ctx = createContext();
+
+const api = createApi(ctx, async (file) => {
+  // After every comments mutation, re-broadcast the updated list.
+  const comments = await api.loadCommentsForFile(file);
+  ctx.bus.emit('comments', { file, comments });
+});
+
+const inspect = createInspect(ctx, (file) => api.loadCommentsForFile(file));
+await inspect.load();
+
+const ws = createWs(ctx, api, inspect);
+const http = createHttp(ctx, api, inspect);
+const fsWatch = createFsWatch(ctx);
+
+// Port: --port arg > $PORT > $MDCC_DEV_PORT > 4399.
+function resolvePort(): number {
+  const i = process.argv.indexOf('--port');
+  if (i !== -1 && process.argv[i + 1]) return Number(process.argv[i + 1]);
+  const env = process.env.PORT ?? process.env.MDCC_DEV_PORT;
+  if (env) return Number(env);
+  return 4399;
+}
+
+const PORT = resolvePort();
+
+const server = Bun.serve<{ id: string; remote: string }, never>({
+  port: PORT,
+  hostname: '127.0.0.1',
+  development: process.env.NODE_ENV !== 'production',
+  routes: http.routes,
+  async fetch(req, srv) {
+    // WebSocket upgrade.
+    if (new URL(req.url).pathname.startsWith('/_ws')) {
+      const ok = srv.upgrade(req, {
+        data: {
+          id: crypto.randomUUID(),
+          remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+        },
+      });
+      if (ok) return undefined as unknown as Response;
+      return new Response('Upgrade failed', { status: 400 });
+    }
+    return http.fetch(req);
+  },
+  websocket: ws.handler,
+  error(e) {
+    console.error('[bun.serve error]', e);
+    return new Response('Server error', { status: 500 });
+  },
+});
+
+await Bun.write(
+  ctx.paths.serverInfoFile,
+  JSON.stringify(
+    {
+      pid: process.pid,
+      port: server.port,
+      url: `http://localhost:${server.port}`,
+      started: new Date().toISOString(),
+      project: ctx.cfg.name,
+      config_source: ctx.cfg._source,
+    },
+    null,
+    2
+  )
+);
+
+fsWatch.start();
+startHeapWatch();
+
+const url = `http://localhost:${server.port}`;
+console.log(`\n  ${ctx.projectLabel} — local browser`);
+console.log('  ─────────────────────────────');
+console.log(`  ${url}`);
+console.log(`  Project:   ${ctx.cfg.name}`);
+console.log(`  Config:    ${ctx.cfg._source}`);
+console.log(`  Design:    ${ctx.paths.designRoot}`);
+console.log(`  Active:    ${ctx.paths.activeFile}`);
+console.log('  Press Ctrl+C to stop.\n');
+
+if (!process.env.NO_OPEN) {
+  if (process.platform === 'darwin')
+    spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+  else if (process.platform === 'linux')
+    spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+}
+
+async function shutdown() {
+  console.log('\n  Stopping…');
+  fsWatch.stop();
+  try {
+    await Bun.write(ctx.paths.serverInfoFile, '').catch(() => {});
+    // Remove the file by writing empty then unlinking.
+    const fs = await import('node:fs/promises');
+    await fs.unlink(ctx.paths.serverInfoFile).catch(() => {});
+  } catch {
+    /* ignore */
+  }
+  server.stop();
+  process.exit(0);
+}
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/plugins/design/dev-server/test/_helpers.ts

@@ -0,0 +1,81 @@
+// Shared test scaffolding. Bun-test only.
+
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type Subprocess, spawn } from 'bun';
+
+export interface Sandbox {
+  root: string;
+  designRoot: string;
+}
+
+export function makeSandbox(): Sandbox {
+  const root = mkdtempSync(join(tmpdir(), 'mdcc-test-'));
+  const designRoot = join(root, '.design');
+  mkdirSync(designRoot, { recursive: true });
+  writeFileSync(
+    join(designRoot, 'config.json'),
+    JSON.stringify(
+      {
+        name: 'test',
+        designRoot: '.design',
+        canvasGroups: [
+          { label: 'System', path: 'system' },
+          { label: 'UI', path: 'ui' },
+        ],
+      },
+      null,
+      2
+    )
+  );
+  mkdirSync(join(designRoot, 'ui'), { recursive: true });
+  writeFileSync(
+    join(designRoot, 'ui', 'fixture.html'),
+    '<!doctype html><html><head><title>fix</title></head><body><h1>fixture</h1></body></html>'
+  );
+  return { root, designRoot };
+}
+
+let portCounter = 4500;
+export function nextPort(): number {
+  // Bump on every call so parallel tests don't collide. Bun.serve will throw
+  // EADDRINUSE if the host happened to bind one — caller retries with nextPort().
+  portCounter += 1;
+  return portCounter;
+}
+
+export async function bootServer(root: string, port: number): Promise<Subprocess> {
+  const serverPath = join(import.meta.dir, '..', 'server.ts');
+  const proc = spawn({
+    cmd: ['bun', 'run', serverPath, '--port', String(port), '--root', root],
+    cwd: join(import.meta.dir, '..'),
+    env: { ...process.env, NO_OPEN: '1', NODE_ENV: 'test' },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  // Wait up to 3 s for the server to bind.
+  const start = Date.now();
+  while (Date.now() - start < 3000) {
+    try {
+      const r = await fetch(`http://localhost:${port}/_health`, {
+        signal: AbortSignal.timeout(200),
+      });
+      if (r.ok) return proc;
+    } catch {
+      /* not up yet */
+    }
+    await Bun.sleep(50);
+  }
+  proc.kill();
+  throw new Error(`server did not start on port ${port} within 3 s`);
+}
+
+export async function killProc(proc: Subprocess) {
+  proc.kill();
+  try {
+    await proc.exited;
+  } catch {
+    /* ignore */
+  }
+}

package/plugins/design/dev-server/test/active-state.test.ts

@@ -0,0 +1,145 @@
+// Smoke: WS `active` + `tabs` + `select` messages reflect into _active.json.
+
+import { describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+async function openWs(port: number): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://localhost:${port}/_ws`);
+  await new Promise<void>((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('ws open timeout')), 2000);
+    ws.addEventListener('open', () => {
+      clearTimeout(t);
+      resolve();
+    });
+    ws.addEventListener('error', (e) => {
+      clearTimeout(t);
+      reject(e);
+    });
+  });
+  return ws;
+}
+
+describe('_active.json round-trip', () => {
+  test('active + tabs + selected persist to disk', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const ws = await openWs(port);
+      ws.send(JSON.stringify({ type: 'active', file: '.design/ui/fixture.html' }));
+      ws.send(JSON.stringify({ type: 'tabs', tabs: ['.design/ui/fixture.html'] }));
+      ws.send(
+        JSON.stringify({
+          type: 'select',
+          selection: {
+            file: '.design/ui/fixture.html',
+            selector: 'h1',
+            tag: 'h1',
+            classes: '',
+            text: 'fixture',
+            dom_path: ['html', 'body', 'h1'],
+            bounds: { x: 0, y: 0, w: 100, h: 24 },
+            html: '<h1>fixture</h1>',
+          },
+        })
+      );
+
+      // Allow time for the queued microtask save to land.
+      await Bun.sleep(150);
+
+      const state = (await Bun.file(join(designRoot, '_active.json')).json()) as {
+        active: string;
+        open_tabs: string[];
+        selected: { selector: string; tag: string; v?: number };
+      };
+      expect(state.active).toBe('.design/ui/fixture.html');
+      expect(state.open_tabs).toContain('.design/ui/fixture.html');
+      expect(state.selected.selector).toBe('h1');
+      expect(state.selected.tag).toBe('h1');
+      expect(state.selected.v).toBe(1);
+      ws.close();
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('selection carrying data-cd-id stamps v=2 + canvas slug', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const ws = await openWs(port);
+      ws.send(JSON.stringify({ type: 'active', file: '.design/ui/fixture.tsx' }));
+      ws.send(
+        JSON.stringify({
+          type: 'select',
+          selection: {
+            file: '.design/ui/fixture.tsx',
+            selector: 'div.btn',
+            tag: 'button',
+            classes: 'btn btn--ghost',
+            text: 'OK',
+            dom_path: ['html', 'body', 'button'],
+            bounds: { x: 10, y: 20, w: 80, h: 32 },
+            html: '<button class="btn btn--ghost">OK</button>',
+            id: 'a1b2c3d4',
+          },
+        })
+      );
+      await Bun.sleep(150);
+
+      const state = (await Bun.file(join(designRoot, '_active.json')).json()) as {
+        selected: { id?: string; canvas?: string; v: number; selector: string };
+      };
+      expect(state.selected.v).toBe(2);
+      expect(state.selected.id).toBe('a1b2c3d4');
+      // Canvas slug = designRoot-relative path, ext-less, POSIX. The fixture
+      // file is `.design/ui/fixture.tsx`; designRel = `.design` → slug =
+      // `ui/fixture`.
+      expect(state.selected.canvas).toBe('ui/fixture');
+      // v=2 still carries the v1 selector as a fallback (legacy readers).
+      expect(state.selected.selector).toBe('div.btn');
+      ws.close();
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('selection without id stays v=1 (legacy HTML canvas / shell chrome click)', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const ws = await openWs(port);
+      ws.send(JSON.stringify({ type: 'active', file: '.design/ui/fixture.html' }));
+      ws.send(
+        JSON.stringify({
+          type: 'select',
+          selection: {
+            file: '.design/ui/fixture.html',
+            selector: 'h1',
+            tag: 'h1',
+            classes: '',
+            text: '',
+            dom_path: ['html', 'body', 'h1'],
+            bounds: { x: 0, y: 0, w: 0, h: 0 },
+            html: '<h1/>',
+          },
+        })
+      );
+      await Bun.sleep(150);
+
+      const state = (await Bun.file(join(designRoot, '_active.json')).json()) as {
+        selected: { v: number; id?: string; canvas?: string };
+      };
+      expect(state.selected.v).toBe(1);
+      expect(state.selected.id).toBeUndefined();
+      expect(state.selected.canvas).toBeUndefined();
+      ws.close();
+    } finally {
+      await killProc(proc);
+    }
+  });
+});

package/plugins/design/dev-server/test/annotations-api.test.ts

@@ -0,0 +1,146 @@
+// /_api/annotations — Phase 5 GET / PUT round-trip + validation gates.
+//
+// Verifies:
+//   - GET returns empty body for a canvas with no annotations file
+//   - PUT writes `<designRoot>/<slug>.annotations.svg`
+//   - GET subsequently returns the saved SVG
+//   - PUT rejects non-SVG bodies (400)
+//   - PUT rejects oversized bodies (>1 MB)
+//   - Unknown method → 405
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+const SVG_OK =
+  '<svg xmlns="http://www.w3.org/2000/svg" data-mdcc-annotations="1">' +
+  '<path data-id="p1" data-tool="pen" stroke="#d63b1f" stroke-width="2" fill="none" d="M0 0 L10 10"/>' +
+  '</svg>';
+
+describe('/_api/annotations — GET/PUT', () => {
+  test('GET on a canvas with no annotations returns empty body (200)', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      writeFileSync(
+        join(designRoot, 'ui', 'Phase5.tsx'),
+        'export default function P(){return <main/>}\n'
+      );
+      const r = await fetch(
+        `http://localhost:${port}/_api/annotations?file=${encodeURIComponent(
+          '.design/ui/Phase5.tsx'
+        )}`
+      );
+      expect(r.status).toBe(200);
+      const body = await r.text();
+      expect(body).toBe('');
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PUT writes <designRoot>/<slug>.annotations.svg and GET round-trips', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      writeFileSync(
+        join(designRoot, 'ui', 'Round.tsx'),
+        'export default function P(){return <main/>}\n'
+      );
+      const put = await fetch(`http://localhost:${port}/_api/annotations`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file: '.design/ui/Round.tsx', svg: SVG_OK }),
+      });
+      expect(put.status).toBe(204);
+
+      // File slug derives from the path under designRoot: `ui-round`.
+      const written = join(designRoot, 'ui-round.annotations.svg');
+      expect(existsSync(written)).toBe(true);
+      expect(readFileSync(written, 'utf8')).toBe(SVG_OK);
+
+      const get = await fetch(
+        `http://localhost:${port}/_api/annotations?file=${encodeURIComponent(
+          '.design/ui/Round.tsx'
+        )}`
+      );
+      expect(get.status).toBe(200);
+      expect(get.headers.get('content-type')).toContain('image/svg+xml');
+      expect(await get.text()).toBe(SVG_OK);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PUT rejects non-SVG bodies with 400', async () => {
+    const { root } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const r = await fetch(`http://localhost:${port}/_api/annotations`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file: '.design/ui/X.tsx', svg: '<p>nope</p>' }),
+      });
+      expect(r.status).toBe(400);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PUT rejects missing file', async () => {
+    const { root } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const r = await fetch(`http://localhost:${port}/_api/annotations`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ svg: SVG_OK }),
+      });
+      expect(r.status).toBe(400);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PUT rejects bodies above the 1 MB ceiling', async () => {
+    const { root } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const huge = `<svg>${'x'.repeat(1024 * 1024 + 100)}</svg>`;
+      const r = await fetch(`http://localhost:${port}/_api/annotations`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file: '.design/ui/X.tsx', svg: huge }),
+      });
+      // readJson throws on body too large → readJson returns null → 400.
+      // saveAnnotations would also reject on length, so either path yields 400.
+      expect(r.status).toBe(400);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('Unknown method (DELETE) returns 405', async () => {
+    const { root } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const r = await fetch(`http://localhost:${port}/_api/annotations`, {
+        method: 'DELETE',
+      });
+      expect(r.status).toBe(405);
+    } finally {
+      await killProc(proc);
+    }
+  });
+});