pr-checkmate 1.23.24 → 2.1.0

package/dist/core/install/cache.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandHome = expandHome;
+exports.resolveCacheDir = resolveCacheDir;
+exports.profileDir = profileDir;
+exports.stalePaths = stalePaths;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../../utils/logger");
+/**
+ * Expand a leading `~`.
+ *
+ * Config files are written by hand, `~/.cache/pr-checkmate` is what a person
+ * writes, and nothing in Node expands it — the directory would be created
+ * literally, as a folder named `~`, in whatever the working directory happened
+ * to be.
+ */
+function expandHome(dir, home = node_os_1.default.homedir()) {
+    if (dir === '~')
+        return home;
+    return dir.startsWith('~/') ? node_path_1.default.join(home, dir.slice(2)) : dir;
+}
+/** A directory we can actually write to, or null. */
+function usable(dir) {
+    try {
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+        // Existence is not permission: a cache directory baked into a container
+        // image is often present and read-only, and finding that out at install
+        // time rather than at write time is the difference between a clear message
+        // and a stack trace halfway through fetching.
+        node_fs_1.default.accessSync(dir, node_fs_1.default.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the cache directory, falling back rather than failing.
+ *
+ * Every candidate below is a real environment: containers without `HOME`, CI
+ * images with a read-only home, and runners where only the temp directory is
+ * writable. A tool that refuses to work in any of them is a tool that fails on
+ * CI for reasons the client cannot see.
+ *
+ * @param version The pr-checkmate version, kept in the path so two projects on
+ *   different versions never share fetched tooling.
+ * @param configured `install.cacheDir`, if the client set one.
+ */
+function resolveCacheDir(version, configured, env = process.env) {
+    const explicit = env.PR_CHECKMATE_CACHE_DIR ?? configured;
+    const candidates = [];
+    if (explicit)
+        candidates.push({ dir: expandHome(explicit), reason: 'configured' });
+    // `homedir()` on a container without HOME returns something like `/` — hence
+    // the write check rather than a bare existence test.
+    candidates.push({ dir: node_path_1.default.join(node_os_1.default.homedir(), '.cache', 'pr-checkmate'), reason: 'home cache' });
+    candidates.push({ dir: node_path_1.default.join(node_os_1.default.tmpdir(), 'pr-checkmate-cache'), reason: 'temp directory' });
+    for (const [index, candidate] of candidates.entries()) {
+        const dir = node_path_1.default.join(candidate.dir, version);
+        if (!usable(dir))
+            continue;
+        if (index > 0) {
+            logger_1.logger.warn(`[install]: ⚠️ cache directory "${candidates[0].dir}" is not writable — using ${candidate.reason} (${dir}). Fetched tooling will not survive a container rebuild.`);
+        }
+        return { dir, preferred: index === 0, reason: candidate.reason };
+    }
+    return null;
+}
+/** Where a single profile's tooling is installed. */
+function profileDir(cacheDir, profile) {
+    return node_path_1.default.join(cacheDir, profile);
+}
+/**
+ * Profile directories left behind by other versions of pr-checkmate.
+ *
+ * Nothing removes these automatically: an upgrade must not delete tooling a
+ * concurrently running older version is in the middle of using. `cache prune`
+ * is the deliberate, separate act.
+ */
+function stalePaths(version, configured) {
+    const location = resolveCacheDir(version, configured);
+    if (!location)
+        return [];
+    const root = node_path_1.default.dirname(location.dir);
+    try {
+        return node_fs_1.default
+            .readdirSync(root, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && entry.name !== version)
+            .map(entry => node_path_1.default.join(root, entry.name));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/install/doctor.d.ts

@@ -0,0 +1,35 @@
+import { type LanguageUsage } from '../../utils/detect-language';
+import { type EnsureResult } from './ensure';
+import { type ProfileDecision } from './profiles';
+/** Our own version, read from the package manifest that ships with us. */
+export declare function packageVersion(): string;
+/**
+ * Everything the install layer knows about this repository, in one shot.
+ *
+ * `usage` is a parameter rather than always detected here so a caller that
+ * already has it — `doctor` prints it — does not scan the repository twice and
+ * log two contradictory-looking detection lines for one command.
+ */
+export declare function planInstall(cwd?: string, usage?: LanguageUsage[]): Promise<{
+    decisions: ProfileDecision[];
+    cacheDir: string | null;
+}>;
+/**
+ * Fetch every profile this repository needs.
+ *
+ * Shared by the `install` command and by the run itself, so a client who never
+ * runs `install` gets the same result lazily. `all` is what a container build or
+ * an air-gapped mirror wants: everything, regardless of what this repository
+ * happens to contain.
+ */
+export declare function installProfiles(cwd?: string, all?: boolean): Promise<EnsureResult[]>;
+/**
+ * Explain what this repository needs, what it has, and what is missing — and why.
+ *
+ * The command exists because adaptive installation makes "why did my typecheck
+ * not run" a routine question, and the answer must be a command rather than a
+ * reading of our source.
+ */
+export declare function runDoctor(cwd?: string): Promise<void>;
+/** Remove cached tooling belonging to other versions of pr-checkmate. */
+export declare function pruneCache(): void;

package/dist/core/install/doctor.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageVersion = packageVersion;
+exports.planInstall = planInstall;
+exports.installProfiles = installProfiles;
+exports.runDoctor = runDoctor;
+exports.pruneCache = pruneCache;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const loader_1 = require("../../config/loader");
+const detect_language_1 = require("../../utils/detect-language");
+const logger_1 = require("../../utils/logger");
+const cache_1 = require("./cache");
+const ensure_1 = require("./ensure");
+const profiles_1 = require("./profiles");
+/** Our own version, read from the package manifest that ships with us. */
+function packageVersion() {
+    try {
+        const manifest = node_path_1.default.resolve(__dirname, '../../..', 'package.json');
+        return JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Everything the install layer knows about this repository, in one shot.
+ *
+ * `usage` is a parameter rather than always detected here so a caller that
+ * already has it — `doctor` prints it — does not scan the repository twice and
+ * log two contradictory-looking detection lines for one command.
+ */
+async function planInstall(cwd = process.cwd(), usage) {
+    const config = (0, loader_1.loadProjectConfig)();
+    const detected = usage ?? (await (0, detect_language_1.detectLanguageUsage)(cwd, config.ignoreDirs, config.detect));
+    const location = (0, cache_1.resolveCacheDir)(packageVersion(), config.install?.cacheDir);
+    return { decisions: (0, profiles_1.planProfiles)(detected, config), cacheDir: location?.dir ?? null };
+}
+/** Whether a profile's tooling is present in the cache right now. */
+function installedProfiles(cacheDir) {
+    if (!cacheDir)
+        return new Set();
+    return new Set(profiles_1.PROFILES.filter(p => node_fs_1.default.existsSync(node_path_1.default.join((0, cache_1.profileDir)(cacheDir, p.name), 'node_modules'))).map(p => p.name));
+}
+/**
+ * Fetch every profile this repository needs.
+ *
+ * Shared by the `install` command and by the run itself, so a client who never
+ * runs `install` gets the same result lazily. `all` is what a container build or
+ * an air-gapped mirror wants: everything, regardless of what this repository
+ * happens to contain.
+ */
+async function installProfiles(cwd = process.cwd(), all = false) {
+    const config = (0, loader_1.loadProjectConfig)();
+    const install = config.install ?? {};
+    const { decisions } = await planInstall(cwd);
+    const denied = new Set(install.deny ?? []);
+    const wanted = (all ? profiles_1.PROFILES.map(p => p.name) : decisions.filter(d => d.required).map(d => d.profile)).filter(name => {
+        const profile = profiles_1.PROFILES.find(p => p.name === name);
+        const blocked = profile?.packages.filter(pkg => denied.has(pkg)) ?? [];
+        if (blocked.length === 0)
+            return true;
+        logger_1.logger.info(`[install]: profile "${name}" skipped — install.deny lists ${blocked.join(', ')}`);
+        return false;
+    });
+    const results = [];
+    // Sequential on purpose. Parallel installs of profiles that share hundreds of
+    // packages fight over npm's cache and gain nothing; the wall-clock cost lands
+    // once, on a cold cache, and clarity of the log matters more there.
+    for (const profile of wanted) {
+        results.push(await (0, ensure_1.ensureProfile)(profile, { cwd, version: packageVersion(), install }));
+    }
+    return results;
+}
+/**
+ * Explain what this repository needs, what it has, and what is missing — and why.
+ *
+ * The command exists because adaptive installation makes "why did my typecheck
+ * not run" a routine question, and the answer must be a command rather than a
+ * reading of our source.
+ */
+async function runDoctor(cwd = process.cwd()) {
+    const config = (0, loader_1.loadProjectConfig)();
+    const usage = await (0, detect_language_1.detectLanguageUsage)(cwd, config.ignoreDirs, config.detect);
+    const { decisions, cacheDir } = await planInstall(cwd, usage);
+    const present = installedProfiles(cacheDir);
+    const lines = [];
+    lines.push('PR CheckMate — install doctor');
+    lines.push('');
+    lines.push(`  version    ${packageVersion()}`);
+    lines.push(`  repository ${cwd}`);
+    lines.push(`  cache      ${cacheDir ?? 'unavailable (no writable directory)'}`);
+    lines.push(`  strategy   ${config.install?.strategy ?? 'adaptive'}`);
+    lines.push('');
+    lines.push('  Languages');
+    if (usage.length === 0)
+        lines.push('    none detected');
+    for (const u of usage) {
+        // The distinction that decides downloads: a marker declares a language, a
+        // file proves it. Only the second is worth a toolchain.
+        const evidence = u.files > 0 ? `${u.files} file(s)` : 'marker file only';
+        lines.push(`    ${u.lang.padEnd(12)} ${evidence}`);
+    }
+    lines.push('');
+    lines.push('  Profiles');
+    for (const decision of decisions) {
+        const state = decision.required ? (present.has(decision.profile) ? '✅' : '⬇️ ') : '—';
+        lines.push(`    ${state} ${decision.profile.padEnd(12)} ${decision.reason}`);
+    }
+    const missing = decisions.filter(d => d.required && !present.has(d.profile));
+    if (missing.length > 0) {
+        lines.push('');
+        lines.push(`  ${missing.length} profile(s) not installed yet. They are fetched on the next`);
+        lines.push('  run, or now with: npx pr-checkmate install');
+    }
+    const stale = (0, cache_1.stalePaths)(packageVersion(), config.install?.cacheDir);
+    if (stale.length > 0) {
+        lines.push('');
+        lines.push(`  ${stale.length} directory(ies) from other versions: npx pr-checkmate cache-prune`);
+    }
+    logger_1.logger.print(lines.join('\n'));
+}
+/** Remove cached tooling belonging to other versions of pr-checkmate. */
+function pruneCache() {
+    const config = (0, loader_1.loadProjectConfig)();
+    const stale = (0, cache_1.stalePaths)(packageVersion(), config.install?.cacheDir);
+    if (stale.length === 0) {
+        logger_1.logger.print('Nothing to prune — no tooling from other versions is cached.');
+        return;
+    }
+    for (const dir of stale) {
+        try {
+            node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+            logger_1.logger.print(`removed ${dir}`);
+        }
+        catch (err) {
+            // Another version may be running right now; refusing to delete its
+            // tooling is the correct outcome, not an error worth failing on.
+            logger_1.logger.warn(`[cache-prune]: could not remove ${dir}: ${err.message}`);
+        }
+    }
+}

package/dist/core/install/ensure.d.ts

@@ -0,0 +1,60 @@
+import type { InstallConfig } from '../../interfaces';
+import type { ProfileName } from './profiles';
+/**
+ * What happened to one profile, in the words the report and `doctor` use.
+ *
+ * `skipped` and `failed` are deliberately distinct. Skipped means we chose not
+ * to fetch — offline, `strategy: "manual"`, an explicit exclusion — and the
+ * client already knows why. Failed means we tried and could not, which is the
+ * case that has to reach the report: ticket 057 is the standing reminder that a
+ * check quietly vanishing is worse than a check failing loudly.
+ */
+export type EnsureStatus = 'cached' | 'installed' | 'skipped' | 'failed';
+export interface EnsureResult {
+    profile: ProfileName;
+    status: EnsureStatus;
+    reason: string;
+    dir?: string;
+    durationMs?: number;
+}
+/** Whether the fetch succeeded, and what to quote in the report when it did not. */
+export interface InstallOutcome {
+    ok: boolean;
+    detail?: string;
+}
+/** Options `ensureProfile` needs that do not come from the config file. */
+export interface EnsureOptions {
+    /** Repository under review — the cwd npm runs in, so the client's `.npmrc` applies. */
+    cwd: string;
+    /** pr-checkmate's own version; part of the cache path. */
+    version: string;
+    install: InstallConfig;
+    /**
+     * The fetch itself. Defaults to `npm ci`; injected by tests.
+     *
+     * A seam rather than a mock of the module: everything around the fetch — the
+     * lock, the cache stamp, the offline and strategy branches, the reasons that
+     * end up in the report — is logic worth pinning, and without this the only way
+     * to reach it is to actually download tooling from the network in a unit test.
+     */
+    installer?: (dir: string) => Promise<InstallOutcome>;
+}
+/** Where the shipped manifests live inside the installed package. */
+export declare function manifestDir(profile: string): string;
+/**
+ * Make one profile's tooling available, fetching it only if it is not already there.
+ *
+ * Idempotent by design: this is the single entry point for both the postinstall
+ * warm-up and the lazy path taken when postinstall never ran (`npm ci
+ * --ignore-scripts`, a `node_modules` restored from a CI cache). Two code paths
+ * for the same job is how the two drift apart and how one of them silently stops
+ * working.
+ *
+ * The install itself is a plain `npm ci` against a manifest we generated from our
+ * own lockfile, run from the client's repository so their `.npmrc`, registry and
+ * proxy settings apply unchanged. `--ignore-scripts` is not negotiable: we are a
+ * supply-chain tool, and running arbitrary install hooks from a security check
+ * would be indefensible. Integrity is npm's own, over the whole transitive tree —
+ * a tampered tarball aborts with `EINTEGRITY` rather than being installed.
+ */
+export declare function ensureProfile(profile: ProfileName, opts: EnsureOptions): Promise<EnsureResult>;

package/dist/core/install/ensure.js

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.manifestDir = manifestDir;
+exports.ensureProfile = ensureProfile;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const execa_1 = require("../../utils/execa");
+const logger_1 = require("../../utils/logger");
+const cache_1 = require("./cache");
+const lock_1 = require("./lock");
+/** Where the shipped manifests live inside the installed package. */
+function manifestDir(profile) {
+    return node_path_1.default.resolve(__dirname, '../../..', 'install-manifests', profile);
+}
+const stampPath = (dir) => node_path_1.default.join(dir, '.pr-checkmate-installed');
+/** The manifest pair copied into the cache; `npm ci` reads exactly these two. */
+const MANIFEST_FILES = ['package.json', 'package-lock.json'];
+const LOCKFILE = MANIFEST_FILES[1];
+/**
+ * A fingerprint of the manifest a profile directory was installed from.
+ *
+ * Comparing the lockfile hash rather than merely checking that `node_modules`
+ * exists is what makes an upgrade correct: the cache path already includes our
+ * version, but a client can also pin a `cacheDir` shared between checkouts, and
+ * a half-written directory from an interrupted install must not read as ready.
+ */
+function manifestHash(dir) {
+    try {
+        const lock = node_fs_1.default.readFileSync(node_path_1.default.join(dir, LOCKFILE));
+        return node_crypto_1.default.createHash('sha256').update(lock).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether this profile directory already holds exactly this manifest, installed. */
+function isInstalled(dir, expected) {
+    if (!expected)
+        return false;
+    try {
+        return (node_fs_1.default.readFileSync(stampPath(dir), 'utf-8').trim() === expected &&
+            node_fs_1.default.existsSync(node_path_1.default.join(dir, 'node_modules')));
+    }
+    catch {
+        return false;
+    }
+}
+/** Copy the shipped manifest into the cache so `npm ci` has something to read. */
+function stageManifest(from, to) {
+    node_fs_1.default.mkdirSync(to, { recursive: true });
+    for (const file of MANIFEST_FILES) {
+        node_fs_1.default.copyFileSync(node_path_1.default.join(from, file), node_path_1.default.join(to, file));
+    }
+}
+/**
+ * Make one profile's tooling available, fetching it only if it is not already there.
+ *
+ * Idempotent by design: this is the single entry point for both the postinstall
+ * warm-up and the lazy path taken when postinstall never ran (`npm ci
+ * --ignore-scripts`, a `node_modules` restored from a CI cache). Two code paths
+ * for the same job is how the two drift apart and how one of them silently stops
+ * working.
+ *
+ * The install itself is a plain `npm ci` against a manifest we generated from our
+ * own lockfile, run from the client's repository so their `.npmrc`, registry and
+ * proxy settings apply unchanged. `--ignore-scripts` is not negotiable: we are a
+ * supply-chain tool, and running arbitrary install hooks from a security check
+ * would be indefensible. Integrity is npm's own, over the whole transitive tree —
+ * a tampered tarball aborts with `EINTEGRITY` rather than being installed.
+ */
+async function ensureProfile(profile, opts) {
+    const { install } = opts;
+    if (install.strategy === 'manual') {
+        return { profile, status: 'skipped', reason: 'install.strategy is "manual"' };
+    }
+    const source = manifestDir(profile);
+    const expected = manifestHash(source);
+    if (!expected) {
+        return { profile, status: 'failed', reason: `no shipped manifest for profile "${profile}"` };
+    }
+    const location = (0, cache_1.resolveCacheDir)(opts.version, install.cacheDir);
+    if (!location) {
+        return {
+            profile,
+            status: 'failed',
+            reason: 'no writable cache directory (tried the configured path, ~/.cache and the temp dir)',
+        };
+    }
+    const dir = (0, cache_1.profileDir)(location.dir, profile);
+    if (isInstalled(dir, expected)) {
+        return { profile, status: 'cached', reason: 'already installed', dir };
+    }
+    if (install.offline || process.env.PR_CHECKMATE_OFFLINE === 'true') {
+        return {
+            profile,
+            status: 'skipped',
+            reason: 'install.offline is set and the profile is not in the cache',
+            dir,
+        };
+    }
+    // The lock file lives in the profile directory, so the directory has to exist
+    // before there is anything to lock. Creating it inside `withLock` would put
+    // the creation itself outside the lock, which is the race it exists to close.
+    try {
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        return { profile, status: 'failed', reason: `cannot create ${dir}: ${err.message}` };
+    }
+    const release = await (0, lock_1.withLock)(dir, install.waitTimeoutMs ?? 120000);
+    if (!release) {
+        return { profile, status: 'failed', reason: `cannot write to ${dir}`, dir };
+    }
+    try {
+        // Re-checked inside the lock: while we waited, the process we were waiting
+        // for probably did the work. Without this, waiting is pointless — every
+        // queued job would reinstall in turn.
+        if (isInstalled(dir, expected)) {
+            return { profile, status: 'cached', reason: 'installed by another process', dir };
+        }
+        return await runInstall(profile, source, dir, expected, opts);
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * The real fetch: `npm ci` against the staged manifest.
+ *
+ * Run from the repository under review so the client's `.npmrc` — registry,
+ * scopes, proxy, auth — is the one npm reads; we never substitute our own.
+ * `--ignore-scripts` is not negotiable in a supply-chain tool.
+ */
+async function npmCi(dir, opts) {
+    const result = await (0, execa_1.execa)('npm', ['ci', '--prefix', dir, '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel', 'error'], { cwd: opts.cwd, reject: false, timeout: opts.install.installTimeoutMs ?? 300000 });
+    if (result.exitCode === 0)
+        return { ok: true };
+    const detail = (result.stderr || result.stdout || '').split('\n').slice(-3).join(' ').trim();
+    return { ok: false, detail: detail || `exit ${result.exitCode}` };
+}
+/** The fetch itself, once we hold the lock and know it is needed. */
+async function runInstall(profile, source, dir, expected, opts) {
+    const started = Date.now();
+    stageManifest(source, dir);
+    const count = Object.keys(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, LOCKFILE), 'utf-8')).packages).length;
+    // Always logged, never behind --debug: this is a security tool downloading
+    // code at run time, and that must be visible in every CI log by default.
+    logger_1.logger.info(`[install]: 📦 fetching profile "${profile}" (${count} packages) → ${dir}`);
+    try {
+        const install = opts.installer ?? ((target) => npmCi(target, opts));
+        const result = await install(dir);
+        if (!result.ok) {
+            return { profile, status: 'failed', reason: `npm ci failed: ${result.detail}`, dir };
+        }
+        node_fs_1.default.writeFileSync(stampPath(dir), expected);
+        const durationMs = Date.now() - started;
+        logger_1.logger.info(`[install]: ✅ profile "${profile}" ready in ${(durationMs / 1000).toFixed(1)}s`);
+        return { profile, status: 'installed', reason: `${count} packages`, dir, durationMs };
+    }
+    catch (err) {
+        // A timeout arrives here as a thrown error. It is a skip, not a crash: the
+        // rest of the run is still worth doing, and the affected checks say why.
+        return { profile, status: 'failed', reason: `npm ci failed: ${err.message}`, dir };
+    }
+}

package/dist/core/install/lock.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether the process named in a lock is still alive.
+ *
+ * Signal 0 performs the permission and existence checks without delivering
+ * anything. `EPERM` means the process exists but belongs to another user — alive,
+ * and not ours to override.
+ */
+export declare function processAlive(pid: number): boolean;
+/**
+ * Take the lock, waiting for whoever holds it.
+ *
+ * A held lock is not an error — it is the normal path when jobs run in parallel,
+ * and the right response is to wait and then use what the other process fetched.
+ * Waiting is announced and its progress printed: a silent wait is indistinguishable
+ * from a hang, and the whole point of the log is that a client can tell the
+ * difference at a glance.
+ *
+ * @param dir Profile directory to lock.
+ * @param timeoutMs How long to wait before taking the lock by force.
+ * @param deps Injected for tests: waiting, the clock, and how liveness of the
+ *   holding process is decided. The last one matters because `process.kill(pid, 0)`
+ *   is the one part whose answer depends on the operating system, and a test that
+ *   depends on it is a test that behaves differently on a CI runner than on the
+ *   machine it was written on.
+ * @returns A release function, or `null` when the lock could not be created at
+ *   all (an unwritable directory — the caller reports that, it is not fatal here).
+ */
+export interface LockDeps {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    alive?: (pid: number) => boolean;
+}
+export declare function withLock(dir: string, timeoutMs: number, deps?: LockDeps): Promise<(() => void) | null>;

package/dist/core/install/lock.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processAlive = processAlive;
+exports.withLock = withLock;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../../utils/logger");
+const lockPath = (dir) => node_path_1.default.join(dir, '.pr-checkmate-install.lock');
+function readLock(file) {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the process named in a lock is still alive.
+ *
+ * Signal 0 performs the permission and existence checks without delivering
+ * anything. `EPERM` means the process exists but belongs to another user — alive,
+ * and not ours to override.
+ */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+async function withLock(dir, timeoutMs, deps = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
+    const alive = deps.alive ?? processAlive;
+    const file = lockPath(dir);
+    const deadline = now() + timeoutMs;
+    let announced = false;
+    for (;;) {
+        try {
+            const record = { pid: process.pid, startedAt: now(), host: 'local' };
+            node_fs_1.default.writeFileSync(file, JSON.stringify(record), { flag: 'wx' });
+            return () => {
+                try {
+                    node_fs_1.default.unlinkSync(file);
+                }
+                catch {
+                    // Already gone: another process broke a lock it believed to be stale.
+                    // Nothing to undo, and nothing worth failing a run over.
+                }
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                return null;
+        }
+        const held = readLock(file);
+        // A lock whose owner died — the job was cancelled, the container was killed —
+        // would otherwise block every later run forever. Breaking it needs to be
+        // loud: it is the one case where two installs could genuinely overlap.
+        if (held && !alive(held.pid)) {
+            logger_1.logger.warn(`[install]: ⚠️ removing a stale lock left by process ${held.pid}, which is no longer running.`);
+            try {
+                node_fs_1.default.unlinkSync(file);
+            }
+            catch {
+                // Someone else got there first; the next iteration will find it gone.
+            }
+            // Yield before retrying. Both `continue`s below used to loop straight back
+            // to `writeFileSync`, so an unlink that kept failing became a tight loop
+            // that never returned to the event loop: no output, no timer, no timeout
+            // — a process pegged at 100% until something killed it. A hang with no
+            // symptom is the worst failure mode this code could have.
+            await sleep(50);
+            continue;
+        }
+        if (now() >= deadline) {
+            logger_1.logger.warn(`[install]: ⚠️ waited ${Math.round(timeoutMs / 1000)}s for another process to finish installing — taking over.`);
+            try {
+                node_fs_1.default.unlinkSync(file);
+            }
+            catch {
+                // Same as above.
+            }
+            await sleep(50);
+            continue;
+        }
+        if (!announced) {
+            const age = held ? Math.round((now() - held.startedAt) / 1000) : 0;
+            logger_1.logger.info(`[install]: ⏳ another process is installing into ${node_path_1.default.basename(dir)} (started ${age}s ago) — waiting up to ${Math.round(timeoutMs / 1000)}s`);
+            announced = true;
+        }
+        await sleep(500);
+    }
+}