@agent-workspace/utils 0.7.0 → 0.8.3

package/dist/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE5E;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAQ3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,CAEhG;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAEpF"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG5E;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAQ3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,CAEhG;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAEpF"}

package/dist/frontmatter.js

@@ -1,5 +1,6 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import matter from "gray-matter";
+import { atomicWriteFile } from "./safe-io.js";
 /**
  * Parse an AWP workspace file (Markdown with YAML frontmatter).
  *
@@ -32,7 +33,7 @@ export function serializeWorkspaceFile(file) {
  */
 export async function writeWorkspaceFile(file) {
     const content = serializeWorkspaceFile(file);
-    await writeFile(file.filePath, content, "utf-8");
+    await atomicWriteFile(file.filePath, content);
 }
 /**
  * Extract the type from frontmatter data.

package/dist/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO;QACL,WAAW,EAAE,IAAS;QACtB,IAAI,EAAE,OAAO;QACb,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAA4B,IAAsB;IACtF,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAsB;IAEtB,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,OAAO,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO;QACL,WAAW,EAAE,IAAS;QACtB,IAAI,EAAE,OAAO;QACb,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAA4B,IAAsB;IACtF,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAsB;IAEtB,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,OAAO,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -4,10 +4,11 @@
  * Shared utilities for AWP packages including validation,
  * reputation calculations, frontmatter parsing, and workspace helpers.
  */
-export { validateSlug, sanitizeSlug, validatePath, isValidDate, isValidTimestamp, } from "./validation.js";
+export { validateSlug, sanitizeSlug, validatePath, isValidDate, isValidTimestamp, VALID_TASK_STATUSES, VALID_PROJECT_STATUSES, VALID_PROVENANCE_ACTIONS, VALID_PRIORITIES, normalizeTaskStatus, normalizeProvenanceAction, suggestValidValue, } from "./validation.js";
 export { computeConfidence, computeDecayedScore, updateDimension, computeWeightedScore, } from "./reputation.js";
 export { parseWorkspaceFile, serializeWorkspaceFile, writeWorkspaceFile, getFrontmatterType, } from "./frontmatter.js";
 export { findWorkspaceRoot, loadManifest, fileExists, getAgentDid, safeReadFile, getWorkspaceRoot, } from "./workspace.js";
 export { type TaskNode, type DependencyGraph, type GraphAnalysis, buildGraph, topologicalSort, detectCycles, findCriticalPath, getBlockedTasks, analyzeGraph, getTaskSlug, getProjectSlug, } from "./graph.js";
+export { atomicWriteFile, withFileLock, safeWriteJson, loadJsonFile, type AtomicWriteOptions, type FileLockOptions, } from "./safe-io.js";
 export { type RecruitmentCandidate, type RecruitmentResult, findCandidatesForRole, autoRecruitSwarm, isSwarmFullyStaffed, getSwarmStaffingSummary, } from "./swarm.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAEhB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -5,7 +5,9 @@
  * reputation calculations, frontmatter parsing, and workspace helpers.
  */
 // Validation utilities
-export { validateSlug, sanitizeSlug, validatePath, isValidDate, isValidTimestamp, } from "./validation.js";
+export { validateSlug, sanitizeSlug, validatePath, isValidDate, isValidTimestamp, 
+// Agent-friendly normalization
+VALID_TASK_STATUSES, VALID_PROJECT_STATUSES, VALID_PROVENANCE_ACTIONS, VALID_PRIORITIES, normalizeTaskStatus, normalizeProvenanceAction, suggestValidValue, } from "./validation.js";
 // Reputation utilities
 export { computeConfidence, computeDecayedScore, updateDimension, computeWeightedScore, } from "./reputation.js";
 // Frontmatter utilities
@@ -14,6 +16,8 @@ export { parseWorkspaceFile, serializeWorkspaceFile, writeWorkspaceFile, getFron
 export { findWorkspaceRoot, loadManifest, fileExists, getAgentDid, safeReadFile, getWorkspaceRoot, } from "./workspace.js";
 // Graph utilities (dependency analysis)
 export { buildGraph, topologicalSort, detectCycles, findCriticalPath, getBlockedTasks, analyzeGraph, getTaskSlug, getProjectSlug, } from "./graph.js";
+// Safe I/O utilities
+export { atomicWriteFile, withFileLock, safeWriteJson, loadJsonFile, } from "./safe-io.js";
 // Swarm utilities (recruitment)
 export { findCandidatesForRole, autoRecruitSwarm, isSwarmFullyStaffed, getSwarmStaffingSummary, } from "./swarm.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,uBAAuB;AACvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,wCAAwC;AACxC,OAAO,EAIL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,gCAAgC;AAChC,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB;AAChB,+BAA+B;AAC/B,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,uBAAuB;AACvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,wCAAwC;AACxC,OAAO,EAIL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,qBAAqB;AACrB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,GAGb,MAAM,cAAc,CAAC;AAEtB,gCAAgC;AAChC,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/safe-io.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Safe file I/O utilities inspired by clawdbot.
+ *
+ * Provides atomic writes (temp file + rename), file locking with stale
+ * detection, backup rotation, and safe JSON helpers.
+ */
+export interface AtomicWriteOptions {
+    /** Enable backup rotation on overwrite (default: true) */
+    backup?: boolean;
+    /** Maximum number of backup copies to keep (default: 5) */
+    maxBackups?: number;
+}
+export interface FileLockOptions {
+    /** Lock acquisition timeout in milliseconds (default: 10_000) */
+    timeout?: number;
+    /** Age in milliseconds after which a lock is considered stale (default: 1_800_000 = 30min) */
+    staleThreshold?: number;
+}
+/**
+ * Write a file atomically using temp file + rename.
+ *
+ * - Writes content to a uniquely-named temp file
+ * - Backs up the existing file with rotation (if it exists)
+ * - Atomically renames the temp file to the target
+ * - Falls back to copyFile on cross-device or Windows errors
+ * - Cleans up the temp file on failure
+ */
+export declare function atomicWriteFile(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Execute a function while holding an exclusive file lock.
+ *
+ * - Uses `fs.open(lockPath, "wx")` for exclusive creation
+ * - Supports nested lock counting (same process, same file)
+ * - Detects stale locks via timestamp age and PID liveness
+ * - Retries with exponential backoff up to timeout
+ * - Always releases lock in finally block
+ */
+export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Write a JSON file atomically with directory creation.
+ */
+export declare function safeWriteJson(filePath: string, data: unknown, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Load and parse a JSON file, returning undefined if missing or corrupt.
+ */
+export declare function loadJsonFile<T = unknown>(filePath: string): Promise<T | undefined>;
+//# sourceMappingURL=safe-io.d.ts.map

package/dist/safe-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.d.ts","sourceRoot":"","sources":["../src/safe-io.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAwED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAqCf;AAMD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,CAAC,CAAC,CA2FZ;AAMD;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAGf;AAMD;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAWxF"}

package/dist/safe-io.js

@@ -0,0 +1,227 @@
+/**
+ * Safe file I/O utilities inspired by clawdbot.
+ *
+ * Provides atomic writes (temp file + rename), file locking with stale
+ * detection, backup rotation, and safe JSON helpers.
+ */
+import { mkdir, writeFile, readFile, rename, copyFile, unlink, open, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, basename, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+const HELD_LOCKS = new Map();
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Check if a process is still alive via signal 0.
+ */
+function isProcessAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read and parse lock file payload.
+ */
+async function readLockPayload(lockPath) {
+    try {
+        const raw = await readFile(lockPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number" || typeof parsed.createdAt !== "string")
+            return null;
+        return { pid: parsed.pid, createdAt: parsed.createdAt };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rotate backup files: .bak → .bak.1, .bak.1 → .bak.2, etc.
+ * Deletes the oldest backup if at max capacity.
+ */
+async function rotateBackups(filePath, maxBackups) {
+    if (maxBackups <= 1)
+        return;
+    const backupBase = `${filePath}.bak`;
+    const maxIndex = maxBackups - 1;
+    // Delete oldest
+    await unlink(`${backupBase}.${maxIndex}`).catch(() => { });
+    // Shift all down
+    for (let i = maxIndex - 1; i >= 1; i--) {
+        await rename(`${backupBase}.${i}`, `${backupBase}.${i + 1}`).catch(() => { });
+    }
+    // Move current .bak to .bak.1
+    await rename(backupBase, `${backupBase}.1`).catch(() => { });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// atomicWriteFile
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Write a file atomically using temp file + rename.
+ *
+ * - Writes content to a uniquely-named temp file
+ * - Backs up the existing file with rotation (if it exists)
+ * - Atomically renames the temp file to the target
+ * - Falls back to copyFile on cross-device or Windows errors
+ * - Cleans up the temp file on failure
+ */
+export async function atomicWriteFile(filePath, content, options) {
+    const doBackup = options?.backup !== false;
+    const maxBackups = options?.maxBackups ?? 5;
+    const dir = dirname(filePath);
+    const base = basename(filePath);
+    const tmp = join(dir, `${base}.${process.pid}.${randomUUID()}.tmp`);
+    // Ensure directory exists
+    await mkdir(dir, { recursive: true });
+    // Write to temp file
+    await writeFile(tmp, content, { encoding: "utf-8" });
+    try {
+        // Backup existing file
+        if (doBackup && existsSync(filePath)) {
+            await rotateBackups(filePath, maxBackups);
+            await copyFile(filePath, `${filePath}.bak`).catch(() => { });
+        }
+        // Atomic rename
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        const code = err.code;
+        // Cross-device rename or Windows permission error: fall back to copy
+        if (code === "EXDEV" || code === "EPERM" || code === "EEXIST") {
+            await copyFile(tmp, filePath);
+            await unlink(tmp).catch(() => { });
+            return;
+        }
+        // Clean up temp file on unexpected error
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// withFileLock
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a function while holding an exclusive file lock.
+ *
+ * - Uses `fs.open(lockPath, "wx")` for exclusive creation
+ * - Supports nested lock counting (same process, same file)
+ * - Detects stale locks via timestamp age and PID liveness
+ * - Retries with exponential backoff up to timeout
+ * - Always releases lock in finally block
+ */
+export async function withFileLock(filePath, fn, options) {
+    const timeout = options?.timeout ?? 10_000;
+    const staleThreshold = options?.staleThreshold ?? 30 * 60 * 1000;
+    const normalizedPath = resolve(filePath);
+    const lockPath = `${normalizedPath}.lock`;
+    // Check for nested lock (same process already holds this lock)
+    const held = HELD_LOCKS.get(normalizedPath);
+    if (held) {
+        held.count++;
+        try {
+            return await fn();
+        }
+        finally {
+            held.count--;
+            if (held.count <= 0) {
+                HELD_LOCKS.delete(normalizedPath);
+                await rm(held.lockPath, { force: true }).catch(() => { });
+            }
+        }
+    }
+    // Acquire new lock
+    const startedAt = Date.now();
+    let attempt = 0;
+    while (Date.now() - startedAt < timeout) {
+        attempt++;
+        try {
+            // Ensure directory exists
+            await mkdir(dirname(lockPath), { recursive: true });
+            // Exclusive creation — fails with EEXIST if lock already held
+            const handle = await open(lockPath, "wx");
+            const payload = JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2);
+            await handle.writeFile(payload, "utf-8");
+            await handle.close();
+            // Register in-process lock
+            HELD_LOCKS.set(normalizedPath, { count: 1, lockPath });
+            try {
+                return await fn();
+            }
+            finally {
+                const current = HELD_LOCKS.get(normalizedPath);
+                if (current) {
+                    current.count--;
+                    if (current.count <= 0) {
+                        HELD_LOCKS.delete(normalizedPath);
+                        await rm(current.lockPath, { force: true }).catch(() => { });
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+            // Lock file exists — check if stale
+            const lockPayload = await readLockPayload(lockPath);
+            if (lockPayload) {
+                const createdAt = Date.parse(lockPayload.createdAt);
+                const isStale = !Number.isFinite(createdAt) || Date.now() - createdAt > staleThreshold;
+                const isAlive = isProcessAlive(lockPayload.pid);
+                if (isStale || !isAlive) {
+                    // Remove stale lock and retry immediately
+                    await rm(lockPath, { force: true }).catch(() => { });
+                    continue;
+                }
+            }
+            else {
+                // Can't read lock file — remove and retry
+                await rm(lockPath, { force: true }).catch(() => { });
+                continue;
+            }
+            // Lock is held by a live process — wait with backoff
+            const delay = Math.min(1000, 50 * attempt);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    // Timeout
+    const lockPayload = await readLockPayload(lockPath);
+    const owner = lockPayload?.pid ? `pid=${lockPayload.pid}` : "unknown";
+    throw new Error(`File lock timeout (${timeout}ms): ${owner} holds ${lockPath}`);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// safeWriteJson
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Write a JSON file atomically with directory creation.
+ */
+export async function safeWriteJson(filePath, data, options) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await atomicWriteFile(filePath, JSON.stringify(data, null, 2) + "\n", options);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// loadJsonFile
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Load and parse a JSON file, returning undefined if missing or corrupt.
+ */
+export async function loadJsonFile(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || err instanceof SyntaxError) {
+            return undefined;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=safe-io.js.map

package/dist/safe-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.js","sourceRoot":"","sources":["../src/safe-io.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAS,IAAI,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA6BzC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAqB,CAAC;AAEhD,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;GAEG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,eAAe,CAC5B,QAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACxF,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,UAAkB;IAC/D,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO;IAE5B,MAAM,UAAU,GAAG,GAAG,QAAQ,MAAM,CAAC;IACrC,MAAM,QAAQ,GAAG,UAAU,GAAG,CAAC,CAAC;IAEhC,gBAAgB;IAChB,MAAM,MAAM,CAAC,GAAG,UAAU,IAAI,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAE1D,iBAAiB;IACjB,KAAK,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,MAAM,CAAC,GAAG,UAAU,IAAI,CAAC,EAAE,EAAE,GAAG,UAAU,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED,8BAA8B;IAC9B,MAAM,MAAM,CAAC,UAAU,EAAE,GAAG,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAAe,EACf,OAA4B;IAE5B,MAAM,QAAQ,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IAEpE,0BAA0B;IAC1B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtC,qBAAqB;IACrB,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAErD,IAAI,CAAC;QACH,uBAAuB;QACvB,IAAI,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,MAAM,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAC1C,MAAM,QAAQ,CAAC,QAAQ,EAAE,GAAG,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9D,CAAC;QAED,gBAAgB;QAChB,MAAM,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QAEjD,qEAAqE;QACrE,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC9B,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QAED,yCAAyC;QACzC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,EAAoB,EACpB,OAAyB;IAEzB,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC;IAC3C,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEjE,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,cAAc,OAAO,CAAC;IAE1C,+DAA+D;IAC/D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5C,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBACpB,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;gBAClC,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;QACxC,OAAO,EAAE,CAAC;QAEV,IAAI,CAAC;YACH,0BAA0B;YAC1B,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAEpD,8DAA8D;YAC9D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAC5B,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EACzD,IAAI,EACJ,CAAC,CACF,CAAC;YACF,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAErB,2BAA2B;YAC3B,UAAU,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YAEvD,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;oBAAS,CAAC;gBACT,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;gBAC/C,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,CAAC,KAAK,EAAE,CAAC;oBAChB,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;wBACvB,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;wBAClC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBAC9D,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAEjC,oCAAoC;YACpC,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,WAAW,EAAE,CAAC;gBAChB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;gBACpD,MAAM,OAAO,GACX,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,cAAc,CAAC;gBACzE,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAEhD,IAAI,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;oBACxB,0CAA0C;oBAC1C,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACpD,SAAS;gBACX,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,0CAA0C;gBAC1C,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;gBACpD,SAAS;YACX,CAAC;YAED,qDAAqD;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;YAC3C,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,UAAU;IACV,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,QAAQ,KAAK,UAAU,QAAQ,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,IAAa,EACb,OAA4B;IAE5B,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACjF,CAAC;AAED,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAc,QAAgB;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;YACpD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/safe-io.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=safe-io.test.d.ts.map

package/dist/safe-io.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.test.d.ts","sourceRoot":"","sources":["../src/safe-io.test.ts"],"names":[],"mappings":""}

package/dist/safe-io.test.js

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, readFile, writeFile, readdir, rm, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { atomicWriteFile, withFileLock, safeWriteJson, loadJsonFile } from "./safe-io.js";
+let testDir;
+beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), "awp-safe-io-test-"));
+});
+afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// atomicWriteFile
+// ─────────────────────────────────────────────────────────────────────────────
+describe("atomicWriteFile", () => {
+    it("writes file content correctly", async () => {
+        const filePath = join(testDir, "test.md");
+        await atomicWriteFile(filePath, "hello world");
+        const content = await readFile(filePath, "utf-8");
+        expect(content).toBe("hello world");
+    });
+    it("creates parent directories", async () => {
+        const filePath = join(testDir, "a", "b", "c", "test.md");
+        await atomicWriteFile(filePath, "nested");
+        const content = await readFile(filePath, "utf-8");
+        expect(content).toBe("nested");
+    });
+    it("creates .bak on overwrite", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "original", "utf-8");
+        await atomicWriteFile(filePath, "updated");
+        expect(await readFile(filePath, "utf-8")).toBe("updated");
+        expect(await readFile(`${filePath}.bak`, "utf-8")).toBe("original");
+    });
+    it("rotates backups on repeated overwrites", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "v1", "utf-8");
+        await atomicWriteFile(filePath, "v2");
+        await atomicWriteFile(filePath, "v3");
+        await atomicWriteFile(filePath, "v4");
+        expect(await readFile(filePath, "utf-8")).toBe("v4");
+        expect(await readFile(`${filePath}.bak`, "utf-8")).toBe("v3");
+        expect(await readFile(`${filePath}.bak.1`, "utf-8")).toBe("v2");
+        expect(await readFile(`${filePath}.bak.2`, "utf-8")).toBe("v1");
+    });
+    it("does not create backup when backup=false", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "original", "utf-8");
+        await atomicWriteFile(filePath, "updated", { backup: false });
+        expect(await readFile(filePath, "utf-8")).toBe("updated");
+        expect(existsSync(`${filePath}.bak`)).toBe(false);
+    });
+    it("does not leave temp files on success", async () => {
+        const filePath = join(testDir, "test.md");
+        await atomicWriteFile(filePath, "content");
+        const files = await readdir(testDir);
+        expect(files.filter((f) => f.includes(".tmp"))).toHaveLength(0);
+    });
+    it("respects maxBackups option", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "v1", "utf-8");
+        for (let i = 2; i <= 6; i++) {
+            await atomicWriteFile(filePath, `v${i}`, { maxBackups: 2 });
+        }
+        // Should only keep 2 backups: .bak and .bak.1
+        expect(existsSync(`${filePath}.bak`)).toBe(true);
+        expect(existsSync(`${filePath}.bak.1`)).toBe(true);
+        // .bak.2 should not exist (maxBackups=2 means slots: .bak, .bak.1)
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// withFileLock
+// ─────────────────────────────────────────────────────────────────────────────
+describe("withFileLock", () => {
+    it("acquires lock and runs callback", async () => {
+        const filePath = join(testDir, "data.md");
+        const result = await withFileLock(filePath, async () => {
+            return 42;
+        });
+        expect(result).toBe(42);
+    });
+    it("cleans up lock file after callback", async () => {
+        const filePath = join(testDir, "data.md");
+        await withFileLock(filePath, async () => { });
+        const files = await readdir(testDir);
+        expect(files.filter((f) => f.includes(".lock"))).toHaveLength(0);
+    });
+    it("cleans up lock file after callback throws", async () => {
+        const filePath = join(testDir, "data.md");
+        await expect(withFileLock(filePath, async () => {
+            throw new Error("test error");
+        })).rejects.toThrow("test error");
+        const files = await readdir(testDir);
+        expect(files.filter((f) => f.includes(".lock"))).toHaveLength(0);
+    });
+    it("serializes concurrent access", async () => {
+        const filePath = join(testDir, "counter.txt");
+        await writeFile(filePath, "0", "utf-8");
+        // Run 5 concurrent increments
+        const results = await Promise.all(Array.from({ length: 5 }, () => withFileLock(filePath, async () => {
+            const val = parseInt(await readFile(filePath, "utf-8"), 10);
+            await writeFile(filePath, String(val + 1), "utf-8");
+            return val + 1;
+        })));
+        // All increments should have serialized correctly
+        const finalValue = await readFile(filePath, "utf-8");
+        expect(parseInt(finalValue, 10)).toBe(5);
+        // Results should contain all values 1-5
+        expect(results.sort()).toEqual([1, 2, 3, 4, 5]);
+    });
+    it("supports nested lock counting", async () => {
+        const filePath = join(testDir, "data.md");
+        const result = await withFileLock(filePath, async () => {
+            // Nested lock on same file should not deadlock
+            return withFileLock(filePath, async () => {
+                return "nested ok";
+            });
+        });
+        expect(result).toBe("nested ok");
+    });
+    it("times out if lock cannot be acquired", async () => {
+        const filePath = join(testDir, "data.md");
+        const lockPath = `${filePath}.lock`;
+        // Create a lock file from a "live" process (our own PID)
+        await mkdir(testDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }), "utf-8");
+        // Should timeout since lock is held by a "live" process
+        await expect(withFileLock(filePath, async () => { }, { timeout: 200 })).rejects.toThrow(/timeout/i);
+        // Clean up the lock file manually
+        await rm(lockPath, { force: true });
+    });
+    it("detects stale locks from dead process", async () => {
+        const filePath = join(testDir, "data.md");
+        const lockPath = `${filePath}.lock`;
+        // Create a lock from a definitely-dead PID
+        await mkdir(testDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify({ pid: 999999999, createdAt: new Date().toISOString() }), "utf-8");
+        // Should succeed because the PID is dead
+        const result = await withFileLock(filePath, async () => "recovered");
+        expect(result).toBe("recovered");
+    });
+    it("detects stale locks by age", async () => {
+        const filePath = join(testDir, "data.md");
+        const lockPath = `${filePath}.lock`;
+        // Create a lock from our own PID but with an old timestamp
+        await mkdir(testDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify({
+            pid: process.pid,
+            createdAt: new Date(Date.now() - 2_000_000).toISOString(),
+        }), "utf-8");
+        // Should succeed because the lock is stale (older than 30min default)
+        const result = await withFileLock(filePath, async () => "recovered");
+        expect(result).toBe("recovered");
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// safeWriteJson
+// ─────────────────────────────────────────────────────────────────────────────
+describe("safeWriteJson", () => {
+    it("writes valid JSON with formatting", async () => {
+        const filePath = join(testDir, "data.json");
+        await safeWriteJson(filePath, { key: "value", num: 42 });
+        const raw = await readFile(filePath, "utf-8");
+        expect(raw).toBe('{\n  "key": "value",\n  "num": 42\n}\n');
+    });
+    it("creates directories recursively", async () => {
+        const filePath = join(testDir, "a", "b", "data.json");
+        await safeWriteJson(filePath, { ok: true });
+        const data = JSON.parse(await readFile(filePath, "utf-8"));
+        expect(data).toEqual({ ok: true });
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// loadJsonFile
+// ─────────────────────────────────────────────────────────────────────────────
+describe("loadJsonFile", () => {
+    it("loads valid JSON", async () => {
+        const filePath = join(testDir, "data.json");
+        await writeFile(filePath, '{"key": "value"}', "utf-8");
+        const data = await loadJsonFile(filePath);
+        expect(data).toEqual({ key: "value" });
+    });
+    it("returns undefined for missing file", async () => {
+        const data = await loadJsonFile(join(testDir, "nonexistent.json"));
+        expect(data).toBeUndefined();
+    });
+    it("returns undefined for corrupt JSON", async () => {
+        const filePath = join(testDir, "corrupt.json");
+        await writeFile(filePath, "not valid json {{{", "utf-8");
+        const data = await loadJsonFile(filePath);
+        expect(data).toBeUndefined();
+    });
+});
+//# sourceMappingURL=safe-io.test.js.map

package/dist/safe-io.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.test.js","sourceRoot":"","sources":["../src/safe-io.test.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -1,3 +1,42 @@
+/** Valid task statuses */
+export declare const VALID_TASK_STATUSES: readonly ["pending", "in-progress", "blocked", "review", "completed", "cancelled"];
+/** Valid project statuses */
+export declare const VALID_PROJECT_STATUSES: readonly ["draft", "active", "paused", "completed", "archived"];
+/** Valid provenance actions */
+export declare const VALID_PROVENANCE_ACTIONS: readonly ["created", "updated", "merged"];
+/** Valid priorities */
+export declare const VALID_PRIORITIES: readonly ["low", "medium", "high", "critical"];
+/**
+ * Normalize a task status, accepting common variants and typos.
+ * Returns the canonical status or null if unrecognizable.
+ *
+ * @example
+ * normalizeTaskStatus("in_progress") // => "in-progress"
+ * normalizeTaskStatus("WIP") // => "in-progress"
+ * normalizeTaskStatus("garbage") // => null
+ */
+export declare function normalizeTaskStatus(status: string): string | null;
+/**
+ * Normalize a provenance action, accepting common variants.
+ * Returns the canonical action or null if unrecognizable.
+ *
+ * @example
+ * normalizeProvenanceAction("drafted") // => "created"
+ * normalizeProvenanceAction("edit") // => "updated"
+ */
+export declare function normalizeProvenanceAction(action: string): string | null;
+/**
+ * Suggest the closest valid value for a given input.
+ * Returns the suggestion and a helpful error message.
+ *
+ * @example
+ * suggestValidValue("in_progress", VALID_TASK_STATUSES)
+ * // => { suggestion: "in-progress", message: "Did you mean 'in-progress'?" }
+ */
+export declare function suggestValidValue(input: string, validValues: readonly string[]): {
+    suggestion: string | null;
+    message: string;
+};
 /**
  * Validate an artifact or profile slug.
  * Slugs must be lowercase alphanumeric with hyphens, not starting with hyphen.
@@ -28,6 +67,7 @@ export declare function validatePath(root: string, targetPath: string): string;
  *
  * @param dateStr - The date string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export declare function isValidDate(dateStr: string): boolean;
 /**
@@ -35,6 +75,7 @@ export declare function isValidDate(dateStr: string): boolean;
  *
  * @param timestamp - The timestamp string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export declare function isValidTimestamp(timestamp: string): boolean;
 //# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG3D"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAcA,0BAA0B;AAC1B,eAAO,MAAM,mBAAmB,oFAOtB,CAAC;AAEX,6BAA6B;AAC7B,eAAO,MAAM,sBAAsB,iEAMzB,CAAC;AAEX,+BAA+B;AAC/B,eAAO,MAAM,wBAAwB,2CAA4C,CAAC;AAElF,uBAAuB;AACvB,eAAO,MAAM,gBAAgB,gDAAiD,CAAC;AA+B/E;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcjE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA6BhD;AAmCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG3D"}

package/dist/validation.js

@@ -3,6 +3,162 @@ import { resolve, relative, isAbsolute } from "node:path";
 const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 /** Maximum slug length */
 const MAX_SLUG_LENGTH = 100;
+// ============================================================================
+// Agent-Friendly Normalization
+// ============================================================================
+// These functions help agents avoid common format errors by auto-correcting
+// typos and accepting common variants. This makes AWP more "plug and play".
+/** Valid task statuses */
+export const VALID_TASK_STATUSES = [
+    "pending",
+    "in-progress",
+    "blocked",
+    "review",
+    "completed",
+    "cancelled",
+];
+/** Valid project statuses */
+export const VALID_PROJECT_STATUSES = [
+    "draft",
+    "active",
+    "paused",
+    "completed",
+    "archived",
+];
+/** Valid provenance actions */
+export const VALID_PROVENANCE_ACTIONS = ["created", "updated", "merged"];
+/** Valid priorities */
+export const VALID_PRIORITIES = ["low", "medium", "high", "critical"];
+/** Common typo mappings for task status */
+const TASK_STATUS_ALIASES = {
+    // Underscore variants
+    in_progress: "in-progress",
+    in_review: "review",
+    // CamelCase variants
+    inProgress: "in-progress",
+    inReview: "review",
+    // Other common typos
+    "in progress": "in-progress",
+    done: "completed",
+    todo: "pending",
+    wip: "in-progress",
+    complete: "completed",
+    cancelled: "cancelled",
+    canceled: "cancelled",
+};
+/** Common typo mappings for provenance actions */
+const PROVENANCE_ACTION_ALIASES = {
+    drafted: "created",
+    create: "created",
+    update: "updated",
+    edit: "updated",
+    edited: "updated",
+    modified: "updated",
+    merge: "merged",
+};
+/**
+ * Normalize a task status, accepting common variants and typos.
+ * Returns the canonical status or null if unrecognizable.
+ *
+ * @example
+ * normalizeTaskStatus("in_progress") // => "in-progress"
+ * normalizeTaskStatus("WIP") // => "in-progress"
+ * normalizeTaskStatus("garbage") // => null
+ */
+export function normalizeTaskStatus(status) {
+    const lower = status.toLowerCase().trim();
+    // Direct match
+    if (VALID_TASK_STATUSES.includes(lower)) {
+        return lower;
+    }
+    // Alias match
+    if (TASK_STATUS_ALIASES[lower]) {
+        return TASK_STATUS_ALIASES[lower];
+    }
+    return null;
+}
+/**
+ * Normalize a provenance action, accepting common variants.
+ * Returns the canonical action or null if unrecognizable.
+ *
+ * @example
+ * normalizeProvenanceAction("drafted") // => "created"
+ * normalizeProvenanceAction("edit") // => "updated"
+ */
+export function normalizeProvenanceAction(action) {
+    const lower = action.toLowerCase().trim();
+    // Direct match
+    if (VALID_PROVENANCE_ACTIONS.includes(lower)) {
+        return lower;
+    }
+    // Alias match
+    if (PROVENANCE_ACTION_ALIASES[lower]) {
+        return PROVENANCE_ACTION_ALIASES[lower];
+    }
+    return null;
+}
+/**
+ * Suggest the closest valid value for a given input.
+ * Returns the suggestion and a helpful error message.
+ *
+ * @example
+ * suggestValidValue("in_progress", VALID_TASK_STATUSES)
+ * // => { suggestion: "in-progress", message: "Did you mean 'in-progress'?" }
+ */
+export function suggestValidValue(input, validValues) {
+    const lower = input.toLowerCase().trim();
+    // Check for underscore/camelCase variants
+    const hyphenated = lower
+        .replace(/_/g, "-")
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .toLowerCase();
+    if (validValues.includes(hyphenated)) {
+        return {
+            suggestion: hyphenated,
+            message: `Did you mean '${hyphenated}'? (Use hyphens, not underscores)`,
+        };
+    }
+    // Simple Levenshtein-like check for close matches
+    for (const valid of validValues) {
+        if (levenshteinDistance(lower, valid) <= 2) {
+            return {
+                suggestion: valid,
+                message: `Did you mean '${valid}'?`,
+            };
+        }
+    }
+    return {
+        suggestion: null,
+        message: `Valid values: ${validValues.join(", ")}`,
+    };
+}
+/**
+ * Simple Levenshtein distance for typo detection.
+ */
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
 /**
  * Validate an artifact or profile slug.
  * Slugs must be lowercase alphanumeric with hyphens, not starting with hyphen.
@@ -52,6 +208,7 @@ export function validatePath(root, targetPath) {
  *
  * @param dateStr - The date string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export function isValidDate(dateStr) {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
@@ -65,6 +222,7 @@ export function isValidDate(dateStr) {
  *
  * @param timestamp - The timestamp string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export function isValidTimestamp(timestamp) {
     const date = new Date(timestamp);

package/dist/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE1D,8FAA8F;AAC9F,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,0BAA0B;AAC1B,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,2EAA2E,CAClG,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sBAAsB,eAAe,aAAa,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAAkB;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAEvC,8BAA8B;IAC9B,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-workspace/utils",
-  "version": "0.7.0",
+  "version": "0.8.3",
   "description": "Shared utilities for AWP packages — validation, reputation calculations, and frontmatter parsing",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agent-workspace/core": "0.7.0",
+    "@agent-workspace/core": "0.8.2",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {