@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/scripts/lib/allowed-plugins.mjs

@@ -0,0 +1,52 @@
+/**
+ * allowed-plugins.mjs — the DEFAULT set of plugin bundles this package ships.
+ *
+ * Owner decision, 2026-09-15: bundled-extensions.json names the defaults; it is
+ * NOT an allow-list. Install and uninstall of ANY resolvable bundle must work
+ * from the CLI. The previous behaviour refused every name but `enact-repo`, and
+ * refused on the RESOLVED NAME before resolution ran — so even an explicit path
+ * was rejected, while the error advised passing one.
+ *
+ * bundled-extensions.json remains the single place to change which bundles ship
+ * as defaults, and is still validated loudly rather than falling back to a scan
+ * of extensions/.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+
+export const BUNDLED_EXTENSIONS_PATH = join(PACKAGE_ROOT, "bundled-extensions.json");
+
+/**
+ * Read and validate bundled-extensions.json. Throws loudly (never falls back
+ * to scanning extensions/) when the file is missing or malformed.
+ *
+ * @returns {string[]} the default plugin names.
+ */
+export function loadBundledPluginNames() {
+  if (!existsSync(BUNDLED_EXTENSIONS_PATH)) {
+    throw new Error(
+      `[enact-extensions] ${BUNDLED_EXTENSIONS_PATH} is missing; cannot determine the default plugin set.`,
+    );
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(BUNDLED_EXTENSIONS_PATH, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `[enact-extensions] failed to parse ${BUNDLED_EXTENSIONS_PATH}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  if (!Array.isArray(raw.bundled) || raw.bundled.some((n) => typeof n !== "string" || !n)) {
+    throw new Error(
+      `[enact-extensions] ${BUNDLED_EXTENSIONS_PATH} must contain a "bundled" array of non-empty plugin name strings.`,
+    );
+  }
+
+  return raw.bundled;
+}

package/scripts/lib/build-index.mjs

@@ -25,9 +25,7 @@ export function buildIndex(roots, opts = {}) {
   const { now = null, packageRoot } = opts;
 
   // Resolve package root: two levels up from this file (scripts/lib/ → repo root)
-  const pkgRoot =
-    packageRoot ??
-    new URL("../../", import.meta.url).pathname.replace(/\/$/, "");
+  const pkgRoot = packageRoot ?? new URL("../../", import.meta.url).pathname.replace(/\/$/, "");
 
   // Source bundles via the canonical list-bundles helper (deduplicated, resilient).
   const entries = listBundles(roots);

package/scripts/lib/resolve-bundle.mjs

@@ -115,7 +115,5 @@ export function resolveBundlePath(arg, opts = {}) {
   // --- 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.`,
-  );
+  throw new Error(`Plugin "${arg}" not found. Looked in:\n${candidateList}\nPass an explicit path instead.`);
 }

package/scripts/lib/run-repo-doctor.mjs

@@ -0,0 +1,604 @@
+/**
+ * `enact-extensions doctor enact-repo --repo <path> [--json]` — READ-ONLY
+ * health check for a repo-local `enact-repo` install. Never writes anything
+ * (not the lock, not any host file, not any global config). Replaces the
+ * `doctor`/`status` surface of the retired `enact-repo-controls` tool for the
+ * repo-local installer in this package.
+ *
+ * Checks:
+ *   - installed?                         (lock present)
+ *   - plugin version vs bundle version    (outdated?), plus per-file content
+ *                                          drift against what the CURRENT
+ *                                          bundle would generate
+ *   - lock integrity                      (every managed file present + hash
+ *                                          match; every merged JSON entry /
+ *                                          TOML block present; list drifted
+ *                                          or missing)
+ *   - per-host status: claude (marketplace + settings present; trust +
+ *     "start a new session" note), codex (files present; read-only
+ *     ~/.codex/config.toml projects."<repo>".trust_level; hooks-review-
+ *     pending note), cursor (files present; MCP approval note), kimi
+ *     (.kimi-code/mcp.json present; global hooks are enact-vps-owned, so we
+ *     only report whether ~/.kimi-code/config.toml has the
+ *     `# BEGIN ENACT KIMI HOOKS` block; PLUS a read-only Kimi Code
+ *     workspace-trust check — Kimi only loads project MCP servers, including
+ *     `.kimi-code/mcp.json`, once the workspace is trusted), opencode
+ *     (plugin file present and generated from the current bundle)
+ *   - required global binaries on PATH (enact-hook, lean-ctx,
+ *     code-review-graph/crg, azure-devops-mcp) with versions
+ *   - root `enact-config.toml` marker: present, parses as TOML, has our
+ *     `[extensions]` table (other tools' tables are never inspected); a leftover
+ *     `.agents/enact-repo.toml` is reported as stale (existence only, never
+ *     read -- HARDCUT, no fallback)
+ *   - `enact-hook doctor --repo <path>` passthrough, best-effort (never a
+ *     hard requirement — reports "not available" when the binary or that
+ *     sub-command isn't there)
+ *   - enact-hook per-repo logs (informational, read-only): both log paths
+ *     (`.agents/hooks/hooks.log` deny log, `.agents/hooks/hooks-activity.log`
+ *     activity log), whether each exists, its row count, and (deny log only)
+ *     the last 5 rows parsed into named columns
+ *
+ * Non-zero exit (report.exitCode = 1) ONLY for hard requirements: not
+ * installed, lock integrity failure, a missing required global binary, or an
+ * invalid/missing `enact-config.toml` marker. Everything else (outdated
+ * version, host trust/approval notes, hookDoctor unavailability, a stale
+ * `.agents/enact-repo.toml`) is informational.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import * as TOML from "@iarna/toml";
+import { entryPresent, findBlock } from "../../dist/index.js";
+import {
+  abs,
+  buildPlan,
+  CONFIG_PATH,
+  fileSha,
+  HOOK_LOG_FILES,
+  lockRel,
+  REPO_HOSTS,
+  readBundle,
+  readJsonStrict,
+  readLock,
+  resolveRepoRoot,
+  sha256,
+} from "./run-repo-install.mjs";
+
+const STALE_MARKER_PATH = ".agents/enact-repo.toml";
+const KIMI_HOOKS_MARKER = "# BEGIN ENACT KIMI HOOKS";
+const REQUIRED_BINARIES = ["enact-hook", "lean-ctx", "azure-devops-mcp"];
+
+// enact-hook per-repo logs: `.agents/hooks/hooks.log` (deny log CSV) and
+// `.agents/hooks/hooks-activity.log` (activity log CSV -- deny columns plus
+// host/kind/event/tool/session/downstream/duration_ms). Written by the
+// global `enact-hook` runtime, never by this package; reported read-only.
+const [DENY_LOG_REL, ACTIVITY_LOG_REL] = HOOK_LOG_FILES;
+const DENY_LOG_COLUMNS = ["timestamp", "surface", "reason_id", "command", "agent_message"];
+const ACTIVITY_LOG_COLUMNS = [
+  ...DENY_LOG_COLUMNS,
+  "host",
+  "kind",
+  "event",
+  "tool",
+  "session",
+  "downstream",
+  "duration_ms",
+];
+const DENY_LOG_LAST_ROWS = 5;
+
+// ---------------------------------------------------------------------------
+// small read-only helpers
+// ---------------------------------------------------------------------------
+
+function checkBinary(name) {
+  const which = spawnSync("which", [name], { encoding: "utf8" });
+  if (which.status !== 0 || !which.stdout.trim()) return { found: false };
+  const path = which.stdout.trim();
+  const ver = spawnSync(name, ["--version"], { encoding: "utf8", timeout: 5000 });
+  const version = ver.status === 0 ? `${ver.stdout || ver.stderr || ""}`.trim().split("\n")[0] : null;
+  return { found: true, path, version };
+}
+
+function checkCrgBinary() {
+  for (const name of ["crg", "code-review-graph"]) {
+    const r = checkBinary(name);
+    if (r.found) return { ...r, name };
+  }
+  return { found: false, name: "crg (or code-review-graph)" };
+}
+
+function computeCurrentPlanHashes(pluginRoot, bundle, hosts, repo) {
+  const plan = buildPlan(pluginRoot, bundle, hosts, repo);
+  const map = new Map();
+  for (const [rel, content] of plan.files) map.set(rel, sha256(content));
+  return map;
+}
+
+// Codex: read-only check of ~/.codex/config.toml `projects."<path>".trust_level`
+// for this EXACT repo path. Never writes.
+function checkCodexTrust(repo, home) {
+  const configPath = join(home, ".codex", "config.toml");
+  if (!existsSync(configPath)) {
+    return { configFound: false, trustLevel: null, note: `${configPath} not found` };
+  }
+  let doc;
+  try {
+    doc = TOML.parse(readFileSync(configPath, "utf8"));
+  } catch (err) {
+    return {
+      configFound: true,
+      trustLevel: null,
+      note: `cannot parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  const entry = doc.projects && typeof doc.projects === "object" ? doc.projects[repo] : undefined;
+  const trustLevel =
+    entry && typeof entry === "object" && typeof entry.trust_level === "string" ? entry.trust_level : null;
+  return {
+    configFound: true,
+    trustLevel,
+    note: trustLevel
+      ? undefined
+      : `repo not marked trusted in ${configPath} (projects."${repo}".trust_level) -- Codex hooks/config load only after you trust this project`,
+  };
+}
+
+// Kimi hooks are global-only (installed by enact-vps); we only REPORT whether
+// the global block is present, never write it ourselves.
+function checkKimiGlobalHooks(home) {
+  const configPath = join(home, ".kimi-code", "config.toml");
+  if (!existsSync(configPath)) return { configFound: false, hooksBlockPresent: false, configPath };
+  const text = readFileSync(configPath, "utf8");
+  return { configFound: true, hooksBlockPresent: text.includes(KIMI_HOOKS_MARKER), configPath };
+}
+
+function kimiCodeHome() {
+  return process.env.KIMI_CODE_HOME || join(homedir(), ".kimi-code");
+}
+
+function kimiWorkspaceTrustSlug(repo) {
+  return basename(repo)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Kimi Code v0.39.1 loads project MCP servers (`.kimi-code/mcp.json` included)
+// ONLY when the workspace is trusted:
+// `loadMcpServers({ includeProject: trust.isTrusted() })`. Trust record:
+// `${KIMI_CODE_HOME:-~/.kimi-code}/workspace-trust/wd_<slug>_<sha256(absRoot)[:12]>`
+// containing `{"root": "<abs path>", "trustedAt": <ms>}`. READ-ONLY: never
+// creates or modifies the trust record -- granting trust is the user's own
+// action in Kimi Code ("Trust this folder").
+function checkKimiWorkspaceTrust(repo) {
+  const home = kimiCodeHome();
+  const slug = kimiWorkspaceTrustSlug(repo);
+  const hash = createHash("sha256").update(repo).digest("hex").slice(0, 12);
+  const recordPath = join(home, "workspace-trust", `wd_${slug}_${hash}`);
+  const untrustedNote = (why) =>
+    `${why} -- open ${repo} in Kimi Code once and accept "Trust this folder"; until then Kimi loads no enact-repo MCP servers (project MCP, including .kimi-code/mcp.json, is skipped for untrusted workspaces)`;
+
+  if (!existsSync(recordPath)) {
+    return { trusted: false, recordPath, note: untrustedNote(`not trusted (no trust record at ${recordPath})`) };
+  }
+  let record;
+  try {
+    record = JSON.parse(readFileSync(recordPath, "utf8"));
+  } catch (err) {
+    return {
+      trusted: false,
+      recordPath,
+      note: untrustedNote(
+        `trust record at ${recordPath} is malformed JSON (${err instanceof Error ? err.message : String(err)})`,
+      ),
+    };
+  }
+  if (!record || record.root !== repo) {
+    return {
+      trusted: false,
+      recordPath,
+      note: untrustedNote(
+        `trust record at ${recordPath} is for a different root (${record?.root ?? "(none)"}), not ${repo}`,
+      ),
+    };
+  }
+  return { trusted: true, recordPath, trustedAt: record.trustedAt ?? null };
+}
+
+// ---------------------------------------------------------------------------
+// enact-hook per-repo logs (read-only) — robust CSV parsing: quoted fields
+// (so a quoted `command`/`agent_message` may embed commas, or even raw
+// newlines) plus plain unquoted fields (the common case, already flattened
+// to a single line by the writer). RFC4180-shaped, minus a header row (both
+// logs are append-only data rows, no header).
+// ---------------------------------------------------------------------------
+function parseCsvRows(text) {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += c;
+      }
+      continue;
+    }
+    if (c === '"') {
+      inQuotes = true;
+      continue;
+    }
+    if (c === ",") {
+      row.push(field);
+      field = "";
+      continue;
+    }
+    if (c === "\r") continue;
+    if (c === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+      continue;
+    }
+    field += c;
+  }
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  // Drop blank trailing/interstitial lines (a single empty field).
+  return rows.filter((r) => r.length > 1 || r[0] !== "");
+}
+
+function readHookLogSummary(repo, rel, columns, lastN) {
+  const path = abs(repo, rel);
+  if (!existsSync(path)) return { path: rel, exists: false, rowCount: 0, lastRows: [] };
+  const rows = parseCsvRows(readFileSync(path, "utf8"));
+  const lastRows =
+    lastN > 0
+      ? rows.slice(-lastN).map((cols) => Object.fromEntries(columns.map((name, i) => [name, cols[i] ?? ""])))
+      : [];
+  return { path: rel, exists: true, rowCount: rows.length, lastRows };
+}
+
+// Informational only (never affects `problems`/exitCode) -- these logs are
+// the runtime's own operational history, not an install-health signal.
+function checkHookLogs(repo) {
+  return {
+    denyLog: readHookLogSummary(repo, DENY_LOG_REL, DENY_LOG_COLUMNS, DENY_LOG_LAST_ROWS),
+    activityLog: readHookLogSummary(repo, ACTIVITY_LOG_REL, ACTIVITY_LOG_COLUMNS, 0),
+  };
+}
+
+function runHookDoctor(repo, enactHook) {
+  if (!enactHook?.found) {
+    return { available: false, note: "enact-hook not found on PATH; skipping `enact-hook doctor --repo`" };
+  }
+  const res = spawnSync("enact-hook", ["doctor", "--repo", repo], { encoding: "utf8", timeout: 10000 });
+  if (res.error) {
+    return { available: false, note: `could not run enact-hook doctor --repo: ${res.error.message}` };
+  }
+  const combined = `${res.stdout ?? ""}${res.stderr ?? ""}`;
+  if (res.status !== 0 && /unknown or missing hook kind/i.test(combined)) {
+    return { available: false, note: "the installed enact-hook does not support the 'doctor' sub-command yet" };
+  }
+  return { available: true, exitCode: res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+// ---------------------------------------------------------------------------
+// lock integrity — every managed file present + hash match; every merged
+// JSON entry / TOML block present; lists drifted/missing.
+// ---------------------------------------------------------------------------
+function checkLockIntegrity(repo, name, lock) {
+  const missingFiles = [];
+  const driftedFiles = [];
+  for (const [rel, { sha256: want }] of Object.entries(lock.files)) {
+    if (!existsSync(abs(repo, rel))) missingFiles.push(rel);
+    else if (fileSha(repo, rel) !== want) driftedFiles.push(rel);
+  }
+  const jsonIssues = [];
+  for (const [rel, record] of Object.entries(lock.merged)) {
+    const path = abs(repo, rel);
+    if (!existsSync(path)) {
+      jsonIssues.push(`${rel} (file missing)`);
+      continue;
+    }
+    let doc;
+    try {
+      doc = readJsonStrict(path, rel);
+    } catch (err) {
+      jsonIssues.push(`${rel} (${err instanceof Error ? err.message : String(err)})`);
+      continue;
+    }
+    for (const entry of record.entries) {
+      if (!entryPresent(doc, entry)) jsonIssues.push(`${rel} (${entry.path.join(".")})`);
+    }
+  }
+  const tomlIssues = [];
+  for (const [rel, record] of Object.entries(lock.toml)) {
+    const path = abs(repo, rel);
+    const found = existsSync(path) ? findBlock(readFileSync(path, "utf8"), name) : null;
+    if (!found || sha256(found.block) !== record.sha256) tomlIssues.push(rel);
+  }
+  // Managed symlinks (today: the Claude plugin's skills -> ../../.agents/skills
+  // link). These carry no content hash, so `lock.files`-style verification does
+  // not reach them: a broken or retargeted link is invisible to every other
+  // check here. It is not a cosmetic gap -- a dangling link makes Claude Code
+  // report `Skills (0)` while the repo still looks installed, which is exactly
+  // the "presence is not armedness" failure AGENTS.md exists to catch. Verify
+  // by the link's own mechanism: it must BE a symlink, point where the lock
+  // says, and actually resolve.
+  //
+  // lstatSync, never existsSync: existsSync follows the link and returns false
+  // for a dangling one, so it cannot tell "absent" from "present but broken".
+  const symlinkIssues = [];
+  for (const [rel, record] of Object.entries(lock.symlinks ?? {})) {
+    const path = abs(repo, rel);
+    const st = lstatSync(path, { throwIfNoEntry: false });
+    if (!st) {
+      symlinkIssues.push(`${rel} (missing)`);
+      continue;
+    }
+    if (!st.isSymbolicLink()) {
+      symlinkIssues.push(`${rel} (not a symlink)`);
+      continue;
+    }
+    const target = readlinkSync(path);
+    if (target !== record.target) {
+      symlinkIssues.push(`${rel} (target is ${target}, expected ${record.target})`);
+      continue;
+    }
+    if (!existsSync(path)) symlinkIssues.push(`${rel} (dangling -> ${target})`);
+  }
+  const valid =
+    missingFiles.length === 0 &&
+    driftedFiles.length === 0 &&
+    jsonIssues.length === 0 &&
+    tomlIssues.length === 0 &&
+    symlinkIssues.length === 0;
+  return { valid, missingFiles, driftedFiles, jsonIssues, tomlIssues, symlinkIssues };
+}
+
+// ---------------------------------------------------------------------------
+// per-host status
+// ---------------------------------------------------------------------------
+function checkHosts(repo, lock, home, contentOutdated) {
+  const hosts = {};
+  for (const host of REPO_HOSTS) {
+    const targeted = lock.hosts.includes(host);
+    if (host === "claude") {
+      const present =
+        !targeted ||
+        (existsSync(abs(repo, ".claude-plugin/marketplace.json")) && existsSync(abs(repo, ".claude/settings.json")));
+      hosts.claude = {
+        targeted,
+        present,
+        note: targeted
+          ? "loads only after you TRUST this folder in Claude Code -- the marketplace registers on first launch; if hooks/skills are missing in that FIRST session, start a NEW session in this folder"
+          : "not targeted by this install",
+      };
+    } else if (host === "codex") {
+      const present =
+        !targeted || existsSync(abs(repo, ".codex/hooks.json")) || existsSync(abs(repo, ".codex/config.toml"));
+      hosts.codex = {
+        targeted,
+        present,
+        trust: checkCodexTrust(repo, home),
+        note: targeted
+          ? "config/hooks load only after you trust this project; hooks review (/hooks) is pending until you review them in Codex"
+          : "not targeted by this install",
+      };
+    } else if (host === "cursor") {
+      const present =
+        !targeted || existsSync(abs(repo, ".cursor/hooks.json")) || existsSync(abs(repo, ".cursor/mcp.json"));
+      hosts.cursor = {
+        targeted,
+        present,
+        note: targeted
+          ? "Cursor prompts for MCP server approval on first use -- approve code-review-graph/lean-ctx in Cursor's MCP settings"
+          : "not targeted by this install",
+      };
+    } else if (host === "kimi") {
+      const present = !targeted || existsSync(abs(repo, ".kimi-code/mcp.json"));
+      const globalHooks = checkKimiGlobalHooks(home);
+      hosts.kimi = {
+        targeted,
+        present,
+        globalHooksInstalled: globalHooks.hooksBlockPresent,
+        globalHooksNote: !globalHooks.configFound
+          ? `${globalHooks.configPath} not found`
+          : globalHooks.hooksBlockPresent
+            ? "global Kimi hooks block present (owned + installed by enact-vps)"
+            : `global Kimi hooks block ("${KIMI_HOOKS_MARKER}") not found in ${globalHooks.configPath} -- hooks are global-only and enact-vps-owned; this repo install never writes them`,
+        workspaceTrust: checkKimiWorkspaceTrust(repo),
+      };
+    } else if (host === "opencode") {
+      const rel = `.opencode/plugins/${lock.plugin}.ts`;
+      const present = !targeted || existsSync(abs(repo, rel));
+      const generatedFromCurrentBundle = targeted && present ? !contentOutdated.includes(rel) : null;
+      hosts.opencode = {
+        targeted,
+        present,
+        generatedFromCurrentBundle,
+        note: targeted
+          ? "one generated plugin file; re-run install after a bundle update to regenerate it"
+          : "not targeted by this install",
+      };
+    }
+  }
+  return hosts;
+}
+
+// ---------------------------------------------------------------------------
+// managed-repo marker
+// ---------------------------------------------------------------------------
+function checkMarker(repo) {
+  const path = abs(repo, CONFIG_PATH);
+  const base = { path: CONFIG_PATH };
+  if (!existsSync(path)) {
+    return {
+      ...base,
+      present: false,
+      parses: false,
+      extensionsPresent: false,
+      valid: false,
+      note: "missing -- enact-hook only acts in repos containing this file; re-run install",
+    };
+  }
+  let doc;
+  try {
+    doc = TOML.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    return {
+      ...base,
+      present: true,
+      parses: false,
+      extensionsPresent: false,
+      valid: false,
+      note: `cannot parse: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  // `[extensions]` is the marker: its presence is what makes a repo
+  // enact-hook-managed, and its sub-tables are the declared extension set.
+  const extensionsPresent = doc.extensions !== undefined;
+  const declared = extensionsPresent
+    ? Object.entries(doc.extensions)
+        .filter(([, v]) => v && typeof v === "object" && !Array.isArray(v))
+        .map(([k]) => k)
+    : [];
+  return {
+    ...base,
+    present: true,
+    parses: true,
+    extensionsPresent,
+    declared,
+    valid: extensionsPresent,
+    note: extensionsPresent ? undefined : "present but has no [extensions] table -- re-run install",
+  };
+}
+
+// Existence check only: the old marker is never read (HARDCUT, no dual-read).
+function checkStaleMarker(repo) {
+  const present = existsSync(abs(repo, STALE_MARKER_PATH));
+  return {
+    path: STALE_MARKER_PATH,
+    present,
+    note: present
+      ? `stale leftover from the pre-${CONFIG_PATH} installer; nothing reads it -- safe to delete`
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// entrypoint
+// ---------------------------------------------------------------------------
+export function runRepoDoctor(pluginRoot, options = {}) {
+  // Derived from the bundle being doctored, never hardcoded: any plugin is
+  // installable from the CLI, so doctoring `enact-loop` must read
+  // `.agents/enact-loop.lock.json`, not enact-repo's. A hardcoded name here
+  // reported "not installed" for a plugin that was installed perfectly well.
+  const name = readBundle(pluginRoot).name;
+  const repo = resolveRepoRoot(options.repo);
+  const home = options.home ?? homedir();
+  const problems = [];
+
+  const lock = readLock(repo, name);
+  if (!lock) {
+    return {
+      name,
+      repo,
+      installed: false,
+      problems: [
+        `${name} is not installed in ${repo} (no ${lockRel(name)}) -- install with: enact-extensions install ${name} --repo ${repo}`,
+      ],
+      exitCode: 1,
+    };
+  }
+
+  let bundle = null;
+  let bundleError = null;
+  try {
+    bundle = readBundle(pluginRoot);
+  } catch (err) {
+    bundleError = err instanceof Error ? err.message : String(err);
+  }
+
+  let contentOutdated = [];
+  if (bundle) {
+    try {
+      const currentHashes = computeCurrentPlanHashes(pluginRoot, bundle, lock.hosts, repo);
+      for (const [rel, want] of currentHashes) {
+        const have = lock.files[rel]?.sha256;
+        if (have && have !== want) contentOutdated.push(rel);
+      }
+    } catch {
+      // Best-effort enrichment only; lock-integrity below is the hard check.
+      contentOutdated = [];
+    }
+  }
+
+  const version = {
+    installed: lock.version,
+    bundle: bundle ? bundle.version : null,
+    outdated: bundle ? bundle.version !== lock.version : null,
+    contentOutdated,
+    note: bundleError,
+  };
+
+  const lockIntegrity = checkLockIntegrity(repo, name, lock);
+  if (!lockIntegrity.valid) {
+    problems.push(
+      `lock integrity: ${lockIntegrity.missingFiles.length} missing + ${lockIntegrity.driftedFiles.length} drifted managed file(s), ` +
+        `${lockIntegrity.jsonIssues.length} json + ${lockIntegrity.tomlIssues.length} toml + ` +
+        `${lockIntegrity.symlinkIssues.length} symlink issue(s) -- ` +
+        `re-run "install --force" to repair or "uninstall --force" to remove`,
+    );
+  }
+
+  const hosts = checkHosts(repo, lock, home, contentOutdated);
+
+  const binaries = {};
+  for (const bin of REQUIRED_BINARIES) binaries[bin] = checkBinary(bin);
+  binaries.crg = checkCrgBinary();
+  const missingBinaries = Object.entries(binaries)
+    .filter(([, v]) => !v.found)
+    .map(([k, v]) => v.name ?? k);
+  if (missingBinaries.length > 0) {
+    problems.push(`missing required global binaries on PATH: ${missingBinaries.join(", ")}`);
+  }
+
+  const marker = checkMarker(repo);
+  if (!marker.valid) problems.push(`${CONFIG_PATH}: ${marker.note}`);
+  const staleMarker = checkStaleMarker(repo);
+
+  const hookDoctor = runHookDoctor(repo, binaries["enact-hook"]);
+  const hookLogs = checkHookLogs(repo);
+
+  return {
+    name,
+    repo,
+    installed: true,
+    version,
+    lock: lockIntegrity,
+    hosts,
+    binaries,
+    marker,
+    staleMarker,
+    hookDoctor,
+    hookLogs,
+    problems,
+    exitCode: problems.length > 0 ? 1 : 0,
+  };
+}