@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/scripts/lib/serve.mjs

@@ -1,472 +0,0 @@
-/**
- * serve.mjs — dependency-free localhost API + static-file server for enact-extensions.
- *
- * Security model:
- *  - Binds to 127.0.0.1 by default (localhost-only). Never 0.0.0.0 by default.
- *    An explicit --host flag may override, but the caller is responsible for the
- *    risk; the docs (and help text) note that binding to a non-loopback address
- *    exposes the API to other machines on the network.
- *  - Static files are restricted to web/assets/ via path normalisation. Any
- *    request that resolves outside that directory is rejected with 400.
- *  - User input (name/platform/scope) is validated against an allowlist and
- *    passed to JS library functions directly — never to a shell.
- *
- * Exports:
- *  createServer(opts) → http.Server   (does NOT auto-listen)
- *  startServer(opts)  → Promise<{ server, url }>  (listens, returns url string)
- *
- * Routes:
- *  GET  /                  → web/index.html if present, else placeholder HTML
- *  GET  /assets/*          → web/assets/<path> (path-traversal guarded)
- *  GET  /api/index         → buildIndex() JSON
- *  GET  /api/installed     → { "<name>": [{platform,scope,home,path},...] }
- *  POST /api/install       → { name, platform, scope } → runInstall
- *  POST /api/uninstall     → { name, platform, scope } → runUninstall
- *  *    unknown            → 404
- *  *    wrong method       → 405 (for known routes with wrong method)
- */
-
-import http from "node:http";
-import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, normalize, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { buildIndex } from "./build-index.mjs";
-import { findInstalled } from "./ledger.mjs";
-import { listBundles } from "./list-bundles.mjs";
-import { resolveBundlePath } from "./resolve-bundle.mjs";
-import { runInstall } from "./run-install.mjs";
-import { runUninstall } from "./run-uninstall.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/**
- * Resolve the package root (two levels up from scripts/lib/).
- * Can be overridden via opts.packageRoot for tests.
- */
-const DEFAULT_PACKAGE_ROOT = resolve(__dirname, "..", "..");
-
-// ---------------------------------------------------------------------------
-// Validation constants
-// ---------------------------------------------------------------------------
-
-const VALID_PLATFORMS = new Set(["codex", "claude", "cursor", "enact", "shared", "all"]);
-const VALID_SCOPES = new Set(["global", "local"]);
-
-// ---------------------------------------------------------------------------
-// Content-type helpers
-// ---------------------------------------------------------------------------
-
-const MIME_TYPES = {
-  ".html": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".svg": "image/svg+xml",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-};
-
-function mimeForPath(filePath) {
-  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
-  return MIME_TYPES[ext] ?? "application/octet-stream";
-}
-
-// ---------------------------------------------------------------------------
-// Response helpers
-// ---------------------------------------------------------------------------
-
-function sendJson(res, status, body) {
-  const json = JSON.stringify(body, null, 2);
-  res.writeHead(status, {
-    "Content-Type": "application/json; charset=utf-8",
-    "Content-Length": Buffer.byteLength(json),
-  });
-  res.end(json);
-}
-
-function sendHtml(res, status, html) {
-  res.writeHead(status, {
-    "Content-Type": "text/html; charset=utf-8",
-    "Content-Length": Buffer.byteLength(html),
-  });
-  res.end(html);
-}
-
-function sendError(res, status, message) {
-  sendJson(res, status, { ok: false, error: message });
-}
-
-// ---------------------------------------------------------------------------
-// Placeholder HTML (served when web/index.html is absent)
-// ---------------------------------------------------------------------------
-
-function placeholderHtml() {
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>enact-extensions</title>
-  <link rel="stylesheet" href="/assets/tokens/colors.css" />
-  <link rel="stylesheet" href="/assets/tokens/base.css" />
-  <style>
-    body { font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
-    pre { background: #f4f4f4; padding: 1rem; border-radius: 4px; overflow: auto; }
-    h1 { color: var(--adl-teal-600, #147f84); }
-  </style>
-</head>
-<body>
-  <h1>enact-extensions</h1>
-  <p>The UI is loading. Discovery index:</p>
-  <pre id="index-output">Loading <a href="/api/index">/api/index</a>…</pre>
-  <script type="module">
-    const res = await fetch('/api/index');
-    const data = await res.json();
-    document.getElementById('index-output').textContent = JSON.stringify(data, null, 2);
-  </script>
-</body>
-</html>`;
-}
-
-// ---------------------------------------------------------------------------
-// Parse request body (JSON)
-// ---------------------------------------------------------------------------
-
-const MAX_BODY_BYTES = 64 * 1024; // 64 KiB — more than enough for name+platform+scope
-
-function readJsonBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    let totalBytes = 0;
-    req.on("data", (c) => {
-      totalBytes += c.length;
-      if (totalBytes > MAX_BODY_BYTES) {
-        req.destroy();
-        reject(new Error("Request body too large"));
-        return;
-      }
-      chunks.push(c);
-    });
-    req.on("end", () => {
-      const raw = Buffer.concat(chunks).toString("utf8");
-      if (!raw.trim()) {
-        resolve({});
-        return;
-      }
-      try {
-        resolve(JSON.parse(raw));
-      } catch {
-        reject(new Error("Invalid JSON body"));
-      }
-    });
-    req.on("error", reject);
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Static asset handler — guard against path traversal
-// ---------------------------------------------------------------------------
-
-function serveAsset(_req, res, assetsRoot, urlPath) {
-  // Decode URI, then normalise to strip ../ sequences
-  let relPath;
-  try {
-    relPath = decodeURIComponent(urlPath.slice("/assets".length));
-  } catch {
-    return sendError(res, 400, "Malformed URL");
-  }
-
-  // Normalise and ensure it stays within assetsRoot
-  const resolved = resolve(assetsRoot, "." + normalize(relPath));
-  if (!resolved.startsWith(assetsRoot + "/") && resolved !== assetsRoot) {
-    return sendError(res, 400, "Path traversal detected");
-  }
-
-  if (!existsSync(resolved)) {
-    return sendError(res, 404, `Asset not found: ${urlPath}`);
-  }
-
-  const mime = mimeForPath(resolved);
-  let stat;
-  try {
-    stat = statSync(resolved);
-  } catch {
-    return sendError(res, 500, "Failed to stat asset");
-  }
-
-  res.writeHead(200, {
-    "Content-Type": mime,
-    "Content-Length": stat.size,
-  });
-
-  const stream = createReadStream(resolved);
-  stream.pipe(res);
-  stream.on("error", () => {
-    if (!res.headersSent) {
-      sendError(res, 500, "Failed to read asset");
-    } else {
-      res.destroy();
-    }
-  });
-}
-
-// ---------------------------------------------------------------------------
-// createServer — build the http.Server (does NOT start listening)
-// ---------------------------------------------------------------------------
-
-/**
- * @param {object} opts
- * @param {string} [opts.packageRoot]  - Package root for locating web/ and extensions/.
- * @param {object} [opts.installDefaults] - Option bag merged into every runInstall/runUninstall call.
- *   Use this in tests to redirect ledgerHome, sharedHome, etc. to temp dirs.
- * @returns {http.Server}
- */
-export function createServer(opts = {}) {
-  const packageRoot = opts.packageRoot ?? DEFAULT_PACKAGE_ROOT;
-  const installDefaults = opts.installDefaults ?? {};
-
-  const webRoot = join(packageRoot, "web");
-  const assetsRoot = join(webRoot, "assets");
-  const indexHtmlPath = join(webRoot, "index.html");
-  const extensionsRoot = join(packageRoot, "extensions");
-
-  const server = http.createServer(async (req, res) => {
-    const url = req.url ?? "/";
-    const method = (req.method ?? "GET").toUpperCase();
-
-    // ---- GET / ----------------------------------------------------------
-    if (url === "/" || url === "") {
-      if (method !== "GET" && method !== "HEAD") {
-        return sendJson(res, 405, { ok: false, error: "Method not allowed" });
-      }
-      if (existsSync(indexHtmlPath)) {
-        const html = readFileSync(indexHtmlPath, "utf8");
-        return sendHtml(res, 200, html);
-      }
-      return sendHtml(res, 200, placeholderHtml());
-    }
-
-    // ---- GET /assets/* --------------------------------------------------
-    if (url.startsWith("/assets/") || url === "/assets") {
-      if (method !== "GET" && method !== "HEAD") {
-        return sendJson(res, 405, { ok: false, error: "Method not allowed" });
-      }
-      return serveAsset(req, res, assetsRoot, url);
-    }
-
-    // ---- GET /api/index -------------------------------------------------
-    if (url === "/api/index") {
-      if (method !== "GET" && method !== "HEAD") {
-        return sendJson(res, 405, { ok: false, error: "Method not allowed" });
-      }
-      try {
-        const index = buildIndex([extensionsRoot], {
-          now: new Date().toISOString(),
-          packageRoot,
-        });
-        return sendJson(res, 200, index);
-      } catch (err) {
-        return sendError(res, 500, err instanceof Error ? err.message : String(err));
-      }
-    }
-
-    // ---- GET /api/installed ---------------------------------------------
-    if (url === "/api/installed") {
-      if (method !== "GET" && method !== "HEAD") {
-        return sendJson(res, 405, { ok: false, error: "Method not allowed" });
-      }
-      try {
-        const bundles = listBundles([extensionsRoot]);
-        const ledgerOpts = installDefaults.ledgerHome
-          ? { home: installDefaults.ledgerHome }
-          : {};
-        const result = {};
-        for (const bundle of bundles) {
-          const entries = findInstalled(bundle.name, ledgerOpts);
-          if (entries.length > 0) {
-            result[bundle.name] = entries;
-          }
-        }
-        return sendJson(res, 200, result);
-      } catch (err) {
-        return sendError(res, 500, err instanceof Error ? err.message : String(err));
-      }
-    }
-
-    // ---- POST /api/install ----------------------------------------------
-    if (url === "/api/install") {
-      if (method !== "POST") {
-        return sendJson(res, 405, { ok: false, error: "Method not allowed" });
-      }
-      let body;
-      try {
-        body = await readJsonBody(req);
-      } catch {
-        return sendError(res, 400, "Invalid JSON body");
-      }
-
-      const { name, platform, scope, noProvision } = body;
-
-      // Validate inputs
-      if (!name || typeof name !== "string") {
-        return sendError(res, 400, "Missing required field: name");
-      }
-      if (platform && !VALID_PLATFORMS.has(platform)) {
-        return sendError(
-          res,
-          400,
-          `Unknown platform: "${platform}". Valid: codex, claude, cursor, enact, shared, all`,
-        );
-      }
-      if (scope && !VALID_SCOPES.has(scope)) {
-        return sendError(res, 400, `Unknown scope: "${scope}". Valid: global, local`);
-      }
-
-      // Resolve bundle path
-      let bundlePath;
-      try {
-        bundlePath = resolveBundlePath(name, { cwd: packageRoot });
-      } catch (err) {
-        return sendError(res, 400, err instanceof Error ? err.message : String(err));
-      }
-
-      // Run install — MCP dependency provisioning is ON by default; the client
-      // may opt out with { noProvision: true }.
-      try {
-        const runOpts = {
-          platform: platform ?? "codex",
-          scope: scope ?? "global",
-          sync: false,
-          noProvision: noProvision === true,
-          ...installDefaults,
-        };
-        const result = runInstall(bundlePath, runOpts);
-        // Surface the provision results so the UI can report them. The result's
-        // `provision` array is attached by runInstall (single + multi paths).
-        const provision = Array.isArray(result.provision) ? result.provision : [];
-        return sendJson(res, 200, { ok: true, result, provision });
-      } catch (err) {
-        return sendError(res, 500, err instanceof Error ? err.message : String(err));
-      }
-    }
-
-    // ---- POST /api/uninstall --------------------------------------------
-    if (url === "/api/uninstall") {
-      if (method !== "POST") {
-        return sendJson(res, 405, { ok: false, error: "Method not allowed" });
-      }
-      let body;
-      try {
-        body = await readJsonBody(req);
-      } catch {
-        return sendError(res, 400, "Invalid JSON body");
-      }
-
-      const { name, platform, scope } = body;
-
-      // Validate inputs
-      if (!name || typeof name !== "string") {
-        return sendError(res, 400, "Missing required field: name");
-      }
-      if (platform && !VALID_PLATFORMS.has(platform)) {
-        return sendError(
-          res,
-          400,
-          `Unknown platform: "${platform}". Valid: codex, claude, cursor, enact, shared, all`,
-        );
-      }
-      if (scope && !VALID_SCOPES.has(scope)) {
-        return sendError(res, 400, `Unknown scope: "${scope}". Valid: global, local`);
-      }
-
-      // Resolve bundle path to get the canonical plugin name
-      // (We pass the name string directly to runUninstall since it accepts plugin names)
-      // First verify the plugin name is known
-      try {
-        resolveBundlePath(name, { cwd: packageRoot });
-      } catch (err) {
-        return sendError(res, 400, err instanceof Error ? err.message : String(err));
-      }
-
-      // Run uninstall
-      try {
-        const runOpts = {
-          platform: platform ?? "codex",
-          scope: scope ?? "global",
-          sync: false,
-          ...installDefaults,
-        };
-        const result = runUninstall(name, runOpts);
-        return sendJson(res, 200, { ok: true, result });
-      } catch (err) {
-        return sendError(res, 500, err instanceof Error ? err.message : String(err));
-      }
-    }
-
-    // ---- 404 for everything else ----------------------------------------
-    return sendError(res, 404, `Not found: ${url}`);
-  });
-
-  return server;
-}
-
-// ---------------------------------------------------------------------------
-// startServer — creates + listens; returns { server, url }
-// ---------------------------------------------------------------------------
-
-/**
- * Start the server and return the URL.
- *
- * Security note: host defaults to '127.0.0.1' (loopback only). Passing any
- * other value via --host exposes the API to other machines on the network —
- * document this risk to operators.
- *
- * @param {object} opts
- * @param {number} [opts.port=43217]   - Port to listen on. Pass 0 for ephemeral.
- * @param {string} [opts.host='127.0.0.1'] - Bind address. MUST be 127.0.0.1 by default.
- * @param {string} [opts.packageRoot] - Package root override.
- * @param {object} [opts.installDefaults] - Merged into runInstall/runUninstall calls.
- * @returns {Promise<{ server: http.Server, url: string }>}
- */
-// ENACT OS port-registry convention: dev listeners live in 43xxx, prod in 53xxx.
-export const DEV_PORT = 43217;
-export const PROD_PORT = 53217;
-
-/**
- * Resolve the serve port: an explicit `--port` always wins; otherwise `--prod`
- * selects the prod-series port (53217) and the default is the dev-series port
- * (43217). Pure (no I/O) so it is unit-testable without binding a socket.
- * @param {object} [opts]
- * @param {number} [opts.port] - Explicit port (wins; 0 = ephemeral).
- * @param {boolean} [opts.prod] - Use the prod-series port (53217).
- * @returns {number}
- */
-export function resolveServePort(opts = {}) {
-  if (opts.port !== undefined && opts.port !== null) return opts.port;
-  return opts.prod ? PROD_PORT : DEV_PORT;
-}
-
-export function startServer(opts = {}) {
-  const host = opts.host ?? "127.0.0.1";
-  const port = resolveServePort(opts);
-
-  const server = createServer(opts);
-
-  return new Promise((resolve, reject) => {
-    server.on("error", reject);
-    server.listen(port, host, () => {
-      const addr = server.address();
-      const actualPort = typeof addr === "object" && addr ? addr.port : port;
-      const url = `http://${host}:${actualPort}`;
-      resolve({ server, url });
-    });
-  });
-}