@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/lib/run-install.mjs

@@ -1,60 +1,333 @@
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
 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";
+import { registerPluginHooks, removePluginHooks } from "./hooks.mjs";
+import { assertSupportedHookEvents } from "../../dist/index.js";
 
-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/agent, ~/.claude, ~/.cursor, ~/.agents)
+//        "local"            -> a project-scoped home under the current dir (./.codex, ./.enact/agent, ...)
+// 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/agent") : 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"];
+
+// ---------------------------------------------------------------------------
+// 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}`);
+  } 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`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+  }
+}
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readPluginHookConfig(pluginRoot) {
+  const manifest = readJsonIfExists(join(pluginRoot, ".agents", "plugin.json"));
+  const hooksPath = typeof manifest?.hooks === "string" ? manifest.hooks : null;
+  if (!hooksPath) return null;
+  const normalized = hooksPath.replace(/^\.\//, "");
+  return readJsonIfExists(join(pluginRoot, normalized));
+}
+
+function registerInstalledPluginHooks(pluginRoot, platform, result, homes, options) {
+  // codex reads hooks from the installed plugin bundle (no config.toml
+  // registration); cursor likewise. claude/enact register into their config.
+  if (!["claude", "cursor", "enact"].includes(platform)) return;
+  const hookConfig = readPluginHookConfig(pluginRoot);
+  const name = result?.name ?? result?.results?.[0]?.name;
+  if (!name) return;
+
+  const hookOpts = {
+    cwd: options.cwd ?? pluginRoot,
+    claudeHome: platform === "claude" ? homes.claudeHome : undefined,
+    cursorHome: platform === "cursor" ? homes.cursorHome : undefined,
+    enactHome: platform === "enact" ? homes.enactHome : undefined,
+  };
+
+  // Self-healing reconcile: first remove ALL of THIS plugin's prior hook
+  // registrations (orphaned events dropped from the bundle + duplicate entries
+  // accumulated by earlier appends), then register the current bundle's set.
+  // Removal is marker/command scoped per plugin, so the user's own hooks and
+  // other plugins' hooks are never touched.
+  removePluginHooks(platform, name, hookOpts);
+
+  if (!hookConfig) return;
+  const hookResult = registerPluginHooks(platform, name, hookConfig, hookOpts);
+  if (hookResult.result !== "skipped") {
+    console.log(`hooks ${hookResult.result} for ${name} on ${platform} -> ${hookResult.location}`);
+  }
+}
+
+function removeLegacyCodexPluginHooks(name, result, homes, options) {
+  if (!name) return;
+
+  if (Array.isArray(result?.results)) {
+    for (const install of result.results) {
+      const codexHome = install.configPath ? dirname(install.configPath) : homes.codexHome;
+      const hookResult = removePluginHooks("codex", name, {
+        cwd: options.cwd ?? process.cwd(),
+        codexHome,
+      });
+      if (hookResult.result === "removed") {
+        console.log(`removed legacy codex hooks for ${name} -> ${hookResult.location}`);
+      }
     }
-    return result;
+    return;
   }
 
-  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}`);
+  const hookResult = removePluginHooks("codex", name, {
+    cwd: options.cwd ?? process.cwd(),
+    codexHome: homes.codexHome,
+  });
+  if (hookResult.result === "removed") {
+    console.log(`removed legacy codex hooks for ${name} -> ${hookResult.location}`);
+  }
+}
+
+// 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,
+        marketplaceName: options.marketplaceName ?? "enact-os-plugins",
+      },
+      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);
+    registerInstalledPluginHooks(pluginRoot, platform, result, homes, options);
     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 +335,96 @@ export function runInstall(pluginRoot, options = {}) {
       console.log(`refreshed ${path}`);
     }
   }
+  recordInstall("codex", result, homes, options, hash);
+  removeLegacyCodexPluginHooks(result.results[0]?.name, result, homes, options);
   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 = {}) {
+  // Refuse to install a bundle that declares hook events outside the
+  // cross-surface intersection (claude, codex, cursor, enact).
+  assertSupportedHookEvents(pluginRoot);
+
+  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-prune.mjs

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { cwd as processCwd } from "node:process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { listInstalled } from "./ledger.mjs";
+import { parsePlatforms, runUninstall } from "./run-uninstall.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+const DEFAULT_MARKETPLACE = "enact-os-plugins";
+
+function defaultSourceRoots(cwd) {
+  const roots = [join(PACKAGE_ROOT, "extensions")];
+  const cwdExtensions = join(cwd, "extensions");
+  if (resolve(cwdExtensions) !== resolve(roots[0])) roots.push(cwdExtensions);
+  return roots;
+}
+
+function sourceBundleExists(name, sourceRoots) {
+  return sourceRoots.some((root) => existsSync(join(root, name, ".agents", "plugin.json")));
+}
+
+function homeOptionForPlatform(platform) {
+  switch (platform) {
+    case "codex": return "codexHome";
+    case "claude": return "claudeHome";
+    case "cursor": return "cursorHome";
+    case "enact": return "enactHome";
+    case "shared": return "sharedHome";
+    default: return "codexHome";
+  }
+}
+
+export function runPrune(options = {}) {
+  const cwd = options.cwd ?? processCwd();
+  const ledgerHome = options.ledgerHome ?? options.home ?? homedir();
+  const marketplaceName = options.marketplaceName ?? DEFAULT_MARKETPLACE;
+  const platforms = new Set(parsePlatforms(options.platform ?? "all"));
+  const sourceRoots = options.sourceRoots ?? defaultSourceRoots(cwd);
+  const installed = listInstalled({ home: ledgerHome });
+
+  const candidates = installed
+    .filter((entry) => platforms.has(entry.platform))
+    .filter((entry) => entry.marketplaceName === marketplaceName)
+    .filter((entry) => !sourceBundleExists(entry.name, sourceRoots));
+
+  const pruned = [];
+  const failed = [];
+
+  if (options.dryRun) {
+    return { candidates, pruned, failed, dryRun: true };
+  }
+
+  for (const entry of candidates) {
+    const homeOption = homeOptionForPlatform(entry.platform);
+    try {
+      runUninstall(entry.name, {
+        platform: entry.platform,
+        scope: entry.scope,
+        [homeOption]: entry.home,
+        marketplaceName,
+        ledgerHome,
+        version: entry.version,
+      });
+      pruned.push(entry);
+    } catch (err) {
+      failed.push({ entry, error: err instanceof Error ? err : new Error(String(err)) });
+    }
+  }
+
+  return { candidates, pruned, failed, dryRun: false };
+}

package/scripts/lib/run-sync.mjs

@@ -1,6 +1,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { syncPlatformManifests, createEnactManifest } from "../../dist/index.js";
+import {
+  syncPlatformManifests,
+  createEnactManifest,
+  assertSupportedHookEvents,
+} from "../../dist/index.js";
 
 export function runSync(pluginRoot, { name } = {}) {
   const enactPath = join(pluginRoot, ".agents/plugin.json");
@@ -16,6 +20,10 @@ export function runSync(pluginRoot, { name } = {}) {
     enact = createEnactManifest({ name });
   }
 
+  // Refuse to project manifests for a bundle that declares hook events outside
+  // the cross-surface intersection (claude, codex, cursor, enact).
+  assertSupportedHookEvents(pluginRoot);
+
   const results = syncPlatformManifests(pluginRoot, enact);
   for (const r of results) {
     console.log(`${r.written ? "wrote" : "skip"} ${r.manifestPath}`);