@planu/cli 4.13.0 → 4.14.1

package/dist/engine/safety/file-mutex.js

@@ -1,113 +1,181 @@
-// SPEC-094 AC-4: File-based mutex for resource locking
-import { writeFile, readFile, unlink, mkdir } from 'node:fs/promises';
-import { createHash } from 'node:crypto';
-const LOCK_DIR = 'data/.locks';
-const STALE_THRESHOLD_MS = 30_000;
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { LockLeaseStore } from './lock-lease-store.js';
+import { assertNoObsoleteFileLock } from './obsolete-lock-guard.js';
+const NAMESPACE = 'file-mutex';
+const SCOPE_ID = 'global';
 const DEFAULT_TIMEOUT_MS = 10_000;
 const POLL_INTERVAL_MS = 100;
+const MAX_LEASE_MS = 86_400_000;
 function hashResource(resource) {
-    return createHash('sha256').update(resource).digest('hex').slice(0, 16);
+    return createHash('sha256').update(resource).digest('hex');
 }
-/* v8 ignore next 8 -- process.kill(pid, 0) is OS-dependent, not unit-testable */
-function isProcessRunning(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
+function obsoleteFileLockPath(resource) {
+    const legacyHash = createHash('sha256').update(resource).digest('hex').slice(0, 16);
+    return join(dirname(resolveStorageLayout().lockDatabase), `${legacyHash}.lock`);
 }
-/* v8 ignore start -- depends on isProcessRunning which is OS-dependent */
-function isStale(content) {
-    const lockAge = Date.now() - new Date(content.timestamp).getTime();
-    if (lockAge > STALE_THRESHOLD_MS) {
-        return true;
-    }
-    if (!isProcessRunning(content.pid)) {
-        return true;
+function processIsDead(pid, ownerHostname) {
+    if (ownerHostname !== hostname()) {
+        return false;
     }
-    return false;
-}
-/* v8 ignore stop */
-async function tryReadLock(lockPath) {
     try {
-        const raw = await readFile(lockPath, 'utf-8');
-        return JSON.parse(raw);
+        process.kill(pid, 0);
+        return false;
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error.code === 'ESRCH') {
+            return true;
+        }
+        reportClassifiedDegradation('LOCK_OWNER_PROBE', error);
+        return false;
     }
 }
-async function ensureLockDir() {
-    await mkdir(LOCK_DIR, { recursive: true });
+function makeCandidate(resourceId, nowMs) {
+    return {
+        namespace: NAMESPACE,
+        scopeId: SCOPE_ID,
+        resourceId,
+        lockId: randomUUID(),
+        sessionId: process.env.PLANU_SESSION_ID ?? randomUUID(),
+        pid: process.pid,
+        hostname: hostname(),
+        nowMs,
+        leaseExpiresAtMs: nowMs + MAX_LEASE_MS,
+        hardExpiresAtMs: nowMs + MAX_LEASE_MS,
+        reason: 'serialized file mutation',
+    };
 }
-/**
- * Acquires a file-based lock for a named resource.
- * Polls until the lock is available or timeout expires.
- * Stale locks (old timestamp or dead PID) are auto-released.
- */
+/** Acquire a transactional mutex for a named file resource. */
 export async function acquireLock(resource, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    await ensureLockDir();
-    const hash = hashResource(resource);
-    const lockPath = `${LOCK_DIR}/${hash}.lock`;
+    const resourceId = hashResource(resource);
+    await assertNoObsoleteFileLock(obsoleteFileLockPath(resource), resource);
     const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const existing = await tryReadLock(lockPath);
-        if (existing) {
-            if (isStale(existing)) {
-                try {
-                    await unlink(lockPath);
-                }
-                catch {
-                    // Another process may have already removed it
+    do {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const nowMs = Date.now();
+            const candidate = makeCandidate(resourceId, nowMs);
+            const store = __addDisposableResource(env_1, new LockLeaseStore(), false);
+            let acquired = store.acquire(candidate);
+            if (acquired === undefined) {
+                const current = store.get(candidate);
+                if (current !== undefined && processIsDead(current.pid, current.hostname)) {
+                    acquired = store.reclaim({
+                        namespace: NAMESPACE,
+                        scopeId: SCOPE_ID,
+                        resourceId,
+                        expectedLockId: current.lockId,
+                        expectedFencingToken: current.fencingToken,
+                        nowMs,
+                        ownerDead: true,
+                        candidate,
+                    });
                 }
             }
-            else {
-                await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-                continue;
+            if (acquired !== undefined) {
+                return {
+                    resource,
+                    resourceId,
+                    scopeId: SCOPE_ID,
+                    lockId: acquired.lockId,
+                    fencingToken: acquired.fencingToken,
+                    lockPath: resolveStorageLayout().lockDatabase,
+                    pid: process.pid,
+                    acquiredAt: new Date(acquired.acquiredAtMs).toISOString(),
+                };
+            }
+            if (Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
             }
         }
-        const content = {
-            pid: process.pid,
-            timestamp: new Date().toISOString(),
-            resource,
-        };
-        try {
-            await writeFile(lockPath, JSON.stringify(content, null, 2), {
-                flag: 'wx',
-            });
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
         }
-        catch /* v8 ignore start */ {
-            // File was created between our check and write — retry
-            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-            continue;
-        } /* v8 ignore stop */
-        return {
-            resource,
-            lockPath,
-            pid: process.pid,
-            acquiredAt: content.timestamp,
-        };
-    }
-    const error = new Error(`Lock timeout after ${timeoutMs}ms for resource "${resource}". Another process holds the lock.`);
+        finally {
+            __disposeResources(env_1);
+        }
+    } while (Date.now() < deadline);
+    const error = new Error(`Lock timeout after ${String(timeoutMs)}ms for resource "${resource}". Another process holds the lock.`);
     error.code = 'LOCK_TIMEOUT';
     throw error;
 }
-/**
- * Releases a previously acquired lock.
- * No-op if the lock file was already removed.
- */
-export async function releaseLock(handle) {
+/** Release only the exact acquisition represented by this handle. */
+export function releaseLock(handle) {
+    const env_2 = { stack: [], error: void 0, hasError: false };
     try {
-        await unlink(handle.lockPath);
+        const store = __addDisposableResource(env_2, new LockLeaseStore(), false);
+        store.release({
+            namespace: NAMESPACE,
+            scopeId: handle.scopeId,
+            resourceId: handle.resourceId,
+            lockId: handle.lockId,
+            fencingToken: handle.fencingToken,
+            nowMs: Date.now(),
+        });
+        return Promise.resolve();
     }
-    catch (err) {
-        /* v8 ignore start -- defensive: non-ENOENT errors from unlink */
-        if (err.code !== 'ENOENT') {
-            throw err;
-        }
-        /* v8 ignore stop */
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
+    }
+    finally {
+        __disposeResources(env_2);
     }
 }
 //# sourceMappingURL=file-mutex.js.map

package/dist/engine/safety/health-monitor.js

@@ -1,6 +1,7 @@
 // SPEC-094 AC-8: Health monitoring for storage and service
 import { access, constants, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 function aggregateStatus(checks) {
     if (checks.some((c) => c.status === 'fail')) {
         return 'unhealthy';
@@ -18,7 +19,9 @@ export async function checkStorageHealth(projectPath) {
         await access(projectPath, constants.W_OK);
         checks.push({ name: 'disk-writable', status: 'pass', message: 'Project path is writable' });
     }
-    catch {
+    catch (error) {
+        // reliability-optional: HEALTH_PROJECT_WRITE — typed health result records failure
+        reportClassifiedDegradation('HEALTH_PROJECT_WRITE', error);
         checks.push({ name: 'disk-writable', status: 'fail', message: 'Project path is not writable' });
     }
     // 2. specs-json
@@ -33,7 +36,9 @@ export async function checkStorageHealth(projectPath) {
         await access(dataDir, constants.R_OK);
         checks.push({ name: 'data-dir-exists', status: 'pass', message: 'Data directory exists' });
     }
-    catch {
+    catch (error) {
+        // reliability-optional: HEALTH_DATA_READ — typed health result records failure
+        reportClassifiedDegradation('HEALTH_DATA_READ', error);
         checks.push({ name: 'data-dir-exists', status: 'fail', message: 'Data directory not found' });
     }
     return {
@@ -46,16 +51,20 @@ async function checkJsonFile(filePath, checkName) {
     try {
         await access(filePath, constants.R_OK);
     }
-    catch {
-        // File not existing is OK (not yet created)
-        return { name: checkName, status: 'pass', message: `${checkName} not found (optional)` };
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { name: checkName, status: 'pass', message: `${checkName} not found (optional)` };
+        }
+        return { name: checkName, status: 'fail', message: `${checkName} is unreadable` };
     }
     try {
         const content = await readFile(filePath, 'utf-8');
         JSON.parse(content);
         return { name: checkName, status: 'pass', message: `${checkName} is valid JSON` };
     }
-    catch {
+    catch (error) {
+        // reliability-optional: HEALTH_JSON_PARSE — typed health result records corruption
+        reportClassifiedDegradation('HEALTH_JSON_PARSE', error);
         return { name: checkName, status: 'fail', message: `${checkName} contains corrupt JSON` };
     }
 }

package/dist/engine/safety/lock-lease-store.d.ts

@@ -0,0 +1,79 @@
+export interface LockLeaseKey {
+    readonly namespace: string;
+    readonly scopeId: string;
+    readonly resourceId: string;
+}
+export interface LockLeaseCandidate extends LockLeaseKey {
+    readonly lockId: string;
+    readonly sessionId: string;
+    readonly pid: number;
+    readonly hostname: string;
+    readonly nowMs: number;
+    readonly leaseExpiresAtMs: number;
+    readonly hardExpiresAtMs: number;
+    readonly reason?: string;
+}
+export interface LockLeaseRecord extends LockLeaseKey {
+    readonly lockId: string;
+    readonly sessionId: string;
+    readonly pid: number;
+    readonly hostname: string;
+    readonly acquiredAtMs: number;
+    readonly heartbeatAtMs: number;
+    readonly leaseExpiresAtMs: number;
+    readonly hardExpiresAtMs: number;
+    readonly fencingToken: number;
+    readonly reason?: string;
+}
+export interface LockLeaseStoreOptions {
+    readonly path?: string;
+    readonly busyTimeoutMs?: number;
+}
+export interface LockLeaseExpectedInput extends LockLeaseKey {
+    readonly expectedLockId: string;
+    readonly expectedFencingToken: number;
+    readonly nowMs: number;
+    readonly ownerDead?: boolean;
+}
+export interface LockLeaseListInput {
+    readonly namespace?: string;
+    readonly scopeId?: string;
+}
+/** Dedicated SQLite authority for cross-process leases and monotonic fencing tokens. */
+export declare class LockLeaseStore implements Disposable {
+    readonly path: string;
+    readonly schemaVersion = 1;
+    private readonly database;
+    private closed;
+    constructor(options?: LockLeaseStoreOptions);
+    private configureJournal;
+    private assertOpen;
+    private protectDatabaseFiles;
+    private migrate;
+    private transaction;
+    private row;
+    private nextFencingToken;
+    private preserveFence;
+    private insert;
+    acquire(candidate: LockLeaseCandidate): LockLeaseRecord | undefined;
+    reclaim(input: LockLeaseExpectedInput & {
+        readonly candidate: LockLeaseCandidate;
+    }): LockLeaseRecord | undefined;
+    heartbeat(input: LockLeaseKey & {
+        readonly lockId: string;
+        readonly fencingToken: number;
+        readonly nowMs: number;
+        readonly leaseExpiresAtMs: number;
+    }): boolean;
+    release(input: LockLeaseKey & {
+        readonly lockId: string;
+        readonly fencingToken: number;
+        readonly nowMs: number;
+    }): boolean;
+    get(keyInput: LockLeaseKey): LockLeaseRecord | undefined;
+    list(input?: LockLeaseListInput): readonly LockLeaseRecord[];
+    scavengeLease(input: LockLeaseExpectedInput): boolean;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=lock-lease-store.d.ts.map