@planu/cli 4.13.0 → 4.14.1

package/dist/engine/safety/atomic-writer.js

@@ -2,6 +2,9 @@
 import { rename, copyFile, unlink, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { withFileLock } from '../../storage/file-mutex.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 const DEFAULT_BACKUP_COUNT = 3;
 /**
  * Write JSON data atomically with backup rotation.
@@ -14,9 +17,12 @@ const DEFAULT_BACKUP_COUNT = 3;
  * On failure during steps 2-4, the `.tmp` file is cleaned up silently.
  */
 export async function writeJsonSafe(filePath, data, opts) {
+    return withFileLock(filePath, () => writeJsonSafeLocked(filePath, data, opts));
+}
+async function writeJsonSafeLocked(filePath, data, opts) {
     const backupCount = opts?.backupCount ?? DEFAULT_BACKUP_COUNT;
     const verify = opts?.verify ?? true;
-    const tmpPath = `${filePath}.tmp`;
+    const tmpPath = `${filePath}.tmp.${process.pid.toString()}.${randomBytes(4).toString('hex')}`;
     // Ensure parent directory exists
     await mkdir(dirname(filePath), { recursive: true });
     // Rotate backups if target already exists
@@ -42,8 +48,9 @@ export async function writeJsonSafe(filePath, data, opts) {
         try {
             await unlink(tmpPath);
         }
-        catch {
-            // Ignore cleanup errors
+        catch (cleanupError) {
+            // reliability-cleanup: JSON_TEMP_UNLINK — original write failure remains primary
+            reportClassifiedDegradation('JSON_TEMP_UNLINK', cleanupError);
         }
         throw err;
     }

package/dist/engine/safety/cross-process-lock.d.ts

@@ -1,52 +1,15 @@
-import type { CrossProcessLockMetadata, AcquireLockOptions, LockHandle, LockInfo } from '../../types/spec-lock-v2.js';
+import type { AcquireLockOptions, CrossProcessLockMetadata, LockHandle, LockInfo } from '../../types/spec-lock-v2.js';
 export { getLockScavengeMetrics, resetLockScavengeMetricsForTests, scavengeStaleLockArtifacts, } from './lock-scavenger.js';
 declare const HEARTBEAT_INTERVAL_MS = 30000;
 export { HEARTBEAT_INTERVAL_MS };
-/** Thrown by withSpecLock when the lock is held by another live session. */
 export declare class LockBusyError extends Error {
     readonly code: 'LOCK_BUSY';
     readonly holder: CrossProcessLockMetadata;
     constructor(holder: CrossProcessLockMetadata);
 }
-/**
- * Try to acquire a cross-process lock for `specId`.
- *
- * Returns a LockHandle on success, or null if the lock is held by another live session.
- * Stale locks (PID dead, heartbeat expired, or TTL expired) are reclaimed automatically.
- *
- * @remarks
- * NFS / SMB caveat: O_EXCL is not guaranteed atomic on network filesystems.
- * This implementation is reliable on local POSIX filesystems (APFS, HFS+, ext4, tmpfs).
- */
-export declare function acquireLock(projectPath: string, specId: string, opts?: AcquireLockOptions): Promise<LockHandle | null>;
-/**
- * Release a lock if it is still held by the given handle.
- * Idempotent: calling twice on the same handle is safe.
- * Will NOT unlink a lockfile that is now held by a different session.
- */
+export declare function acquireLock(projectPath: string, specId: string, options?: AcquireLockOptions): Promise<LockHandle | null>;
 export declare function releaseLock(handle: LockHandle): Promise<void>;
-/**
- * Read the current lockfile state for a spec.
- * Returns null when no lockfile exists.
- * Enriches the result with computed staleness fields.
- */
 export declare function isLocked(projectPath: string, specId: string): Promise<LockInfo | null>;
-/**
- * List all cross-process locks for a project, filtering out stale ones.
- * Non-existent `.locks/` directory returns an empty array.
- */
 export declare function listActiveCrossProcessLocks(projectPath: string): Promise<LockInfo[]>;
-/**
- * High-level wrapper: acquire → run fn → release.
- * Automatically sets up a 30s heartbeat and tears it down on completion.
- * Throws LockBusyError if the lock cannot be acquired.
- *
- * @example
- * ```ts
- * await withSpecLock(projectPath, specId, async (_handle) => {
- *   await mutatSpec();
- * }, { reason: 'update_status(approved)' });
- * ```
- */
-export declare function withSpecLock<T>(projectPath: string, specId: string, fn: (handle: LockHandle) => Promise<T>, opts?: AcquireLockOptions): Promise<T>;
+export declare function withSpecLock<T>(projectPath: string, specId: string, fn: (handle: LockHandle) => Promise<T>, options?: AcquireLockOptions): Promise<T>;
 //# sourceMappingURL=cross-process-lock.d.ts.map