pr-checkmate 3.0.4 → 3.1.0

package/dist/esm/core/install/doctor.js

@@ -0,0 +1,164 @@
+import fs from 'node:fs';
+import { loadProjectConfig } from '../../config/loader.js';
+import { detectLanguageUsage } from '../../utils/detect-language.js';
+import { logger } from '../../utils/logger.js';
+import { packageVersion } from '../../utils/package-version.js';
+import { resolveCacheDir, stalePaths } from './cache.js';
+import { cachedProfiles, ensureTooling } from './ensure.js';
+import { profileSatisfiedLocally } from './prepare.js';
+import { planProfiles, PROFILES } from './profiles.js';
+// Re-exported: `doctor` has been the home of this since ticket 064, and the
+// callers that import it from here are not worth churning. The reader itself
+// moved to utils so the report header and the update notice share one answer.
+export { packageVersion };
+/**
+ * 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 async function planInstall(cwd = process.cwd(), usage) {
+    const config = loadProjectConfig();
+    const detected = usage ?? (await detectLanguageUsage(cwd, config.ignoreDirs, config.detect));
+    const location = resolveCacheDir(packageVersion(), config.install?.cacheDir);
+    return { decisions: planProfiles(detected, config), cacheDir: location?.dir ?? null };
+}
+/**
+ * Which profiles are usable right now, and why — fetched, or shipped with us.
+ *
+ * The cache is only half the answer, and reporting only that half was a lie in
+ * the client's favour's opposite direction: most profiles ship inside the
+ * package, are never fetched, and were listed as "not installed yet" on a machine
+ * where they worked perfectly. `doctor` exists to answer "why did my typecheck
+ * not run", so telling someone seven profiles are missing when six of them are
+ * present sends them to debug nothing.
+ *
+ * The cached half is read from the tooling directory's own stamp rather than
+ * inferred from paths: there is one tree for everything fetched, so what went
+ * into it is recorded rather than visible in the layout (ticket 087).
+ */
+function installedProfiles(cacheDir) {
+    const present = new Map();
+    for (const profile of PROFILES) {
+        if (profileSatisfiedLocally(profile))
+            present.set(profile.name, 'ships with the package');
+    }
+    if (cacheDir) {
+        for (const name of cachedProfiles(cacheDir))
+            present.set(name, 'fetched');
+    }
+    return present;
+}
+/**
+ * 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 async function installProfiles(cwd = process.cwd(), all = false) {
+    const config = loadProjectConfig();
+    const install = config.install ?? {};
+    const { decisions } = await planInstall(cwd);
+    const denied = new Set(install.deny ?? []);
+    const wanted = (all ? PROFILES.map(p => p.name) : decisions.filter(d => d.required).map(d => d.profile)).filter(name => {
+        const profile = PROFILES.find(p => p.name === name);
+        // Nothing to fetch for a profile whose packages already ship with us, and
+        // fetching it anyway is not merely wasted: `--all` downloaded a second copy
+        // of every bundled profile — some 800 packages — beside the ones already in
+        // `node_modules`. On a container build that lands in the image (ticket 083).
+        if (profile && profileSatisfiedLocally(profile)) {
+            logger.info(`[install]: profile "${name}" already ships with the package`);
+            return false;
+        }
+        const blocked = profile?.packages.filter(pkg => denied.has(pkg)) ?? [];
+        if (blocked.length === 0)
+            return true;
+        logger.info(`[install]: profile "${name}" skipped — install.deny lists ${blocked.join(', ')}`);
+        return false;
+    });
+    // One install for the whole set. Profiles that share hundreds of packages used
+    // to be fetched into a tree each, which fought over npm's cache and downloaded
+    // the shared half once per profile (ticket 087).
+    const result = await ensureTooling(wanted, {
+        cwd,
+        version: packageVersion(),
+        install,
+    });
+    return [result];
+}
+/**
+ * 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 async function runDoctor(cwd = process.cwd()) {
+    const config = loadProjectConfig();
+    const usage = await 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 source = present.get(decision.profile);
+        const state = decision.required ? (source ? '✅' : '⬇️ ') : '—';
+        // Where a present profile came from, because "it works" and "it works
+        // because it was downloaded onto this runner" are different situations for
+        // anyone debugging a cache or an air-gapped build.
+        const how = decision.required && source ? ` (${source})` : '';
+        lines.push(`    ${state} ${decision.profile.padEnd(12)} ${decision.reason}${how}`);
+    }
+    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 = 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.print(lines.join('\n'));
+}
+/** Remove cached tooling belonging to other versions of pr-checkmate. */
+export function pruneCache() {
+    const config = loadProjectConfig();
+    const stale = stalePaths(packageVersion(), config.install?.cacheDir);
+    if (stale.length === 0) {
+        logger.print('Nothing to prune — no tooling from other versions is cached.');
+        return;
+    }
+    for (const dir of stale) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            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.warn(`[cache-prune]: could not remove ${dir}: ${err.message}`);
+        }
+    }
+}

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

@@ -0,0 +1,77 @@
+import type { InstallConfig } from '../../interfaces/index.js';
+import type { ProfileName } from './profiles.js';
+/**
+ * What happened to the tooling cache, 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.
+ */
+type EnsureStatus = 'cached' | 'installed' | 'skipped' | 'failed';
+export interface EnsureResult {
+    status: EnsureStatus;
+    reason: string;
+    dir?: string;
+    /** Profiles the directory holds once this call is done. */
+    profiles: ProfileName[];
+    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 `ensureTooling` 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;
+/**
+ * Which profiles the tooling cache holds, as recorded by the install that filled it.
+ *
+ * The one way to ask, so the stamp's format has a single owner. There is one tree
+ * for all fetched tooling now, so what is in it is written down rather than
+ * readable from the directory layout.
+ */
+export declare function cachedProfiles(cacheDir: string): ProfileName[];
+/**
+ * Make a set of profiles' tooling available, fetching only what is not already there.
+ *
+ * Idempotent by design: this is the single entry point for both the `install`
+ * command and the lazy path taken when it was never run (`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.
+ *
+ * Everything needed goes into **one** tree. Profiles overlap heavily — `js` and
+ * `commitlint` share 30 MB — and a directory each left npm nothing to
+ * deduplicate: 267 MB against the 211 one merged tree costs for the same set
+ * (ticket 087). The set only ever grows: a run needing a profile the directory
+ * lacks reinstalls the union, so nothing already fetched is lost.
+ *
+ * The install itself is a plain `npm ci` against a manifest merged from the ones
+ * 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 ensureTooling(wanted: ProfileName[], opts: EnsureOptions): Promise<EnsureResult>;
+export {};

package/dist/esm/core/install/ensure.js

@@ -0,0 +1,269 @@
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __dirnameFn } from 'node:path';
+const __dirname = __dirnameFn(__fileURLToPath(import.meta.url));
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execa } from '../../utils/execa.js';
+import { logger } from '../../utils/logger.js';
+import { findOwnPackageRoot } from '../../utils/own-deps.js';
+import { resolveCacheDir, toolingDir } from './cache.js';
+import { withLock } from './lock.js';
+import { mergeManifests } from './merge.js';
+/** Where the shipped manifests live inside the installed package. */
+export function manifestDir(profile) {
+    return path.join(findOwnPackageRoot() ?? path.resolve(__dirname, '../../..'), 'install-manifests', profile);
+}
+const stampPath = (dir) => path.join(dir, '.pr-checkmate-installed');
+const MANIFEST = 'package.json';
+const LOCKFILE = 'package-lock.json';
+/**
+ * Merge the shipped manifests for a set of profiles, or say which one is missing.
+ *
+ * Returns `null` rather than throwing on a missing manifest, because that is an
+ * ordinary condition: a stamp written by another version can name a profile this
+ * one no longer ships. A *disagreement* between two manifests is different and
+ * still throws — see {@link mergeManifests}.
+ */
+function manifestFor(profiles) {
+    const dirs = profiles.map(name => ({ name, dir: manifestDir(name) }));
+    if (dirs.some(d => !fs.existsSync(path.join(d.dir, LOCKFILE))))
+        return null;
+    return mergeManifests(dirs);
+}
+/**
+ * A fingerprint of the manifest a tooling 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 hashOf(manifest) {
+    return crypto.createHash('sha256').update(JSON.stringify(manifest.lockfile)).digest('hex');
+}
+function readStamp(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(stampPath(dir), 'utf-8'));
+        return Array.isArray(parsed.profiles) && typeof parsed.hash === 'string' ? parsed : null;
+    }
+    catch {
+        // Unreadable, absent, or written by a version that stamped a bare hash.
+        // All three mean the same thing here: we cannot claim to know what is there.
+        return null;
+    }
+}
+/**
+ * Whether the directory already holds everything asked for.
+ *
+ * A **superset** check, not an equality one, and that is the point of the shared
+ * directory. `install --all` warms the cache with every profile; a run that needs
+ * two of them must read that as ready, or the pre-warming built into our Docker
+ * image buys nothing — the failure ticket 083 was about. It is also what makes a
+ * language added six months later cost one install rather than one per run.
+ *
+ * The stamp's own hash is re-derived from the manifests we ship *now*, so a
+ * directory installed by a build with different manifests is correctly rejected
+ * even when its profile list still looks right.
+ */
+function holdsAll(dir, stamp, needed) {
+    if (!stamp || !fs.existsSync(path.join(dir, 'node_modules')))
+        return false;
+    if (!needed.every(p => stamp.profiles.includes(p)))
+        return false;
+    const installed = manifestFor(stamp.profiles);
+    return installed !== null && hashOf(installed) === stamp.hash;
+}
+/** Write the merged manifest into the cache so `npm ci` has something to read. */
+function writeManifest(dir, manifest) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, MANIFEST), JSON.stringify(manifest.pkg, null, 2));
+    fs.writeFileSync(path.join(dir, LOCKFILE), JSON.stringify(manifest.lockfile, null, 2));
+}
+/** Sorted, de-duplicated, so a set is one set however it was assembled. */
+const normalise = (profiles) => [...new Set(profiles)].sort();
+/**
+ * Which profiles the tooling cache holds, as recorded by the install that filled it.
+ *
+ * The one way to ask, so the stamp's format has a single owner. There is one tree
+ * for all fetched tooling now, so what is in it is written down rather than
+ * readable from the directory layout.
+ */
+export function cachedProfiles(cacheDir) {
+    const dir = toolingDir(cacheDir);
+    if (!fs.existsSync(path.join(dir, 'node_modules')))
+        return [];
+    return readStamp(dir)?.profiles ?? [];
+}
+/**
+ * Make a set of profiles' tooling available, fetching only what is not already there.
+ *
+ * Idempotent by design: this is the single entry point for both the `install`
+ * command and the lazy path taken when it was never run (`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.
+ *
+ * Everything needed goes into **one** tree. Profiles overlap heavily — `js` and
+ * `commitlint` share 30 MB — and a directory each left npm nothing to
+ * deduplicate: 267 MB against the 211 one merged tree costs for the same set
+ * (ticket 087). The set only ever grows: a run needing a profile the directory
+ * lacks reinstalls the union, so nothing already fetched is lost.
+ *
+ * The install itself is a plain `npm ci` against a manifest merged from the ones
+ * 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 async function ensureTooling(wanted, opts) {
+    const { install } = opts;
+    const needed = normalise(wanted);
+    if (needed.length === 0) {
+        return { status: 'cached', reason: 'nothing to fetch', profiles: [] };
+    }
+    const location = resolveCacheDir(opts.version, install.cacheDir);
+    if (!location) {
+        return {
+            status: 'failed',
+            reason: 'no writable cache directory (tried the configured path, ~/.cache and the temp dir)',
+            profiles: [],
+        };
+    }
+    const dir = toolingDir(location.dir);
+    const stamp = readStamp(dir);
+    if (holdsAll(dir, stamp, needed)) {
+        return { status: 'cached', reason: 'already installed', dir, profiles: stamp?.profiles ?? [] };
+    }
+    // Never shrink: whatever the directory already holds stays, or a repository
+    // that alternates between two languages would reinstall on every run.
+    const target = normalise([...(stamp?.profiles ?? []), ...needed]);
+    let installing = target;
+    let manifest = manifestFor(target);
+    if (!manifest) {
+        // The stamp names a profile this version no longer ships. Keeping it would
+        // make the directory permanently un-installable; dropping it costs a refetch
+        // of tooling that is obsolete anyway.
+        installing = needed;
+        manifest = manifestFor(needed);
+    }
+    if (!manifest) {
+        return {
+            status: 'failed',
+            reason: `no shipped manifest for ${needed.join(', ')}`,
+            profiles: [],
+        };
+    }
+    // Both of these mean "do not fetch", and both are asked AFTER the cache check
+    // above — because neither means "do not use what has already been fetched".
+    //
+    // `offline` was always in the right place; `manual` was not, and returned before
+    // the cache was ever looked at. So `install --all`, the command the product's
+    // own log recommends for pre-warming, did nothing for anyone who then set
+    // `manual` — including our Docker image, which sets it precisely because
+    // everything is supposed to already be there. `Python Types` in that image
+    // could not run at all (ticket 083).
+    // The env var as well as the config key, exactly as `PR_CHECKMATE_OFFLINE` is
+    // read below: the Docker image sets the strategy through the environment, and a
+    // guarantee that only holds when it is written in a config file is not a
+    // guarantee.
+    const strategy = process.env.PR_CHECKMATE_INSTALL_STRATEGY ?? install.strategy;
+    if (strategy === 'manual') {
+        return {
+            status: 'skipped',
+            reason: 'install.strategy is "manual" and the tooling is not in the cache',
+            dir,
+            profiles: stamp?.profiles ?? [],
+        };
+    }
+    if (install.offline || process.env.PR_CHECKMATE_OFFLINE === 'true') {
+        return {
+            status: 'skipped',
+            reason: 'install.offline is set and the tooling is not in the cache',
+            dir,
+            profiles: stamp?.profiles ?? [],
+        };
+    }
+    // The lock file lives in the tooling 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 {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            reason: `cannot create ${dir}: ${err.message}`,
+            profiles: [],
+        };
+    }
+    const release = await withLock(dir, install.waitTimeoutMs ?? 120000);
+    if (!release) {
+        return { status: 'failed', reason: `cannot write to ${dir}`, dir, profiles: [] };
+    }
+    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 (holdsAll(dir, readStamp(dir), needed)) {
+            return {
+                status: 'cached',
+                reason: 'installed by another process',
+                dir,
+                profiles: readStamp(dir)?.profiles ?? [],
+            };
+        }
+        return await runInstall(installing, manifest, dir, 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 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(profiles, manifest, dir, opts) {
+    const started = Date.now();
+    writeManifest(dir, manifest);
+    const named = profiles.join(', ');
+    const count = Object.keys(manifest.lockfile.packages).length - 1;
+    // 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.info(`[install]: 📦 fetching tooling for ${named} (${count} packages) → ${dir}`);
+    try {
+        const install = opts.installer ?? ((target) => npmCi(target, opts));
+        const result = await install(dir);
+        if (!result.ok) {
+            return { status: 'failed', reason: `npm ci failed: ${result.detail}`, dir, profiles: [] };
+        }
+        const stamp = { hash: hashOf(manifest), profiles };
+        fs.writeFileSync(stampPath(dir), JSON.stringify(stamp));
+        const durationMs = Date.now() - started;
+        logger.info(`[install]: ✅ tooling ready in ${(durationMs / 1000).toFixed(1)}s (${named})`);
+        return { status: 'installed', reason: `${count} packages`, dir, profiles, 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 {
+            status: 'failed',
+            reason: `npm ci failed: ${err.message}`,
+            dir,
+            profiles: [],
+        };
+    }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 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).
+ */
+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>;
+export {};

package/dist/esm/core/install/lock.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../../utils/logger.js';
+const lockPath = (dir) => path.join(dir, '.pr-checkmate-install.lock');
+function readLock(file) {
+    try {
+        return JSON.parse(fs.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.
+ */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+export 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' };
+            fs.writeFileSync(file, JSON.stringify(record), { flag: 'wx' });
+            return () => {
+                try {
+                    fs.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.warn(`[install]: ⚠️ removing a stale lock left by process ${held.pid}, which is no longer running.`);
+            try {
+                fs.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.warn(`[install]: ⚠️ waited ${Math.round(timeoutMs / 1000)}s for another process to finish installing — taking over.`);
+            try {
+                fs.unlinkSync(file);
+            }
+            catch {
+                // Same as above.
+            }
+            await sleep(50);
+            continue;
+        }
+        if (!announced) {
+            const age = held ? Math.round((now() - held.startedAt) / 1000) : 0;
+            logger.info(`[install]: ⏳ another process is installing into ${path.basename(dir)} (started ${age}s ago) — waiting up to ${Math.round(timeoutMs / 1000)}s`);
+            announced = true;
+        }
+        await sleep(500);
+    }
+}