@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/scripts/lib/run-update.mjs

@@ -0,0 +1,152 @@
+/**
+ * run-update.mjs — refresh installed plugins that have drifted from their
+ * canonical source bundle.
+ *
+ * runUpdate({ name?, all?, dryRun?, home?, cwd? }) → summary
+ *
+ * The update is driven ENTIRELY by the ledger, per (plugin, surface, home):
+ *
+ *   1. computeOutdated({ home, cwd }) classifies every installed surface as
+ *      fresh | outdated | orphaned.
+ *   2. We keep only the OUTDATED surfaces (fresh needs nothing; orphaned can't be
+ *      refreshed because the canonical source is gone).
+ *   3. Scope the candidate set:
+ *        --all          → every outdated surface
+ *        <name>         → only outdated surfaces for that plugin
+ *        (neither)      → error (don't silently update everything without --all)
+ *   4. For each target outdated surface, re-install THAT plugin to THAT ONE surface
+ *      at THAT recorded home, by calling runInstall(canonicalPath, {
+ *        platform: entry.platform, scope: entry.scope, <matching *-home>: entry.home,
+ *        ledgerHome: home, sync: false }).
+ *      runInstall appends a fresh ledger entry (with the new hash), so the ledger
+ *      self-updates and a later computeOutdated reports the surface as fresh.
+ *
+ * CRITICAL: we ONLY touch surfaces the plugin is actually installed on. A plugin
+ * installed only on cursor updates ONLY cursor — it is never installed to a
+ * surface it isn't already on.
+ *
+ * --dry-run: report what WOULD be updated and do NOTHING (no install, no ledger
+ * writes).
+ *
+ * Returns a summary:
+ *   {
+ *     planned: Entry[],   // outdated surfaces in scope (what was / would be targeted)
+ *     updated: Entry[],   // surfaces actually re-installed (empty on dry-run)
+ *     skipped: Entry[],   // orphaned surfaces in scope (can't refresh)
+ *     failed:  { entry, error }[],  // surfaces whose re-install threw
+ *     dryRun:  boolean,
+ *   }
+ * where each Entry is the OutdatedEntry { name, platform, scope, home, status, ... }.
+ */
+
+import { homedir } from "node:os";
+import { cwd as processCwd } from "node:process";
+import { computeOutdated } from "./outdated.mjs";
+import { resolveBundlePath } from "./resolve-bundle.mjs";
+import { runInstall } from "./run-install.mjs";
+
+// Map a ledger platform → the runInstall option key that carries its home.
+// (Mirrors the homeField mapping in run-install.mjs PLATFORM_TARGETS; codex has
+// no dedicated *-home table entry there, so it maps to codexHome explicitly.)
+const PLATFORM_HOME_OPTION = {
+  codex: "codexHome",
+  claude: "claudeHome",
+  cursor: "cursorHome",
+  enact: "enactHome",
+  shared: "sharedHome",
+};
+
+/**
+ * Resolve the canonical bundle path for a plugin name, or null when the source
+ * cannot be found (so an outdated→install attempt degrades to a skip rather than
+ * a crash).
+ *
+ * @param {string} name
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function safeResolveBundlePath(name, cwd) {
+  try {
+    return resolveBundlePath(name, { cwd });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Refresh outdated installed plugin surfaces, driven by the ledger.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.name]   — restrict to a single plugin name.
+ * @param {boolean} [opts.all]   — update every outdated surface.
+ * @param {boolean} [opts.dryRun]— report only; make no changes.
+ * @param {string} [opts.home]   — ledger home override (defaults to os.homedir()).
+ * @param {string} [opts.cwd]    — working dir for canonical bundle resolution.
+ * @returns {{ planned: object[], updated: object[], skipped: object[], failed: {entry: object, error: Error}[], dryRun: boolean }}
+ */
+export function runUpdate({ name, all, dryRun, home, cwd } = {}) {
+  const resolvedHome = home ?? homedir();
+  const resolvedCwd = cwd ?? processCwd();
+
+  // Scope guard: require an explicit target. Never silently update everything.
+  if (!all && !name) {
+    throw new Error(
+      "update requires a plugin name or --all. " +
+        'Use "update <name>" to refresh one plugin, or "update --all" to refresh every outdated plugin.',
+    );
+  }
+
+  // 1. Compute freshness across every installed surface.
+  const outdatedReport = computeOutdated({ home: resolvedHome, cwd: resolvedCwd });
+
+  // 2. Restrict to the requested plugin (when a name is given).
+  const inScope = name
+    ? outdatedReport.filter((e) => e.name === name)
+    : outdatedReport;
+
+  // 3. Split into actionable (outdated) vs orphaned (skip). fresh is ignored.
+  /** @type {object[]} */
+  const planned = inScope.filter((e) => e.status === "outdated");
+  /** @type {object[]} */
+  const skipped = inScope.filter((e) => e.status === "orphaned");
+
+  /** @type {object[]} */
+  const updated = [];
+  /** @type {{ entry: object, error: Error }[]} */
+  const failed = [];
+
+  // Dry-run: report the plan, change nothing.
+  if (dryRun) {
+    return { planned, updated, skipped, failed, dryRun: true };
+  }
+
+  // 4. Re-install each outdated surface to its EXACT recorded platform + home.
+  for (const entry of planned) {
+    const canonicalPath = safeResolveBundlePath(entry.name, resolvedCwd);
+    if (!canonicalPath) {
+      // Source vanished between the freshness scan and now → treat as orphaned skip.
+      skipped.push({ ...entry, status: "orphaned" });
+      continue;
+    }
+
+    const homeOption = PLATFORM_HOME_OPTION[entry.platform] ?? "codexHome";
+    try {
+      runInstall(canonicalPath, {
+        platform: entry.platform,
+        scope: entry.scope,
+        [homeOption]: entry.home,
+        ledgerHome: resolvedHome,
+        // Refresh the already-installed surface only; do not regenerate source
+        // manifests, and skip MCP provisioning (a refresh re-installs identical
+        // package deps — provisioning is best-effort and not needed here).
+        sync: false,
+        noProvision: true,
+      });
+      updated.push(entry);
+    } catch (err) {
+      failed.push({ entry, error: err instanceof Error ? err : new Error(String(err)) });
+    }
+  }
+
+  return { planned, updated, skipped, failed, dryRun: false };
+}

package/scripts/lib/run-validate.mjs

@@ -1,20 +1,18 @@
 import {
-  validatePluginBundle,
-  checkComponentPaths,
-  checkPluginBundleComponentPaths,
-  readManifestFile,
+  validatePluginBundleFromCanonical,
+  checkPluginBundleComponentPathsFromCanonical,
 } from "../../dist/index.js";
 
+/**
+ * Validate a plugin bundle using IN-MEMORY manifest derivation from the
+ * canonical `.agents/plugin.json`.  No source `.<platform>-plugin/` dirs are
+ * read or created.
+ *
+ * For backward-compatibility, `platforms` defaults to all four surfaces.
+ */
 export function runValidate(pluginRoot, platforms) {
-  const report = validatePluginBundle(pluginRoot, platforms);
-  let warnings = [];
-
-  try {
-    const enact = readManifestFile(pluginRoot, "enact");
-    warnings = checkComponentPaths(pluginRoot, enact);
-  } catch {
-    // enact manifest optional for partial bundles
-  }
+  const report = validatePluginBundleFromCanonical(pluginRoot, platforms);
+  const warnings = checkPluginBundleComponentPathsFromCanonical(pluginRoot);
 
   for (const result of report.results) {
     const status = result.ok ? "ok" : "FAIL";
@@ -27,10 +25,6 @@ export function runValidate(pluginRoot, platforms) {
   for (const warn of warnings) {
     console.log(`[warn] ${warn}`);
   }
-  const componentIssues = checkPluginBundleComponentPaths(pluginRoot, platforms);
-  for (const issue of componentIssues) {
-    console.log(`[FAIL] ${issue}`);
-  }
 
-  return report.ok && componentIssues.length === 0;
+  return report.ok && warnings.length === 0;
 }

package/scripts/lib/serve.mjs

@@ -0,0 +1,454 @@
+/**
+ * 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 }>}
+ */
+export function startServer(opts = {}) {
+  const host = opts.host ?? "127.0.0.1";
+  const port = opts.port ?? 43217;
+
+  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 });
+    });
+  });
+}