@teambit/isolator 1.0.1001 → 1.0.1003

package/dist/capsule-cache.d.ts

@@ -0,0 +1,192 @@
+import type { Logger } from '@teambit/logger';
+import type { CLIMain } from '@teambit/cli';
+import type { ConfigStoreMain } from '@teambit/config-store';
+import type CapsuleList from './capsule-list';
+/**
+ * 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.
+ */
+export declare const CAPSULE_ORIGIN_FILE = ".bit-capsule-origin.json";
+export declare const CAPSULE_TRASH_DIR = ".trash";
+export type CapsuleKind = 'workspace' | 'scope-aspects-root' | 'scope-aspect' | 'scope';
+export type CapsuleOriginMarker = {
+    originPath: string;
+    createdAt: string;
+    kind: CapsuleKind;
+};
+export type PruneCapsulesOptions = {
+    olderThanDays?: number;
+    includeOrphans?: boolean;
+    keepWorkspaceCaps?: boolean;
+    sizeTargetGb?: number;
+    dryRun?: boolean;
+    /**
+     * Compute byte sizes for every entry being considered. When false, all `sizeBytes`
+     * in the report are 0 and the cache walk skips the expensive recursive `lstat` pass —
+     * deletion (rename-to-trash) is O(1) and runs in milliseconds even on multi-GB caches.
+     * Forced on when `sizeTargetGb` is set because that path needs sizes to enforce.
+     */
+    withSizes?: boolean;
+};
+export type PruneCapsulesReport = {
+    /** `originPath` is the workspace/scope a capsule was created for (from its marker), when known. */
+    removed: {
+        path: string;
+        kind: CapsuleKind | 'unmarked';
+        reason: string;
+        sizeBytes: number;
+        originPath?: string;
+    }[];
+    totalRemovedBytes: number;
+    totalSizeBeforeBytes: number;
+    totalSizeAfterBytes: number;
+    dryRun: boolean;
+};
+export type CapsuleRootEntry = {
+    path: string;
+    kind: CapsuleKind | 'unmarked';
+    originPath?: string;
+    lastUsedMs: number;
+    sizeBytes: number;
+};
+export declare class CapsuleCache {
+    private logger;
+    private cli;
+    private configStore;
+    /** Thunk so the cache stays independent of `GlobalConfigMain` — IsolatorMain forwards it. */
+    private getRootDir;
+    constructor(logger: Logger, cli: CLIMain, configStore: ConfigStoreMain, 
+    /** Thunk so the cache stays independent of `GlobalConfigMain` — IsolatorMain forwards it. */
+    getRootDir: () => string);
+    deleteCapsules(rootDir?: string): Promise<string>;
+    /**
+     * 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.
+     */
+    scheduleFastDelete(dir: string): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private isSweepLockActive;
+    /**
+     * 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(): void;
+    private maybeAutoPrune;
+    /**
+     * 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.
+     */
+    private spawnDetachedAutoPrune;
+    /**
+     * 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.
+     */
+    private spawnDetachedSweep;
+    /**
+     * 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.
+     */
+    ensureOriginMarker(dir: string, kind: CapsuleKind, originPath: string): Promise<void>;
+    /**
+     * Mark all per-component capsule subdirs as scope-aspect kind, originated from the
+     * scope-aspects root. Used right after a scope-aspects isolation.
+     */
+    ensureAspectCapsuleMarkers(capsuleList: CapsuleList, rootOriginPath: string): Promise<void>;
+    /**
+     * 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?: Date): string;
+    /**
+     * 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.
+     */
+    private isPrunableSubdir;
+    /**
+     * 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.
+     */
+    private readMarkerInfo;
+    private readOriginMarker;
+    private getOriginMarkerMtime;
+    /**
+     * Walk the global capsules root and return entries with their classification, size, and
+     * last-used time. Used by prune and by `bit capsule list`.
+     */
+    listAllCapsuleRoots(opts?: {
+        withSizes?: boolean;
+    }): Promise<CapsuleRootEntry[]>;
+    /**
+     * 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.
+     */
+    private computeDirSize;
+    /**
+     * 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
+     */
+    pruneCapsules(opts?: PruneCapsulesOptions): Promise<PruneCapsulesReport>;
+    /**
+     * 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.
+     */
+    private recordRemoval;
+    /**
+     * 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.
+     */
+    private pruneDatedCapsulesChildren;
+    /**
+     * 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`).
+     */
+    private looksLikeAspectsRoot;
+    /**
+     * 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.
+     */
+    private pruneAspectsRootChildren;
+    /**
+     * After the standard prune, if total still exceeds the target, keep evicting the
+     * oldest remaining aspect-version subdirs until under the limit.
+     */
+    private applySizeTarget;
+}