@nitpicker/archive 0.0.0 → 0.25.1

package/lib/archive-accessor.js

@@ -0,0 +1,477 @@
+import { raceWithTimeout } from '@d-zero/shared/race-with-timeout';
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+import { log } from './debug.js';
+import { readJSON } from './filesystem/read-json.js';
+import { readText } from './filesystem/read-text.js';
+import Page from './page.js';
+import Resource from './resource.js';
+import { safePath } from './safe-path.js';
+/**
+ * Provides read-only access to an archive's database and stored data files.
+ *
+ * This class is the base for the `Archive` class and is also returned
+ * by `Archive.connect` for read-only access to an existing archive.
+ * It supports querying pages, anchors, referrers, resources, and custom data.
+ */
+/**
+ * Default timeout for {@link ArchiveAccessor.close}'s `db.destroy()` step.
+ *
+ * `knex.destroy()` will otherwise wait the full `acquireTimeoutMillis`
+ * (10 minutes in this repo) for in-flight queries to drain. For a viewer
+ * shut down by Ctrl-C while the live crawler holds a long write lock that
+ * is an unacceptable user experience, so we bound the wait and treat the
+ * accessor as closed after the timeout regardless.
+ */
+const DEFAULT_CLOSE_TIMEOUT_MS = 5000;
+export class ArchiveAccessor extends EventEmitter {
+    /**
+     * Promise tracking an in-progress (or completed) close. `null` means the
+     * accessor is open and idle; a settled promise means we are closed (the
+     * accessor stays "closed" even if `db.destroy()` rejected, because there
+     * is nothing safe to retry — see {@link ArchiveAccessor.close}).
+     */
+    #closeOnce = null;
+    /** The SQLite database instance for querying archived data. */
+    #db;
+    /**
+     * Whether this accessor was opened in read-only mode. With HTML stored
+     * as a SQLite BLOB, this no longer toggles any code path — the SELECT
+     * is identical for writer- and reader-mode accessors. Kept on the
+     * accessor so callers like the viewer can still surface "this archive
+     * is being read read-only" UI hints without re-deriving it.
+     */
+    #readOnly;
+    /** Absolute path to the temporary working directory containing the database and files. */
+    #tmpDir;
+    /**
+     * Whether this accessor was opened in read-only mode (no filesystem
+     * mutation on `tmpDir`).
+     */
+    get readOnly() {
+        return this.#readOnly;
+    }
+    /**
+     * The absolute path to the temporary working directory used by this accessor.
+     */
+    get tmpDir() {
+        return this.#tmpDir;
+    }
+    /**
+     * Creates a new ArchiveAccessor instance.
+     * @param tmpDir - The path to the temporary directory containing the archive data.
+     * @param db - The Database instance for querying the SQLite database.
+     * @param options - Construction options.
+     * @param options.readOnly - When `true`, helpers must not mutate the
+     *   filesystem under `tmpDir` (used for live-crawl / stub-mode opens
+     *   where any write would race the crawler).
+     */
+    constructor(tmpDir, db, options = {}) {
+        super();
+        this.#tmpDir = tmpDir;
+        this.#db = db;
+        this.#readOnly = options.readOnly ?? false;
+        this.#db.on('error', (e) => {
+            void this.emit('error', e);
+        });
+    }
+    /**
+     * Enables `await using accessor = ...`. Delegates to {@link close} with
+     * the default timeout — callers that need a non-default `timeoutMs`
+     * must call `close` explicitly instead of relying on disposal.
+     *
+     * Dispatches through the instance's own `close`, so an `Archive`
+     * (which overrides `close`) gets its full teardown here too — this
+     * method does not need to be re-implemented on subclasses.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    /**
+     * Closes the underlying database connection.
+     *
+     * This is the **read-only** close path: it releases the SQLite handle and
+     * does nothing else. The temporary working directory is left untouched and
+     * no `.nitpicker` archive is produced. This makes it safe to call from
+     * read-only consumers (e.g. the viewer attached to an in-progress crawl's
+     * tmpDir), where touching the filesystem would race with — or destroy —
+     * the live crawler's working state.
+     *
+     * Subclasses that own the archive's lifecycle (notably `Archive`)
+     * override this to add write/cleanup steps.
+     *
+     * **Idempotent and concurrent-safe**: the first invocation captures the
+     * close promise; later invocations (from the same caller, a shutdown
+     * signal handler, or a parallel manager teardown) await the same
+     * promise and resolve together. If `db.destroy()` rejects, the
+     * rejection propagates to *all* awaiters and the accessor stays
+     * latched closed — a hung knex pool is not safe to "retry close".
+     *
+     * **Bounded**: when the optional `timeoutMs` (default {@link
+     * DEFAULT_CLOSE_TIMEOUT_MS}) elapses before `db.destroy()` settles, the
+     * call resolves with a warning. This prevents a viewer shutdown from
+     * being held for the underlying pool's 10-minute `acquireTimeoutMillis`
+     * when the live crawler holds the SQLite write lock.
+     * @param options - Close options.
+     * @param options.timeoutMs - Milliseconds to wait for `db.destroy()`
+     *   before giving up. Use `Infinity` to wait indefinitely (only
+     *   advisable in tests and batch jobs that own the DB exclusively).
+     */
+    async close(options = {}) {
+        if (this.#closeOnce) {
+            return this.#closeOnce;
+        }
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS;
+        this.#closeOnce = this.#runClose(timeoutMs);
+        return this.#closeOnce;
+    }
+    /**
+     * Retrieves anchor (link) data for a specific page by its database ID.
+     * @param pageId - The database ID of the page whose anchors to retrieve.
+     * @returns An array of anchor records found on the page.
+     */
+    async getAnchorsOnPage(pageId) {
+        const refs = await this.#db.getAnchorsOnPage(pageId);
+        return refs;
+    }
+    /**
+     * Retrieves the audios within the given page's detected main content
+     * region, from `page_main_content_audios`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered audio rows.
+     */
+    async getAudiosOfPage(pageId) {
+        return this.#db.getAudiosOfPage(pageId);
+    }
+    /**
+     * Retrieves the button-like elements within the given page's detected
+     * main content region, from `page_main_content_buttons`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered button rows.
+     */
+    async getButtonsOfPage(pageId) {
+        return this.#db.getButtonsOfPage(pageId);
+    }
+    /**
+     * Retrieves the canvases within the given page's detected main content
+     * region, from `page_main_content_canvases`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered canvas rows.
+     */
+    async getCanvasesOfPage(pageId) {
+        return this.#db.getCanvasesOfPage(pageId);
+    }
+    /**
+     * Retrieves the crawl configuration stored in the archive database.
+     * @returns The parsed {@link Config} object.
+     */
+    async getConfig() {
+        return this.#db.getConfig();
+    }
+    /**
+     * Retrieves the Web Components (custom elements) within the given page's
+     * detected main content region, from `page_main_content_custom_elements`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered custom-element rows.
+     */
+    async getCustomElementsOfPage(pageId) {
+        return this.#db.getCustomElementsOfPage(pageId);
+    }
+    async getData(name, format = 'json') {
+        const filePath = safePath(this.#tmpDir, `${name}.${format}`);
+        if (format === 'json') {
+            return await readJSON(filePath);
+        }
+        return await readText(filePath);
+    }
+    /**
+     * Retrieves the headings within the given page's detected main content
+     * region, from `page_main_content_headings`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered heading rows.
+     */
+    async getHeadingsOfPage(pageId) {
+        return this.#db.getHeadingsOfPage(pageId);
+    }
+    /**
+     * Reads the HTML snapshot of a page from the archive.
+     *
+     * HTML is stored as zstd-compressed BLOBs in `page_html_blobs` (keyed by
+     * SHA-256 of the raw bytes) with `page_html_ref` linking `page_id → hash`.
+     * The read is a straight join + decompress; writer- and read-only (stub)
+     * accessors take the same code path because nothing here touches the
+     * filesystem.
+     *
+     * Returns `null` when the page row exists but has no stored body — for
+     * example a redirect source, a non-HTML resource (PDF), a page that
+     * failed to render, or an external page (whose row is metadata-only).
+     * Distinguishing "no body stored" from "empty body" is preserved: an
+     * empty HTML string returns `''`, not `null`.
+     *
+     * Throws if the page's referenced blob is missing, its codec marker is
+     * unrecognised, its zstd data is corrupt, or it decompresses past
+     * `MAX_DECODED_SNAPSHOT_BYTES` — each indicates an archive that was
+     * truncated, damaged or written by a future tool, none of which we
+     * silently paper over. A decode failure names the page and the blob hash
+     * (`HTML snapshot of page <id> (page_html_blobs hash <hex>) could not be decoded: …`).
+     * @param pageId - The database id of the page to read.
+     * @returns The HTML content as a UTF-8 string, or `null` when no body
+     *   is stored for `pageId`.
+     * @example
+     * const html = await accessor.getHtmlOfPage(pageId);
+     * if (html === null) {
+     *   // page has no stored body — redirect source / non-HTML / failed render
+     * } else {
+     *   processHtml(html);
+     * }
+     */
+    async getHtmlOfPage(pageId) {
+        const html = await this.#db.getHtmlOfPageById(pageId);
+        if (html === null) {
+            log('No HTML body stored for page id=%d', pageId);
+        }
+        return html;
+    }
+    /**
+     * Retrieves the iframes within the given page's detected main content
+     * region, from `page_main_content_iframes`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered iframe rows.
+     */
+    async getIframesOfPage(pageId) {
+        return this.#db.getIframesOfPage(pageId);
+    }
+    /**
+     * Retrieves the JSON-LD / SpeculationRules entries for the given page,
+     * parsed back from the `page_jsonld` table.
+     * @param pageId - The database id of the page.
+     * @returns Ordered entries with `kind`, `type`, `raw`, `parsed`, `parseError`.
+     */
+    async getJsonLdOfPage(pageId) {
+        return this.#db.getJsonLdOfPage(pageId);
+    }
+    /**
+     * Returns the underlying Knex query builder instance for direct SQL access.
+     * Enables advanced queries (GROUP BY, HAVING, JOINs) at the database layer
+     * for performance-critical operations on large datasets.
+     * @returns The Knex instance connected to the SQLite database.
+     */
+    getKnex() {
+        return this.#db.getKnex();
+    }
+    /**
+     * Retrieves the images within the given page's detected main content
+     * region, from `page_main_content_images`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered image rows.
+     */
+    async getMainContentImagesOfPage(pageId) {
+        return this.#db.getMainContentImagesOfPage(pageId);
+    }
+    /**
+     * Retrieves the tables within the given page's detected main content
+     * region, from `page_main_content_tables`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered table rows.
+     */
+    async getMainContentTablesOfPage(pageId) {
+        return this.#db.getMainContentTablesOfPage(pageId);
+    }
+    /**
+     * Retrieves all pages from the archive, optionally filtered by type.
+     * Eagerly loads redirect relationships (`redirectFrom`) but does NOT load
+     * anchor or referrer relationships.
+     * Use {@link getPagesWithRefs} if you need those relationships.
+     * @param filter - An optional filter to narrow the results (e.g., `'internal-page'`, `'external-page'`).
+     * @returns An array of {@link Page} instances.
+     */
+    async getPages(filter) {
+        const pages = await this.#db.getPages(filter);
+        if (pages.length === 0)
+            return [];
+        const pageIds = pages.map((p) => p.id);
+        const redirects = await this.#db.getRedirectsForPages(pageIds);
+        const redirectMap = new Map();
+        for (const redirect of redirects) {
+            const current = redirectMap.get(redirect.pageId);
+            if (current) {
+                current.push(redirect);
+                continue;
+            }
+            redirectMap.set(redirect.pageId, [redirect]);
+        }
+        return pages.map((page) => new Page(this, page, redirectMap.get(page.id) || []));
+    }
+    /**
+     * Retrieves pages with their related data (redirects, anchors, referrers) in batches.
+     * Processes pages in chunks of `limit` size, calling the callback for each batch.
+     * @param limit - The maximum number of pages to load per batch.
+     * @param callback - A function called for each batch of pages with the current offset and total count.
+     * @param options - Optional URL parsing options and whether to include referrer relationships.
+     */
+    async getPagesWithRefs(limit, callback, options) {
+        const max = await this.#getPageCount();
+        let times = 0;
+        while (true) {
+            const offset = times * limit;
+            log('%d times loop: %o', times, {
+                offset,
+                limit,
+                max,
+            });
+            const pages = await this.#getPagesWithRels(offset, limit, options);
+            if (pages.length === 0) {
+                break;
+            }
+            await callback(pages, offset, max);
+            times++;
+        }
+    }
+    /**
+     * Retrieves the confidence-combined technology roll-up for the given
+     * page, from the `page_technologies` table.
+     * @param pageId - The database id of the page.
+     * @returns Technology rows with category, version, confidence, signalCount.
+     */
+    async getPageTechnologiesOfPage(pageId) {
+        return this.#db.getPageTechnologiesOfPage(pageId);
+    }
+    /**
+     * Retrieves pages that link to the specified page (incoming links).
+     * @param pageId - The database ID of the target page.
+     * @returns An array of referrer records.
+     */
+    async getReferrersOfPage(pageId) {
+        const refs = await this.#db.getReferrersOfPage(pageId);
+        return refs;
+    }
+    /**
+     * Retrieves page URLs that reference the specified resource.
+     * @param pageId - The database ID of the resource.
+     * @returns An array of page URL strings that reference this resource.
+     */
+    async getReferrersOfResource(pageId) {
+        const refs = await this.#db.getReferrersOfResource(pageId);
+        return refs;
+    }
+    /**
+     * Retrieves all sub-resources (CSS, JS, images, etc.) stored in the archive.
+     * @returns An array of {@link Resource} instances.
+     */
+    async getResources() {
+        const resources = await this.#db.getResources();
+        return resources.map((r) => new Resource(this, r));
+    }
+    /**
+     * Retrieves a flat list of all resource URLs stored in the archive.
+     * @param onProgress - Forwarded to {@link Database.getResourceUrlList} —
+     *   see that method's docs.
+     * @returns An array of resource URL strings.
+     */
+    async getResourceUrlList(onProgress) {
+        return this.#db.getResourceUrlList(onProgress);
+    }
+    /**
+     * Retrieves the raw technology-detection signals for the given page,
+     * from the `technology_signals` table.
+     * @param pageId - The database id of the page.
+     * @returns Ordered signal rows with technology, signalType, evidence, weight.
+     */
+    async getTechnologySignalsOfPage(pageId) {
+        return this.#db.getTechnologySignalsOfPage(pageId);
+    }
+    /**
+     * Retrieves the videos within the given page's detected main content
+     * region, from `page_main_content_videos`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered video rows.
+     */
+    async getVideosOfPage(pageId) {
+        return this.#db.getVideosOfPage(pageId);
+    }
+    /**
+     * Returns the total number of internal pages in the archive.
+     */
+    async #getPageCount() {
+        return this.#db.getPageCount();
+    }
+    /**
+     * Loads a batch of pages with their related data (redirects, anchors, referrers).
+     * When `withRefs` is false, loads only pages without relationships for better performance.
+     * @param offset - The number of pages to skip
+     * @param limit - The maximum number of pages to return
+     * @param options - URL parsing and referrer loading options
+     */
+    async #getPagesWithRels(offset, limit, options) {
+        if (options?.withRefs === false) {
+            const pages = await this.#db.getPages('internal-page', offset, limit);
+            return pages.map((page) => new Page(this, page));
+        }
+        const { pages, redirects, anchors, referrers } = await this.#db.getPagesWithRels(offset, limit);
+        const redirectMap = new Map();
+        const anchorMap = new Map();
+        const refersMap = new Map();
+        log('Mapping redirects');
+        for (const redirect of redirects) {
+            const current = redirectMap.get(redirect.pageId);
+            if (current) {
+                current.push(redirect);
+                continue;
+            }
+            redirectMap.set(redirect.pageId, [redirect]);
+        }
+        log('Mapping anchors');
+        for (const anchor of anchors) {
+            const current = anchorMap.get(anchor.pageId);
+            if (current) {
+                current.push(anchor);
+                continue;
+            }
+            anchorMap.set(anchor.pageId, [anchor]);
+        }
+        log('Mapping referrers');
+        for (const referrer of referrers) {
+            const current = refersMap.get(referrer.pageId);
+            if (current) {
+                current.push(referrer);
+                continue;
+            }
+            refersMap.set(referrer.pageId, [referrer]);
+        }
+        log('Create Page Data');
+        const pPages = [];
+        for (const page of pages) {
+            const pRedirects = redirectMap.get(page.id) || [];
+            const pAnchors = anchorMap.get(page.id) || [];
+            const pRefers = refersMap.get(page.id) || [];
+            pPages.push(new Page(this, page, pRedirects, pAnchors, pRefers, options?.disableQueries));
+        }
+        log('Create Page Data: Done');
+        return pPages;
+    }
+    /**
+     * Actual close worker — invoked exactly once per accessor via
+     * {@link close}'s shared promise. Races `db.destroy()` against the
+     * caller-supplied timeout; on timeout we log and resolve so the
+     * consumer (typically a process shutting down) is not blocked, even
+     * though the underlying knex pool may still be draining in the
+     * background.
+     * @param timeoutMs - Maximum time to wait for `db.destroy()`.
+     */
+    async #runClose(timeoutMs) {
+        if (!Number.isFinite(timeoutMs)) {
+            await this.#db.destroy();
+            return;
+        }
+        // Track destroy() so we can attach an error-suppressing handler if we
+        // give up waiting — otherwise a late rejection becomes an unhandled
+        // promise rejection on the process.
+        const destroy = this.#db.destroy().then(() => 'done');
+        const { timeout } = await raceWithTimeout(() => destroy, timeoutMs);
+        if (timeout) {
+            log('ArchiveAccessor.close: db.destroy() did not settle within %dms — giving up', timeoutMs);
+            destroy.catch((error) => {
+                log('ArchiveAccessor.close: late db.destroy() rejection (post-timeout): %O', error);
+            });
+        }
+    }
+}

package/lib/archive-lock.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Lock failure surfaced when an archive's tmpDir is already in use by another
+ * live process.
+ *
+ * The lock path and PID of the holder are exposed so callers (CLI / orchestrator)
+ * can render a precise error message and let operators recover manually.
+ */
+export declare class ArchiveLockError extends Error {
+    /** PID of the live process currently holding the lock, or `null` if unknown. */
+    readonly holderPid: number | null;
+    /** The lock directory path that could not be acquired. */
+    readonly lockPath: string;
+    /**
+     * @param lockPath - Absolute path of the lock directory.
+     * @param holderPid - PID stored in the lock's `pid.txt`, or `null` if unreadable.
+     */
+    constructor(lockPath: string, holderPid: number | null);
+}
+/**
+ * Acquire an advisory lock on the given tmpDir.
+ *
+ * Uses `fs.mkdir(lockPath, { recursive: false })` as the atomic primitive so
+ * that two concurrent processes targeting the same archive cannot both believe
+ * they own it. The lock is published as a sibling directory named
+ * `{tmpDir}.lock` containing a `pid.txt` file with the holder's PID.
+ *
+ * On `EEXIST` the function tries once to detect a stale lock: if the recorded
+ * PID is not alive any more (`process.kill(pid, 0)` throws `ESRCH`), the stale
+ * directory is removed and a single retry is issued. If acquisition still
+ * fails — or the holder is alive — an {@link ArchiveLockError} is thrown.
+ *
+ * The returned function releases the lock; it is idempotent so callers can put
+ * it in a `finally` block without worrying about double-release.
+ * @param tmpDir - Absolute path to the archive's temporary working directory.
+ * @returns A release function to be called when the work is done.
+ * @throws {ArchiveLockError} When the lock cannot be acquired even after a stale-lock retry.
+ * @example
+ * const releaseLock = await acquireArchiveLock(tmpDir);
+ * try {
+ *   // ... exclusive work against tmpDir ...
+ * } finally {
+ *   await releaseLock();
+ * }
+ */
+export declare function acquireArchiveLock(tmpDir: string): Promise<() => Promise<void>>;

package/lib/archive-lock.js

@@ -0,0 +1,154 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Lock failure surfaced when an archive's tmpDir is already in use by another
+ * live process.
+ *
+ * The lock path and PID of the holder are exposed so callers (CLI / orchestrator)
+ * can render a precise error message and let operators recover manually.
+ */
+export class ArchiveLockError extends Error {
+    /** PID of the live process currently holding the lock, or `null` if unknown. */
+    holderPid;
+    /** The lock directory path that could not be acquired. */
+    lockPath;
+    /**
+     * @param lockPath - Absolute path of the lock directory.
+     * @param holderPid - PID stored in the lock's `pid.txt`, or `null` if unreadable.
+     */
+    constructor(lockPath, holderPid) {
+        const suffix = holderPid === null ? '' : ` (PID ${holderPid})`;
+        super(`Archive is being used by another process${suffix}: ${lockPath}`);
+        this.name = 'ArchiveLockError';
+        this.lockPath = lockPath;
+        this.holderPid = holderPid;
+    }
+}
+/**
+ * Acquire an advisory lock on the given tmpDir.
+ *
+ * Uses `fs.mkdir(lockPath, { recursive: false })` as the atomic primitive so
+ * that two concurrent processes targeting the same archive cannot both believe
+ * they own it. The lock is published as a sibling directory named
+ * `{tmpDir}.lock` containing a `pid.txt` file with the holder's PID.
+ *
+ * On `EEXIST` the function tries once to detect a stale lock: if the recorded
+ * PID is not alive any more (`process.kill(pid, 0)` throws `ESRCH`), the stale
+ * directory is removed and a single retry is issued. If acquisition still
+ * fails — or the holder is alive — an {@link ArchiveLockError} is thrown.
+ *
+ * The returned function releases the lock; it is idempotent so callers can put
+ * it in a `finally` block without worrying about double-release.
+ * @param tmpDir - Absolute path to the archive's temporary working directory.
+ * @returns A release function to be called when the work is done.
+ * @throws {ArchiveLockError} When the lock cannot be acquired even after a stale-lock retry.
+ * @example
+ * const releaseLock = await acquireArchiveLock(tmpDir);
+ * try {
+ *   // ... exclusive work against tmpDir ...
+ * } finally {
+ *   await releaseLock();
+ * }
+ */
+export async function acquireArchiveLock(tmpDir) {
+    const lockPath = `${tmpDir}.lock`;
+    await tryAcquire(lockPath);
+    let released = false;
+    return async () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        await releaseLock(lockPath);
+    };
+}
+/**
+ * Attempt to create the lock directory and write the holder PID, handling one
+ * round of stale-lock recovery.
+ * @param lockPath - The absolute lock directory path.
+ */
+async function tryAcquire(lockPath) {
+    try {
+        await fs.mkdir(lockPath, { recursive: false });
+        await fs.writeFile(path.join(lockPath, 'pid.txt'), String(process.pid), 'utf8');
+        return;
+    }
+    catch (error) {
+        if (!isEexist(error)) {
+            throw error;
+        }
+    }
+    const holderPid = await readHolderPid(lockPath);
+    if (holderPid !== null && isProcessAlive(holderPid)) {
+        throw new ArchiveLockError(lockPath, holderPid);
+    }
+    // Stale lock — clean up and retry once. A concurrent acquirer may have
+    // already reclaimed the directory, so a second EEXIST is treated as a real
+    // collision and surfaced to the caller.
+    await fs.rm(lockPath, { recursive: true, force: true });
+    try {
+        await fs.mkdir(lockPath, { recursive: false });
+        await fs.writeFile(path.join(lockPath, 'pid.txt'), String(process.pid), 'utf8');
+    }
+    catch (error) {
+        if (isEexist(error)) {
+            const pid = await readHolderPid(lockPath);
+            throw new ArchiveLockError(lockPath, pid);
+        }
+        throw error;
+    }
+}
+/**
+ * Remove the lock directory. `ENOENT` is swallowed so `finally`-style callers
+ * tolerate an externally-cleaned lock, but any other failure (permissions,
+ * disk full, etc.) is propagated so the caller can react.
+ * @param lockPath - The absolute lock directory path.
+ */
+async function releaseLock(lockPath) {
+    try {
+        await fs.rm(lockPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+/**
+ * Read the PID stored in the lock directory's `pid.txt`.
+ * @param lockPath - The absolute lock directory path.
+ * @returns The parsed PID, or `null` if the file is missing or malformed.
+ */
+async function readHolderPid(lockPath) {
+    try {
+        const raw = await fs.readFile(path.join(lockPath, 'pid.txt'), 'utf8');
+        const pid = Number.parseInt(raw.trim(), 10);
+        return Number.isFinite(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check whether the given PID is still alive using a signal-0 probe.
+ * @param pid - The process id to probe.
+ * @returns `true` if the process exists (regardless of permission).
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but is owned by another user — still alive.
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Type-guard for an `EEXIST` filesystem error.
+ * @param error - The error value to inspect.
+ * @returns `true` when the error is a Node `EEXIST` from a filesystem call.
+ */
+function isEexist(error) {
+    return error?.code === 'EEXIST';
+}