@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/scripts/enact-extensions.mjs

@@ -1,40 +1,137 @@
 #!/usr/bin/env node
 import { resolvePluginRoot } from "./lib/resolve-plugin-root.mjs";
+import { resolveBundlePath } from "./lib/resolve-bundle.mjs";
+import { listBundles } from "./lib/list-bundles.mjs";
+import { buildIndex } from "./lib/build-index.mjs";
 import { runValidate } from "./lib/run-validate.mjs";
 import { runSync } from "./lib/run-sync.mjs";
 import { runInstall } from "./lib/run-install.mjs";
+import { runUpdate } from "./lib/run-update.mjs";
+import { runUninstall } from "./lib/run-uninstall.mjs";
+import { readLedger } from "./lib/ledger.mjs";
+import { computeOutdated } from "./lib/outdated.mjs";
+import { startServer } from "./lib/serve.mjs";
+import { registerHook, removeHook, SUPPORTED_SURFACES } from "./lib/hooks.mjs";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { cwd as processCwd } from "node:process";
+import { homedir } from "node:os";
+import { Ajv } from "ajv";
+import addFormatsModule from "ajv-formats";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const HELP = `enact-extensions — Enact multi-platform plugin manifests
 
 Usage:
-  enact-extensions validate [path]   Validate manifests (default: cwd)
-  enact-extensions sync [path]       Sync host manifests from .agents/plugin.json (default: cwd)
-  enact-extensions sync [path] --name <id>   Create .agents/plugin.json then sync (new plugin)
-  enact-extensions install [path]    Sync and install plugin into Codex-compatible homes (default: cwd)
-  enact-extensions install [path] --platform claude    Install to Claude Code
-  enact-extensions install [path] --platform cursor   Install to Cursor
-  enact-extensions install [path] --platform enact    Install to Enact (Codex fork)
-  enact-extensions install [path] --platform codex    Install to Codex (explicit)
+  enact-extensions list [dir]             List available plugin bundles (default: bundled + cwd/extensions/)
+  enact-extensions list [dir] --json      Emit machine-readable JSON array
+  enact-extensions log                    Print the install ledger (single global file), newest first
+  enact-extensions log --json             Emit the raw ledger array as JSON
+  enact-extensions outdated               Report freshness drift: installed vs canonical source (per plugin+surface)
+  enact-extensions outdated --json        Emit JSON array [{name, platform, scope, home, status, installedHash, currentHash, version}]
+  enact-extensions update <name>          Refresh an outdated plugin on every surface it is installed on (ledger-driven)
+  enact-extensions update --all           Refresh EVERY outdated plugin/surface
+  enact-extensions update <name> --dry-run  Show what would be refreshed; change nothing
+  enact-extensions update --all --dry-run   Show every outdated surface that would be refreshed
+  enact-extensions index [--out <path>]   Generate a discovery index of all bundles (generated artifact, never committed)
+  enact-extensions index --out -          Print the discovery index JSON to stdout
+  enact-extensions index --stdout         Alias for --out -
+  enact-extensions validate [path|name]   Validate manifests (default: cwd)
+  enact-extensions sync [path|name]       Sync host manifests from .agents/plugin.json (default: cwd)
+  enact-extensions sync [path|name] --name <id>   Create .agents/plugin.json then sync (new plugin)
+  enact-extensions install [path|name]    Sync and install plugin into Codex-compatible homes (default: cwd)
+  enact-extensions install [path|name] --platform claude    Install to Claude Code
+  enact-extensions install [path|name] --platform cursor   Install to Cursor
+  enact-extensions install [path|name] --platform enact    Install to Enact (Codex fork)
+  enact-extensions install [path|name] --platform codex    Install to Codex (explicit)
+  enact-extensions install [path|name] --platform shared   Install skills to host-neutral .agents/skills/
+  enact-extensions install [path|name] --platform all      Install to every platform (codex, claude, cursor, enact, shared)
+  enact-extensions install [path|name] --platform claude,cursor   Install to a subset of platforms
+  enact-extensions install [path|name] --global            Install into the default agent home (default)
+  enact-extensions install [path|name] --local             Install into a project home under cwd (./.codex, ...)
+  enact-extensions uninstall [path|name]                   Uninstall plugin from Codex-compatible homes (default: enact)
+  enact-extensions uninstall [path|name] --platform claude    Uninstall from Claude Code
+  enact-extensions uninstall [path|name] --platform cursor   Uninstall from Cursor
+  enact-extensions uninstall [path|name] --platform enact    Uninstall from Enact (Codex fork)
+  enact-extensions uninstall [path|name] --platform codex    Uninstall from Codex (explicit)
+  enact-extensions uninstall [path|name] --platform shared   Remove skills from host-neutral .agents/skills/
+  enact-extensions uninstall [path|name] --platform all      Uninstall from every platform
+  enact-extensions uninstall [path|name] --platform claude,cursor   Uninstall from a subset of platforms
+  enact-extensions serve [--port 43217] [--host 127.0.0.1] [--open]  Start the localhost management UI + API
+  enact-extensions hooks [setup] [--surfaces <list>|--all] [--remove] [--local]
+                                          Register (or remove) the session-start drift-check hook
+                                          for each named surface (claude, codex, cursor, enact).
+
+Hooks command:
+  enact-extensions hooks setup --surfaces claude,codex   Register the drift hook for Claude and Codex
+  enact-extensions hooks setup --all                     Register for all surfaces (claude, codex, cursor, enact)
+  enact-extensions hooks setup --surfaces claude --remove  Remove the drift hook from Claude
+  enact-extensions hooks setup --all --remove            Remove the drift hook from all surfaces
+  enact-extensions hooks setup --surfaces claude --local  Register using project-local home (under cwd)
+  enact-extensions hooks setup                           Interactive surface picker (TTY only)
 
 Options:
-  path    Plugin root (skills/, .agents/, etc.). Defaults to process.cwd().
-  --platform <name>        Target platform: codex (default), claude, cursor, enact
+  path|name  Plugin root path, or a bare plugin name resolved from bundled extensions.
+             Defaults to process.cwd() when omitted.
+  --out <path>             (index only) Output file path. Use - or --stdout to print to stdout.
+                           Default: generated/index.json under the package root.
+  --stdout                 (index only) Alias for --out -.
+  --json                   (list only) Emit a JSON array to stdout instead of a human table.
+  --platform <name>        Target platform: codex (default), claude, cursor, enact, shared.
+                           Use "all" to install to every platform, or a comma-separated list
+                           (e.g. "claude,cursor") to install to a named subset.
+  --global                 Install into the agent's default home (default)
+  --local                  Install into a project-scoped home under the current dir
   --codex-home <path>      Install only into the given Codex-compatible home
   --enact-home <path>      Target a specific local Enact home (default: ~/.enact)
   --claude-home <path>     Target a specific local Claude home (default: ~/.claude)
   --cursor-home <path>     Target a specific local Cursor home (default: ~/.cursor)
+  --shared-home <path>     Base dir for shared install (skills land at <path>/.agents/skills/)
   --marketplace <name>     Marketplace name (default: enact-os-plugins)
   --no-enable              Install files without enabling the Codex/Enact plugin
   --skip-sync              Install current manifests without regenerating them
+  --no-provision           Skip auto-provisioning the bundle's MCP-server packages.
+                           By default, install resolves each declared MCP server
+                           (.mcp.json) and provisions its package: uvx → uv tool
+                           install, npx → npm install -g, pipx → pipx install,
+                           pip/pip3 → pip install. Best-effort; never fails install.
+
+Name resolution (bare plugin names):
+  When a bare name (no "/" in it) is given, it is resolved in this order:
+    1. <this-package-root>/extensions/<name>  (bundled extensions in this repo)
+    2. <cwd>/extensions/<name>                (extensions in a sibling product repo)
+    3. <npm-global-root>/@amsterdamdatalabs/enact-extensions/extensions/<name>
+
+Multi-platform notes:
+  - Platforms are installed sequentially in deterministic order: codex, claude, cursor, enact, shared.
+  - Per-platform --<platform>-home flags apply to their respective platform in a multi-target run.
+  - If any platform fails, the others still proceed; a non-zero exit is returned and the summary
+    of succeeded/failed platforms is printed to stderr.
 
 Examples:
+  enact-extensions list
+  enact-extensions list --json
+  enact-extensions list /path/to/extensions
+  enact-extensions index                   Generate generated/index.json (gitignored, local discovery artifact)
+  enact-extensions index --out -           Print discovery index JSON to stdout (pipe-friendly)
+  enact-extensions index --stdout          Same as --out -
+  enact-extensions index --out /tmp/my-index.json
   cd ../enact-operator/extensions && enact-extensions validate
   enact-extensions sync . --name my-plugin
-  enact-extensions install ../enact-operator/extensions
+  enact-extensions install net-revenue-management --platform enact --global
+  enact-extensions install net-revenue-management --platform enact --local
+  enact-extensions install extensions/net-revenue-management --platform enact --global
   enact-extensions install ../enact-operator/extensions --platform claude
   enact-extensions install ../enact-operator/extensions --platform cursor
-  enact-extensions install ../enact-operator/extensions --platform enact
-  enact-extensions validate ../enact-operator/extensions
+  enact-extensions install net-revenue-management --platform shared
+  enact-extensions install net-revenue-management --platform shared --local
+  enact-extensions install net-revenue-management --platform all
+  enact-extensions install net-revenue-management --platform claude,cursor
+  enact-extensions install net-revenue-management --platform all --enact-home /path/to/enact
+  enact-extensions validate extensions/plugin-dev
+  enact-extensions validate plugin-dev
 `;
 
 function parseArgs(argv) {
@@ -43,7 +140,11 @@ function parseArgs(argv) {
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (arg === "--name" && argv[i + 1]) {
+    if (arg === "--out" && argv[i + 1]) {
+      options.out = argv[++i];
+    } else if (arg === "--stdout") {
+      options.out = "-";
+    } else if (arg === "--name" && argv[i + 1]) {
       options.name = argv[++i];
     } else if (arg === "--codex-home" && argv[i + 1]) {
       options.codexHome = argv[++i];
@@ -53,6 +154,8 @@ function parseArgs(argv) {
       options.enable = false;
     } else if (arg === "--skip-sync") {
       options.sync = false;
+    } else if (arg === "--no-provision") {
+      options.noProvision = true;
     } else if (arg === "--platform" && argv[i + 1]) {
       options.platform = argv[++i];
     } else if (arg === "--claude-home" && argv[i + 1]) {
@@ -61,6 +164,29 @@ function parseArgs(argv) {
       options.cursorHome = argv[++i];
     } else if (arg === "--enact-home" && argv[i + 1]) {
       options.enactHome = argv[++i];
+    } else if (arg === "--shared-home" && argv[i + 1]) {
+      options.sharedHome = argv[++i];
+    } else if (arg === "--local") {
+      options.scope = "local";
+    } else if (arg === "--global") {
+      options.scope = "global";
+    } else if (arg === "--all") {
+      options.all = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--port" && argv[i + 1]) {
+      options.port = parseInt(argv[++i], 10);
+    } else if (arg === "--host" && argv[i + 1]) {
+      options.host = argv[++i];
+    } else if (arg === "--open") {
+      options.open = true;
+    } else if (arg === "--surfaces" && argv[i + 1]) {
+      // Comma-separated list of surfaces: claude,codex,cursor,enact
+      options.surfaces = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (arg === "--remove") {
+      options.remove = true;
     } else if (arg === "-h" || arg === "--help") {
       positional.push("help");
     } else if (!arg.startsWith("-")) {
@@ -78,7 +204,570 @@ if (!command || command === "help") {
   process.exit(command ? 0 : 1);
 }
 
-const pluginRoot = resolvePluginRoot(path);
+// ---------------------------------------------------------------------------
+// `hooks` command — register or remove the session-start drift-check hook.
+//
+// Surfaces: claude, codex, cursor, enact
+// Registration is idempotent and reversible.
+// ---------------------------------------------------------------------------
+if (command === "hooks") {
+  // Sub-command: `hooks setup` or just `hooks` (treat bare `hooks` as `hooks setup`).
+  // path is positional[1] — could be "setup" or undefined.
+  const subCommand = path ?? "setup";
+
+  if (subCommand !== "setup") {
+    process.stderr.write(`[enact-extensions hooks] Unknown sub-command: ${subCommand}. Did you mean 'setup'?\n`);
+    process.exit(1);
+  }
+
+  const isRemove = options.remove ?? false;
+  const isLocal = options.scope === "local";
+  const cwd = processCwd();
+
+  // Determine which surfaces to act on.
+  let surfaces = [];
+  if (options.all) {
+    surfaces = [...SUPPORTED_SURFACES];
+  } else if (options.surfaces && options.surfaces.length > 0) {
+    // Validate provided surface names.
+    const invalid = options.surfaces.filter((s) => !SUPPORTED_SURFACES.includes(s));
+    if (invalid.length > 0) {
+      process.stderr.write(`[enact-extensions hooks] Unknown surface(s): ${invalid.join(", ")}. Valid: ${SUPPORTED_SURFACES.join(", ")}\n`);
+      process.exit(1);
+    }
+    surfaces = options.surfaces;
+  } else {
+    // No surfaces specified — check if TTY for interactive picker.
+    if (process.stdin.isTTY) {
+      // Interactive picker via node:readline.
+      const { createInterface } = await import("node:readline");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+      const question = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+
+      process.stdout.write(`\nenact-extensions hooks setup — interactive surface picker\n`);
+      process.stdout.write(`Available surfaces: ${SUPPORTED_SURFACES.map((s, i) => `${i + 1}. ${s}`).join(", ")}\n`);
+      process.stdout.write(`Enter surface names or numbers (comma-separated), or 'all':\n`);
+
+      const answer = await question("> ");
+      rl.close();
+
+      if (answer.trim().toLowerCase() === "all") {
+        surfaces = [...SUPPORTED_SURFACES];
+      } else {
+        surfaces = answer
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+          .map((s) => {
+            // Allow numeric selection.
+            const idx = parseInt(s, 10);
+            if (!isNaN(idx) && idx >= 1 && idx <= SUPPORTED_SURFACES.length) {
+              return SUPPORTED_SURFACES[idx - 1];
+            }
+            return s.toLowerCase();
+          })
+          .filter((s) => SUPPORTED_SURFACES.includes(s));
+
+        if (surfaces.length === 0) {
+          process.stderr.write(`[enact-extensions hooks] No valid surfaces selected. Exiting.\n`);
+          process.exit(0);
+        }
+      }
+    } else {
+      // Non-TTY, no surface flags → print notice and exit 0.
+      process.stdout.write(
+        `[enact-extensions hooks] No surface specified. Run with --surfaces or --all:\n` +
+        `  enact-extensions hooks setup --surfaces claude,codex\n` +
+        `  enact-extensions hooks setup --all\n`,
+      );
+      process.exit(0);
+    }
+  }
+
+  // Execute registration or removal for each surface.
+  const hookOpts = {
+    claudeHome: options.claudeHome,
+    codexHome: options.codexHome,
+    cursorHome: options.cursorHome,
+    enactHome: options.enactHome,
+    local: isLocal,
+    cwd,
+  };
+
+  for (const surface of surfaces) {
+    let res;
+    if (isRemove) {
+      res = removeHook(surface, hookOpts);
+    } else {
+      res = registerHook(surface, hookOpts);
+    }
+
+    // Print per-surface result.
+    const status = res.result;
+    const location = res.location ? ` → ${res.location}` : "";
+    const note = res.note ? ` (${res.note})` : "";
+
+    if (status === "registered") {
+      process.stdout.write(`  [hooks] ${surface}: registered${location}\n`);
+    } else if (status === "already_registered") {
+      process.stdout.write(`  [hooks] ${surface}: already registered (skipped)${location}\n`);
+    } else if (status === "removed") {
+      process.stdout.write(`  [hooks] ${surface}: removed${location}\n`);
+    } else if (status === "not_found") {
+      process.stdout.write(`  [hooks] ${surface}: not found (nothing to remove)${location}\n`);
+    } else {
+      process.stdout.write(`  [hooks] ${surface}: skipped${note}\n`);
+    }
+
+    if (res.note && status !== "skipped") {
+      process.stderr.write(`  [hooks] ${surface} note: ${res.note}\n`);
+    }
+  }
+
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// `list` command — enumerate available plugin bundles.
+// ---------------------------------------------------------------------------
+if (command === "list") {
+  // The package's own extensions/ dir, resolved relative to this script.
+  const PACKAGE_ROOT = resolve(__dirname, "..");
+  const packageExtensions = join(PACKAGE_ROOT, "extensions");
+
+  let roots;
+  if (path) {
+    // Explicit dir argument → scan only that dir.
+    roots = [resolve(processCwd(), path)];
+  } else {
+    // Default: package-bundled extensions/ + cwd/extensions/ (if it differs).
+    roots = [packageExtensions];
+    const cwdExtensions = join(processCwd(), "extensions");
+    if (resolve(cwdExtensions) !== resolve(packageExtensions) && existsSync(cwdExtensions)) {
+      roots.push(cwdExtensions);
+    }
+  }
+
+  const entries = listBundles(roots);
+
+  if (options.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    process.exit(0);
+  }
+
+  // Human-readable table.
+  const TRUNC = 60;
+  function trunc(str, len) {
+    if (!str) return "";
+    return str.length > len ? str.slice(0, len - 1) + "…" : str;
+  }
+
+  if (entries.length === 0) {
+    console.log("No plugin bundles found.");
+    process.exit(0);
+  }
+
+  // Header.
+  const COL_NAME = 28;
+  const COL_VER  = 8;
+  const COL_CAT  = 18;
+  const COL_SURF = 22;
+
+  function padR(str, n) { return String(str ?? "").padEnd(n).slice(0, n); }
+
+  const hr = "─".repeat(COL_NAME + COL_VER + COL_CAT + COL_SURF + 3 + TRUNC);
+  console.log(hr);
+  console.log(
+    padR("Name", COL_NAME) + "  " +
+    padR("Ver", COL_VER) + "  " +
+    padR("Category", COL_CAT) + "  " +
+    padR("Surfaces", COL_SURF) + "  " +
+    "Description"
+  );
+  console.log(hr);
+
+  for (const e of entries) {
+    const surfaces = e.targets.join(", ");
+    console.log(
+      padR(e.name, COL_NAME) + "  " +
+      padR(e.version, COL_VER) + "  " +
+      padR(e.category, COL_CAT) + "  " +
+      padR(surfaces, COL_SURF) + "  " +
+      trunc(e.description, TRUNC)
+    );
+  }
+  console.log(hr);
+  console.log(`${entries.length} bundle${entries.length === 1 ? "" : "s"} found.`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// `index` command — generate a discovery index of all plugin bundles.
+//
+// The index is a LOCAL GENERATED ARTIFACT (never committed). The generated/
+// directory is gitignored. The schema at spec/index.json is the committed
+// contract. No network, no marketplace, no catalog/ — purely local.
+// ---------------------------------------------------------------------------
+if (command === "index") {
+  const PACKAGE_ROOT = resolve(__dirname, "..");
+  const packageExtensions = join(PACKAGE_ROOT, "extensions");
+
+  // Same default roots as `list`.
+  const roots = [packageExtensions];
+  const cwdExtensions = join(processCwd(), "extensions");
+  if (resolve(cwdExtensions) !== resolve(packageExtensions) && existsSync(cwdExtensions)) {
+    roots.push(cwdExtensions);
+  }
+
+  // Build the index. The wall-clock timestamp is computed here at the CLI
+  // boundary and passed in — buildIndex itself stays pure (never calls Date).
+  let index;
+  try {
+    index = buildIndex(roots, { now: new Date().toISOString(), packageRoot: PACKAGE_ROOT });
+  } catch (err) {
+    console.error(`[enact-extensions index] Failed to build index: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  // Validate against spec/index.json before writing.
+  const schemaPath = join(PACKAGE_ROOT, "spec", "index.json");
+  let schema;
+  try {
+    schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  } catch (err) {
+    console.error(`[enact-extensions index] Cannot read schema ${schemaPath}: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  const addFormats = addFormatsModule.default ?? addFormatsModule;
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  const valid = validate(index);
+  if (!valid) {
+    const errs = (validate.errors ?? []).map((e) => `  ${e.instancePath || "/"}: ${e.message}`).join("\n");
+    console.error(`[enact-extensions index] Generated index failed schema validation:\n${errs}`);
+    process.exit(1);
+  }
+
+  const json = JSON.stringify(index, null, 2);
+  // --stdout is normalized to "-" during arg parsing, so this single check covers both.
+  const toStdout = options.out === "-";
+
+  if (toStdout) {
+    // Write JSON to stdout; summary to stderr (keeps stdout pipe-clean).
+    process.stdout.write(json + "\n");
+    process.stderr.write(`[enact-extensions index] ${index.count} plugin${index.count === 1 ? "" : "s"} indexed.\n`);
+  } else {
+    const outPath = options.out
+      ? resolve(processCwd(), options.out)
+      : join(PACKAGE_ROOT, "generated", "index.json");
+
+    // Ensure parent directory exists.
+    const outDir = resolve(outPath, "..");
+    mkdirSync(outDir, { recursive: true });
+
+    writeFileSync(outPath, json + "\n", "utf8");
+    process.stderr.write(`[enact-extensions index] Wrote ${index.count} plugin${index.count === 1 ? "" : "s"} to ${outPath}\n`);
+  }
+
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// `log` command — print the install ledger (single global file), newest first.
+//
+// Human table to stdout (chrome to stderr) or `--json` (raw ledger array).
+// Reading a missing ledger yields an empty list — never an error.
+// ---------------------------------------------------------------------------
+if (command === "log") {
+  const entries = readLedger();
+  // Most-recent-first.
+  const sorted = [...entries].sort((a, b) =>
+    String(b.ts ?? "").localeCompare(String(a.ts ?? "")),
+  );
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(sorted, null, 2) + "\n");
+    process.exit(0);
+  }
+
+  if (sorted.length === 0) {
+    process.stderr.write("No install ledger entries found.\n");
+    process.exit(0);
+  }
+
+  const COL_TS = 24;
+  const COL_ACT = 10;
+  const COL_NAME = 28;
+  const COL_PLAT = 8;
+  const COL_SCOPE = 7;
+  function padR(str, n) { return String(str ?? "").padEnd(n).slice(0, n); }
+
+  const hr = "─".repeat(COL_TS + COL_ACT + COL_NAME + COL_PLAT + COL_SCOPE + 4 + 40);
+  console.log(hr);
+  console.log(
+    padR("Timestamp", COL_TS) + " " +
+    padR("Action", COL_ACT) + " " +
+    padR("Name", COL_NAME) + " " +
+    padR("Platform", COL_PLAT) + " " +
+    padR("Scope", COL_SCOPE) + " " +
+    "Home",
+  );
+  console.log(hr);
+  for (const e of sorted) {
+    console.log(
+      padR(e.ts, COL_TS) + " " +
+      padR(e.action, COL_ACT) + " " +
+      padR(e.name, COL_NAME) + " " +
+      padR(e.platform, COL_PLAT) + " " +
+      padR(e.scope, COL_SCOPE) + " " +
+      String(e.home ?? ""),
+    );
+  }
+  console.log(hr);
+  process.stderr.write(`${sorted.length} ledger entr${sorted.length === 1 ? "y" : "ies"}.\n`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// `outdated` command — report drift between installed plugins and canonical source.
+//
+// Classifies each installed (plugin, platform) surface as:
+//   fresh    → installed hash matches canonical source hash
+//   outdated → hash mismatch (or recorded hash missing), needs re-install
+//   orphaned → canonical source does not exist (can't refresh)
+//
+// Exit code: always 0 (it's a report, not a failure gate).
+// Human chrome → stderr; --json stdout is always pure JSON.
+// ---------------------------------------------------------------------------
+if (command === "outdated") {
+  let entries;
+  try {
+    entries = computeOutdated({ cwd: processCwd() });
+  } catch (err) {
+    process.stderr.write(
+      `[enact-extensions outdated] Error: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
+    process.exit(0);
+  }
+
+  // Human-readable table.
+  if (entries.length === 0) {
+    process.stderr.write("No installed plugins found in the ledger.\n");
+    process.exit(0);
+  }
+
+  const COL_NAME  = 30;
+  const COL_PLAT  = 10;
+  const COL_SCOPE = 8;
+  const COL_VER   = 10;
+  const COL_STAT  = 10;
+
+  function padR(str, n) { return String(str ?? "").padEnd(n).slice(0, n); }
+
+  const hr = "─".repeat(COL_NAME + COL_PLAT + COL_SCOPE + COL_VER + COL_STAT + 4 + 8);
+  console.log(hr);
+  console.log(
+    padR("Plugin", COL_NAME) + "  " +
+    padR("Platform", COL_PLAT) + "  " +
+    padR("Scope", COL_SCOPE) + "  " +
+    padR("Version", COL_VER) + "  " +
+    padR("Status", COL_STAT),
+  );
+  console.log(hr);
+
+  for (const e of entries) {
+    console.log(
+      padR(e.name, COL_NAME) + "  " +
+      padR(e.platform, COL_PLAT) + "  " +
+      padR(e.scope, COL_SCOPE) + "  " +
+      padR(e.version, COL_VER) + "  " +
+      padR(e.status, COL_STAT),
+    );
+  }
+  console.log(hr);
+  process.stderr.write(`${entries.length} surface${entries.length === 1 ? "" : "s"} checked.\n`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// `update` command — refresh outdated installed plugins, driven by the ledger.
+//
+// Re-installs each OUTDATED (plugin, surface, home) to the EXACT surface + home
+// recorded in the ledger — never to a surface the plugin isn't already on.
+//
+//   update <name>   → refresh only that plugin (across its installed surfaces)
+//   update --all    → refresh every outdated surface
+//   update --dry-run→ report what WOULD change; touch nothing
+//
+// Exit code: non-zero ONLY on a real install failure or a missing target (no
+// name + no --all). Orphaned and fresh surfaces are never failures.
+// Human chrome → stderr; the ledger self-updates via runInstall.
+// ---------------------------------------------------------------------------
+if (command === "update") {
+  let summary;
+  try {
+    summary = runUpdate({
+      name: path,            // positional[1]: a bare plugin name (or undefined)
+      all: options.all,
+      dryRun: options.dryRun,
+      home: homedir(),       // single global ledger home
+      cwd: processCwd(),     // canonical bundle resolution
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[enact-extensions update] ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+
+  const verb = summary.dryRun ? "would update" : "updated";
+
+  if (summary.dryRun) {
+    if (summary.planned.length === 0) {
+      process.stderr.write("Nothing to update — no outdated surfaces in scope.\n");
+    }
+    for (const e of summary.planned) {
+      const from = e.installedHash ? String(e.installedHash).slice(0, 12) : "(none)";
+      const to = e.currentHash ? String(e.currentHash).slice(0, 12) : "(unknown)";
+      console.log(`${verb}: ${e.name} [${e.platform}] @ ${e.home}  ${from} -> ${to}`);
+    }
+  } else {
+    for (const e of summary.updated) {
+      console.log(`updated: ${e.name} [${e.platform}] @ ${e.home}`);
+    }
+  }
+
+  for (const e of summary.skipped) {
+    process.stderr.write(
+      `skipped-orphaned: ${e.name} [${e.platform}] @ ${e.home} (canonical source gone)\n`,
+    );
+  }
+  for (const f of summary.failed) {
+    const e = f.entry;
+    process.stderr.write(
+      `failed: ${e.name} [${e.platform}] @ ${e.home}: ${f.error.message}\n`,
+    );
+  }
+
+  const doneCount = summary.dryRun ? summary.planned.length : summary.updated.length;
+  process.stderr.write(
+    `${doneCount} ${summary.dryRun ? "would be updated" : "updated"}, ` +
+      `${summary.skipped.length} skipped (orphaned), ${summary.failed.length} failed.\n`,
+  );
+
+  // Non-zero exit ONLY on a real install failure.
+  process.exit(summary.failed.length > 0 ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// `serve` command — localhost API + static-file server (no pluginRoot needed).
+// Handled here (before resolveRoot) because it is async + long-running.
+// ---------------------------------------------------------------------------
+if (command === "serve") {
+  const PACKAGE_ROOT = resolve(__dirname, "..");
+  const port = options.port ?? 43217;
+  const host = options.host ?? "127.0.0.1";
+
+  if (host !== "127.0.0.1" && host !== "localhost" && host !== "::1") {
+    process.stderr.write(
+      `[enact-extensions serve] WARNING: binding to ${host} exposes the API to other machines on the network.\n`,
+    );
+  }
+
+  // Use async IIFE. The http.Server keeps the event loop alive after this IIFE resolves.
+  (async () => {
+    let serverInstance;
+    let url;
+    try {
+      const started = await startServer({
+        port,
+        host,
+        packageRoot: PACKAGE_ROOT,
+        installDefaults: { ledgerHome: homedir() },
+      });
+      serverInstance = started.server;
+      url = started.url;
+    } catch (err) {
+      process.stderr.write(`[enact-extensions serve] Failed to start server: ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
+
+    console.log(`enact-extensions serve: listening at ${url}`);
+
+    if (options.open) {
+      // Best-effort browser open; ignore all errors silently.
+      const { spawn } = await import("node:child_process");
+      const opener =
+        process.platform === "darwin"
+          ? "open"
+          : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+      try {
+        spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+      } catch {
+        // xdg-open / open not available in all environments — ignore
+      }
+    }
+
+    // SIGINT / SIGTERM → graceful shutdown
+    const shutdown = () => serverInstance.close(() => process.exit(0));
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  })();
+
+  // Do NOT fall through to resolveRoot / the plugin-root command block.
+  // process.exit is intentionally NOT called — the http.Server ref keeps Node alive.
+  // Use a throw inside a never-reached block OR just let the module end here.
+  // The trick: throw a synthetic signal so the try/catch-less module scope terminates.
+  // Actually: we use process.exitCode = 0 and allow the event loop to keep running.
+  process.exitCode = 0; // signal intent; overridden to 1 on error inside IIFE
+}
+
+// ---------------------------------------------------------------------------
+// Commands that require resolving a plugin root path.
+// (Only run when command !== "serve" — serve handled above and must not fall through.)
+// ---------------------------------------------------------------------------
+if (command !== "serve") {
+
+// Resolve the plugin root:
+//   - If no path arg given → default to cwd (existing behaviour).
+//   - If a path arg is given → resolveBundlePath handles both explicit paths and
+//     bare plugin names, throwing meaningful errors when nothing resolves.
+const resolveRoot = (pathArg) => {
+  if (!pathArg) return resolvePluginRoot(undefined);
+  return resolveBundlePath(pathArg);
+};
+
+// A bare name has no path separators (so it is not an explicit filesystem path).
+const isBareName = (arg) =>
+  typeof arg === "string" && arg.length > 0 && !arg.includes("/") && !arg.includes("\\");
+
+let pluginRoot = null;
+try {
+  pluginRoot = resolveRoot(path);
+} catch (err) {
+  // UNINSTALL-ONLY FALLBACK: uninstall must work even when the source bundle is
+  // gone. If the arg is a BARE NAME (not an explicit path) that did not resolve
+  // to a bundle, fall back to using the arg verbatim as the plugin name. The
+  // uninstall handler reads the name from `path` when pluginRoot is null.
+  // For an explicit path that does not exist, or for any other command, this is
+  // still a hard error.
+  if (command === "uninstall" && isBareName(path)) {
+    pluginRoot = null; // signal: use the raw `path` as the plugin name
+  } else {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
 
 try {
   if (command === "validate") {
@@ -92,7 +781,51 @@ try {
   }
 
   if (command === "install") {
-    runInstall(pluginRoot, options);
+    // Single global ledger: every install (local or global scope) records to
+    // <homedir>/.enact/extensions/ledger.jsonl so `log` always finds it,
+    // regardless of which per-platform home the bundle was installed to. The
+    // local/global distinction is carried in each entry's `scope` field.
+    runInstall(pluginRoot, { ...options, ledgerHome: homedir() });
+    process.exit(0);
+  }
+
+  if (command === "uninstall") {
+    // Resolve plugin name: if the source bundle resolved on disk, read its
+    // manifest name from .agents/plugin.json (or .codex-plugin/plugin.json).
+    // Otherwise (source bundle gone / bare-name fallback), treat the raw
+    // positional arg as the plugin name. This lets uninstall remove already-
+    // installed plugins even when their source bundle has been deleted.
+    let pluginName = null;
+    if (pluginRoot) {
+      try {
+        const enactManifestPath = join(pluginRoot, ".agents", "plugin.json");
+        if (existsSync(enactManifestPath)) {
+          const manifest = JSON.parse(readFileSync(enactManifestPath, "utf8"));
+          pluginName = typeof manifest.name === "string" ? manifest.name : null;
+        }
+        // Fall back to .codex-plugin/plugin.json
+        if (!pluginName) {
+          const codexManifestPath = join(pluginRoot, ".codex-plugin", "plugin.json");
+          if (existsSync(codexManifestPath)) {
+            const manifest = JSON.parse(readFileSync(codexManifestPath, "utf8"));
+            pluginName = typeof manifest.name === "string" ? manifest.name : null;
+          }
+        }
+      } catch {
+        // Source bundle unreadable — fall through to raw name.
+      }
+    }
+    // Fall back: treat the raw positional arg as the plugin name.
+    // `path` is the raw positional from the CLI. When the source bundle was gone
+    // (pluginRoot === null) this is the only source of the name.
+    if (!pluginName) {
+      pluginName = path ?? (pluginRoot ? pluginRoot.split("/").pop() : null);
+    }
+    if (!pluginName) {
+      console.error("uninstall requires a plugin name or path.");
+      process.exit(1);
+    }
+    runUninstall(pluginName, { ...options, ledgerHome: homedir() });
     process.exit(0);
   }
 
@@ -103,3 +836,5 @@ try {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);
 }
+
+} // end if (command !== "serve")