animader-cli 0.0.0-stage → 0.1.1

package/adapters/devserver.mjs

@@ -0,0 +1,481 @@
+// The dev generation server (plan section 5). It serves the same narrow
+// mounts as the demo server — the player page surface, the prepared
+// runtime, the allowlisted app/example modules — but every project-derived
+// byte comes from one immutable, generation-pinned tree: `/gen/<id>/…`
+// URLs are answered from that generation's own directory with in-flight
+// tracking, and `/config.json` is the current generation's rendered config
+// read once per request, so parallel requests can never mix an old payload
+// with a new timeline or audio asset. Before the first successful build
+// the root serves a small self-contained error/recovery page wired to the
+// development channel — a missing payload never has to reach READY.
+//
+// `/dev` is the development-only notification channel (server-sent
+// events): each connection is greeted with the current generation, and
+// `channel.broadcast` is the session's loudspeaker for reload/stale
+// events. The channel exists only in dev; nothing here is imported by the
+// exported player.
+//
+// Failures keep the demo's identity: a missing runtime root, a refused
+// port and a missing page surface carry the same codes and remedies as the
+// demo server, and close() ends every channel connection before closing
+// the socket.
+
+import { createReadStream } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { inside, requireRoot, send } from './http.mjs';
+import { serverError } from '../lib/errors.mjs';
+import { resolveRequest } from '../lib/routes.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function escapeHtml(text) {
+  return String(text)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+/**
+ * The self-contained page served while no successful generation exists.
+ * It carries no external asset and no player: the build error, its remedy,
+ * the promise that watching continues, and the tiny channel client that
+ * reloads onto the first successful generation.
+ */
+export function errorPageHtml(error) {
+  const failure = error ?? { code: 'build_failed', message: 'the first build has not succeeded yet', remedy: '' };
+  const remedy = failure.remedy ? `<p class="remedy">${escapeHtml(failure.remedy)}</p>` : '';
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="dark">
+<title>animader dev — build failed</title>
+<link rel="icon" href="data:,">
+<style>
+  :root { color-scheme: dark; }
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+         background: #0a0608; color: #d8cfc4; font: 14px/1.4 system-ui, sans-serif; }
+  main { max-width: 42rem; padding: 24px; }
+  h1 { font-size: 16px; color: #f0b27a; margin: 0 0 8px; }
+  p { margin: 6px 0; }
+  code, pre { font: 12px/1.4 ui-monospace, monospace; color: #8f857a; }
+  .banner { border: 1px solid #3a2a33; background: #140d11; padding: 12px; margin-top: 12px; }
+  .remedy { color: #d8cfc4; }
+</style>
+</head>
+<body>
+<main>
+  <h1>animader dev — build failed</h1>
+  <div class="banner" role="alert">
+    <p><code>${escapeHtml(failure.code ?? '')}</code></p>
+    <p>${escapeHtml(failure.message ?? String(failure))}</p>
+    ${remedy}
+  </div>
+  <p>Watching continues. This page reloads itself when a build succeeds; fix the named file and save.</p>
+  <noscript>Reload the page after fixing the project.</noscript>
+</main>
+<script type="module">
+  const status = document.querySelector('.banner');
+  const update = (detail) => {
+    if (!detail?.error) return;
+    status.replaceChildren();
+    const code = document.createElement('p');
+    code.append(document.createElement('code')).textContent = detail.error.code ?? '';
+    const message = document.createElement('p');
+    message.textContent = detail.error.message ?? '';
+    status.append(code, message);
+    if (detail.error.remedy) {
+      const remedy = document.createElement('p');
+      remedy.className = 'remedy';
+      remedy.textContent = detail.error.remedy;
+      status.append(remedy);
+    }
+  };
+  const events = new EventSource('/dev');
+  events.addEventListener('reload', (event) => {
+    const detail = JSON.parse(event.data);
+    if (detail?.url) window.location.replace(detail.url);
+  });
+  events.addEventListener('stale', (event) => {
+    try { update(JSON.parse(event.data)); } catch { /* the banner keeps the last message */ }
+  });
+</script>
+</body>
+</html>
+`;
+}
+
+/**
+ * @param {{
+ *   generations: object, latestError: () => (Object|null),
+ *   runtimeRoot?: string, runtimeFiles?: Array<{path: string, source: string}>,
+ *   onFault?: (line: string) => void,
+ *   host?: string, port?: number, pageRoot?: string, appLibRoot?: string,
+ *   appAdaptersRoot?: string, examplesRoot?: string,
+ * }} options
+ */
+export async function startDevServer({
+  generations,
+  runtimeRoot,
+  runtimeFiles,
+  latestError,
+  onFault = (line) => process.stderr.write(`${line}\n`),
+  host = '127.0.0.1',
+  port = 0,
+  pageRoot = join(PKG_ROOT, 'player'),
+  appLibRoot = join(PKG_ROOT, 'lib'),
+  appAdaptersRoot = join(PKG_ROOT, 'adapters'),
+  examplesRoot = join(PKG_ROOT, 'hello'),
+}) {
+  if (typeof latestError !== 'function') {
+    throw serverError('missing_error_state', 'the dev server needs a latestError provider', 'Pass the dev session error state provider.');
+  }
+  // The runtime mount has exactly one of two shapes: the contributor
+  // workspace's prepared bundle directory, or the installed toolchain's
+  // explicit file map (each /runtime/<path> answered by the package file
+  // the release manifest resolved — no directory, no traversal).
+  let runtimeMount;
+  if (runtimeFiles !== undefined) {
+    if (!Array.isArray(runtimeFiles) || runtimeFiles.length === 0) {
+      throw serverError('runtime_missing', 'the installed runtime file map is empty', 'Reinstall animader-cli; the toolchain manifest describes no runtime files.');
+    }
+    const map = new Map();
+    for (const entry of runtimeFiles) {
+      const info = await stat(entry.source).catch(() => null);
+      if (info === null || !info.isFile()) {
+        throw serverError('runtime_missing', `the installed runtime file ${entry.path} is missing at ${entry.source}`, 'Reinstall animader-cli; the toolchain manifest resolves this file.');
+      }
+      map.set(entry.path, entry.source);
+    }
+    runtimeMount = { kind: 'map', map };
+  } else {
+    const runtimeReal = await requireRoot(
+      runtimeRoot,
+      'runtime_missing',
+      'the prepared runtime bundle is missing',
+      'Run the one-time prepare: node demo/prepare.mjs',
+    );
+    runtimeMount = { kind: 'dir', root: runtimeReal };
+  }
+  const pageReal = await requireRoot(pageRoot, 'page_missing', 'the player page folder is missing', 'Restore the package player folder (npm/cli/player).');
+  const appLibReal = await requireRoot(appLibRoot, 'app_missing', 'the player core module folder is missing', 'Restore the package lib folder (npm/cli/lib).');
+  const appAdaptersReal = await requireRoot(appAdaptersRoot, 'app_missing', 'the player adapter folder is missing', 'Restore the package adapters folder (npm/cli/adapters).');
+  const examplesReal = await requireRoot(
+    examplesRoot,
+    'examples_missing',
+    'the hello player source folder is missing',
+    'Restore the package hello player folder (npm/cli/hello); the page imports its run and join modules.',
+  );
+
+  let pageHtml;
+  try {
+    pageHtml = await readFile(join(pageReal, 'index.html'));
+  } catch {
+    throw serverError('page_missing', 'the player page is missing', 'Restore the package player page (npm/cli/player/index.html).');
+  }
+
+  const roots = {
+    runtime: runtimeMount,
+    player: pageReal,
+    'app-lib': appLibReal,
+    'app-adapters': appAdaptersReal,
+    examples: examplesReal,
+  };
+
+  /** The directory a mount serves by containment under: plain roots answer
+   * themselves, a dir-mount answers its root, and a map mount has no
+   * directory at all (its rows serve by exact lookup only). */
+  function containmentRoot(mount) {
+    const entry = roots[mount];
+    if (entry === undefined) return undefined;
+    if (typeof entry === 'string') return entry;
+    return entry.kind === 'dir' ? entry.root : undefined;
+  }
+
+  /** A server-side fault is never silent: one line to the dev log and a
+   * named body, so an unexpected shape is traceable from both ends. */
+  function faultText(error, where) {
+    const message = String(error?.message ?? error).replace(/\s+/g, ' ').trim().slice(0, 300);
+    onFault(`dev server fault (${where}): internal_error: ${message}`);
+    return `internal_error: ${message}\n`;
+  }
+
+  // The development-only channel: one set of open event-stream responses.
+  const connections = new Set();
+  function frame(name, payload) {
+    return `event: ${name}\ndata: ${JSON.stringify(payload)}\n\n`;
+  }
+  function helloPayload() {
+    const current = generations.current();
+    const error = latestError();
+    return {
+      generation: current ? current.id : null,
+      url: current ? generations.pageUrl(current.id) : null,
+      error: error ? { code: error.code ?? null, message: error.message, remedy: error.remedy ?? null } : null,
+    };
+  }
+  const channel = {
+    connections,
+    helloPayload,
+    broadcast(name, payload) {
+      const text = frame(name, payload);
+      for (const res of connections) {
+        if (!res.destroyed) res.write(text);
+      }
+    },
+  };
+
+  /** Serve one file from a pinned generation with in-flight retention. */
+  async function serveGenerationFile(res, method, generation, route) {
+    generations.retain(generation.id);
+    generations.touch(generation.id);
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      void generations.release(generation.id);
+    };
+    res.on('finish', release);
+    res.on('close', release);
+    try {
+      const real = await inside(generation.dir, route.segments);
+      if (real === null) {
+        send(res, method, 404, 'not found\n');
+        return;
+      }
+      const info = await stat(real);
+      if (!info.isFile()) {
+        send(res, method, 404, 'not found\n');
+        return;
+      }
+      if (route.mime === null) {
+        send(res, method, 415, `unsupported_media_type: the demo has no MIME mapping for ${route.relative}\n`);
+        return;
+      }
+      const headers = {
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+        'Content-Type': route.mime,
+        'Content-Length': String(info.size),
+      };
+      if (method === 'HEAD') {
+        res.writeHead(200, headers);
+        res.end();
+        return;
+      }
+      res.writeHead(200, headers);
+      const stream = createReadStream(real);
+      stream.on('error', () => {
+        if (!res.writableEnded) res.destroy();
+      });
+      stream.pipe(res);
+    } catch (error) {
+      if (!res.headersSent) send(res, method, 500, faultText(error, `generation ${generation.id} ${route.relative}`));
+      else res.destroy();
+    }
+  }
+
+  async function handleChannel(req, res) {
+    res.writeHead(200, {
+      'X-Content-Type-Options': 'nosniff',
+      'Cache-Control': 'no-store',
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      Connection: 'keep-alive',
+    });
+    res.write('retry: 1000\n\n');
+    res.write(frame('hello', helloPayload()));
+    connections.add(res);
+    res.on('close', () => {
+      connections.delete(res);
+    });
+  }
+
+  const server = createServer((req, res) => {
+    handle(req, res).catch((error) => {
+      if (!res.headersSent) send(res, req.method, 500, faultText(error, `${req.method} ${req.url ?? '?'}`));
+      else res.destroy();
+    });
+  });
+
+  async function handle(req, res) {
+    const method = req.method ?? 'GET';
+    if (method !== 'GET' && method !== 'HEAD') {
+      send(res, method, 405, 'method not allowed\n', { Allow: 'GET, HEAD' });
+      return;
+    }
+    const route = resolveRequest(req.url ?? '/');
+    if (route.kind === 'channel') {
+      if (method === 'HEAD') {
+        send(res, method, 405, 'method not allowed\n', { Allow: 'GET' });
+        return;
+      }
+      await handleChannel(req, res);
+      return;
+    }
+    if (route.kind === 'page') {
+      const current = generations.current();
+      if (current === null) {
+        send(res, method, 200, errorPageHtml(latestError()), { 'Content-Type': 'text/html; charset=utf-8' });
+      } else {
+        send(res, method, 200, pageHtml, { 'Content-Type': 'text/html; charset=utf-8' });
+      }
+      return;
+    }
+    if (route.kind === 'config') {
+      const current = generations.current();
+      if (current === null) {
+        send(res, method, 404, 'no successful generation yet\n');
+      } else {
+        send(res, method, 200, current.configBody, { 'Content-Type': 'application/json; charset=utf-8' });
+      }
+      return;
+    }
+    if (route.kind === 'health') {
+      send(res, method, 200, '{"status":"ok","stage":"dev"}\n', { 'Content-Type': 'application/json; charset=utf-8' });
+      return;
+    }
+    if (route.kind === 'generation-config') {
+      const generation = generations.get(route.generation);
+      if (generation === null) {
+        send(res, method, 404, 'not found\n');
+        return;
+      }
+      generations.retain(generation.id);
+      generations.touch(generation.id);
+      res.on('finish', () => void generations.release(generation.id));
+      res.on('close', () => void generations.release(generation.id));
+      send(res, method, 200, generation.configBody, { 'Content-Type': 'application/json; charset=utf-8' });
+      return;
+    }
+    if (route.kind === 'generation-asset') {
+      const generation = generations.get(route.generation);
+      if (generation === null) {
+        send(res, method, 404, 'not found\n');
+        return;
+      }
+      await serveGenerationFile(res, method, generation, route);
+      return;
+    }
+    if (route.kind === 'error') {
+      send(res, method, route.status, `${route.code}: ${route.message}\n`);
+      return;
+    }
+
+    // The runtime mount answers by exact map lookup when installed (no
+    // directory to traverse) and by directory containment otherwise.
+    if (route.mount === 'runtime' && roots.runtime.kind === 'map') {
+      const source = roots.runtime.map.get(route.relative);
+      if (source === undefined) {
+        send(res, method, 404, 'not found\n');
+        return;
+      }
+      const info = await stat(source);
+      const headers = {
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+        'Content-Type': route.mime,
+        'Content-Length': String(info.size),
+      };
+      if (method === 'HEAD') {
+        res.writeHead(200, headers);
+        res.end();
+        return;
+      }
+      res.writeHead(200, headers);
+      const stream = createReadStream(source);
+      stream.on('error', () => {
+        if (!res.writableEnded) res.destroy();
+      });
+      stream.pipe(res);
+      return;
+    }
+
+    const root = containmentRoot(route.mount);
+    if (root === undefined) {
+      send(res, method, 404, 'not found\n');
+      return;
+    }
+    const real = await inside(root, route.segments);
+    if (real === null) {
+      send(res, method, 404, 'not found\n');
+      return;
+    }
+    const info = await stat(real);
+    if (!info.isFile()) {
+      send(res, method, 404, 'not found\n');
+      return;
+    }
+    if (route.mime === null) {
+      send(res, method, 415, `unsupported_media_type: the demo has no MIME mapping for ${route.relative}\n`);
+      return;
+    }
+    const headers = {
+      'X-Content-Type-Options': 'nosniff',
+      'Cache-Control': 'no-store',
+      'Content-Type': route.mime,
+      'Content-Length': String(info.size),
+    };
+    if (method === 'HEAD') {
+      res.writeHead(200, headers);
+      res.end();
+      return;
+    }
+    res.writeHead(200, headers);
+    const stream = createReadStream(real);
+    stream.on('error', () => {
+      if (!res.writableEnded) res.destroy();
+    });
+    stream.pipe(res);
+  }
+
+  try {
+    await new Promise((resolveListen, rejectListen) => {
+      const onError = (error) => {
+        server.off('listening', onListening);
+        rejectListen(error);
+      };
+      const onListening = () => {
+        server.off('error', onError);
+        resolveListen();
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, host);
+    });
+  } catch (error) {
+    if (error.code === 'EADDRINUSE') {
+      throw serverError(
+        'port_in_use',
+        `port ${port} on ${host} is already in use`,
+        'Retry with --port 0 (the default) to choose a free port, or pass another --port.',
+      );
+    }
+    if (error.code === 'EACCES') {
+      throw serverError('port_denied', `the operating system refused port ${port} on ${host}`, 'Retry with --port 0 to choose an unprivileged free port.');
+    }
+    throw serverError('server_bind', `could not bind ${host}:${port}: ${error.message}`, 'Retry with --port 0, or inspect the address family and permissions.');
+  }
+
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address !== null ? address.port : port;
+  let closed = false;
+  async function close() {
+    if (closed) return;
+    closed = true;
+    for (const res of connections) {
+      if (!res.destroyed) res.end();
+    }
+    connections.clear();
+    const done = new Promise((resolveClose) => server.close(resolveClose));
+    server.closeAllConnections?.();
+    await done;
+  }
+
+  return { url: `http://${host}:${actualPort}/`, host, port: actualPort, server, close, channel };
+}