@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/lib/serve.mjs

@@ -0,0 +1,472 @@
+/**
+ * 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 });
+    });
+  });
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * postinstall.mjs — TTY-aware npm postinstall script for enact-extensions.
+ *
+ * CI-SAFETY CONTRACT (most important property):
+ *   - If NOT a TTY → print one-line notice and exit 0. NEVER hang.
+ *   - If CI env var is set → print one-line notice and exit 0.
+ *   - If ENACT_EXTENSIONS_NO_POSTINSTALL is set → print one-line notice and exit 0.
+ *   - If interactive TTY (and not CI) → run `hooks setup` interactive picker.
+ *   - Entire script is wrapped in try/catch → ALWAYS process.exit(0).
+ *     A postinstall that throws would break `npm ci` in CI.
+ *
+ * The CI/TTY guards ensure this script is fully safe in:
+ *   - Docker CI environments (CI=1, no TTY)
+ *   - npm ci / npm install in CI pipelines
+ *   - Automated install tooling (pipes, scripts)
+ *   - Developer machines with interactive TTY (triggers the interactive picker)
+ */
+
+try {
+  const { stdin, env } = process;
+
+  const isCI = !!(env.CI || env.CONTINUOUS_INTEGRATION || env.BUILD_ID || env.GITHUB_ACTIONS);
+  const isNoPostinstall = !!(env.ENACT_EXTENSIONS_NO_POSTINSTALL);
+  const isTTY = !!(stdin.isTTY);
+
+  const NOTICE = `Run \`enact-extensions hooks setup\` to enable session-start drift checks.\n`;
+
+  if (!isTTY || isCI || isNoPostinstall) {
+    // Non-interactive or CI: print notice and exit immediately.
+    process.stdout.write(NOTICE);
+    process.exit(0);
+  }
+
+  // Interactive TTY (non-CI): run the hooks setup interactive picker via CLI.
+  // We spawn a child process rather than importing directly to keep postinstall
+  // isolated from any import-time side-effects in the CLI modules.
+  const { spawnSync } = await import("node:child_process");
+  const { dirname, join, resolve } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const CLI = join(resolve(__dirname, ".."), "scripts", "enact-extensions.mjs");
+
+  // Spawn with stdio inherited so the interactive readline prompt is visible.
+  // We spawn and ignore the exit code — postinstall must always exit 0.
+  spawnSync(process.execPath, [CLI, "hooks", "setup"], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  process.exit(0);
+} catch {
+  // CRITICAL: never let an error propagate from postinstall.
+  // Printing to stderr is best-effort (safe to fail).
+  try {
+    process.stderr.write(
+      "[enact-extensions postinstall] Non-fatal error during hook setup. Run `enact-extensions hooks setup` manually.\n",
+    );
+  } catch {
+    // Even stderr.write failed — just exit 0.
+  }
+  process.exit(0);
+}

package/scripts/setup-enact-context.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Wire enact-context setup into the enact-extensions workspace.
-# Validates the plugin bundle (catalog) then runs consolidated agent setup.
+# Validates the plugin-dev bundle then runs consolidated agent setup.
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -16,7 +16,7 @@ if ! command -v enact-context >/dev/null 2>&1; then
 fi
 
 cd "$ROOT"
-npm run validate:catalog
+npm run validate
 
 echo ""
 echo "Running enact-context setup (claude, codex, opencode, enact, zed)..."