@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/lib/run-uninstall.mjs

@@ -0,0 +1,244 @@
+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";
+import { removePluginHooks } from "./hooks.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/agent") : 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"];
+
+/**
+ * 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,
+      marketplaceName: options.marketplaceName ?? "enact-os-plugins",
+    },
+    options,
+  );
+}
+
+function removeInstalledPluginHooks(name, platform, homes, options) {
+  if (!["codex", "claude", "cursor", "enact"].includes(platform)) return;
+  const hookResult = removePluginHooks(platform, name, {
+    cwd: options.cwd ?? process.cwd(),
+    codexHome: platform === "codex" ? homes.codexHome : undefined,
+    claudeHome: platform === "claude" ? homes.claudeHome : undefined,
+    cursorHome: platform === "cursor" ? homes.cursorHome : undefined,
+    enactHome: platform === "enact" ? homes.enactHome : undefined,
+  });
+  if (hookResult.result !== "not_found" && hookResult.result !== "skipped") {
+    console.log(`hooks ${hookResult.result} for ${name} on ${platform} -> ${hookResult.location}`);
+  }
+}
+
+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;
+
+  // Remove plugin hook registrations before platform uninstall rewrites host
+  // config files. Some serializers preserve hook tables but drop marker
+  // comments, so post-uninstall cleanup would lose its reversible marker.
+  removeInstalledPluginHooks(name, platform, homes, options);
+
+  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) {
+    removeInstalledPluginHooks(name, platform, homes, options);
+    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}`);
+
+  removeInstalledPluginHooks(name, platform, homes, options);
+
+  // 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 };
+}

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,20 @@
 import {
-  validatePluginBundle,
-  checkComponentPaths,
-  checkPluginBundleComponentPaths,
-  readManifestFile,
+  validatePluginBundleFromCanonical,
+  checkPluginBundleComponentPathsFromCanonical,
+  checkHookEvents,
 } 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);
+  const hookErrors = checkHookEvents(pluginRoot);
 
   for (const result of report.results) {
     const status = result.ok ? "ok" : "FAIL";
@@ -24,13 +24,16 @@ export function runValidate(pluginRoot, platforms) {
     }
   }
 
+  if (hookErrors.length > 0) {
+    console.log(`[FAIL] hooks (${pluginRoot})`);
+    for (const err of hookErrors) {
+      console.log(`  - ${err}`);
+    }
+  }
+
   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 && hookErrors.length === 0;
 }