chainlesschain 0.162.148 → 0.162.150

package/src/lib/plugin-runtime/policy.js

@@ -0,0 +1,152 @@
+/**
+ * Managed org policy for plugin LOADING (Phase 3.3j — fail-closed allow/deny at
+ * discovery time, not just at `cc plugin install`).
+ *
+ * The security primitives already exist in ../plugin-security.js
+ * (`enforcePluginPolicy` for name/source allow-deny, `verifyPluginManifest` for
+ * SHA-256 + Ed25519 signature). But before this, they were consulted only when a
+ * user ran `cc plugin validate`/`install` — a plugin that an org later added to
+ * `deniedPlugins`, or one dropped into a scope dir out-of-band, still loaded its
+ * skills/agents/hooks/MCP/LSP/monitors at runtime.
+ *
+ * This wires the SAME `enforcePluginPolicy` into `discoverPlugins`, the single
+ * chokepoint every component collector funnels through, so an org's
+ * allowedPlugins / deniedPlugins is enforced fail-closed across ALL six
+ * component types in one place. When there is no managed settings file the
+ * policy is null and nothing is filtered (zero impact on the common case).
+ *
+ * NOTE: source allow/deny (blockedPluginSources / allowedPluginSources) stays an
+ * INSTALL-time gate — an installed plugin doesn't carry its origin on disk, so
+ * only the name allow/deny applies at load. Signature enforcement
+ * (requireSignedPlugins) is a separate follow-up: it needs the installer to
+ * persist a verified-signature marker, else every plugin would fail closed.
+ */
+
+import { enforcePluginPolicy } from "../plugin-security.js";
+import { loadManagedSettings } from "../settings-loader.cjs";
+import { verifyInstalledSignature } from "./signature.js";
+
+// Managed settings are org-admin controlled and effectively static for a
+// session, and discoverPlugins is called by every collector — memoize the load
+// (keyed by resolved file path) so we don't re-read the file on every call.
+let _cache = new Map();
+
+export const _deps = { loadManagedSettings };
+
+/**
+ * Load the managed plugin policy (memoized). Returns the managed settings object
+ * or null when there is no managed settings file.
+ * @param {object} [opts] { env, managedSettingsFile }
+ */
+export function loadManagedPluginPolicy(opts = {}) {
+  const env = opts.env || process.env;
+  const key = String(
+    opts.managedSettingsFile || env.CC_MANAGED_SETTINGS || "<default>",
+  );
+  if (_cache.has(key)) {
+    const cached = _cache.get(key);
+    // A cached failure sentinel must re-throw on EVERY call — otherwise the
+    // first call fails closed but later callers get the truthy {__invalid}
+    // object, treat it as an empty policy, and silently bypass the org's
+    // deny/allow/requireSignedPlugins enforcement (fail-open).
+    if (cached && cached.__invalid) throw cached.__invalid;
+    return cached;
+  }
+  let settings = null;
+  try {
+    const loaded = _deps.loadManagedSettings({
+      env: opts.env,
+      managedSettingsFile: opts.managedSettingsFile,
+    });
+    settings = loaded.settings;
+  } catch (err) {
+    // Malformed managed settings → fail closed by propagating: a caller that
+    // wants org enforcement must not silently proceed with no policy.
+    _cache.set(key, { __invalid: err });
+    throw err;
+  }
+  _cache.set(key, settings);
+  return settings;
+}
+
+/** Clear the memoized policy (tests / after a managed-settings change). */
+export function _resetPolicyCache() {
+  _cache = new Map();
+}
+
+/**
+ * Filter a discovered-plugin list by managed name allow/deny. Non-throwing:
+ * a plugin the org denies (or omits from a required allowlist) is DROPPED and
+ * collected in `dropped`, rather than throwing — so one denied plugin never
+ * breaks loading of the rest.
+ *
+ * @param {Array<{name}>} plugins
+ * @param {object|null} managed  managed settings (null = no policy → keep all)
+ * @returns {{ kept: Array, dropped: Array<{name, reason}> }}
+ */
+export function filterByManagedPolicy(plugins, managed) {
+  if (!managed) return { kept: plugins, dropped: [] };
+  // requireSignedPlugins (fail-closed): every plugin must carry a valid recorded
+  // signature whose locked manifest hash still matches on disk. Optionally the
+  // signing key must be among managed.trustedPluginKeySha256.
+  const requireSigned =
+    managed.requireSignedPlugins === true ||
+    managed.requireSignedPlugins === "require";
+  const trustedKeys = requireSigned
+    ? new Set(
+        (Array.isArray(managed.trustedPluginKeySha256)
+          ? managed.trustedPluginKeySha256
+          : []
+        )
+          .map((k) => String(k || "").trim())
+          .filter(Boolean),
+      )
+    : null;
+  const kept = [];
+  const dropped = [];
+  for (const p of plugins) {
+    try {
+      enforcePluginPolicy(
+        { name: p.name, source: null, action: "load" },
+        managed,
+      );
+    } catch (err) {
+      dropped.push({ name: p.name, reason: err.message });
+      continue;
+    }
+    if (requireSigned) {
+      const v = verifyInstalledSignature(p, { trustedKeys });
+      if (!v.signed) {
+        dropped.push({
+          name: p.name,
+          reason: `requireSignedPlugins: ${v.reason}`,
+        });
+        continue;
+      }
+    }
+    kept.push(p);
+  }
+  return { kept, dropped };
+}
+
+let _warnedDropped = new Set();
+
+/** One-time stderr warning naming plugins an org policy blocked from loading. */
+export function warnDroppedOnce(dropped) {
+  const fresh = dropped.filter((d) => !_warnedDropped.has(d.name));
+  if (fresh.length === 0) return;
+  for (const d of fresh) _warnedDropped.add(d.name);
+  try {
+    process.stderr.write(
+      `[plugins] blocked by managed policy: ${fresh
+        .map((d) => `${d.name} (${d.reason})`)
+        .join(", ")}\n`,
+    );
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function _resetPolicyWarnings() {
+  _warnedDropped = new Set();
+}

package/src/lib/plugin-runtime/reload.js

@@ -0,0 +1,79 @@
+/**
+ * Hot-reload the plugin runtime (Phase 3.3m — `/reload-plugins`).
+ *
+ * Installing / trusting / upgrading a plugin mid-session normally needs a
+ * restart because several collectors memoize their work (LSP registration is
+ * registered once per root; the managed-policy load + trust/untrusted warnings
+ * are cached). This resets that memoized state and re-runs the declarative
+ * collectors so a freshly-installed/trusted plugin's components appear without
+ * restarting.
+ *
+ * Returns a summary of what is now discovered (per-component counts) so the REPL
+ * can report it. The caller (agent-repl) additionally re-merges hooks and
+ * restarts the monitor supervisor with the fresh set — those hold live session
+ * state (the effective hook map, running child processes) the pure collectors
+ * can't touch. Already-connected MCP servers stay connected for this session
+ * (reconnecting mid-turn is out of scope); newly-added MCP servers are picked up
+ * on the next session.
+ */
+
+import { discoverPlugins } from "./scopes.js";
+import { ensurePluginLspServers, _resetPluginLspLoadState } from "./lsp.js";
+import { _resetPluginServers } from "../lsp/lsp-server-registry.js";
+import { _resetPolicyCache, _resetPolicyWarnings } from "./policy.js";
+import { _resetTrustWarnings } from "./trust.js";
+import { discoverPluginSkillLayers } from "./skills.js";
+import { discoverPluginAgentLayers } from "./agents.js";
+import { collectPluginHooks } from "./hooks.js";
+import { collectPluginMcpServers } from "./mcp.js";
+import { collectPluginMonitors } from "./monitors.js";
+
+/**
+ * Reset memoized plugin-runtime state and re-scan. Pure w.r.t. session state —
+ * the REPL layer applies the hooks/monitors side of the reload.
+ *
+ * @param {object} [opts] { cwd, scopes }
+ * @returns {{ plugins, lspRegistered, skills, agents, hooks, mcp, monitors }}
+ */
+export function reloadPluginRuntime(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const scopes = opts.scopes;
+
+  // 1) Clear caches so the next discovery re-reads managed policy + re-evaluates
+  //    trust, and LSP servers can be cleanly re-registered.
+  _resetPolicyCache();
+  _resetPolicyWarnings();
+  _resetTrustWarnings();
+  _resetPluginServers();
+  _resetPluginLspLoadState();
+
+  // 2) Re-register plugin LSP servers from scratch (force past the per-root memo).
+  let lspRegistered = 0;
+  try {
+    const res = ensurePluginLspServers({ cwd, scopes, force: true });
+    lspRegistered = res?.registered?.length || 0;
+  } catch {
+    lspRegistered = 0;
+  }
+
+  // 3) Re-scan the declarative collectors for a fresh summary.
+  const count = (fn, pick) => {
+    try {
+      const r = fn({ cwd, scopes });
+      return pick(r);
+    } catch {
+      return 0;
+    }
+  };
+  const plugins = count(discoverPlugins, (r) => r.length);
+  const skills = count(discoverPluginSkillLayers, (r) => r.length);
+  const agents = count(discoverPluginAgentLayers, (r) => r.length);
+  const hooks = count(collectPluginHooks, (r) => Object.keys(r).length);
+  const mcp = count(
+    collectPluginMcpServers,
+    (r) => Object.keys(r.servers).length,
+  );
+  const monitors = count(collectPluginMonitors, (r) => r.length);
+
+  return { plugins, lspRegistered, skills, agents, hooks, mcp, monitors };
+}

package/src/lib/plugin-runtime/remote-source.js

@@ -0,0 +1,240 @@
+/**
+ * Remote plugin sources — install from a hosted registry / manifest URL, not
+ * just a local dir or git URL (Phase 3 "远程 manifest" + "私有仓认证" + "离线
+ * seed cache" work items).
+ *
+ * A remote source is an `https?://…/*.json` document, in one of two shapes:
+ *
+ *   1. Registry index — many plugins, selected by name:
+ *      { "name": "acme-registry",
+ *        "plugins": [
+ *          { "name": "toml-tools", "source": "https://github.com/x/toml.git",
+ *            "ref": "v1.0.0", "version": "1.0.0", "description": "…", "sha256": "…" },
+ *          { "name": "py-helpers", "source": "owner/py-helpers" }
+ *        ] }
+ *
+ *   2. Single-plugin manifest — one plugin, no selection needed:
+ *      { "name": "toml-tools", "source": "https://github.com/x/toml.git", "ref": "v1.0.0" }
+ *
+ * The remote layer is an INDIRECTION: it resolves a name → a git source string
+ * that the existing installer (`installFromSource`) already knows how to clone.
+ * This keeps the sync install core untouched and avoids bundling a tarball
+ * extractor. Downloaded registry JSON is cached content-addressed so browsing /
+ * installing works OFFLINE, and a bearer token can gate a PRIVATE registry.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { getElectronUserDataDir } from "../paths.js";
+
+export const _deps = {
+  // Node 22+ global fetch; injectable for tests.
+  fetch: (...args) => globalThis.fetch(...args),
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  existsSync: fs.existsSync,
+  mkdirSync: fs.mkdirSync,
+};
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** True when `raw` looks like a remote registry/manifest URL (http(s) + .json). */
+export function isRemoteSource(raw) {
+  const s = String(raw || "").trim();
+  return /^https?:\/\//i.test(s) && /\.json(\?.*)?(#.*)?$/i.test(s);
+}
+
+/** Where a fetched registry is cached (content-addressed by its URL). */
+export function registryCachePath(url, cacheDir) {
+  const dir =
+    cacheDir || path.join(getElectronUserDataDir(), "plugin-registry-cache");
+  const hash = crypto
+    .createHash("sha256")
+    .update(String(url))
+    .digest("hex")
+    .slice(0, 32);
+  return path.join(dir, `${hash}.json`);
+}
+
+/**
+ * Resolve the bearer token for a registry host from (in order): explicit
+ * `opts.token`, `CC_PLUGIN_REGISTRY_TOKEN` env, or a per-host map in config
+ * (`config.plugins.registryTokens[host]`). Returns null if none — a public
+ * registry needs no token.
+ */
+export function resolveRegistryToken(url, { token, config } = {}) {
+  if (token) return token;
+  if (process.env.CC_PLUGIN_REGISTRY_TOKEN)
+    return process.env.CC_PLUGIN_REGISTRY_TOKEN;
+  try {
+    const host = new URL(url).host;
+    const map = config?.plugins?.registryTokens;
+    if (map && map[host]) return map[host];
+  } catch {
+    /* bad URL — handled by fetch */
+  }
+  return null;
+}
+
+/**
+ * GET a registry/manifest URL as JSON, with optional bearer auth. On success the
+ * body is written to the offline cache; on a network/HTTP failure we fall back
+ * to that cache (so a previously-seen registry still installs offline). Throws
+ * only when neither the network NOR the cache can produce a valid document.
+ *
+ * @returns {Promise<{ registry: object, fromCache: boolean }>}
+ */
+export async function fetchRegistry(url, opts = {}) {
+  const {
+    token,
+    cacheDir,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    allowCache = true,
+  } = opts;
+  const cachePath = registryCachePath(url, cacheDir);
+  const headers = { Accept: "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  let networkErr = null;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await _deps.fetch(url, {
+        headers,
+        redirect: "follow",
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      throw new Error(
+        `registry fetch failed: HTTP ${res.status} ${res.statusText || ""}`.trim(),
+      );
+    }
+    const text = await res.text();
+    const registry = validateRegistry(JSON.parse(text), url);
+    if (allowCache) writeCache(cachePath, text);
+    return { registry, fromCache: false };
+  } catch (err) {
+    networkErr = err;
+  }
+
+  // Network failed — try the offline cache.
+  if (allowCache && _deps.existsSync(cachePath)) {
+    try {
+      const text = _deps.readFileSync(cachePath, "utf8");
+      const registry = validateRegistry(JSON.parse(text), url);
+      return { registry, fromCache: true };
+    } catch {
+      /* cache unreadable — fall through to throw the network error */
+    }
+  }
+  throw new Error(
+    `could not fetch registry ${url}: ${networkErr ? networkErr.message : "unknown error"}` +
+      (allowCache ? " (no offline cache available)" : ""),
+  );
+}
+
+function writeCache(cachePath, text) {
+  try {
+    _deps.mkdirSync(path.dirname(cachePath), { recursive: true });
+    _deps.writeFileSync(cachePath, text, "utf8");
+  } catch {
+    /* caching is best-effort; a read-only cache dir must not break install */
+  }
+}
+
+/** Validate + normalize a fetched document into a registry object. Throws on garbage. */
+export function validateRegistry(doc, url = "") {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    throw new Error(`registry at ${url} is not a JSON object`);
+  }
+  if (Array.isArray(doc.plugins)) {
+    for (const p of doc.plugins) {
+      if (!p || typeof p !== "object" || !p.name || !p.source) {
+        throw new Error(
+          `registry at ${url} has a plugin entry missing name/source`,
+        );
+      }
+    }
+    return doc;
+  }
+  // Single-plugin manifest.
+  if (doc.source) {
+    return { plugins: [doc] };
+  }
+  throw new Error(
+    `registry at ${url} must have a "plugins" array or a top-level "source"`,
+  );
+}
+
+/** List installable entries from a registry (for `cc plugin search`). */
+export function listRegistryPlugins(registry) {
+  return (registry.plugins || []).map((p) => ({
+    name: p.name,
+    version: p.version || null,
+    source: p.source,
+    ref: p.ref || null,
+    description: p.description || "",
+  }));
+}
+
+/**
+ * Pick one plugin entry from a registry. When the registry has exactly one
+ * plugin, `name` is optional; otherwise it must match. Returns the entry, or
+ * throws with a helpful list.
+ */
+export function resolvePluginEntry(registry, name) {
+  const plugins = registry.plugins || [];
+  if (plugins.length === 0) throw new Error("registry has no plugins");
+  if (!name) {
+    if (plugins.length === 1) return plugins[0];
+    throw new Error(
+      `registry has ${plugins.length} plugins — pick one with --name <plugin>:\n  ` +
+        plugins.map((p) => p.name).join(", "),
+    );
+  }
+  const entry = plugins.find((p) => p.name === name);
+  if (!entry) {
+    throw new Error(
+      `plugin "${name}" not found in registry. Available:\n  ` +
+        plugins.map((p) => p.name).join(", "),
+    );
+  }
+  return entry;
+}
+
+/**
+ * Full resolution: fetch the registry (with auth + offline cache), select the
+ * entry, and return the git source string the existing installer consumes plus
+ * carry-through metadata (ref pins the checkout; sha256 becomes an install
+ * integrity check).
+ *
+ * @returns {Promise<{ source: string, ref: string|null, sha256: string|null,
+ *   entry: object, fromCache: boolean }>}
+ */
+export async function resolveRemoteSource(url, opts = {}) {
+  const token = resolveRegistryToken(url, opts);
+  const { registry, fromCache } = await fetchRegistry(url, { ...opts, token });
+  const entry = resolvePluginEntry(registry, opts.name);
+  // Carry a `#ref` on the source string so installFromSource pins the checkout,
+  // matching its existing `owner/repo#ref` / `url#ref` convention.
+  const source = entry.ref ? `${entry.source}#${entry.ref}` : entry.source;
+  return {
+    source,
+    ref: entry.ref || null,
+    sha256: entry.sha256 || null,
+    entry,
+    fromCache,
+  };
+}
+
+/** Best-effort local temp dir helper (kept here so tests can stub fs deps). */
+export function _tmpRoot() {
+  return os.tmpdir();
+}

package/src/lib/plugin-runtime/scopes.js

@@ -0,0 +1,197 @@
+/**
+ * Plugin install scopes + on-disk discovery (Phase 3).
+ *
+ * A plugin can be installed at three scopes, mirroring the skill-loader layering:
+ *
+ *   user     — <userData>/plugins/            global to the machine/user
+ *   project  — <root>/.chainlesschain/plugins/       committed, shared via the repo
+ *   local    — <root>/.chainlesschain/plugins.local/ gitignored, per-developer
+ *
+ * Precedence on a name collision: local > project > user (the most specific
+ * wins, same spirit as the skill layers).
+ *
+ * Each plugin lives in an IMMUTABLE version directory:
+ *
+ *   <scopeRoot>/<encodedName>/<version>/   (+ the plugin body)
+ *
+ * so an in-flight session keeps running its version even while another is
+ * installed. The active version per (scope,name) is the one named by a
+ * `.active` file, or the highest semver present if none is set.
+ */
+
+import fs from "fs";
+import path from "path";
+import semver from "semver";
+import { getElectronUserDataDir } from "../paths.js";
+import { parsePluginManifest } from "./manifest.js";
+import {
+  loadManagedPluginPolicy,
+  filterByManagedPolicy,
+  warnDroppedOnce,
+} from "./policy.js";
+
+export const _deps = {
+  existsSync: fs.existsSync,
+  readdirSync: fs.readdirSync,
+  readFileSync: fs.readFileSync,
+  statSync: fs.statSync,
+};
+
+// Lowest → highest precedence.
+export const SCOPES = ["user", "project", "local"];
+
+/** Filesystem-safe encoding of a (possibly scoped, e.g. @org/name) plugin name. */
+export function encodeName(name) {
+  return String(name || "").replace(/[^a-zA-Z0-9._-]/g, "__");
+}
+
+/**
+ * Resolve the root directory for a scope.
+ * @param {"user"|"project"|"local"} scope
+ * @param {object} [opts] { cwd }
+ */
+export function scopeRoot(scope, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  switch (scope) {
+    case "user":
+      return path.join(getElectronUserDataDir(), "plugins");
+    case "project":
+      return path.join(cwd, ".chainlesschain", "plugins");
+    case "local":
+      return path.join(cwd, ".chainlesschain", "plugins.local");
+    default:
+      throw new Error(`unknown plugin scope: ${scope}`);
+  }
+}
+
+/** Directory that holds all versions of one plugin at a scope. */
+export function pluginNameDir(scope, name, opts = {}) {
+  return path.join(scopeRoot(scope, opts), encodeName(name));
+}
+
+/** Immutable install dir for a specific plugin version. */
+export function pluginVersionDir(scope, name, version, opts = {}) {
+  return path.join(pluginNameDir(scope, name, opts), String(version));
+}
+
+/** Versions present on disk for a plugin, newest semver first. */
+export function listInstalledVersions(scope, name, opts = {}) {
+  const dir = pluginNameDir(scope, name, opts);
+  if (!dirExists(dir)) return [];
+  return _deps
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((v) => semver.valid(v))
+    .sort(semver.rcompare);
+}
+
+/** The active version for a plugin: `.active` file if valid, else highest semver. */
+export function activeVersion(scope, name, opts = {}) {
+  const versions = listInstalledVersions(scope, name, opts);
+  if (versions.length === 0) return null;
+  const activeFile = path.join(pluginNameDir(scope, name, opts), ".active");
+  if (_deps.existsSync(activeFile)) {
+    try {
+      const pinned = _deps.readFileSync(activeFile, "utf8").trim();
+      if (versions.includes(pinned)) return pinned;
+    } catch {
+      /* fall through to highest */
+    }
+  }
+  return versions[0];
+}
+
+/**
+ * Discover every installed plugin's ACTIVE version across all scopes, applying
+ * scope precedence (local > project > user) so a name installed at multiple
+ * scopes resolves to one parsed manifest.
+ *
+ * Managed org policy (allowedPlugins / deniedPlugins) is enforced fail-closed
+ * here — the single chokepoint every component collector funnels through — so a
+ * denied plugin loads NONE of its six component types. Pass `skipPolicy:true`
+ * for tooling that must see even blocked plugins (e.g. `cc plugin installed`
+ * showing why something is blocked). No managed settings file → no filtering.
+ *
+ * @param {object} [opts] { cwd, scopes?, skipPolicy?, env?, managedSettingsFile? }
+ * @returns {Array<{scope, name, version, root, manifest}>}
+ */
+export function discoverPlugins(opts = {}) {
+  const scopes = opts.scopes || SCOPES;
+  const byName = new Map(); // name → record (later scope overrides earlier)
+  for (const scope of scopes) {
+    const root = scopeRoot(scope, opts);
+    if (!dirExists(root)) continue;
+    for (const encoded of listDirs(root)) {
+      const nameDir = path.join(root, encoded);
+      const version = activeVersionForDir(nameDir);
+      if (!version) continue;
+      const versionDir = path.join(nameDir, version);
+      const manifest = parsePluginManifest(versionDir);
+      manifest.scope = scope;
+      const name = manifest.metadata?.name || encoded;
+      byName.set(name, {
+        scope,
+        name,
+        version: manifest.metadata?.version || version,
+        root: versionDir,
+        manifest,
+      });
+    }
+  }
+  const all = [...byName.values()];
+  if (opts.skipPolicy) return all;
+  // Enforce managed org allow/deny at load time (fail-closed). A malformed
+  // managed settings file throws out of loadManagedPluginPolicy — that
+  // propagates so a broken org policy never silently degrades to "no policy".
+  const managed = loadManagedPluginPolicy({
+    env: opts.env,
+    managedSettingsFile: opts.managedSettingsFile,
+  });
+  if (!managed) return all;
+  const { kept, dropped } = filterByManagedPolicy(all, managed);
+  if (dropped.length > 0) warnDroppedOnce(dropped);
+  return kept;
+}
+
+// ── internals ────────────────────────────────────────────────────────────
+
+function activeVersionForDir(nameDir) {
+  if (!dirExists(nameDir)) return null;
+  const versions = _deps
+    .readdirSync(nameDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((v) => semver.valid(v))
+    .sort(semver.rcompare);
+  if (versions.length === 0) return null;
+  const activeFile = path.join(nameDir, ".active");
+  if (_deps.existsSync(activeFile)) {
+    try {
+      const pinned = _deps.readFileSync(activeFile, "utf8").trim();
+      if (versions.includes(pinned)) return pinned;
+    } catch {
+      /* fall through */
+    }
+  }
+  return versions[0];
+}
+
+function dirExists(dir) {
+  try {
+    return _deps.existsSync(dir) && _deps.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function listDirs(dir) {
+  try {
+    return _deps
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}