refactor(infra): extract json file + async lock helpers

src/infra/json-files.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeJsonAtomic(
+  filePath: string,
+  value: unknown,
+  options?: { mode?: number },
+) {
+  const mode = options?.mode ?? 0o600;
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmp = `${filePath}.${randomUUID()}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(value, null, 2), "utf8");
+  try {
+    await fs.chmod(tmp, mode);
+  } catch {
+    // best-effort; ignore on platforms without chmod
+  }
+  await fs.rename(tmp, filePath);
+  try {
+    await fs.chmod(filePath, mode);
+  } catch {
+    // best-effort; ignore on platforms without chmod
+  }
+}
+
+export function createAsyncLock() {
+  let lock: Promise<void> = Promise.resolve();
+  return async function withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const prev = lock;
+    let release: (() => void) | undefined;
+    lock = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release?.();
+    }
+  };
+}