@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/scripts/lib/provision-mcp.mjs

@@ -0,0 +1,369 @@
+/**
+ * provision-mcp.mjs — auto-provision a bundle's MCP-server dependencies at install.
+ *
+ * A bundle's canonical .agents/plugin.json may declare `mcpServers`, either inline
+ * or as a relative path to a .mcp.json file, e.g.:
+ *
+ *   { "mcpServers": "./.mcp.json" }
+ *
+ * and .mcp.json:
+ *
+ *   { "mcpServers": { "net_revenue_rgm": { "command": "uvx",
+ *                                          "args": ["net-revenue-rgm"], "env": {} } } }
+ *
+ * Today install COPIES .mcp.json (registers the server) but never installs the
+ * underlying package — `uvx net-revenue-rgm` only fetches it lazily at first MCP
+ * launch. This module provisions those deps eagerly at install time.
+ *
+ * Command mapping (runner derived from the server's `command`):
+ *   uvx  <pkg>          → uv tool install <pkg>     (uvx is uv's ephemeral runner;
+ *                                                    `uv tool install` makes it resident)
+ *   npx  <pkg>          → npm install -g <pkg>
+ *   pipx <pkg>          → pipx install <pkg>
+ *   pip  install …      → pip  install … (as given)
+ *   pip3 install …      → pip3 install … (as given)
+ *   anything else       → skipped (local path / node / python / docker — nothing to fetch)
+ *
+ * SECURITY
+ *   - Only a fixed allowlist of runners may ever be invoked: uv, npm, pipx, pip, pip3.
+ *   - Arguments are derived from the bundle manifest and the fixed mapping above.
+ *   - Execution always uses spawnSync(runner, [args...], { shell: false }) — never a
+ *     shell string — so nothing in the manifest can inject shell metacharacters.
+ *   - The bundle's raw `command` is NEVER executed directly; only the mapped
+ *     provisioning runner runs.
+ *
+ * BEST-EFFORT
+ *   - Provisioning runs BY DEFAULT. Pass { noProvision: true } to skip it entirely.
+ *   - If the provisioning runner is missing from PATH, we WARN with install
+ *     guidance and record status "missing-runner" — the install is NOT failed.
+ *   - Any exec failure (nonzero exit, spawn error) WARNS and records "failed" —
+ *     the install is NOT failed.
+ *
+ * Per-server result shape:
+ *   { server, command, package, status, detail }
+ *   status ∈ "provisioned" | "skipped" | "missing-runner" | "failed"
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Runner allowlist + install guidance
+// ---------------------------------------------------------------------------
+
+/** Fixed allowlist of provisioning runners that may be invoked. */
+const ALLOWED_RUNNERS = new Set(["uv", "npm", "pipx", "pip", "pip3"]);
+
+/** Install guidance per runner, surfaced when the runner is missing from PATH. */
+const RUNNER_GUIDANCE = {
+  uv: "install: https://docs.astral.sh/uv/",
+  npm: "install Node.js + npm: https://nodejs.org/",
+  pipx: "install: https://pipx.pypa.io/stable/installation/",
+  pip: "install Python + pip: https://pip.pypa.io/",
+  pip3: "install Python + pip: https://pip.pypa.io/",
+};
+
+// ---------------------------------------------------------------------------
+// Package-token validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when a package token is safe to pass to a provisioning runner.
+ *
+ * Rejects tokens that:
+ *   - Start with "-" (option injection: e.g. `--with=evil`, `--index-url=…`)
+ *   - Are empty or non-string
+ *
+ * Shell metacharacters are not a concern (shell:false is enforced at exec time),
+ * but leading dashes are: they become CLI flags for the runner even with
+ * shell:false (e.g. `uv tool install --with=evil` or
+ * `pip install --index-url=https://attacker.com pkg`).
+ *
+ * @param {unknown} token
+ * @returns {boolean}
+ */
+function isSafePackageToken(token) {
+  return typeof token === "string" && token.length > 0 && !token.startsWith("-");
+}
+
+// ---------------------------------------------------------------------------
+// command → { runner, args } mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a bundle server's { command, args } to a persistent provisioning command.
+ * Returns null when the command is unknown / there is nothing to fetch, or when
+ * the resolved package token fails the safety check (starts with "-").
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {{ runner: string, args: string[], package: string } | null}
+ */
+function mapProvisionCommand(command, args) {
+  const a = Array.isArray(args) ? args.filter((x) => typeof x === "string") : [];
+
+  switch (command) {
+    case "uvx": {
+      // uvx <pkg> [extra…] → uv tool install <pkg>.
+      // Only a[0] is used; skip if it starts with "-" (option injection guard).
+      const pkg = a[0];
+      if (!isSafePackageToken(pkg)) return null;
+      return { runner: "uv", args: ["tool", "install", pkg], package: pkg };
+    }
+    case "npx": {
+      // npx [-y] <pkg> → npm install -g <pkg>. Skip leading flags to find the pkg.
+      const pkg = a.find((x) => !x.startsWith("-"));
+      if (!isSafePackageToken(pkg)) return null;
+      return { runner: "npm", args: ["install", "-g", pkg], package: pkg };
+    }
+    case "pipx": {
+      // pipx <pkg> OR pipx run <pkg> → pipx install <pkg>.
+      const rest = a[0] === "run" ? a.slice(1) : a;
+      const pkg = rest.find((x) => !x.startsWith("-"));
+      if (!isSafePackageToken(pkg)) return null;
+      return { runner: "pipx", args: ["install", pkg], package: pkg };
+    }
+    case "pip":
+    case "pip3": {
+      // Only honour an explicit `install` invocation.
+      // SECURITY: pass only the package name, never the raw args array. Passing
+      // the full args array lets a malicious manifest inject pip flags such as
+      // --index-url, --trusted-host, --extra-index-url, or --target, all of
+      // which can redirect the install to an attacker-controlled source/path.
+      if (a[0] !== "install") return null;
+      const pkg = a.slice(1).find((x) => !x.startsWith("-")) ?? "";
+      if (!isSafePackageToken(pkg)) return null;
+      return { runner: command, args: ["install", pkg], package: pkg };
+    }
+    default:
+      // node / python / docker / local path → nothing to fetch.
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default exec runner — a thin spawnSync wrapper (shell:false). Injectable.
+// ---------------------------------------------------------------------------
+
+/**
+ * Default exec runner. NEVER uses a shell.
+ * @param {string} runner
+ * @param {string[]} args
+ * @returns {{ status: number|null, stdout: string, stderr: string, error?: Error }}
+ */
+function defaultExec(runner, args) {
+  const res = spawnSync(runner, args, {
+    shell: false,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    status: res.status,
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? "",
+    error: res.error,
+  };
+}
+
+/**
+ * Default PATH check — is the runner resolvable? Uses the platform `which`/`where`.
+ * @param {string} runner
+ * @returns {boolean}
+ */
+defaultExec.which = (runner) => {
+  const probe = process.platform === "win32" ? "where" : "which";
+  const res = spawnSync(probe, [runner], { shell: false, stdio: "ignore" });
+  return res.status === 0;
+};
+
+// ---------------------------------------------------------------------------
+// readMcpServers — resolve the declared MCP servers for a bundle.
+// ---------------------------------------------------------------------------
+
+function readManifest(pluginRoot) {
+  const manifestPath = join(pluginRoot, ".agents", "plugin.json");
+  if (!existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the `mcpServers` map declared by a bundle's canonical .agents/plugin.json.
+ *
+ * The `mcpServers` field may be:
+ *   - a relative path (e.g. "./.mcp.json") → read that file's `mcpServers` object
+ *   - an inline object → returned directly
+ *   - absent → {}
+ *
+ * @param {string} pluginRoot
+ * @returns {Record<string, { command?: string, args?: string[], env?: object }>}
+ */
+export function readMcpServers(pluginRoot) {
+  const manifest = readManifest(pluginRoot);
+  if (!manifest) return {};
+
+  const field = manifest.mcpServers;
+  if (!field) return {};
+
+  // Inline object form.
+  if (typeof field === "object") {
+    return field;
+  }
+
+  // Path form — resolve relative to the bundle root.
+  if (typeof field === "string") {
+    const mcpPath = isAbsolute(field) ? field : resolve(pluginRoot, field);
+    if (!existsSync(mcpPath)) return {};
+    try {
+      const parsed = JSON.parse(readFileSync(mcpPath, "utf8"));
+      const servers = parsed && typeof parsed === "object" ? parsed.mcpServers : null;
+      return servers && typeof servers === "object" ? servers : {};
+    } catch {
+      return {};
+    }
+  }
+
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// provisionMcp — best-effort provision of every declared server's package.
+// ---------------------------------------------------------------------------
+
+function warn(msg) {
+  process.stderr.write(`[enact-extensions install] ${msg}\n`);
+}
+
+/**
+ * Provision the underlying packages for every MCP server a bundle declares.
+ *
+ * @param {string} pluginRoot
+ * @param {object} [options]
+ * @param {boolean} [options.noProvision]  - Skip provisioning entirely.
+ * @param {Function} [options.exec]        - Injectable exec runner (defaults to a
+ *                                           spawnSync wrapper). Must expose .which().
+ * @returns {Array<{ server, command, package, status, detail }>}
+ */
+export function provisionMcp(pluginRoot, options = {}) {
+  if (options.noProvision) return [];
+
+  const exec = options.exec ?? defaultExec;
+  const which =
+    typeof exec.which === "function" ? exec.which : (r) => ALLOWED_RUNNERS.has(r);
+
+  const servers = readMcpServers(pluginRoot);
+  const results = [];
+
+  for (const [serverName, def] of Object.entries(servers)) {
+    const command = def && typeof def.command === "string" ? def.command : "";
+    const args = def && Array.isArray(def.args) ? def.args : [];
+
+    const mapped = mapProvisionCommand(command, args);
+
+    // Unknown / nothing-to-fetch → skip.
+    if (!mapped) {
+      results.push({
+        server: serverName,
+        command,
+        package: "",
+        status: "skipped",
+        detail: `no provisioning mapping for command "${command || "(none)"}"`,
+      });
+      continue;
+    }
+
+    // Defence-in-depth: never invoke a runner outside the allowlist.
+    if (!ALLOWED_RUNNERS.has(mapped.runner)) {
+      results.push({
+        server: serverName,
+        command,
+        package: mapped.package,
+        status: "skipped",
+        detail: `runner "${mapped.runner}" not on allowlist`,
+      });
+      continue;
+    }
+
+    // PATH check — if the runner is missing, WARN with guidance, do NOT fail.
+    let present;
+    try {
+      present = which(mapped.runner);
+    } catch {
+      present = false;
+    }
+    if (!present) {
+      const guidance = RUNNER_GUIDANCE[mapped.runner] ?? "";
+      const detail = `${mapped.package || serverName} needs \`${command}\` (${mapped.runner}); ${guidance}`;
+      warn(`Warning: ${detail}`);
+      results.push({
+        server: serverName,
+        command,
+        package: mapped.package,
+        status: "missing-runner",
+        detail,
+      });
+      continue;
+    }
+
+    // Provision — best effort. Any failure WARNS but never throws.
+    try {
+      const res = exec(mapped.runner, mapped.args) ?? {};
+      // Success: exit status 0 and no spawn error.
+      if (res.status === 0 && !res.error) {
+        results.push({
+          server: serverName,
+          command,
+          package: mapped.package,
+          status: "provisioned",
+          detail: `${mapped.runner} ${mapped.args.join(" ")}`,
+        });
+        continue;
+      }
+      // Nonzero exit or spawn error.
+      const stderr = res.stderr ? String(res.stderr).trim() : "";
+      const code = res.status;
+      const errMsg = res.error ? res.error.message : "";
+      const detail =
+        `${mapped.runner} ${mapped.args.join(" ")} failed` +
+        (code != null ? ` (exit ${code})` : "") +
+        (stderr ? `: ${stderr}` : errMsg ? `: ${errMsg}` : "");
+      warn(`Warning: ${detail}`);
+      results.push({
+        server: serverName,
+        command,
+        package: mapped.package,
+        status: "failed",
+        detail,
+      });
+    } catch (err) {
+      const detail = `${mapped.runner} ${mapped.args.join(" ")} failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`;
+      warn(`Warning: ${detail}`);
+      results.push({
+        server: serverName,
+        command,
+        package: mapped.package,
+        status: "failed",
+        detail,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Render a concise one-line summary per provisioned/failed server, for logging.
+ * @param {Array<{server, package, status, detail}>} results
+ * @returns {string[]}
+ */
+export function summarizeProvision(results) {
+  return results
+    .filter((r) => r.status !== "skipped")
+    .map((r) => `mcp ${r.server}: ${r.status}${r.package ? ` (${r.package})` : ""}`);
+}

package/scripts/lib/resolve-bundle.mjs

@@ -0,0 +1,121 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { cwd as processCwd } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The package root of enact-extensions (two levels up from scripts/lib/).
+ * This is resolved relative to THIS file's location so it works regardless
+ * of where the CLI is invoked from.
+ */
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+
+/**
+ * Returns true if `dir` looks like a valid plugin bundle root
+ * (i.e. it contains .agents/plugin.json).
+ */
+function isBundle(dir) {
+  return existsSync(join(dir, ".agents", "plugin.json"));
+}
+
+/**
+ * Determine whether arg looks like a filesystem path (contains a separator)
+ * rather than a bare name.
+ */
+function isPathLike(arg) {
+  return arg.includes("/") || arg.includes(sep);
+}
+
+/**
+ * Get the npm global root via `npm root -g`. Returns null on failure.
+ */
+function getNpmGlobalRoot() {
+  try {
+    const result = execSync("npm root -g", { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a plugin argument to an absolute bundle path.
+ *
+ * Resolution order:
+ *   1. If `arg` is an existing path (absolute, or relative to `cwd`) → return it.
+ *   2. Else if `arg` is a bare name (no path separators):
+ *      a. <packageRoot>/extensions/<arg>  (where packageRoot is this CLI's own package)
+ *      b. <cwd>/extensions/<arg>
+ *      c. <npmGlobalRoot>/@amsterdamdatalabs/enact-extensions/extensions/<arg>
+ *   3. If nothing found → throw a clear error listing all candidates tried.
+ *
+ * @param {string} arg - The argument from the CLI (bare name or path).
+ * @param {{ cwd?: string }} [opts]
+ * @returns {string} Resolved absolute path to the bundle root.
+ */
+export function resolveBundlePath(arg, opts = {}) {
+  const cwd = opts.cwd ?? processCwd();
+
+  // --- Rule 1: treat as a path if it contains separators, or if it resolves to an existing path ---
+  if (isPathLike(arg)) {
+    // Path-like: resolve against cwd and return (whether or not it exists — caller will fail later)
+    const resolved = resolve(cwd, arg);
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+    // Path-like but doesn't exist: throw a specific error (not a bare-name resolution)
+    throw new Error(`Plugin path does not exist: ${resolved}\nPass an explicit path instead.`);
+  }
+
+  // Could be an absolute path (bare absolute paths don't contain separators only on Windows,
+  // but on Unix an absolute path starts with '/' which IS a separator, so this handles Unix fine).
+  // Also catch the case where arg resolves to an existing directory (absolute path without /... unlikely).
+  const asAbsolute = resolve(cwd, arg);
+  if (existsSync(asAbsolute) && arg !== asAbsolute) {
+    // Only when resolving it to absolute gives something different and it exists
+    // (e.g. a single-component name that is a direct cwd subdir — unusual on Unix).
+    if (isBundle(asAbsolute)) {
+      return asAbsolute;
+    }
+    // It exists but isn't a bundle — fall through to bare-name search.
+    // Do NOT return early here; a non-bundle dir that happens to share the name
+    // must not silently short-circuit the resolution chain.
+  }
+
+  // --- Rule 2: bare name → candidate search ---
+  const candidates = [];
+
+  // 2a. <packageRoot>/extensions/<arg>
+  const repoCandidate = join(PACKAGE_ROOT, "extensions", arg);
+  candidates.push(repoCandidate);
+  if (isBundle(repoCandidate)) {
+    return repoCandidate;
+  }
+
+  // 2b. <cwd>/extensions/<arg>
+  const cwdCandidate = join(cwd, "extensions", arg);
+  candidates.push(cwdCandidate);
+  if (isBundle(cwdCandidate)) {
+    return cwdCandidate;
+  }
+
+  // 2c. <npmGlobalRoot>/@amsterdamdatalabs/enact-extensions/extensions/<arg>
+  const npmGlobalRoot = getNpmGlobalRoot();
+  if (npmGlobalRoot) {
+    const globalCandidate = join(npmGlobalRoot, "@amsterdamdatalabs", "enact-extensions", "extensions", arg);
+    candidates.push(globalCandidate);
+    if (isBundle(globalCandidate)) {
+      return globalCandidate;
+    }
+  }
+
+  // --- Rule 3: nothing found ---
+  const uniqueCandidates = [...new Set(candidates)];
+  const candidateList = uniqueCandidates.map((c) => `  - ${c}`).join("\n");
+  throw new Error(
+    `Plugin "${arg}" not found. Looked in:\n${candidateList}\nPass an explicit path instead.`,
+  );
+}