@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/lib/ledger.mjs

@@ -0,0 +1,163 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * Install ledger — a JSONL record of install/uninstall events.
+ *
+ * There is exactly ONE ledger location — the GLOBAL file:
+ *   <home>/.enact/extensions/ledger.jsonl   (home defaults to os.homedir())
+ *
+ * The local-vs-global install distinction is tracked PURELY as the `scope`
+ * FIELD inside each entry (scope:"local" | scope:"global"); BOTH scopes write
+ * to this single global ledger. The `home` override exists so tests never touch
+ * the real ~/.enact.
+ *
+ * Entry shape: { ts, action, name, version, platform, scope, home, path, marketplaceName }
+ *
+ * All file I/O is best-effort: failures throw a catchable error so callers
+ * (the install path) can swallow + warn rather than aborting an install.
+ */
+
+/**
+ * Resolve the on-disk ledger path. Always the single global file.
+ * @param {object} [opts]
+ * @param {string} [opts.home] - home dir. Defaults to os.homedir().
+ * @returns {string}
+ */
+export function ledgerPath({ home } = {}) {
+  return join(home ?? homedir(), ".enact", "extensions", "ledger.jsonl");
+}
+
+/**
+ * Append a single entry as one JSON line. Creates the parent dir if missing.
+ * `ts` defaults to new Date().toISOString() when absent (an injected ts is kept).
+ * Best-effort: throws a catchable error on I/O failure.
+ *
+ * @param {object} entry
+ * @param {object} [opts] - { home }
+ */
+export function appendEntry(entry, { home } = {}) {
+  const record = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+  // Ensure ts wins even if entry has an explicit undefined.
+  if (!record.ts) record.ts = new Date().toISOString();
+  const path = ledgerPath({ home });
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+
+/**
+ * Read and parse all entries from the single global ledger.
+ * Missing file → []. Malformed lines are skipped with a stderr warning.
+ *
+ * @param {object} [opts] - { home }
+ * @returns {object[]}
+ */
+export function readLedger({ home } = {}) {
+  const path = ledgerPath({ home });
+  if (!existsSync(path)) return [];
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    process.stderr.write(
+      `[enact-extensions log] Warning: cannot read ledger ${path}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return [];
+  }
+  const entries = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      process.stderr.write(
+        `[enact-extensions log] Warning: skipping malformed ledger line in ${path}\n`,
+      );
+    }
+  }
+  return entries;
+}
+
+/**
+ * Thin alias of {@link readLedger}, retained so existing callers keep working.
+ * With the single-global ledger there is no merge to perform: global- and
+ * local-scope entries are co-located in the one file.
+ *
+ * @param {object} [opts] - { home }
+ * @returns {object[]}
+ */
+export function readMerged({ home } = {}) {
+  return readLedger({ home });
+}
+
+/**
+ * Compute the current install state for `name` by replaying install/uninstall
+ * events in ts order across the single global ledger. Returns the set of
+ * still-installed targets as { platform, scope, home, path }.
+ *
+ * A target is keyed by platform+scope+home+path so the same plugin installed to
+ * multiple platforms/homes is tracked independently.
+ *
+ * @param {string} name
+ * @param {object} [opts] - { home }
+ * @returns {{ platform: string, scope: string, home: string, path: string }[]}
+ */
+export function findInstalled(name, { home } = {}) {
+  const merged = readLedger({ home }).filter((e) => e && e.name === name);
+  // Stable sort by ts (string ISO compares chronologically).
+  merged.sort((a, b) => String(a.ts ?? "").localeCompare(String(b.ts ?? "")));
+
+  const state = new Map();
+  for (const e of merged) {
+    const key = `${e.platform} ${e.scope} ${e.home ?? ""} ${e.path ?? ""}`;
+    if (e.action === "install") {
+      state.set(key, { platform: e.platform, scope: e.scope, home: e.home, path: e.path });
+    } else if (e.action === "uninstall") {
+      state.delete(key);
+    }
+  }
+  return [...state.values()];
+}
+
+/**
+ * Compute the current install state for ALL plugins by replaying install/uninstall
+ * events in ts order across the single global ledger. Returns the set of
+ * still-installed targets across all plugin names.
+ *
+ * Each returned entry carries the full ledger fields for the installed surface:
+ *   { name, version, platform, scope, home, path, hash, marketplaceName }
+ *
+ * A target is keyed by name+platform+scope+home+path so the same plugin installed
+ * to multiple platforms/homes/names is tracked independently.
+ *
+ * @param {object} [opts] - { home }
+ * @returns {{ name: string, version: string, platform: string, scope: string, home: string, path: string, hash: string|null, marketplaceName: string|null }[]}
+ */
+export function listInstalled({ home } = {}) {
+  const all = readLedger({ home });
+  // Stable sort by ts (string ISO compares chronologically).
+  all.sort((a, b) => String(a.ts ?? "").localeCompare(String(b.ts ?? "")));
+
+  const state = new Map();
+  for (const e of all) {
+    if (!e || !e.name) continue;
+    const key = `${e.name} ${e.platform ?? ""} ${e.scope ?? ""} ${e.home ?? ""} ${e.path ?? ""}`;
+    if (e.action === "install") {
+      state.set(key, {
+        name: e.name,
+        version: e.version ?? null,
+        platform: e.platform,
+        scope: e.scope,
+        home: e.home,
+        path: e.path,
+        hash: e.hash ?? null,
+        marketplaceName: e.marketplaceName ?? null,
+      });
+    } else if (e.action === "uninstall") {
+      state.delete(key);
+    }
+  }
+  return [...state.values()];
+}

package/scripts/lib/list-bundles.mjs

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/**
+ * Enumerate plugin bundles under the given root directories.
+ *
+ * For each root, scans direct subdirectories for `.agents/plugin.json`.
+ * - Skips subdirs without a readable `.agents/plugin.json`.
+ * - Warns to stderr on malformed JSON but does NOT throw.
+ * - De-duplicates roots by resolved path so the same directory is never scanned twice.
+ *
+ * @param {string[]} roots - Absolute paths to scan for plugin bundles.
+ * @returns {{ name: string, version: string, category: string, description: string, targets: string[], path: string }[]}
+ */
+export function listBundles(roots) {
+  // De-duplicate roots by resolved absolute path.
+  const seen = new Set();
+  const uniqueRoots = [];
+  for (const r of roots) {
+    const abs = resolve(r);
+    if (!seen.has(abs)) {
+      seen.add(abs);
+      uniqueRoots.push(abs);
+    }
+  }
+
+  const results = [];
+
+  for (const root of uniqueRoots) {
+    if (!existsSync(root)) continue;
+
+    let entries;
+    try {
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch {
+      // Unreadable root — skip silently.
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const bundleDir = join(root, entry.name);
+      const manifestPath = join(bundleDir, ".agents", "plugin.json");
+
+      if (!existsSync(manifestPath)) continue;
+
+      let manifest;
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      } catch (err) {
+        process.stderr.write(
+          `[enact-extensions list] Warning: skipping malformed manifest at ${manifestPath}: ${err.message}\n`,
+        );
+        continue;
+      }
+
+      results.push({
+        name: manifest.name ?? entry.name,
+        version: manifest.version ?? "unknown",
+        category: manifest.interface?.category ?? "",
+        description: manifest.description ?? "",
+        targets: Array.isArray(manifest.targets) ? manifest.targets : [],
+        path: bundleDir,
+      });
+    }
+  }
+
+  return results;
+}

package/scripts/lib/outdated.mjs

@@ -0,0 +1,144 @@
+/**
+ * outdated.mjs — compute freshness drift between installed plugins and their
+ * canonical source bundles.
+ *
+ * computeOutdated({ home?, cwd? }) → OutdatedEntry[]
+ *
+ * For each currently-installed (plugin, platform, scope, home) surface from the
+ * ledger, resolves the canonical source bundle (extensions/<name>) and classifies:
+ *
+ *   fresh    — canonical source exists and its hash matches the ledger's recorded hash.
+ *   outdated — canonical source exists but hash differs (or ledger hash is null/missing),
+ *              or the recorded version differs (future: not currently used for the flag,
+ *              but hash comparison is the primary signal).
+ *   orphaned — canonical source does NOT exist on disk; cannot refresh.
+ *
+ * Returns a sorted array of OutdatedEntry objects:
+ *   { name, platform, scope, home, status, installedHash, currentHash, version }
+ *
+ * Pure-ish: reads ledger + canonical bundle; no writes.
+ */
+
+import { homedir } from "node:os";
+import { cwd as processCwd } from "node:process";
+import { bundleHash } from "./bundle-hash.mjs";
+import { listInstalled } from "./ledger.mjs";
+import { resolveBundlePath } from "./resolve-bundle.mjs";
+
+/**
+ * @typedef {object} OutdatedEntry
+ * @property {string} name
+ * @property {string} platform
+ * @property {string} scope
+ * @property {string} home
+ * @property {"fresh"|"outdated"|"orphaned"} status
+ * @property {string|null} installedHash  — hash recorded at install time (may be null)
+ * @property {string|null} currentHash    — hash of canonical source now (null if orphaned)
+ * @property {string|null} version        — version recorded in the ledger
+ */
+
+/**
+ * Safely compute the canonical bundle hash for a given bundle root.
+ * Returns null on any error (missing manifest, I/O error, etc.).
+ *
+ * @param {string} bundleRoot
+ * @returns {string|null}
+ */
+function safeHash(bundleRoot) {
+  try {
+    return bundleHash(bundleRoot);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the canonical bundle path for a plugin name.
+ * Returns null when the canonical source cannot be found (so caller can
+ * classify as orphaned rather than crashing).
+ *
+ * @param {string} name
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function safeResolveBundlePath(name, cwd) {
+  try {
+    return resolveBundlePath(name, { cwd });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute freshness status for all currently-installed plugin surfaces.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]   — ledger home override (defaults to os.homedir())
+ * @param {string} [opts.cwd]   — working directory for bundle resolution (defaults to process.cwd())
+ * @returns {OutdatedEntry[]} sorted by name, then platform, then scope
+ */
+export function computeOutdated({ home, cwd } = {}) {
+  const resolvedHome = home ?? homedir();
+  const resolvedCwd = cwd ?? processCwd();
+
+  // Get all currently-installed entries (install replayed over uninstall).
+  const installed = listInstalled({ home: resolvedHome });
+
+  /** @type {OutdatedEntry[]} */
+  const results = [];
+
+  for (const entry of installed) {
+    const { name, platform, scope, home: entryHome, version, hash: installedHash } = entry;
+
+    // Resolve canonical source bundle for this plugin name.
+    const canonicalPath = safeResolveBundlePath(name, resolvedCwd);
+
+    if (!canonicalPath) {
+      // Canonical source does not exist → orphaned.
+      results.push({
+        name,
+        platform,
+        scope,
+        home: entryHome,
+        status: "orphaned",
+        installedHash: installedHash ?? null,
+        currentHash: null,
+        version: version ?? null,
+      });
+      continue;
+    }
+
+    // Canonical source exists — compute its current hash.
+    const currentHash = safeHash(canonicalPath);
+
+    let status;
+    if (installedHash == null || currentHash == null || installedHash !== currentHash) {
+      // No recorded hash, or canonical hash is uncomputable, or hashes differ.
+      status = "outdated";
+    } else {
+      status = "fresh";
+    }
+
+    results.push({
+      name,
+      platform,
+      scope,
+      home: entryHome,
+      status,
+      installedHash: installedHash ?? null,
+      currentHash,
+      version: version ?? null,
+    });
+  }
+
+  // Deterministic sort: name → platform → scope
+  results.sort((a, b) => {
+    const n = String(a.name ?? "").localeCompare(String(b.name ?? ""));
+    if (n !== 0) return n;
+    const p = String(a.platform ?? "").localeCompare(String(b.platform ?? ""));
+    if (p !== 0) return p;
+    return String(a.scope ?? "").localeCompare(String(b.scope ?? ""));
+  });
+
+  return results;
+}

package/scripts/lib/provision-mcp.mjs

@@ -0,0 +1,16 @@
+/**
+ * CLI/runtime wrapper over the typed library provisioning API.
+ *
+ * The script-layer helpers remain for backwards compatibility with tests and
+ * the CLI wrapper, but the source of truth now lives in src/provision.ts and is
+ * exported from dist/index.js for in-process consumers like enact-operator.
+ */
+import {
+  provisionMcp as provisionMcpCore,
+  readMcpServers as readMcpServersCore,
+  summarizeProvision as summarizeProvisionCore,
+} from "../../dist/index.js";
+
+export const readMcpServers = readMcpServersCore;
+export const provisionMcp = provisionMcpCore;
+export const summarizeProvision = summarizeProvisionCore;

package/scripts/lib/resolve-bundle.mjs

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