@ac-kit/app-system 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,45 @@
+# @ac-kit/app-system
+
+The things a long-running program has to do to the machine it runs on, and which
+are tedious to get right: claim a PID file without racing another copy of
+itself, roll its log files before they fill the disk, ask whether a binary is on
+`PATH`, list running processes, and run its shutdown hooks in a defined order.
+
+```typescript
+import { ExitManager, hasBinary, ps, writePidFile } from "@ac-kit/app-system";
+
+if (!(await hasBinary("ffmpeg"))) {
+  throw new Error("ffmpeg is required");
+}
+
+await writePidFile("/run/mytool.pid", process.pid);
+
+const exits = new ExitManager();
+exits.registerCleanUpHandler(async () => {
+  await flushEverything();
+});
+
+const running = await ps({ fields: ["pid", "args"] });
+```
+
+`registerCleanUpHandler` takes a priority and returns an unregister function, so
+teardown order is declared rather than implied by registration order.
+
+## What it exposes
+
+- **Process lifecycle** — `readPidFile`/`writePidFile`, `processPidFile`,
+  `processKillByPidFile`, `processWaitPid`, `ExitManager` with ordered
+  priorities, and uncaught-error listeners.
+- **Process inspection** — `ps` with filters, `getProcessesSnapshot`,
+  `hostMetrics`, and `sysfs` readers.
+- **Files** — `rotateLogFiles`, `RotatingFileSink` (optionally gzip-compressed),
+  and an artifact cache.
+- **Locks** — `FileLock` and `UdpBindLock`, for single-instance enforcement.
+- **Terminal and text** — `nodeTerminal`, the Node adapter for
+  `@ac-kit/app-terminal`'s `Terminal`, plus charset encode/decode streams.
+
+Node only, by definition: this is the host-bound layer.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/app-system/)
+for the full reference.

package/dist/async/file-lock.d.ts

@@ -0,0 +1,38 @@
+import { type ILock } from "@ac-kit/async";
+export type FileLockOptions = {
+    /**
+     * The interval in milliseconds to poll for the lock file to be released.
+     * Default is 50ms.
+     */
+    pollIntervalMs?: number;
+};
+/**
+ * A simple file-based lock mechanism.
+ *
+ * Creates a `.lock` file to indicate that a resource is locked. The lock is
+ * acquired by creating the lock file and released by deleting it. If the lock
+ * file already exists, it means the resource is locked by another process.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const lock = new LockFile("/path/to/resource");
+ * const release = await lock.acquire();
+ * try {
+ * 	// Do something with the locked resource
+ * } finally {
+ * 	await release();
+ * }
+ * ```
+ */
+export declare class FileLock implements ILock {
+    readonly filePath: string;
+    private readonly options;
+    private lockHandle;
+    constructor(filePath: string, options?: FileLockOptions);
+    get locked(): boolean;
+    tryLock(): Promise<boolean>;
+    lock(signal?: AbortSignal | null): Promise<void>;
+    unlock(): Promise<void>;
+}
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/async/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/async/file-lock.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAIjE,MAAM,MAAM,eAAe,GAAG;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAMF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,QAAS,YAAW,KAAK;aAKpB,QAAQ,EAAE,MAAM;IAJjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAsC;IAExD,YACiB,QAAQ,EAAE,MAAM,EAChC,OAAO,CAAC,EAAE,eAAe,EAGzB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAEK,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAYhC;IAEK,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrD;IAEK,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAU5B;CACD"}

package/dist/async/file-lock.js

@@ -0,0 +1,67 @@
+import * as fsPromises from "node:fs/promises";
+import { LockNotAcquiredError } from "@ac-kit/async";
+import { defaults, waitFor } from "@ac-kit/core";
+import { isNodeErrorWithCode } from "@ac-kit/node";
+const FILE_LOCK_DEFAULT_OPTIONS = {
+    pollIntervalMs: 50,
+};
+/**
+ * A simple file-based lock mechanism.
+ *
+ * Creates a `.lock` file to indicate that a resource is locked. The lock is
+ * acquired by creating the lock file and released by deleting it. If the lock
+ * file already exists, it means the resource is locked by another process.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const lock = new LockFile("/path/to/resource");
+ * const release = await lock.acquire();
+ * try {
+ * 	// Do something with the locked resource
+ * } finally {
+ * 	await release();
+ * }
+ * ```
+ */
+export class FileLock {
+    filePath;
+    options;
+    lockHandle = null;
+    constructor(filePath, options) {
+        this.filePath = filePath;
+        this.options = defaults(options, FILE_LOCK_DEFAULT_OPTIONS);
+    }
+    get locked() {
+        return this.lockHandle !== null;
+    }
+    async tryLock() {
+        try {
+            // Try to create the lock file exclusively
+            this.lockHandle = await fsPromises.open(`${this.filePath}.lock`, "wx");
+        }
+        catch (error) {
+            if (isNodeErrorWithCode(error, "EEXIST")) {
+                return false;
+            }
+            throw error;
+        }
+        return true;
+    }
+    async lock(signal) {
+        await waitFor(() => this.tryLock(), {
+            signal,
+            intervalMs: this.options.pollIntervalMs,
+        });
+    }
+    async unlock() {
+        if (!this.lockHandle) {
+            throw new LockNotAcquiredError();
+        }
+        const handle = this.lockHandle;
+        this.lockHandle = null;
+        await handle.close();
+        await fsPromises.unlink(`${this.filePath}.lock`);
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/async/file-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.js","sourceRoot":"","sources":["../../src/async/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,oBAAoB,EAAc,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAUnD,MAAM,yBAAyB,GAA8B;IAC5D,cAAc,EAAE,EAAE;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,QAAQ;IAKH,QAAQ;IAJR,OAAO,CAA4B;IAC5C,UAAU,GAAiC,IAAI,CAAC;IAExD,YACiB,QAAgB,EAChC,OAAyB;wBADT,QAAQ;QAGxB,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,IAAI,CAAC;YACJ,0CAA0C;YAC1C,IAAI,CAAC,UAAU,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,OAAO,EAAE,IAAI,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC1C,OAAO,KAAK,CAAC;YACd,CAAC;YAED,MAAM,KAAK,CAAC;QACb,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA2B;QACrC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE;YACnC,MAAM;YACN,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc;SACvC,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM;QACX,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACtB,MAAM,IAAI,oBAAoB,EAAE,CAAC;QAClC,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QAEvB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,OAAO,CAAC,CAAC;IAClD,CAAC;CACD"}

package/dist/async/udp-bind-lock.d.ts

@@ -0,0 +1,75 @@
+import { type ILock } from "@ac-kit/async";
+export type UdpBindLockConfig = {
+    /**
+     * The type of UDP socket to create, either "udp4" for IPv4 or "udp6" for
+     * IPv6.
+     *
+     * It should match the IP version of the `udpBindAddress`.
+     */
+    udpSocketType: "udp4" | "udp6";
+    /**
+     * The address to bind the UDP socket to. Default is "localhost"
+     *
+     * Example: "localhost" or "127.1.2.3" (in which case `udpSocketType` should
+     * be "udp4") or "::1" (in which case `udpSocketType` should be "udp6").
+     *
+     * Note: Using "localhost" is generally safe as it resolves to both IPv4 and
+     * IPv6 loopback addresses, but if you want to be certain about the IP
+     * version, specify the address explicitly.
+     */
+    udpBindAddress?: string | null;
+    /**
+     * The port to bind the UDP socket to.
+     *
+     * Should be a port that is unlikely to be used by other applications.
+     */
+    udpBindPort: number;
+};
+export type UdpBindLockOptions = {
+    /**
+     * Optional polling interval in milliseconds to check if the lock is still
+     * held. Default is 100 ms.
+     */
+    pollIntervalMs?: number;
+};
+/**
+ * A class that provides a mechanism to ensure that only one instance of a
+ * process is running at a time by attempting to bind to a specific UDP port.
+ *
+ * This is useful for preventing multiple instances of a script or application
+ * from running simultaneously.
+ *
+ * Note: The lock is automatically released when the process exits, but it is
+ * recommended to call `release` explicitly when the lock is no longer needed.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const lock = new UdpBindLock({
+ * 	udpSocketType: "udp4",
+ * 	udpBindPort: 12345,
+ * });
+ *
+ * const acquired = await lock.tryAcquire();
+ * if (!acquired) {
+ * 	console.error("Another instance is already running.");
+ * 	process.exit(1);
+ * }
+ *
+ * // ... application logic ...
+ *
+ * await lock.release();
+ * ```
+ */
+export declare class UdpBindLock implements ILock {
+    private readonly config;
+    private readonly options;
+    private udpSocket;
+    constructor(config: UdpBindLockConfig, options?: UdpBindLockOptions);
+    get locked(): boolean;
+    tryLock(): Promise<boolean>;
+    lock(signal?: AbortSignal | null): Promise<void>;
+    unlock(): Promise<void>;
+    private tryCreateAndBindSocket;
+}
+//# sourceMappingURL=udp-bind-lock.d.ts.map

package/dist/async/udp-bind-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"udp-bind-lock.d.ts","sourceRoot":"","sources":["../../src/async/udp-bind-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAIjE,MAAM,MAAM,iBAAiB,GAAG;IAC/B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/B;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,WAAY,YAAW,KAAK;IAKvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,SAAS,CAA4B;IAE7C,YACkB,MAAM,EAAE,iBAAiB,EAC1C,OAAO,CAAC,EAAE,kBAAkB,EAG5B;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAEK,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAEhC;IAEK,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrD;IAEK,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAO5B;YAEa,sBAAsB;CA8BpC"}

package/dist/async/udp-bind-lock.js

@@ -0,0 +1,85 @@
+import { LockNotAcquiredError } from "@ac-kit/async";
+import { defaults, waitFor } from "@ac-kit/core";
+import { DgramSocket, isNodeErrorWithCode } from "@ac-kit/node";
+const UDP_BIND_LOCK_DEFAULT_OPTIONS = {
+    pollIntervalMs: 100,
+};
+/**
+ * A class that provides a mechanism to ensure that only one instance of a
+ * process is running at a time by attempting to bind to a specific UDP port.
+ *
+ * This is useful for preventing multiple instances of a script or application
+ * from running simultaneously.
+ *
+ * Note: The lock is automatically released when the process exits, but it is
+ * recommended to call `release` explicitly when the lock is no longer needed.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const lock = new UdpBindLock({
+ * 	udpSocketType: "udp4",
+ * 	udpBindPort: 12345,
+ * });
+ *
+ * const acquired = await lock.tryAcquire();
+ * if (!acquired) {
+ * 	console.error("Another instance is already running.");
+ * 	process.exit(1);
+ * }
+ *
+ * // ... application logic ...
+ *
+ * await lock.release();
+ * ```
+ */
+export class UdpBindLock {
+    config;
+    options;
+    udpSocket = null;
+    constructor(config, options) {
+        this.config = config;
+        this.options = defaults(options, UDP_BIND_LOCK_DEFAULT_OPTIONS);
+    }
+    get locked() {
+        return this.udpSocket !== null;
+    }
+    async tryLock() {
+        return this.tryCreateAndBindSocket();
+    }
+    async lock(signal) {
+        await waitFor(async () => this.tryCreateAndBindSocket(signal), {
+            intervalMs: this.options.pollIntervalMs,
+            signal,
+        });
+    }
+    async unlock() {
+        if (!this.udpSocket) {
+            throw new LockNotAcquiredError();
+        }
+        await this.udpSocket.close();
+        this.udpSocket = null;
+    }
+    async tryCreateAndBindSocket(signal) {
+        const udpSocket = DgramSocket.from({
+            type: this.config.udpSocketType,
+            signal: signal ?? undefined,
+        });
+        // Prevent the socket from keeping the Node.js process alive
+        udpSocket.unref();
+        try {
+            await udpSocket.bind(this.config.udpBindPort, this.config.udpBindAddress ?? undefined, {
+                exclusive: true,
+            });
+        }
+        catch (error) {
+            if (isNodeErrorWithCode(error, "EADDRINUSE")) {
+                return false;
+            }
+            throw error;
+        }
+        this.udpSocket = udpSocket;
+        return true;
+    }
+}
+//# sourceMappingURL=udp-bind-lock.js.map

package/dist/async/udp-bind-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"udp-bind-lock.js","sourceRoot":"","sources":["../../src/async/udp-bind-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAc,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAuChE,MAAM,6BAA6B,GAAiC;IACnE,cAAc,EAAE,GAAG;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,WAAW;IAKL,MAAM;IAJP,OAAO,CAA+B;IAC/C,SAAS,GAAuB,IAAI,CAAC;IAE7C,YACkB,MAAyB,EAC1C,OAA4B;sBADX,MAAM;QAGvB,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,OAAO,IAAI,CAAC,sBAAsB,EAAE,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA2B;QACrC,MAAM,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAC,MAAM,CAAC,EAAE;YAC9D,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc;YACvC,MAAM;SACN,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM;QACX,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,oBAAoB,EAAE,CAAC;QAClC,CAAC;QAED,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,sBAAsB,CACnC,MAA2B;QAE3B,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC;YAClC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa;YAC/B,MAAM,EAAE,MAAM,IAAI,SAAS;SAC3B,CAAC,CAAC;QAEH,4DAA4D;QAC5D,SAAS,CAAC,KAAK,EAAE,CAAC;QAElB,IAAI,CAAC;YACJ,MAAM,SAAS,CAAC,IAAI,CACnB,IAAI,CAAC,MAAM,CAAC,WAAW,EACvB,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,SAAS,EACvC;gBACC,SAAS,EAAE,IAAI;aACf,CACD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,mBAAmB,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC;gBAC9C,OAAO,KAAK,CAAC;YACd,CAAC;YAED,MAAM,KAAK,CAAC;QACb,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,OAAO,IAAI,CAAC;IACb,CAAC;CACD"}

package/dist/fs/artifact-cache.d.ts

@@ -0,0 +1,124 @@
+export type ArtifactLifetime = 
+/** Content-addressed; survives across runs. */
+"persistent"
+/** Additionally scoped to the current run; removed when the run ends. */
+ | "run";
+export type ArtifactKey = {
+    /** Author-chosen, for a readable cache directory. Not part of identity. */
+    readonly name: string;
+    /**
+     * Everything the artifact depends on — source text, compiler flags, toolchain
+     * version. Hashed to form the identity.
+     */
+    readonly inputs: readonly (string | Uint8Array)[];
+    /** Extra identity components. Node version, platform and arch are implicit. */
+    readonly scope?: readonly string[];
+    /** Default `"persistent"`. */
+    readonly lifetime?: ArtifactLifetime;
+};
+export type ArtifactResolution = {
+    readonly key: ArtifactKey;
+    readonly directory: string;
+    /**
+     * False when this call ran `build`. A cold first run is not comparable with a
+     * warm one, so a consumer that reports timings records this.
+     */
+    readonly cacheHit: boolean;
+};
+export type ArtifactCache = {
+    /**
+     * Returns the cached directory, or invokes `build` once to populate it. Safe
+     * against concurrent callers in other processes.
+     */
+    ensure(key: ArtifactKey, build: (directory: string, signal: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<string>;
+    /** Absolute cache root. */
+    readonly root: string;
+    /**
+     * Absolute directory holding every `lifetime: "run"` artifact of this run, or
+     * `null` when no run id was given. Removing it is the owner's job: the sweep
+     * has to work when a child crashed, which is exactly when something was left
+     * behind, so it cannot be driven by what the children report.
+     */
+    readonly runRoot: string | null;
+};
+export type ArtifactCacheOptions = {
+    /** Absolute, or relative to the current working directory. */
+    readonly root: string;
+    /** Enables `lifetime: "run"`. Supplied by the runner, never by the author. */
+    readonly runId?: string;
+    /** Observes every resolution, for reporting cache hits. */
+    readonly onResolved?: (resolution: ArtifactResolution) => void;
+    /**
+     * How long to wait for a concurrent builder before building anyway. Defaults
+     * to 30 000; `0` skips the lock entirely and always builds. Raise it above
+     * the slowest expected build to make a duplicated build rare; lowering it
+     * only trades waiting for rebuilding, never correctness.
+     */
+    readonly lockWaitMs?: number;
+};
+/** Thrown when a `lifetime: "run"` artifact is requested outside a run. */
+export declare class ArtifactRunScopeUnavailableError extends Error {
+    readonly artifactName: string;
+    constructor(artifactName: string);
+}
+/**
+ * Cross-process cache for expensive setup output — a compiled reference
+ * program, a generated corpus — keyed by a hash of everything the artifact
+ * depends on rather than by an author-chosen id, so a stale artifact is
+ * impossible rather than merely unlikely.
+ *
+ * Concurrency is settled in two layers, and only the second one is
+ * load-bearing:
+ *
+ * 1. A `FileLock` beside the destination keeps concurrent callers from compiling
+ *    the same thing at once. It is acquired best-effort with a `lockWaitMs`
+ *    budget, so a lock left behind by a killed builder costs one wait and one
+ *    duplicated build instead of hanging the run forever.
+ * 2. The build goes to a temp directory and is `rename`d into place. Rename is
+ *    atomic on POSIX and within a Windows volume, so however many callers
+ *    build, exactly one artifact exists and every caller returns the same
+ *    path.
+ *
+ * @example
+ * 	Compile a reference program once, reuse it forever
+ *
+ * 	```ts
+ * 	const cache = createArtifactCache({ root: "node_modules/.cache/my-tool" });
+ * 	const source = await readFile("bench/reference.cpp", "utf8");
+ *
+ * 	const directory = await cache.ensure(
+ * 	{ name: "reference C++", inputs: [source, "-O3"], scope: [compilerVersion] },
+ * 	async (staging, signal) => {
+ * 	await run("g++", ["-O3", "-o", join(staging, "reference"), sourcePath], {
+ * 	signal,
+ * 	});
+ * 	},
+ * 	);
+ * 	const program = join(directory, "reference");
+ * 	```
+ *
+ * 	Changing the source text or `-O3` changes the identity, so the next call
+ * 	rebuilds; nothing has to remember to bump a version.
+ *
+ * @example
+ * 	Scope an artifact to one run, and sweep it afterwards
+ *
+ * 	```ts
+ * 	const cache = createArtifactCache({ root, runId, onResolved: (r) =>
+ * 	report.data({ artifact: r.key.name, cacheHit: r.cacheHit }),
+ * 	});
+ *
+ * 	await cache.ensure(
+ * 	{ name: "corpus", inputs: [spec], lifetime: "run" },
+ * 	generateCorpus,
+ * 	);
+ *
+ * 	// The owner sweeps: a crashed child cannot be asked what it left behind.
+ * 	await rm(cache.runRoot!, { recursive: true, force: true });
+ * 	```
+ *
+ * @param options Root, run scoping, hit reporting and the lock budget. See
+ *   {@link ArtifactCacheOptions}.
+ */
+export declare function createArtifactCache(options: ArtifactCacheOptions): ArtifactCache;
+//# sourceMappingURL=artifact-cache.d.ts.map

package/dist/fs/artifact-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-cache.d.ts","sourceRoot":"","sources":["../../src/fs/artifact-cache.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,gBAAgB;AAC3B,+CAA+C;AAC7C,YAAY;AACd,yEAAyE;GACvE,KAAK,CAAC;AAET,MAAM,MAAM,WAAW,GAAG;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC;IAClD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC3B;;;OAGG;IACH,MAAM,CACL,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,EAChE,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC/D;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,2EAA2E;AAC3E,qBAAa,gCAAiC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,YAAY,YAAY,EAAE,MAAM,EAM/B;CACD;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,oBAAoB,GAC3B,aAAa,CAoEf"}

package/dist/fs/artifact-cache.js

@@ -0,0 +1,183 @@
+import { mkdir, rename, rm } from "node:fs/promises";
+import { join, resolve as resolvePath } from "node:path";
+import { concatBytes, encodeTextUtf8, setUint32Be, slugify, } from "@ac-kit/core";
+import { sha256 } from "@ac-kit/crypto-hash";
+import { createTempDir, isDirectoryAsync } from "@ac-kit/node";
+import { FileLock } from "../async/file-lock.js";
+/** Thrown when a `lifetime: "run"` artifact is requested outside a run. */
+export class ArtifactRunScopeUnavailableError extends Error {
+    artifactName;
+    constructor(artifactName) {
+        super(`artifact "${artifactName}" requires lifetime "run", but the cache has no run id`);
+        this.name = "ArtifactRunScopeUnavailableError";
+        this.artifactName = artifactName;
+    }
+}
+const HASH_LENGTH = 20;
+const DEFAULT_LOCK_WAIT_MS = 30000;
+const NEVER_ABORTED = new AbortController().signal;
+/**
+ * Best-effort: `true` means this caller holds the build lock, `false` means it
+ * gave up waiting and should build unlocked rather than stall.
+ *
+ * Giving up is not a failure path. `FileLock` unlinks its file only from
+ * `unlock()`, so a builder killed mid-build — a `SIGKILL`ed child, a crashed
+ * compiler — leaves a lock nothing will ever remove. Waiting on it forever
+ * would hang every later run; waiting for a bounded time and then duplicating
+ * the work costs one wasted build.
+ */
+async function acquireBuildLock(lock, lockWaitMs, signal) {
+    if (lockWaitMs <= 0) {
+        return false;
+    }
+    const deadline = AbortSignal.timeout(lockWaitMs);
+    try {
+        await lock.lock(signal ? AbortSignal.any([signal, deadline]) : deadline);
+        return true;
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        return false;
+    }
+}
+/** Length-prefixed, so no concatenation of components can collide with another. */
+function framed(part) {
+    const bytes = typeof part === "string" ? encodeTextUtf8(part) : part;
+    const header = new Uint8Array(4);
+    setUint32Be(header, 0, bytes.length);
+    return [header, bytes];
+}
+async function hashKey(key, runId) {
+    const parts = [];
+    for (const component of [
+        process.version,
+        process.platform,
+        process.arch,
+        runId ?? "",
+        ...(key.scope ?? []),
+        ...key.inputs,
+    ]) {
+        parts.push(...framed(component));
+    }
+    return (await sha256(concatBytes(parts))).toHex().slice(0, HASH_LENGTH);
+}
+/**
+ * Cross-process cache for expensive setup output — a compiled reference
+ * program, a generated corpus — keyed by a hash of everything the artifact
+ * depends on rather than by an author-chosen id, so a stale artifact is
+ * impossible rather than merely unlikely.
+ *
+ * Concurrency is settled in two layers, and only the second one is
+ * load-bearing:
+ *
+ * 1. A `FileLock` beside the destination keeps concurrent callers from compiling
+ *    the same thing at once. It is acquired best-effort with a `lockWaitMs`
+ *    budget, so a lock left behind by a killed builder costs one wait and one
+ *    duplicated build instead of hanging the run forever.
+ * 2. The build goes to a temp directory and is `rename`d into place. Rename is
+ *    atomic on POSIX and within a Windows volume, so however many callers
+ *    build, exactly one artifact exists and every caller returns the same
+ *    path.
+ *
+ * @example
+ * 	Compile a reference program once, reuse it forever
+ *
+ * 	```ts
+ * 	const cache = createArtifactCache({ root: "node_modules/.cache/my-tool" });
+ * 	const source = await readFile("bench/reference.cpp", "utf8");
+ *
+ * 	const directory = await cache.ensure(
+ * 	{ name: "reference C++", inputs: [source, "-O3"], scope: [compilerVersion] },
+ * 	async (staging, signal) => {
+ * 	await run("g++", ["-O3", "-o", join(staging, "reference"), sourcePath], {
+ * 	signal,
+ * 	});
+ * 	},
+ * 	);
+ * 	const program = join(directory, "reference");
+ * 	```
+ *
+ * 	Changing the source text or `-O3` changes the identity, so the next call
+ * 	rebuilds; nothing has to remember to bump a version.
+ *
+ * @example
+ * 	Scope an artifact to one run, and sweep it afterwards
+ *
+ * 	```ts
+ * 	const cache = createArtifactCache({ root, runId, onResolved: (r) =>
+ * 	report.data({ artifact: r.key.name, cacheHit: r.cacheHit }),
+ * 	});
+ *
+ * 	await cache.ensure(
+ * 	{ name: "corpus", inputs: [spec], lifetime: "run" },
+ * 	generateCorpus,
+ * 	);
+ *
+ * 	// The owner sweeps: a crashed child cannot be asked what it left behind.
+ * 	await rm(cache.runRoot!, { recursive: true, force: true });
+ * 	```
+ *
+ * @param options Root, run scoping, hit reporting and the lock budget. See
+ *   {@link ArtifactCacheOptions}.
+ */
+export function createArtifactCache(options) {
+    const root = resolvePath(options.root);
+    const runId = options.runId ?? null;
+    const runRoot = runId === null ? null : join(root, `run-${runId}`);
+    const onResolved = options.onResolved;
+    const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+    return {
+        root,
+        runRoot,
+        async ensure(key, build, signal) {
+            const lifetime = key.lifetime ?? "persistent";
+            if (lifetime === "run" && runRoot === null) {
+                throw new ArtifactRunScopeUnavailableError(key.name);
+            }
+            const parent = lifetime === "run" && runRoot ? runRoot : root;
+            const digest = await hashKey(key, lifetime === "run" ? runId : null);
+            const directory = join(parent, `${slugify(key.name, { fallback: "artifact" })}-${digest}`);
+            if (await isDirectoryAsync(directory)) {
+                onResolved?.({ key, directory, cacheHit: true });
+                return directory;
+            }
+            signal?.throwIfAborted();
+            await mkdir(parent, { recursive: true });
+            const lock = new FileLock(directory);
+            const held = await acquireBuildLock(lock, lockWaitMs, signal);
+            try {
+                // Whoever held the lock may have finished while this call waited.
+                if (await isDirectoryAsync(directory)) {
+                    onResolved?.({ key, directory, cacheHit: true });
+                    return directory;
+                }
+                // Staged inside the destination's own filesystem, so rename is atomic.
+                const staging = await createTempDir(".building", parent);
+                try {
+                    await build(staging, signal ?? NEVER_ABORTED);
+                    await rename(staging, directory);
+                }
+                catch (error) {
+                    await rm(staging, { recursive: true, force: true });
+                    // A concurrent winner already renamed its own staging directory into
+                    // place; its result is as valid as the one just discarded.
+                    if (await isDirectoryAsync(directory)) {
+                        onResolved?.({ key, directory, cacheHit: true });
+                        return directory;
+                    }
+                    throw error;
+                }
+            }
+            finally {
+                if (held) {
+                    await lock.unlock();
+                }
+            }
+            onResolved?.({ key, directory, cacheHit: false });
+            return directory;
+        },
+    };
+}
+//# sourceMappingURL=artifact-cache.js.map