@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/scripts/lib/run-install.mjs

@@ -1,60 +1,256 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
 import {
   installPluginBundle,
   installClaudePluginBundle,
   installCursorPluginBundle,
   installCodexPluginBundle,
+  installSharedPluginBundle,
   defaultEnactHome,
+  defaultSharedHome,
 } from "../../dist/index.js";
+import { appendEntry } from "./ledger.mjs";
+import { bundleHash } from "./bundle-hash.mjs";
+import { provisionMcp, summarizeProvision } from "./provision-mcp.mjs";
 
-export function runInstall(pluginRoot, options = {}) {
-  const platform = options.platform ?? "codex";
-
-  if (platform === "claude") {
-    const result = installClaudePluginBundle({
-      pluginRoot,
-      claudeHome: options.claudeHome,
-      marketplaceName: options.marketplaceName,
-      sync: options.sync,
-    });
-    console.log(`installed ${result.name} -> ${result.installedPluginPath}`);
-    console.log(`registered marketplace ${result.marketplaceName} -> ${result.marketplaceDir}`);
-    for (const path of result.refreshedPaths) {
-      console.log(`refreshed ${path}`);
+// scope: "global" (default) -> the agent's default home (~/.codex, ~/.enact, ~/.claude, ~/.cursor, ~/.agents)
+//        "local"            -> a project-scoped home under the current dir (./.codex, ./.enact, ...)
+// An explicit --<platform>-home always wins over the scope default.
+function resolveHomes(options) {
+  const scope = options.scope ?? "global";
+  const local = (sub) => join(process.cwd(), sub);
+  return {
+    scope,
+    codexHome: options.codexHome ?? (scope === "local" ? local(".codex") : undefined),
+    enactHome: options.enactHome ?? (scope === "local" ? local(".enact") : defaultEnactHome()),
+    claudeHome: options.claudeHome ?? (scope === "local" ? local(".claude") : undefined),
+    cursorHome: options.cursorHome ?? (scope === "local" ? local(".cursor") : undefined),
+    // For shared: sharedHome is the base directory; installSharedPluginBundle appends .agents/skills/<name>
+    // Global default: homedir() (skills land at ~/.agents/skills/<name>)
+    // Local: cwd (skills land at ./.agents/skills/<name>)
+    sharedHome: options.sharedHome ?? (scope === "local" ? process.cwd() : defaultSharedHome()),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ALL_PLATFORMS — deterministic order for `--platform all`
+// ---------------------------------------------------------------------------
+const ALL_PLATFORMS = ["codex", "claude", "cursor", "enact", "shared"];
+
+// ---------------------------------------------------------------------------
+// PLATFORM_TARGETS — data-driven dispatch table
+//
+// Each entry describes how to install for a given platform:
+//   homeField  — which field of `homes` supplies the target directory
+//   install    — the function to call; receives (pluginRoot, home, options)
+//   log        — how to log the result
+// ---------------------------------------------------------------------------
+const PLATFORM_TARGETS = {
+  claude: {
+    homeField: "claudeHome",
+    install(pluginRoot, home, options) {
+      return installClaudePluginBundle({
+        pluginRoot,
+        claudeHome: home,
+        marketplaceName: options.marketplaceName,
+        sync: options.sync,
+      });
+    },
+    log(result) {
+      console.log(`installed ${result.name} -> ${result.installedPluginPath}`);
+      console.log(`registered marketplace ${result.marketplaceName} -> ${result.marketplaceDir}`);
+      for (const path of result.refreshedPaths) {
+        console.log(`refreshed ${path}`);
+      }
+    },
+  },
+
+  cursor: {
+    homeField: "cursorHome",
+    install(pluginRoot, home, options) {
+      return installCursorPluginBundle({
+        pluginRoot,
+        cursorHome: home,
+        sync: options.sync,
+      });
+    },
+    log(result) {
+      console.log(`installed ${result.name} -> ${result.installedPluginPath}`);
+      for (const path of result.refreshedPaths) {
+        console.log(`refreshed ${path}`);
+      }
+    },
+  },
+
+  enact: {
+    homeField: "enactHome",
+    install(pluginRoot, home, options) {
+      return installCodexPluginBundle({
+        pluginRoot,
+        codexHome: home,
+        marketplaceName: options.marketplaceName,
+        enable: options.enable,
+        sync: options.sync,
+      });
+    },
+    log(result) {
+      console.log(`installed ${result.pluginConfigKey} -> ${result.configPath}`);
+      console.log(`wrote ${result.marketplacePath}`);
+      for (const path of result.refreshedPaths) {
+        console.log(`refreshed ${path}`);
+      }
+    },
+  },
+
+  shared: {
+    homeField: "sharedHome",
+    install(pluginRoot, home, _options) {
+      return installSharedPluginBundle({
+        pluginRoot,
+        sharedHome: home,
+      });
+    },
+    log(result) {
+      console.log(`installed ${result.name} skills -> ${result.installedSkillsPath}`);
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// parsePlatforms — expand "all" and split comma-separated platform lists.
+// Returns a deduped array of validated platform name strings.
+// Throws on any unknown platform token (no silent codex fallthrough).
+// ---------------------------------------------------------------------------
+function parsePlatforms(platform) {
+  if (!platform || platform === "codex") return ["codex"];
+  if (platform === "all") return ALL_PLATFORMS;
+
+  // Comma-separated: "claude,cursor" → ["claude", "cursor"]. Dedup preserving order.
+  const parts = [...new Set(platform.split(",").map((p) => p.trim()).filter(Boolean))];
+  if (parts.length === 0) return ["codex"];
+
+  // Validate each token. "codex" is valid (table fallthrough); "all" is only valid
+  // as a standalone value, so it is rejected here when mixed with other names.
+  const valid = new Set(["codex", ...Object.keys(PLATFORM_TARGETS)]);
+  for (const part of parts) {
+    if (!valid.has(part)) {
+      throw new Error(
+        `Unknown platform: "${part}". Valid: codex, claude, cursor, enact, shared, all`,
+      );
     }
-    return result;
   }
+  return parts;
+}
 
-  if (platform === "cursor") {
-    const result = installCursorPluginBundle({
-      pluginRoot,
-      cursorHome: options.cursorHome,
-      sync: options.sync,
+// ---------------------------------------------------------------------------
+// Ledger wiring — record successful installs to the install ledger.
+//
+// BEST-EFFORT: every ledger write is wrapped so a failure NEVER throws out of
+// the install. On failure we emit a single-line warning to stderr and continue.
+// ---------------------------------------------------------------------------
+
+// The installed-path field varies by platform result shape.
+function installedPathOf(result) {
+  return result.installedPluginPath ?? result.installedSkillsPath ?? result.configPath ?? "";
+}
+
+function recordLedgerEntry(entry, _homes, options) {
+  try {
+    // Single global ledger: every install (local or global scope) appends to
+    // <home>/.enact/extensions/ledger.jsonl. The scope distinction lives in the
+    // entry's `scope` field, not the path. Tests pass an explicit ledgerHome so
+    // they never write into the real ~/.enact.
+    appendEntry(entry, {
+      home: options.ledgerHome ?? homedir(),
     });
-    console.log(`installed ${result.name} -> ${result.installedPluginPath}`);
-    for (const path of result.refreshedPaths) {
-      console.log(`refreshed ${path}`);
-    }
-    return result;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[enact-extensions install] Warning: failed to write install ledger: ${msg}\n`);
   }
+}
 
-  if (platform === "enact") {
-    const result = installCodexPluginBundle({
-      pluginRoot,
-      codexHome: options.enactHome ?? defaultEnactHome(),
-      marketplaceName: options.marketplaceName,
-      enable: options.enable,
-      sync: options.sync,
-    });
-    console.log(`installed ${result.pluginConfigKey} -> ${result.configPath}`);
-    console.log(`wrote ${result.marketplacePath}`);
-    for (const path of result.refreshedPaths) {
-      console.log(`refreshed ${path}`);
+// ---------------------------------------------------------------------------
+// computeBundleHash — best-effort; never throws out of the install path.
+// Returns the sha256 hex hash of the canonical bundle, or null on failure.
+// The `bundleHashRoot` option (injected by tests) overrides the default
+// pluginRoot so tests can simulate a hash failure without breaking the install.
+// ---------------------------------------------------------------------------
+function computeBundleHash(pluginRoot, options) {
+  const root = options.bundleHashRoot ?? pluginRoot;
+  try {
+    return bundleHash(root);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[enact-extensions install] Warning: cannot compute bundle hash: ${msg}\n`);
+    return null;
+  }
+}
+
+// Append one install entry per installed target in a single-platform result.
+// Tolerant of every result shape (single platform, shared, codex multi-home).
+// `hash` is the pre-computed bundle hash (or null) for this install invocation.
+function recordInstall(platform, result, homes, options, hash) {
+  const targets = [];
+  if (result && Array.isArray(result.results)) {
+    // codex (default) multi-home: one entry per codex home.
+    for (const install of result.results) {
+      targets.push({
+        name: install.name,
+        version: install.version,
+        path: installedPathOf(install),
+        home: install.configPath ? join(install.configPath, "..") : homes.codexHome,
+      });
     }
+  } else if (result) {
+    targets.push({
+      name: result.name,
+      version: result.version,
+      path: installedPathOf(result),
+      home: homes[PLATFORM_TARGETS[platform]?.homeField] ?? homes.codexHome,
+    });
+  }
+
+  for (const t of targets) {
+    if (!t.name) continue;
+    recordLedgerEntry(
+      {
+        action: "install",
+        name: t.name,
+        version: t.version,
+        platform,
+        scope: homes.scope,
+        home: t.home,
+        path: t.path,
+        hash,
+      },
+      homes,
+      options,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// runSinglePlatform — install for one platform; returns the install result.
+// Throws on error (caller catches for partial-failure tracking).
+// `hash` is the pre-computed bundle hash (or null) for this install invocation.
+// ---------------------------------------------------------------------------
+function runSinglePlatform(pluginRoot, platform, homes, options, hash) {
+  const target = PLATFORM_TARGETS[platform];
+  if (target) {
+    const home = homes[target.homeField];
+    const result = target.install(pluginRoot, home, options);
+    target.log(result);
+    recordInstall(platform, result, homes, options, hash);
     return result;
   }
 
-  // codex (default) or explicit --platform codex
-  const result = installPluginBundle({ pluginRoot, cwd: options.cwd ?? pluginRoot, ...options });
+  // codex (default) — multi-home discovery via installPluginBundle.
+  const result = installPluginBundle({
+    pluginRoot,
+    cwd: options.cwd ?? pluginRoot,
+    ...options,
+    codexHome: homes.codexHome,
+  });
   for (const install of result.results) {
     console.log(`installed ${install.pluginConfigKey} -> ${install.configPath}`);
     console.log(`wrote ${install.marketplacePath}`);
@@ -62,5 +258,91 @@ export function runInstall(pluginRoot, options = {}) {
       console.log(`refreshed ${path}`);
     }
   }
+  recordInstall("codex", result, homes, options, hash);
   return result;
 }
+
+// ---------------------------------------------------------------------------
+// MCP dependency provisioning — best-effort, platform-independent.
+//
+// After a successful install we provision any packages the bundle's declared
+// MCP servers need (uvx → `uv tool install`, npx → `npm install -g`, etc.).
+// This runs ONCE per runInstall call (provisioning is platform-independent; a
+// `--platform all` install still provisions a single time). Provisioning is on
+// by DEFAULT; pass `--no-provision` / { noProvision: true } to skip. A failure
+// here NEVER fails the install — provisionMcp is best-effort by contract.
+// ---------------------------------------------------------------------------
+function runProvision(pluginRoot, options) {
+  try {
+    const provisionResults = provisionMcp(pluginRoot, {
+      noProvision: options.noProvision,
+      exec: options.provisionExec, // injectable for tests; undefined → real spawnSync
+    });
+    for (const line of summarizeProvision(provisionResults)) {
+      console.log(`provision: ${line}`);
+    }
+    return provisionResults;
+  } catch (err) {
+    // Defence-in-depth: provisionMcp is already best-effort, but never let a
+    // provisioning bug fail an otherwise-successful install.
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[enact-extensions install] Warning: MCP provisioning errored: ${msg}\n`);
+    return [];
+  }
+}
+
+export function runInstall(pluginRoot, options = {}) {
+  const platforms = parsePlatforms(options.platform);
+  const homes = resolveHomes(options);
+  console.log(`install scope: ${homes.scope}${homes.scope === "local" ? ` (${process.cwd()})` : ""}`);
+
+  // Compute bundle hash ONCE per runInstall invocation (best-effort, never throws).
+  // Applied to every per-platform ledger entry for this bundle.
+  const hash = computeBundleHash(pluginRoot, options);
+
+  // Single-platform path — unchanged behaviour (no .platforms wrapper).
+  if (platforms.length === 1) {
+    const result = runSinglePlatform(pluginRoot, platforms[0], homes, options, hash);
+    // Provision once after a successful install.
+    result.provision = runProvision(pluginRoot, options);
+    return result;
+  }
+
+  // Multi-platform path — run each sequentially, collect results + errors.
+  const platformResults = [];
+  let hasError = false;
+
+  for (const platform of platforms) {
+    console.log(`\n[${platform}] installing...`);
+    try {
+      const result = runSinglePlatform(pluginRoot, platform, homes, options, hash);
+      console.log(`[${platform}] ✓ done`);
+      platformResults.push({ platform, result, error: null });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[${platform}] ✗ failed: ${msg}`);
+      platformResults.push({ platform, result: null, error: err });
+      hasError = true;
+    }
+  }
+
+  // Provision ONCE for the whole multi-platform run (platform-independent), as
+  // long as at least one platform installed successfully.
+  let provision = [];
+  if (platformResults.some((r) => !r.error)) {
+    provision = runProvision(pluginRoot, options);
+  }
+
+  if (hasError) {
+    const failed = platformResults.filter((r) => r.error).map((r) => r.platform);
+    const succeeded = platformResults.filter((r) => !r.error).map((r) => r.platform);
+    const summary = `Multi-platform install: ${succeeded.length} succeeded (${succeeded.join(", ")}), ${failed.length} failed (${failed.join(", ")})`;
+    console.error(`\n${summary}`);
+    const err = new Error(summary);
+    err.platforms = platformResults;
+    err.provision = provision;
+    throw err;
+  }
+
+  return { platforms: platformResults, provision };
+}

package/scripts/lib/run-uninstall.mjs

@@ -0,0 +1,220 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import {
+  uninstallCodexPluginBundle,
+  uninstallClaudePluginBundle,
+  uninstallCursorPluginBundle,
+  uninstallSharedPluginBundle,
+  defaultEnactHome,
+  defaultSharedHome,
+} from "../../dist/index.js";
+import { appendEntry } from "./ledger.mjs";
+
+// ---------------------------------------------------------------------------
+// resolveHomes — mirrors run-install.mjs; same scope/per-platform-home logic.
+// ---------------------------------------------------------------------------
+function resolveHomes(options) {
+  const scope = options.scope ?? "global";
+  const local = (sub) => join(process.cwd(), sub);
+  return {
+    scope,
+    codexHome: options.codexHome ?? (scope === "local" ? local(".codex") : undefined),
+    enactHome: options.enactHome ?? (scope === "local" ? local(".enact") : defaultEnactHome()),
+    claudeHome: options.claudeHome ?? (scope === "local" ? local(".claude") : undefined),
+    cursorHome: options.cursorHome ?? (scope === "local" ? local(".cursor") : undefined),
+    sharedHome: options.sharedHome ?? (scope === "local" ? process.cwd() : defaultSharedHome()),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ALL_PLATFORMS / parsePlatforms — reuse same logic as run-install.mjs
+// ---------------------------------------------------------------------------
+const ALL_PLATFORMS = ["codex", "claude", "cursor", "enact", "shared"];
+
+/**
+ * Expand "all" and split comma-separated platform lists.
+ * Returns a deduped array of validated platform name strings.
+ * Throws on unknown platform tokens.
+ */
+export function parsePlatforms(platform) {
+  if (!platform || platform === "codex") return ["codex"];
+  if (platform === "all") return ALL_PLATFORMS;
+
+  const parts = [...new Set(platform.split(",").map((p) => p.trim()).filter(Boolean))];
+  if (parts.length === 0) return ["codex"];
+
+  const valid = new Set(["codex", "claude", "cursor", "enact", "shared"]);
+  for (const part of parts) {
+    if (!valid.has(part)) {
+      throw new Error(
+        `Unknown platform: "${part}". Valid: codex, claude, cursor, enact, shared, all`,
+      );
+    }
+  }
+  return parts;
+}
+
+// ---------------------------------------------------------------------------
+// Ledger wiring — best-effort; a write failure NEVER aborts the uninstall.
+// ---------------------------------------------------------------------------
+function recordLedgerEntry(entry, options) {
+  try {
+    appendEntry(entry, {
+      home: options.ledgerHome ?? homedir(),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      `[enact-extensions uninstall] Warning: failed to write uninstall ledger: ${msg}\n`,
+    );
+  }
+}
+
+function recordUninstall(name, version, platform, homes, options, result) {
+  if (!name) return;
+  // Determine the path field from the uninstall result
+  const path = (result && result.removedPaths && result.removedPaths[0]) ?? "";
+  recordLedgerEntry(
+    {
+      action: "uninstall",
+      name,
+      version: version ?? "0.0.0",
+      platform,
+      scope: homes.scope,
+      home: homes[platformHomeField(platform)] ?? homes.enactHome,
+      path,
+    },
+    options,
+  );
+}
+
+function platformHomeField(platform) {
+  switch (platform) {
+    case "enact": return "enactHome";
+    case "codex": return "codexHome";
+    case "claude": return "claudeHome";
+    case "cursor": return "cursorHome";
+    case "shared": return "sharedHome";
+    default: return "enactHome";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-platform uninstall dispatch
+// ---------------------------------------------------------------------------
+/**
+ * Uninstall `name` from a single platform. Returns the uninstall result.
+ * Emits a stderr warning (never throws) when the plugin is not installed.
+ */
+function runSinglePlatform(name, platform, homes, options) {
+  let result;
+
+  switch (platform) {
+    case "enact":
+      result = uninstallCodexPluginBundle(name, {
+        codexHome: homes.enactHome,
+        marketplaceName: options.marketplaceName,
+      });
+      break;
+    case "codex":
+      result = uninstallCodexPluginBundle(name, {
+        codexHome: homes.codexHome,
+        marketplaceName: options.marketplaceName,
+      });
+      break;
+    case "claude":
+      result = uninstallClaudePluginBundle(name, {
+        claudeHome: homes.claudeHome,
+        marketplaceName: options.marketplaceName,
+      });
+      break;
+    case "cursor":
+      result = uninstallCursorPluginBundle(name, {
+        cursorHome: homes.cursorHome,
+      });
+      break;
+    case "shared":
+      result = uninstallSharedPluginBundle(name, {
+        sharedHome: homes.sharedHome,
+      });
+      break;
+    default:
+      throw new Error(`Unknown platform: "${platform}"`);
+  }
+
+  if (result.noop) {
+    process.stderr.write(
+      `[enact-extensions uninstall] Nothing to remove for ${name} on ${platform} (not installed).\n`,
+    );
+    return result;
+  }
+
+  for (const p of result.removedPaths) {
+    console.log(`removed ${p}`);
+  }
+  console.log(`uninstalled ${name} from ${platform}`);
+
+  // Record uninstall in ledger (best-effort)
+  recordUninstall(name, options.version, platform, homes, options, result);
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// runUninstall — main entry point (mirrors runInstall signature)
+// ---------------------------------------------------------------------------
+/**
+ * Uninstall `nameOrPath` from the given platform(s).
+ *
+ * `nameOrPath` may be:
+ *   - a plugin name (string), used directly
+ *   - a path to a bundle root (resolveBundlePath should have been called by the CLI)
+ *
+ * The CLI passes the resolved name. Library callers may pass the name directly.
+ *
+ * @param {string} name - Plugin name (not a bundle path).
+ * @param {object} options - Same option bag as runInstall, plus optional `version`.
+ */
+export function runUninstall(name, options = {}) {
+  const platforms = parsePlatforms(options.platform);
+  const homes = resolveHomes(options);
+
+  console.log(
+    `uninstall scope: ${homes.scope}${homes.scope === "local" ? ` (${process.cwd()})` : ""}`,
+  );
+
+  // Single-platform path
+  if (platforms.length === 1) {
+    return runSinglePlatform(name, platforms[0], homes, options);
+  }
+
+  // Multi-platform path — run each sequentially, collect results + errors.
+  const platformResults = [];
+  let hasError = false;
+
+  for (const platform of platforms) {
+    console.log(`\n[${platform}] uninstalling...`);
+    try {
+      const result = runSinglePlatform(name, platform, homes, options);
+      console.log(`[${platform}] ✓ done`);
+      platformResults.push({ platform, result, error: null });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[${platform}] ✗ failed: ${msg}`);
+      platformResults.push({ platform, result: null, error: err });
+      hasError = true;
+    }
+  }
+
+  if (hasError) {
+    const failed = platformResults.filter((r) => r.error).map((r) => r.platform);
+    const succeeded = platformResults.filter((r) => !r.error).map((r) => r.platform);
+    const summary = `Multi-platform uninstall: ${succeeded.length} succeeded (${succeeded.join(", ")}), ${failed.length} failed (${failed.join(", ")})`;
+    console.error(`\n${summary}`);
+    const err = new Error(summary);
+    err.platforms = platformResults;
+    throw err;
+  }
+
+  return { platforms: platformResults };
+}