@nitpicker/archive 0.0.0-stage → 0.25.0

package/lib/cache/extract-archive-to-cache.js

@@ -0,0 +1,326 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { acquireArchiveLock, ArchiveLockError } from '../archive-lock.js';
+import { Database } from '../database.js';
+import { peekTarTopDir } from '../filesystem/peek-tar-top-dir.js';
+import { rename } from '../filesystem/rename.js';
+import { untar } from '../filesystem/untar.js';
+import { IncompatibleArchiveError } from '../meta/types.js';
+import { computeArchiveCacheKey } from './compute-archive-cache-key.js';
+/**
+ * How long {@link extractArchiveToCache} waits in total for a peer
+ * extractor to finish (ms). 5 minutes is enough for the largest archives
+ * the crawler currently produces (~10 GB untars in ~10 s; 5 min gives
+ * 30× headroom) while still bounded so a deadlocked process eventually
+ * surfaces as a real error instead of hanging the viewer indefinitely.
+ */
+const PEER_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Polling interval while waiting on a peer extractor (ms). Short enough
+ * to keep latency low when the peer is fast, long enough to avoid
+ * burning CPU on a busy `fs.stat` loop.
+ */
+const PEER_WAIT_POLL_MS = 50;
+/**
+ * Marker file dropped into a cache directory only after the extraction
+ * has fully completed AND the contents have passed a structural sanity
+ * check (db.sqlite present, schema compatible, migrations applied).
+ *
+ * Internal — the file name is an implementation detail. Tests should
+ * assert through externally observable behaviour (cache hit on second
+ * open) rather than importing this constant.
+ */
+const READY_MARKER = '.nitpicker-cache-ready';
+/**
+ * In-process deduplication for concurrent {@link extractArchiveToCache}
+ * calls targeting the same `cacheDir`.
+ *
+ * The file-based {@link acquireArchiveLock} (mkdir-based) cannot defend
+ * against same-process race windows because the lock holder writes its
+ * `pid.txt` in a separate `await` from the directory creation: a sibling
+ * promise that observes the `EEXIST` between those two steps sees an
+ * empty `pid.txt`, mistakes the lock for stale, and clobbers it.
+ *
+ * Single-process dedup eliminates that race entirely for the common
+ * "viewer + MCP in the same process" topology while still letting the
+ * inner file lock guard cross-process collisions.
+ */
+const inFlightByCacheDir = new Map();
+/**
+ * Untar a `.nitpicker` archive into the given cache directory.
+ *
+ * Concurrency / re-entry contract:
+ *
+ * - Two viewers opening the same archive race for the cache lock; the
+ *   loser waits and recheck-loops until the winner writes the ready
+ *   marker, then short-circuits.
+ * - Same-process concurrent callers dedupe through
+ *   `inFlightByCacheDir` so they share one extraction promise.
+ *
+ * Per-archive staging:
+ *
+ * - The tar's inner directory is extracted into `${cacheDir}.staging/`
+ *   first, then atomically renamed into `cacheDir`. Crucially, the
+ *   staging path is keyed off `cacheDir` (not the tar's inner directory
+ *   name) so two archives that happen to share an inner-dir name never
+ *   collide on the same staging slot.
+ *
+ * Integrity guard:
+ *
+ * - After rename, we run the writer-side `Database.connect` so all
+ *   migrations apply (column adds, new tables) and the version check
+ *   fires before the ready marker is written. A corrupt or incompatible
+ *   archive therefore poisons no cache entry — the cacheDir is removed
+ *   and the next caller retries from scratch.
+ *
+ * TOCTOU guard:
+ *
+ * - The cache key is recomputed from the file's stat AFTER the untar
+ *   completes. If the file changed mid-flight (a concurrent
+ *   `crawl --append` rewrote it), the freshly-landed cache contents do
+ *   not correspond to the original key, so we abort and remove the
+ *   cacheDir so the caller upstream sees the inconsistency rather than
+ *   serving misattributed data.
+ * @param archivePath - Absolute path to the source `.nitpicker` file.
+ * @param cacheRoot - Absolute path to the cache root directory.
+ * @param cacheDir - Absolute path the extracted contents should end up at.
+ * @param cacheKey - The cache key used to derive `cacheDir`. Recomputed
+ *   after extraction to detect concurrent writers; must match.
+ * @param onExtractProgress - Called during the untar step with bytes read
+ *   so far and the archive's total size (issue #294: a cold cache on a
+ *   large archive can take tens of seconds with no other signal it isn't
+ *   hung). Never called on a cache hit — {@link isCacheDirReady} short-
+ *   circuits before `untar` runs — so callers can treat "never invoked" as
+ *   the definition of a hit and skip printing a phase label until the
+ *   first call actually arrives. Only the first concurrent caller for a
+ *   given `cacheDir` sees callbacks; same-`cacheDir` callers deduped
+ *   through {@link inFlightByCacheDir} just await the shared promise.
+ * @param onLog - Forwarded to the cache-miss writer connection
+ *   (`runMigrationsOnCacheDir`'s `Database.connect`) so a legacy archive's
+ *   self-healing schema migrations do not fall back to a bare
+ *   `console.error` mid-redraw of a caller's display (issue #294). Omit for
+ *   that fallback — see `Archive.openCached`'s own `onLog` doc.
+ * @returns Resolves once `cacheDir` is ready to be opened read-only.
+ */
+export async function extractArchiveToCache(archivePath, cacheRoot, cacheDir, cacheKey, onExtractProgress, onLog) {
+    if (await isCacheDirReady(cacheDir)) {
+        return;
+    }
+    const existing = inFlightByCacheDir.get(cacheDir);
+    if (existing) {
+        return existing;
+    }
+    const promise = runExtraction(archivePath, cacheRoot, cacheDir, cacheKey, onExtractProgress, onLog).finally(() => {
+        inFlightByCacheDir.delete(cacheDir);
+    });
+    inFlightByCacheDir.set(cacheDir, promise);
+    return promise;
+}
+/**
+ * The actual extraction work. Split out from {@link extractArchiveToCache}
+ * so the in-process dedup map can wrap it without disturbing the
+ * extraction flow itself.
+ * @param archivePath - Absolute path to the source `.nitpicker` file.
+ * @param cacheRoot - Absolute path to the cache root directory.
+ * @param cacheDir - Absolute path the extracted contents should end up at.
+ * @param cacheKey - Pre-extraction cache key, re-verified post-extraction.
+ * @param onExtractProgress - See {@link extractArchiveToCache}.
+ * @param onLog - See {@link extractArchiveToCache}.
+ */
+async function runExtraction(archivePath, cacheRoot, cacheDir, cacheKey, onExtractProgress, onLog) {
+    await fs.mkdir(cacheRoot, { recursive: true });
+    const releaseLock = await acquireLockWithPeerWait(cacheDir);
+    try {
+        if (await isCacheDirReady(cacheDir)) {
+            return;
+        }
+        // Half-populated cacheDir recovery: another extractor crashed
+        // before writing the marker. Rename it aside instead of `rm`-ing
+        // in place so any reader that somehow still holds an fd on the
+        // old contents (the cache layer doesn't refcount readers) is not
+        // pulled out from under. The renamed quarantine dir is left for
+        // OS-level temp cleanup.
+        await quarantineHalfPopulatedCacheDir(cacheDir);
+        const stagingDir = `${cacheDir}.staging`;
+        // Stage clean: a previous crashed run may have left
+        // `<cacheDir>.staging/` around. `untar` would happily merge into
+        // it (with `newer:true` cherrypicking entries) so wipe first.
+        await fs.rm(stagingDir, { recursive: true, force: true });
+        await fs.mkdir(stagingDir, { recursive: true });
+        await untar(archivePath, { cwd: stagingDir, onProgress: onExtractProgress });
+        // Concurrent-writer detection: if the source archive changed
+        // during our untar, the contents we just landed do NOT match the
+        // `cacheKey` that named the directory. Drop the staging dir and
+        // surface as an error so the caller (or a retry) can pick up the
+        // new key.
+        const postKey = await computeArchiveCacheKey(archivePath);
+        if (postKey !== cacheKey) {
+            await fs.rm(stagingDir, { recursive: true, force: true });
+            throw new Error(`Archive changed during cache extraction (key ${cacheKey} -> ${postKey}); ` +
+                `refusing to land mismatched contents at ${cacheDir}.`);
+        }
+        const innerDirName = await peekTarTopDir(archivePath);
+        const extractedInner = path.resolve(stagingDir, innerDirName);
+        // Move the inner directory into the cache slot. Any old quarantine
+        // is already aside, so the target is guaranteed empty.
+        await rename(extractedInner, cacheDir, true);
+        // The empty `stagingDir` wrapper is no longer useful — best effort
+        // remove (ignore errors, OS cleanup catches stragglers).
+        await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        // Validate + migrate: open in WRITER mode so the full migration
+        // stack runs (initSchema / migrate*). On failure (db.sqlite
+        // missing, incompatible archive, broken schema), tear down the
+        // cache entry so the next caller does not get stuck on a
+        // "ready"-marked but broken cache.
+        try {
+            await runMigrationsOnCacheDir(cacheDir, onLog);
+        }
+        catch (error) {
+            await fs.rm(cacheDir, { recursive: true, force: true });
+            throw error;
+        }
+        await fs.writeFile(path.join(cacheDir, READY_MARKER), '', 'utf8');
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * Acquire the cache lock, blocking until any peer extractor finishes
+ * (rather than failing fast on `EEXIST` the way the writer-oriented
+ * {@link acquireArchiveLock} does). Returns the release function once
+ * the lock is held.
+ * @param cacheDir - Absolute path the lock guards.
+ */
+async function acquireLockWithPeerWait(cacheDir) {
+    const startedAt = Date.now();
+    while (true) {
+        if (await isCacheDirReady(cacheDir)) {
+            // Peer finished and the marker is up. Return a no-op release
+            // so the caller can `finally`-await it without branching.
+            return async () => { };
+        }
+        try {
+            return await acquireArchiveLock(cacheDir);
+        }
+        catch (error) {
+            if (!(error instanceof ArchiveLockError)) {
+                throw error;
+            }
+            if (Date.now() - startedAt > PEER_WAIT_TIMEOUT_MS) {
+                throw error;
+            }
+            await sleep(PEER_WAIT_POLL_MS);
+        }
+    }
+}
+/**
+ * Open the migrated DB in writer mode so all migrations apply, then
+ * release the handle. Cache entries land migrated, so the subsequent
+ * `Archive.connect` read-only open never needs to mutate the cache dir
+ * (and never silently misses a newly-added column).
+ * @param cacheDir - Absolute path to the freshly-extracted cache dir.
+ * @param onLog - See {@link extractArchiveToCache}.
+ */
+async function runMigrationsOnCacheDir(cacheDir, onLog) {
+    const dbPath = path.join(cacheDir, 'db.sqlite');
+    if (!(await fileExists(dbPath))) {
+        throw new Error(`Cache directory does not contain db.sqlite: ${cacheDir}`);
+    }
+    const db = await Database.connect({ filename: dbPath, readOnly: false, onLog });
+    try {
+        // `Database.connect` ran migrations during init. Closing here
+        // flushes WAL + drops the handle so the read-only re-open in
+        // `Archive.connect` does not race the writer connection.
+        await db.destroy();
+    }
+    catch (error) {
+        // Propagate after attempting cleanup of the connection (best
+        // effort — the cache dir tear-down happens in the caller).
+        if (error instanceof IncompatibleArchiveError) {
+            throw error;
+        }
+        throw error;
+    }
+}
+/**
+ * Move a half-populated cacheDir aside so the next extraction can land
+ * cleanly without yanking live readers' files out from under them. The
+ * quarantine path gets a unique suffix so two crashes in succession
+ * don't collide.
+ * @param cacheDir - Absolute path of the cache slot to free.
+ */
+async function quarantineHalfPopulatedCacheDir(cacheDir) {
+    try {
+        await fs.access(cacheDir);
+    }
+    catch {
+        // Nothing to quarantine.
+        return;
+    }
+    if (await isCacheDirReady(cacheDir)) {
+        // Already settled — caller will short-circuit, no quarantine needed.
+        return;
+    }
+    const quarantinePath = `${cacheDir}.corrupt.${process.pid}.${nextQuarantineCounter()}`;
+    try {
+        await fs.rename(cacheDir, quarantinePath);
+    }
+    catch {
+        // If rename fails (e.g. cross-volume), fall back to direct
+        // removal — accepting the rm-while-reader risk this single time
+        // since we have no other option.
+        await fs.rm(cacheDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Monotonic counter appended to quarantine directory names so multiple
+ * recoveries in a single process never collide on the same path. Resets
+ * to zero after `2 ** 32` increments; that bound is far larger than any
+ * realistic per-process quarantine count.
+ */
+let quarantineCounter = 0;
+/**
+ * Issue the next quarantine sequence number.
+ * @returns A non-negative integer, monotonically increasing per process.
+ */
+function nextQuarantineCounter() {
+    quarantineCounter = (quarantineCounter + 1) % 0x1_00_00_00_00;
+    return quarantineCounter;
+}
+/**
+ * Async existence probe — avoids blocking the event loop on the warm
+ * cache-hit fast path.
+ * @param targetPath - Absolute path to probe.
+ * @returns `true` if the path is reachable via `fs.access`.
+ */
+async function fileExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a cache directory contains a fully-validated extraction. The
+ * READY marker is the only trustworthy signal — sibling files alone
+ * cannot be trusted because a half-extracted dir can also contain a
+ * `db.sqlite`.
+ * @param cacheDir - Absolute path to a candidate cache directory.
+ * @returns `true` if the marker exists.
+ */
+async function isCacheDirReady(cacheDir) {
+    return await fileExists(path.join(cacheDir, READY_MARKER));
+}
+/**
+ * Promise-based sleep used by the peer-wait poll. Kept inline so the
+ * file has no external sleep dependency and so the implementation can
+ * later swap for an AbortSignal-aware version without touching the
+ * call site.
+ * @param ms - Milliseconds to wait.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/cache/get-archive-cache-root.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve the directory where extracted `.nitpicker` archives are cached.
+ *
+ * Resolution order:
+ *
+ * 1. `NITPICKER_TAR_CACHE_DIR` env — explicit override (CI, testing, or
+ *    operators who want the cache on a specific volume). Must be a
+ *    path; values that look like boolean / sentinel words (e.g. `0`,
+ *    `false`) are ignored to keep the cache from landing somewhere
+ *    surprising when the user mistakes the env contract.
+ * 2. `<os.tmpdir()>/nitpicker/cache/` — default. Lives under the OS
+ *    temp directory so the platform's own cleanup (macOS reboot, Linux
+ *    `systemd-tmpfiles`, Windows Disk Cleanup) reclaims stale entries
+ *    without bespoke logic on our side.
+ *
+ * The returned path is absolute. The caller is responsible for creating
+ * it on demand (this function is pure).
+ * @returns Absolute path to the cache root directory.
+ */
+export declare function getArchiveCacheRoot(): string;

package/lib/cache/get-archive-cache-root.js

@@ -0,0 +1,53 @@
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Env values that look like a "disable" sentinel rather than a path.
+ *
+ * A user who copy-pastes the `NITPICKER_DISABLE_TAR_CACHE` convention
+ * onto `NITPICKER_TAR_CACHE_DIR` (e.g. `NITPICKER_TAR_CACHE_DIR=0`
+ * thinking it means "use default") would otherwise silently land the
+ * cache at `$PWD/0/` — multi-gigabyte extracts polluting the project
+ * tree, never reclaimed by OS temp cleanup. Reject these explicitly
+ * and fall back to the default location instead.
+ */
+const SENTINEL_LIKE_OVERRIDES = new Set([
+    '0',
+    '1',
+    'false',
+    'true',
+    'no',
+    'yes',
+    'off',
+    'on',
+    'null',
+    'undefined',
+]);
+/**
+ * Resolve the directory where extracted `.nitpicker` archives are cached.
+ *
+ * Resolution order:
+ *
+ * 1. `NITPICKER_TAR_CACHE_DIR` env — explicit override (CI, testing, or
+ *    operators who want the cache on a specific volume). Must be a
+ *    path; values that look like boolean / sentinel words (e.g. `0`,
+ *    `false`) are ignored to keep the cache from landing somewhere
+ *    surprising when the user mistakes the env contract.
+ * 2. `<os.tmpdir()>/nitpicker/cache/` — default. Lives under the OS
+ *    temp directory so the platform's own cleanup (macOS reboot, Linux
+ *    `systemd-tmpfiles`, Windows Disk Cleanup) reclaims stale entries
+ *    without bespoke logic on our side.
+ *
+ * The returned path is absolute. The caller is responsible for creating
+ * it on demand (this function is pure).
+ * @returns Absolute path to the cache root directory.
+ */
+export function getArchiveCacheRoot() {
+    const envOverride = process.env.NITPICKER_TAR_CACHE_DIR;
+    if (envOverride && envOverride.trim().length > 0) {
+        const trimmed = envOverride.trim();
+        if (!SENTINEL_LIKE_OVERRIDES.has(trimmed.toLowerCase())) {
+            return path.resolve(trimmed);
+        }
+    }
+    return path.resolve(os.tmpdir(), 'nitpicker', 'cache');
+}

package/lib/cache/is-archive-cache-disabled.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether the tar cache is disabled by the `NITPICKER_DISABLE_TAR_CACHE`
+ * env var.
+ *
+ * Useful for two scenarios:
+ *
+ * 1. Debugging — bypass the cache to reproduce the cold-start behaviour
+ *    against a fresh tmpDir.
+ * 2. Sandboxed CI — when the runner's tmpfs would not survive between
+ *    steps anyway, the cache only adds first-step overhead.
+ *
+ * Accepted truthy values: `1`, `true`, `yes`, `on` (case-insensitive).
+ * Anything else (including unset) keeps the cache enabled.
+ * @returns `true` when the cache should be bypassed.
+ * @example
+ * ```ts
+ * if (isArchiveCacheDisabled()) {
+ *   // Fall back to the writer path; cwd tmpDir + close-time cleanup.
+ *   const archive = await Archive.open({ filePath });
+ *   ...
+ * }
+ * ```
+ */
+export declare function isArchiveCacheDisabled(): boolean;

package/lib/cache/is-archive-cache-disabled.js

@@ -0,0 +1,34 @@
+/**
+ * Whether the tar cache is disabled by the `NITPICKER_DISABLE_TAR_CACHE`
+ * env var.
+ *
+ * Useful for two scenarios:
+ *
+ * 1. Debugging — bypass the cache to reproduce the cold-start behaviour
+ *    against a fresh tmpDir.
+ * 2. Sandboxed CI — when the runner's tmpfs would not survive between
+ *    steps anyway, the cache only adds first-step overhead.
+ *
+ * Accepted truthy values: `1`, `true`, `yes`, `on` (case-insensitive).
+ * Anything else (including unset) keeps the cache enabled.
+ * @returns `true` when the cache should be bypassed.
+ * @example
+ * ```ts
+ * if (isArchiveCacheDisabled()) {
+ *   // Fall back to the writer path; cwd tmpDir + close-time cleanup.
+ *   const archive = await Archive.open({ filePath });
+ *   ...
+ * }
+ * ```
+ */
+export function isArchiveCacheDisabled() {
+    const raw = process.env.NITPICKER_DISABLE_TAR_CACHE;
+    if (!raw) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return (normalized === '1' ||
+        normalized === 'true' ||
+        normalized === 'yes' ||
+        normalized === 'on');
+}

package/lib/cache/list-archive-cache-entries.d.ts

@@ -0,0 +1,23 @@
+import type { ArchiveCacheEntry } from './types.js';
+/**
+ * List the top-level entries found directly under an archive cache root,
+ * with a recursive size total and the most recent mtime found in each.
+ *
+ * Pure: takes `cacheRoot` as a parameter and never resolves it itself (see
+ * {@link import('./get-archive-cache-root.js').getArchiveCacheRoot} for the
+ * production root), so tests can point it at a throwaway directory instead
+ * of the real OS temp cache.
+ *
+ * Symbolic links are reported but never followed, both at the top level and
+ * while walking a directory's contents — this avoids escaping `cacheRoot`
+ * and crashing on dangling links.
+ * @param cacheRoot - Absolute path to the cache root to inspect.
+ * @returns One entry per top-level child of `cacheRoot`, in `fs.readdir`
+ *   order. Returns `[]` if `cacheRoot` does not exist.
+ * @example
+ * ```ts
+ * const entries = await listArchiveCacheEntries(getArchiveCacheRoot());
+ * const totalBytes = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+ * ```
+ */
+export declare function listArchiveCacheEntries(cacheRoot: string): Promise<ArchiveCacheEntry[]>;

package/lib/cache/list-archive-cache-entries.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * List the top-level entries found directly under an archive cache root,
+ * with a recursive size total and the most recent mtime found in each.
+ *
+ * Pure: takes `cacheRoot` as a parameter and never resolves it itself (see
+ * {@link import('./get-archive-cache-root.js').getArchiveCacheRoot} for the
+ * production root), so tests can point it at a throwaway directory instead
+ * of the real OS temp cache.
+ *
+ * Symbolic links are reported but never followed, both at the top level and
+ * while walking a directory's contents — this avoids escaping `cacheRoot`
+ * and crashing on dangling links.
+ * @param cacheRoot - Absolute path to the cache root to inspect.
+ * @returns One entry per top-level child of `cacheRoot`, in `fs.readdir`
+ *   order. Returns `[]` if `cacheRoot` does not exist.
+ * @example
+ * ```ts
+ * const entries = await listArchiveCacheEntries(getArchiveCacheRoot());
+ * const totalBytes = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+ * ```
+ */
+export async function listArchiveCacheEntries(cacheRoot) {
+    let topLevel;
+    try {
+        topLevel = await fs.readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const entries = [];
+    for (const dirent of topLevel) {
+        const entryPath = path.join(cacheRoot, dirent.name);
+        if (dirent.isSymbolicLink()) {
+            entries.push({
+                kind: 'unknown',
+                name: dirent.name,
+                path: entryPath,
+                sizeBytes: 0,
+                mtimeMs: 0,
+            });
+            continue;
+        }
+        if (dirent.isDirectory()) {
+            const { sizeBytes, mtimeMs } = await computeDirectoryStats(entryPath);
+            entries.push({
+                kind: classifyEntryName(dirent.name),
+                name: dirent.name,
+                path: entryPath,
+                sizeBytes,
+                mtimeMs,
+            });
+            continue;
+        }
+        const stat = await fs.stat(entryPath);
+        entries.push({
+            kind: 'unknown',
+            name: dirent.name,
+            path: entryPath,
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs,
+        });
+    }
+    return entries;
+}
+/**
+ * Matches the corrupt-quarantine suffix `extractArchiveToCache` appends
+ * (`${cacheDir}.corrupt.${pid}.${counter}`, both segments always numeric —
+ * see `quarantineHalfPopulatedCacheDir` in `extract-archive-to-cache.ts`).
+ * Anchored and numeric-specific rather than a loose `includes('.corrupt.')`
+ * so an archive whose own (sanitized) basename merely contains the
+ * substring `.corrupt.` — e.g. `my.corrupt.report.nitpicker` — is not
+ * misclassified as an orphan and offered up for deletion by `cache list`.
+ */
+const CORRUPT_QUARANTINE_SUFFIX = /\.corrupt\.\d+\.\d+$/;
+/**
+ * Name of the sibling scratch directory earlier versions created for
+ * analyze-plugin tables. Nothing writes it any more, so a leftover one is
+ * reported as an orphan that `cache clear` can reclaim.
+ */
+const LEGACY_TABLE_CACHE_DIR_NAME = 'table';
+/**
+ * Classify a cache-root child by name pattern alone (no filesystem access).
+ *
+ * This is a heuristic: `.staging`/corrupt-quarantine suffixes are appended
+ * by `extractArchiveToCache` onto an existing tar-cache dir name, so an
+ * archive whose own sanitized basename happens to end in exactly one of
+ * these literal suffixes is indistinguishable from a real orphan by name
+ * alone. Disambiguating fully would require re-deriving each entry's
+ * expected name from its source archive, which `list`/`clear` (by design,
+ * see grill-me scope) never has access to. Accepted as a rare, low-cost
+ * misclassification.
+ * @param name - Base name of the top-level entry.
+ */
+function classifyEntryName(name) {
+    if (name === LEGACY_TABLE_CACHE_DIR_NAME ||
+        name.endsWith('.staging') ||
+        CORRUPT_QUARANTINE_SUFFIX.test(name)) {
+        return 'orphan';
+    }
+    return 'tar-cache';
+}
+/**
+ * Recursively sum file sizes and find the most recent mtime under a
+ * directory. Symbolic links are neither followed nor counted.
+ * @param dirPath - Absolute path to the directory to walk.
+ */
+async function computeDirectoryStats(dirPath) {
+    let sizeBytes = 0;
+    let mtimeMs = 0;
+    const children = await fs.readdir(dirPath, { recursive: true, withFileTypes: true });
+    for (const child of children) {
+        if (!child.isFile()) {
+            continue;
+        }
+        const childPath = path.join(child.parentPath, child.name);
+        const stat = await fs.stat(childPath);
+        sizeBytes += stat.size;
+        mtimeMs = Math.max(mtimeMs, stat.mtimeMs);
+    }
+    if (mtimeMs === 0) {
+        const dirStat = await fs.stat(dirPath);
+        mtimeMs = dirStat.mtimeMs;
+    }
+    return { sizeBytes, mtimeMs };
+}

package/lib/cache/path-exists.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Async existence probe — avoids blocking the event loop on the common
+ * "check before remove" path shared by
+ * {@link import('./clear-archive-cache-root.js').clearArchiveCacheRoot} and
+ * {@link import('./clear-archive-cache-entry.js').clearArchiveCacheEntry}.
+ * @param targetPath - Absolute path to probe.
+ * @returns `true` if the path is reachable via `fs.access`.
+ */
+export declare function pathExists(targetPath: string): Promise<boolean>;

package/lib/cache/path-exists.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+/**
+ * Async existence probe — avoids blocking the event loop on the common
+ * "check before remove" path shared by
+ * {@link import('./clear-archive-cache-root.js').clearArchiveCacheRoot} and
+ * {@link import('./clear-archive-cache-entry.js').clearArchiveCacheEntry}.
+ * @param targetPath - Absolute path to probe.
+ * @returns `true` if the path is reachable via `fs.access`.
+ */
+export async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/cache/resolve-archive-cache-dir.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Build the absolute path to a single archive's cache directory.
+ *
+ * The directory name is `<cacheKey>-<safeBasename>`:
+ *
+ * - `cacheKey` carries the freshness signal (size/mtime/ctime) and is
+ *   what actually drives cache hit vs miss.
+ * - `safeBasename` is appended purely so a human running `ls` on the
+ *   cache root can recognise which archive an entry belongs to. It is
+ *   NOT used to disambiguate keys — two archives with identical inode
+ *   metadata (e.g. an identical copy under a different name) intentionally
+ *   share an entry under the first basename that landed there.
+ *
+ * The basename is sanitised: anything outside `[A-Za-z0-9._-]` becomes
+ * `_`. This keeps the path portable across filesystems (no spaces,
+ * unicode normalisation surprises, Windows-reserved chars) and removes
+ * any chance that a crafted archive name could escape the cache root
+ * (e.g. via `..` or path separators), independent of the upstream
+ * `path.basename` call that already drops directory components.
+ * @param cacheRoot - Absolute path returned by `getArchiveCacheRoot()`.
+ * @param cacheKey - The freshness key from `computeArchiveCacheKey()`.
+ * @param archivePath - Absolute path to the source `.nitpicker` file;
+ *   only its basename contributes to the cache entry name.
+ * @returns Absolute path to the per-archive cache directory.
+ */
+export declare function resolveArchiveCacheDir(cacheRoot: string, cacheKey: string, archivePath: string): string;