@teambit/isolator 1.0.1002 → 1.0.1003

package/dist/capsule-cache.js

@@ -0,0 +1,733 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CapsuleCache = exports.CAPSULE_TRASH_DIR = exports.CAPSULE_ORIGIN_FILE = void 0;
+function _fsExtra() {
+  const data = _interopRequireDefault(require("fs-extra"));
+  _fsExtra = function () {
+    return data;
+  };
+  return data;
+}
+function _uuid() {
+  const data = require("uuid");
+  _uuid = function () {
+    return data;
+  };
+  return data;
+}
+function _path() {
+  const data = _interopRequireDefault(require("path"));
+  _path = function () {
+    return data;
+  };
+  return data;
+}
+function _child_process() {
+  const data = require("child_process");
+  _child_process = function () {
+    return data;
+  };
+  return data;
+}
+function _pMap() {
+  const data = _interopRequireDefault(require("p-map"));
+  _pMap = function () {
+    return data;
+  };
+  return data;
+}
+function _harmonyModules() {
+  const data = require("@teambit/harmony.modules.concurrency");
+  _harmonyModules = function () {
+    return data;
+  };
+  return data;
+}
+function _harmonyModules2() {
+  const data = require("@teambit/harmony.modules.feature-toggle");
+  _harmonyModules2 = function () {
+    return data;
+  };
+  return data;
+}
+function _legacy() {
+  const data = require("@teambit/legacy.constants");
+  _legacy = function () {
+    return data;
+  };
+  return data;
+}
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Manages the global capsules cache: origin markers, fast-delete + trash sweep, and the
+ * prune pipeline (manual `bit capsule prune` and the gated auto-prune trigger).
+ *
+ * Owned by `IsolatorMain` but operationally independent — the isolator constructs an
+ * instance, registers its hooks, and delegates the externally-visible cache-management
+ * methods (`deleteCapsules`, `pruneCapsules`, `listAllCapsuleRoots`) to it. Keeps
+ * `isolator.main.runtime.ts` focused on creating isolated component environments rather
+ * than also being responsible for evicting them.
+ */
+
+/**
+ * Marker file written into every capsule dir we manage. Its presence tells the prune logic
+ * what kind of dir this is, where it came from, and (via its mtime) when it was last used.
+ */
+const CAPSULE_ORIGIN_FILE = exports.CAPSULE_ORIGIN_FILE = '.bit-capsule-origin.json';
+const CAPSULE_TRASH_DIR = exports.CAPSULE_TRASH_DIR = '.trash';
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const VALID_CAPSULE_KINDS = new Set(['workspace', 'scope-aspects-root', 'scope-aspect', 'scope']);
+function toFiniteNumber(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+class CapsuleCache {
+  constructor(logger, cli, configStore, /** Thunk so the cache stays independent of `GlobalConfigMain` — IsolatorMain forwards it. */
+  getRootDir) {
+    this.logger = logger;
+    this.cli = cli;
+    this.configStore = configStore;
+    this.getRootDir = getRootDir;
+  }
+  async deleteCapsules(rootDir) {
+    const dirToDelete = rootDir || this.getRootDir();
+    const marker = await this.readOriginMarker(dirToDelete);
+    this.logger.debug(`[capsule-delete] removing ${dirToDelete}` + (marker?.originPath ? ` origin=${marker.originPath}` : ''));
+    await this.scheduleFastDelete(dirToDelete);
+    return dirToDelete;
+  }
+
+  /**
+   * Move a capsule dir into a sibling `.trash/<uuid>/` so it disappears from the cache
+   * immediately (same-filesystem rename is O(1)), then kick off a detached `rm -rf` so the
+   * actual byte-by-byte cleanup happens in the background. This avoids the multi-second
+   * stalls users see when deleting capsules with thousands of files.
+   */
+  async scheduleFastDelete(dir) {
+    const exists = await _fsExtra().default.pathExists(dir);
+    if (!exists) return;
+    const globalRoot = this.getRootDir();
+    // Edge case: deleting the global root itself. We can't move a dir into its own
+    // child (`.trash/...`), so just do a direct remove. This is rare — only `bit
+    // capsule delete --all` hits it.
+    if (_path().default.resolve(dir) === _path().default.resolve(globalRoot)) {
+      await _fsExtra().default.remove(dir);
+      return;
+    }
+    const trashRoot = _path().default.join(globalRoot, CAPSULE_TRASH_DIR);
+    await _fsExtra().default.ensureDir(trashRoot);
+    const trashTarget = _path().default.join(trashRoot, `${_path().default.basename(dir)}-${(0, _uuid().v4)()}`);
+    try {
+      await _fsExtra().default.move(dir, trashTarget, {
+        overwrite: true
+      });
+    } catch (err) {
+      // Likely cross-device — fall back to a synchronous remove.
+      this.logger.debug(`scheduleFastDelete: rename failed for ${dir}, falling back to fs.remove (${err.message})`);
+      await _fsExtra().default.remove(dir);
+      return;
+    }
+    // Run through the gated sweepTrashAsync path so we never have more than one sweep
+    // running concurrently — even if many bit processes are moving things to trash.
+    this.sweepTrashAsync();
+  }
+
+  /**
+   * Sweep the `.trash` dir in a detached background process. Gated by a PID-stamped
+   * lock so we never have more than one sweep running at a time across all concurrent
+   * bit processes — previously we spawned one per `bit` invocation and they piled up
+   * into the thousands, saturating disk I/O.
+   */
+  sweepTrashAsync() {
+    const trashRoot = _path().default.join(this.getRootDir(), CAPSULE_TRASH_DIR);
+    // No trash → nothing to do. Cheap synchronous check avoids spawning a process at all.
+    if (!_fsExtra().default.existsSync(trashRoot)) return;
+    const lockPath = _path().default.join(this.getRootDir(), '.trash-sweep.lock');
+    if (this.isSweepLockActive(lockPath)) {
+      this.logger.debug(`trash sweep already running (per ${lockPath}), skipping`);
+      return;
+    }
+    try {
+      _fsExtra().default.writeFileSync(lockPath, String(process.pid), {
+        flag: 'w'
+      });
+    } catch (err) {
+      this.logger.debug(`failed to write sweep lock at ${lockPath}: ${err.message}`);
+      return;
+    }
+    this.spawnDetachedSweep(trashRoot, lockPath);
+  }
+
+  /**
+   * A sweep lock is "active" if the PID it names is still running. If the PID file
+   * exists but the process is gone (e.g. crashed mid-sweep), we treat it as stale and
+   * allow a new sweep to claim it.
+   */
+  isSweepLockActive(lockPath) {
+    let pidStr;
+    try {
+      pidStr = _fsExtra().default.readFileSync(lockPath, 'utf8').trim();
+    } catch {
+      return false;
+    }
+    const pid = Number(pidStr);
+    if (!Number.isFinite(pid) || pid <= 0) return false;
+    try {
+      // Signal 0 = "is this PID alive?" — no actual signal sent.
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Register a process-exit hook that, at most once per ~24h, spawns a detached
+   * `bit capsule prune` child so the actual work runs out-of-process and never delays
+   * the parent's exit. Gated by the mtime of a stamp file under the capsules root so
+   * concurrent Bit invocations can't all trigger it at once, and behind the
+   * `capsule-auto-prune` feature flag while the behavior is being validated.
+   */
+  registerAutoPruneHook() {
+    this.cli.registerOnBeforeExit(async () => {
+      try {
+        await this.maybeAutoPrune();
+      } catch (err) {
+        this.logger.debug(`auto-prune skipped due to error: ${err?.message ?? err}`);
+      }
+    });
+  }
+  async maybeAutoPrune() {
+    // Experimental: the automatic prune only runs for users who opt in via the feature flag
+    // (`BIT_FEATURES=capsule-auto-prune` or `bit config set features=capsule-auto-prune`).
+    // Until it's promoted to GA, the default behavior is unchanged — capsules are never
+    // auto-deleted. The manual `bit capsule prune` command is always available regardless.
+    if (!(0, _harmonyModules2().isFeatureEnabled)(_harmonyModules2().CAPSULE_AUTO_PRUNE)) return;
+
+    // configStore may surface this as either string `'false'` (from `bit config set`)
+    // or boolean `false` (from a hand-edited JSON config) — accept both. This is a
+    // secondary escape hatch for once the feature is GA and the flag is removed.
+    const enabled = this.configStore.getConfig(_legacy().CFG_CAPSULES_AUTO_PRUNE);
+    if (enabled === 'false' || enabled === false) return;
+    const root = this.getRootDir();
+    if (!(await _fsExtra().default.pathExists(root))) return;
+    const stampPath = _path().default.join(root, '.last-capsule-prune');
+    const isStampFresh = async () => {
+      try {
+        const stat = await _fsExtra().default.stat(stampPath);
+        return Date.now() - stat.mtime.getTime() < ONE_DAY_MS;
+      } catch {
+        return false; // missing — needs a prune
+      }
+    };
+    // Fast path: stamp is recent, nothing to do (no contention here).
+    if (await isStampFresh()) return;
+
+    // Atomic claim: only one process across all concurrent bit invocations may win the
+    // daily slot. `wx` is O_CREAT|O_EXCL — it throws if the lock already exists, so the
+    // check-and-write below can't race. The lock is held only for the few ms it takes to
+    // re-check the stamp and spawn the detached child, then removed in `finally`.
+    const claimPath = `${stampPath}.claim`;
+    let claimed = false;
+    try {
+      await _fsExtra().default.close(await _fsExtra().default.open(claimPath, 'wx'));
+      claimed = true;
+    } catch {
+      // Another process is mid-claim, or a previous run leaked the lock. If it's stale
+      // (older than the daily window), reclaim it by removing + re-opening with O_EXCL —
+      // if two processes race the reclaim, only one's `wx` open succeeds and the other
+      // yields. Otherwise yield.
+      try {
+        const claimStat = await _fsExtra().default.stat(claimPath);
+        if (Date.now() - claimStat.mtime.getTime() < ONE_DAY_MS) return;
+        await _fsExtra().default.remove(claimPath);
+        await _fsExtra().default.close(await _fsExtra().default.open(claimPath, 'wx'));
+        claimed = true;
+      } catch {
+        return;
+      }
+    }
+    try {
+      // Re-check under the lock: a process that just held it may have refreshed the stamp.
+      if (await isStampFresh()) return;
+      await _fsExtra().default.outputFile(stampPath, '');
+
+      // Guard against non-numeric/empty config (NaN) and negative values (which would
+      // invert the age cutoff / size target and wipe the whole cache).
+      const olderThanDays = Math.max(0, toFiniteNumber(this.configStore.getConfig(_legacy().CFG_CAPSULES_MAX_AGE_DAYS)) ?? 30);
+      const sizeTargetGb = Math.max(0, toFiniteNumber(this.configStore.getConfig(_legacy().CFG_CAPSULES_MAX_SIZE_GB)) ?? 10);
+      this.logger.debug(`[auto-prune] spawning detached child. olderThanDays=${olderThanDays}, sizeTargetGb=${sizeTargetGb}`);
+      this.spawnDetachedAutoPrune(olderThanDays, sizeTargetGb);
+    } finally {
+      if (claimed) {
+        try {
+          await _fsExtra().default.remove(claimPath);
+        } catch {
+          // ignore — a stale claim lock is reclaimed by the age check above
+        }
+      }
+    }
+  }
+
+  /**
+   * Fire-and-forget: spawn a detached child running `bit capsule prune`. Using the same
+   * bit binary that's currently running (via process.argv[0] + argv[1]) so we don't depend
+   * on PATH. stdio is ignored so nothing leaks to the user's terminal.
+   *
+   * Recursion guard: the child also runs onBeforeExit → maybeAutoPrune, but it reads the
+   * stamp file that we just wrote and bails out before re-spawning.
+   */
+  spawnDetachedAutoPrune(olderThanDays, sizeTargetGb) {
+    const bitEntry = process.argv[1];
+    if (!bitEntry) {
+      this.logger.debug('[auto-prune] cannot detach: process.argv[1] is empty');
+      return;
+    }
+    try {
+      const child = (0, _child_process().spawn)(process.execPath, [bitEntry, 'capsule', 'prune', '--older-than', String(olderThanDays), '--size-target', String(sizeTargetGb)], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true
+      });
+      child.unref();
+    } catch (err) {
+      this.logger.debug(`[auto-prune] failed to spawn detached child: ${err.message}`);
+    }
+  }
+
+  /**
+   * Spawn one detached Node process that recursively removes `trashRoot`. Using
+   * `process.execPath` with an inline `fs.rmSync` keeps this portable across macOS,
+   * Linux, and Windows (where there's no `rm` binary). When `lockPath` is given, the
+   * child clears the lock on exit so the next bit invocation can claim a fresh sweep slot.
+   */
+  spawnDetachedSweep(trashRoot, lockPath) {
+    const script = lockPath ? `try { require('fs').rmSync(${JSON.stringify(trashRoot)}, { recursive: true, force: true }); } finally { try { require('fs').rmSync(${JSON.stringify(lockPath)}, { force: true }); } catch (_) {} }` : `require('fs').rmSync(${JSON.stringify(trashRoot)}, { recursive: true, force: true })`;
+    try {
+      const child = (0, _child_process().spawn)(process.execPath, ['-e', script], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true
+      });
+      child.unref();
+    } catch (err) {
+      this.logger.debug(`failed to spawn detached trash sweep: ${err.message}`);
+      // Don't leak the lock if the spawn itself failed. Use fs-extra's removeSync
+      // (rmSync isn't in the @types/fs-extra version pinned by this component).
+      if (lockPath) {
+        try {
+          _fsExtra().default.removeSync(lockPath);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  /**
+   * Write the origin marker if missing; otherwise just bump its mtime so it reflects
+   * "last used at". Failures are non-fatal — markers are best-effort metadata.
+   */
+  async ensureOriginMarker(dir, kind, originPath) {
+    const markerPath = _path().default.join(dir, CAPSULE_ORIGIN_FILE);
+    try {
+      if (await _fsExtra().default.pathExists(markerPath)) {
+        const now = new Date();
+        await _fsExtra().default.utimes(markerPath, now, now);
+        return;
+      }
+      const marker = {
+        originPath,
+        createdAt: new Date().toISOString(),
+        kind
+      };
+      await _fsExtra().default.outputJson(markerPath, marker);
+    } catch (err) {
+      this.logger.debug(`failed to write capsule origin marker at ${markerPath}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Mark all per-component capsule subdirs as scope-aspect kind, originated from the
+   * scope-aspects root. Used right after a scope-aspects isolation.
+   */
+  async ensureAspectCapsuleMarkers(capsuleList, rootOriginPath) {
+    await Promise.all(capsuleList.map(async capsule => {
+      if (!_fsExtra().default.existsSync(capsule.path)) return;
+      await this.ensureOriginMarker(capsule.path, 'scope-aspect', rootOriginPath);
+    }));
+  }
+
+  /**
+   * Single source of truth for the dated-capsules date-dir name (`YYYY-M-D`, no zero-pad).
+   * Used by `getCapsulesRootDir` when writing and `pruneDatedCapsulesChildren` when reading,
+   * so the two can never drift.
+   */
+  getDatedCapsuleDirName(date = new Date()) {
+    return `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`;
+  }
+
+  /**
+   * Standard filter for "real" capsule subdirs we may walk or prune. Skips files, the trash
+   * dir (dot-prefixed), `node_modules`, and any other hidden/internal dir.
+   */
+  isPrunableSubdir(entry) {
+    return entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.');
+  }
+
+  /**
+   * Combined marker read + last-used resolution for a capsule dir: one `readJson`, one
+   * fallback `stat`. Replaces the three-syscall (`readMarker` + `getOriginMarkerMtime` +
+   * dir `stat`) idiom that was copy-pasted across the prune walks.
+   */
+  async readMarkerInfo(dir) {
+    const marker = await this.readOriginMarker(dir);
+    if (marker) {
+      const mtime = await this.getOriginMarkerMtime(dir);
+      if (mtime) return {
+        marker,
+        lastUsedMs: mtime.getTime()
+      };
+    }
+    const stat = await _fsExtra().default.stat(dir).catch(() => undefined);
+    return {
+      marker,
+      lastUsedMs: (stat?.mtime ?? new Date(0)).getTime()
+    };
+  }
+  async readOriginMarker(dir) {
+    try {
+      const raw = await _fsExtra().default.readJson(_path().default.join(dir, CAPSULE_ORIGIN_FILE));
+      if (raw && typeof raw.originPath === 'string' &&
+      // Reject unknown kinds (corrupted markers or values from a future Bit) so they
+      // fall through to the 'unmarked' path in pruneCapsules rather than silently
+      // skipping deletion.
+      VALID_CAPSULE_KINDS.has(raw.kind)) {
+        return raw;
+      }
+    } catch {
+      // missing or malformed — treat as unmarked
+    }
+    return undefined;
+  }
+  async getOriginMarkerMtime(dir) {
+    try {
+      const stat = await _fsExtra().default.stat(_path().default.join(dir, CAPSULE_ORIGIN_FILE));
+      return stat.mtime;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Walk the global capsules root and return entries with their classification, size, and
+   * last-used time. Used by prune and by `bit capsule list`.
+   */
+  async listAllCapsuleRoots(opts = {}) {
+    const withSizes = opts.withSizes !== false;
+    const root = this.getRootDir();
+    if (!(await _fsExtra().default.pathExists(root))) return [];
+    const entries = await _fsExtra().default.readdir(root, {
+      withFileTypes: true
+    });
+    const subdirs = entries.filter(e => this.isPrunableSubdir(e));
+    // Bounded concurrency: on a multi-GB cache with hundreds of subdirs and tens of
+    // thousands of files per subdir, an unbounded Promise.all of recursive size walks
+    // can hit OS file-descriptor limits (EMFILE) and thrash disk.
+    return (0, _pMap().default)(subdirs, async entry => {
+      const subPath = _path().default.join(root, entry.name);
+      const {
+        marker,
+        lastUsedMs
+      } = await this.readMarkerInfo(subPath);
+      const sizeBytes = withSizes ? await this.computeDirSize(subPath) : 0;
+      return {
+        path: subPath,
+        kind: marker?.kind ?? 'unmarked',
+        originPath: marker?.originPath,
+        lastUsedMs,
+        sizeBytes
+      };
+    }, {
+      concurrency: (0, _harmonyModules().concurrentIOLimit)()
+    });
+  }
+
+  /**
+   * Sum sizes of all entries under `dir`. Tolerant of symlinks and permission errors —
+   * any failure returns the partial sum so we never throw from the prune path.
+   * Uses bounded concurrency to avoid EMFILE on deep trees.
+   */
+  async computeDirSize(dir) {
+    let total = 0;
+    const concurrency = (0, _harmonyModules().concurrentIOLimit)();
+    const walk = async current => {
+      let entries;
+      try {
+        entries = await _fsExtra().default.readdir(current, {
+          withFileTypes: true
+        });
+      } catch {
+        return;
+      }
+      await (0, _pMap().default)(entries, async entry => {
+        const p = _path().default.join(current, entry.name);
+        if (entry.isDirectory()) {
+          await walk(p);
+        } else if (entry.isFile()) {
+          try {
+            const st = await _fsExtra().default.lstat(p);
+            total += st.size;
+          } catch {
+            // ignore
+          }
+        }
+      }, {
+        concurrency
+      });
+    };
+    await walk(dir);
+    return total;
+  }
+
+  /**
+   * Apply the prune rules from the plan:
+   *   - workspace caps: deleted unconditionally (unless keepWorkspaceCaps)
+   *   - scope-aspects-root: never deleted as a whole; per-aspect-version children pruned by age
+   *   - scope caps and unmarked dirs older than threshold: deleted
+   *   - orphans (marker says originPath gone): deleted
+   *   - after the above, if sizeTargetGb given and size still exceeds it, evict oldest-first
+   */
+  async pruneCapsules(opts = {}) {
+    // Clamp to >= 0: a negative age would put the cutoff in the future (everything looks
+    // "too old" → whole cache deleted); a negative size target would force evicting
+    // everything. Both are almost certainly user error, so floor them at 0.
+    const olderThanDays = Math.max(0, opts.olderThanDays ?? 30);
+    const sizeTargetGb = opts.sizeTargetGb === undefined ? undefined : Math.max(0, opts.sizeTargetGb);
+    const includeOrphans = opts.includeOrphans !== false;
+    const keepWorkspaceCaps = opts.keepWorkspaceCaps === true;
+    const dryRun = opts.dryRun === true;
+    // Size accounting requires an expensive recursive lstat across the whole cache. Skip
+    // it by default so the foreground command returns in ms (deletes are O(1) renames);
+    // force on for size-target enforcement and when the caller asks for byte accounting.
+    const computeSizes = opts.withSizes === true || sizeTargetGb !== undefined;
+    const ageCutoffMs = Date.now() - olderThanDays * ONE_DAY_MS;
+    const datedDirName = this.configStore.getConfig(_legacy().CFG_CAPSULES_SCOPES_ASPECTS_DATED_DIR) || 'dated-capsules';
+    const roots = await this.listAllCapsuleRoots({
+      withSizes: computeSizes
+    });
+    const totalSizeBefore = computeSizes ? roots.reduce((sum, r) => sum + r.sizeBytes, 0) : 0;
+    const removed = [];
+    const removeEntry = (p, kind, reason, sizeBytes, originPath) => this.recordRemoval(removed, {
+      path: p,
+      kind,
+      reason,
+      sizeBytes,
+      originPath
+    }, dryRun);
+    for (const root of roots) {
+      if (_path().default.basename(root.path) === datedDirName) {
+        await this.pruneDatedCapsulesChildren(root.path, dryRun, computeSizes, removed);
+        continue;
+      }
+      if (root.kind === 'workspace') {
+        if (keepWorkspaceCaps) continue;
+        await removeEntry(root.path, root.kind, 'workspace-cap', root.sizeBytes, root.originPath);
+        continue;
+      }
+      if (root.kind === 'scope' || root.kind === 'unmarked') {
+        const orphan = includeOrphans && root.originPath && !(await _fsExtra().default.pathExists(root.originPath));
+        const tooOld = root.lastUsedMs < ageCutoffMs;
+        if (orphan) {
+          await removeEntry(root.path, root.kind, 'orphan', root.sizeBytes, root.originPath);
+        } else if (tooOld) {
+          // For unmarked dirs, sniff content first to avoid nuking a legacy scope-aspects root.
+          if (root.kind === 'unmarked' && (await this.looksLikeAspectsRoot(root.path))) {
+            await this.pruneAspectsRootChildren(root.path, ageCutoffMs, dryRun, computeSizes, removed);
+          } else {
+            await removeEntry(root.path, root.kind, `older-than-${olderThanDays}d`, root.sizeBytes, root.originPath);
+          }
+        }
+        continue;
+      }
+      if (root.kind === 'scope-aspects-root') {
+        await this.pruneAspectsRootChildren(root.path, ageCutoffMs, dryRun, computeSizes, removed);
+        continue;
+      }
+    }
+    if (sizeTargetGb !== undefined) {
+      await this.applySizeTarget(sizeTargetGb, removed, dryRun);
+    }
+    const totalRemovedBytes = removed.reduce((sum, r) => sum + r.sizeBytes, 0);
+    // For dry-run, report the *projected* post-prune size so the CLI summary stays
+    // internally consistent (cache: X → X − freed). Real prune subtracts the same.
+    const totalSizeAfter = Math.max(0, totalSizeBefore - totalRemovedBytes);
+    return {
+      removed,
+      totalRemovedBytes,
+      totalSizeBeforeBytes: totalSizeBefore,
+      totalSizeAfterBytes: totalSizeAfter,
+      dryRun
+    };
+  }
+
+  /**
+   * Record a removal in the prune report and, unless this is a dry run, actually delete it
+   * (fast rename-to-trash). Keeps the "report and delete are gated by the same dryRun flag"
+   * invariant in one place so the per-kind prune helpers can't drift apart.
+   */
+  async recordRemoval(removed, entry, dryRun) {
+    removed.push(entry);
+    this.logger.debug(`[capsule-prune] ${dryRun ? 'would remove' : 'removing'} [${entry.kind} · ${entry.reason}] ${entry.path}` + (entry.originPath ? ` origin=${entry.originPath}` : ''));
+    if (!dryRun) await this.scheduleFastDelete(entry.path);
+  }
+
+  /**
+   * The `dated-capsules` dir holds per-date subdirs (`YYYY-M-D`) of in-flight isolation
+   * runs. These are recreated on every isolation, so anything that isn't *today*'s
+   * subdir is leftover from a previous run and safe to delete. Today's subdir is
+   * preserved to avoid racing a concurrent bit process that may still be writing to it.
+   */
+  async pruneDatedCapsulesChildren(rootPath, dryRun, computeSizes, removed) {
+    const todayDir = this.getDatedCapsuleDirName();
+    let entries;
+    try {
+      entries = await _fsExtra().default.readdir(rootPath, {
+        withFileTypes: true
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!this.isPrunableSubdir(entry)) continue;
+      if (entry.name === todayDir) continue;
+      const childPath = _path().default.join(rootPath, entry.name);
+      const sizeBytes = computeSizes ? await this.computeDirSize(childPath) : 0;
+      await this.recordRemoval(removed, {
+        path: childPath,
+        kind: 'unmarked',
+        reason: 'dated-capsules-not-today',
+        sizeBytes
+      }, dryRun);
+    }
+  }
+
+  /**
+   * Legacy unmarked dirs may still be a scope-aspects root. Heuristic: a child subdir whose
+   * name contains `@` (aspect-version pattern like `teambit.node_node@1.3.4`).
+   */
+  async looksLikeAspectsRoot(dir) {
+    try {
+      const entries = await _fsExtra().default.readdir(dir, {
+        withFileTypes: true
+      });
+      return entries.some(e => e.isDirectory() && e.name.includes('@'));
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Prune per-aspect-version children of a scope-aspects root purely by age (marker mtime,
+   * which is touched on every aspect load).
+   *
+   * Note there's deliberately no orphan check here: a scope-aspect child's `originPath` is
+   * the *logical* scope-aspects path (e.g. `<scope.path>-aspects`) used only to hash the
+   * capsule root dir name — it need not exist as a real directory, so treating a missing
+   * `originPath` as "orphan" would wrongly delete capsules of currently-used aspects.
+   * Orphan pruning is still honored elsewhere for `workspace`/`scope` kinds.
+   */
+  async pruneAspectsRootChildren(rootPath, ageCutoffMs, dryRun, computeSizes, removed) {
+    let entries;
+    try {
+      entries = await _fsExtra().default.readdir(rootPath, {
+        withFileTypes: true
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!this.isPrunableSubdir(entry)) continue;
+      const childPath = _path().default.join(rootPath, entry.name);
+      const {
+        marker,
+        lastUsedMs
+      } = await this.readMarkerInfo(childPath);
+      if (lastUsedMs < ageCutoffMs) {
+        const sizeBytes = computeSizes ? await this.computeDirSize(childPath) : 0;
+        await this.recordRemoval(removed, {
+          path: childPath,
+          kind: 'scope-aspect',
+          reason: 'aspect-older-than-cutoff',
+          sizeBytes,
+          originPath: marker?.originPath
+        }, dryRun);
+      }
+    }
+  }
+
+  /**
+   * After the standard prune, if total still exceeds the target, keep evicting the
+   * oldest remaining aspect-version subdirs until under the limit.
+   */
+  async applySizeTarget(sizeTargetGb, removed, dryRun) {
+    const targetBytes = sizeTargetGb * 1024 * 1024 * 1024;
+    const removedPaths = new Set(removed.map(r => r.path));
+    // Re-walk what's left (one pass, with sizes) to find both the current total and the
+    // oldest aspect-version children to evict.
+    const roots = await this.listAllCapsuleRoots();
+    const totalBytes = roots.reduce((sum, r) => sum + r.sizeBytes, 0);
+    const aspectChildren = [];
+    for (const root of roots) {
+      if (root.kind !== 'scope-aspects-root' && !(root.kind === 'unmarked' && (await this.looksLikeAspectsRoot(root.path)))) {
+        continue;
+      }
+      let entries = [];
+      try {
+        entries = await _fsExtra().default.readdir(root.path, {
+          withFileTypes: true
+        });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!this.isPrunableSubdir(entry)) continue;
+        const childPath = _path().default.join(root.path, entry.name);
+        if (removedPaths.has(childPath)) continue;
+        const {
+          marker,
+          lastUsedMs
+        } = await this.readMarkerInfo(childPath);
+        const sizeBytes = await this.computeDirSize(childPath);
+        aspectChildren.push({
+          path: childPath,
+          lastUsedMs,
+          sizeBytes,
+          originPath: marker?.originPath
+        });
+      }
+    }
+    aspectChildren.sort((a, b) => a.lastUsedMs - b.lastUsedMs);
+    // In dry-run the standard-prune entries are still on disk (counted in totalBytes), so
+    // subtract them; in a real run they were already moved to trash and excluded from the walk.
+    let remainingBytes = totalBytes - (dryRun ? removed.reduce((s, r) => s + r.sizeBytes, 0) : 0);
+    for (const child of aspectChildren) {
+      if (remainingBytes <= targetBytes) break;
+      await this.recordRemoval(removed, {
+        path: child.path,
+        kind: 'scope-aspect',
+        reason: `size-target-${sizeTargetGb}gb`,
+        sizeBytes: child.sizeBytes,
+        originPath: child.originPath
+      }, dryRun);
+      remainingBytes -= child.sizeBytes;
+    }
+  }
+}
+exports.CapsuleCache = CapsuleCache;
+
+//# sourceMappingURL=capsule-cache.js.map