leerness 1.36.183 → 1.36.185

package/lib/io.js

@@ -7,6 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const cp = require('child_process');
+const crypto = require('crypto');
 
 // 1.10.2 (UR-0146): quiet 모드 — 사람용 출력(log/ok/warn) 억제. init --json 등에서 큰 핸들러의 다수 log 를 비침투적으로 묵음 → 순수 JSON 1개만 출력.
 //   fail/failJson(오류)은 묵음 대상 아님(에러는 항상 노출). setQuiet 로 토글, 호출부 finally 에서 반드시 복구.
@@ -175,6 +176,10 @@ function _patchFsForDryRun() {
   }
 }
 function setDryRunGuard(on) { _dryGuard = !!on; if (on) _patchFsForDryRun(); }
+// File-descriptor based writers cannot be intercepted by the fs path mutator
+// wrappers. Call this before opening a descriptor so --dry-run retains its
+// process-wide zero-persistent-write contract.
+function assertWriteAllowed(p) { _dryCheck(p); }
 //   ⚠ `mkdirp` 은 가드하지 **않는다**. 한 번 넣었다가 부작용을 재서 뺀다 —
 //     `_withLock` 이 락 디렉토리를 만드는 것까지 막혀 락 획득이 실패하고 **무보호 진행**으로 떨어졌다
 //     (실측: `state start --dry-run` → "락 획득 실패 — 보호 없이 진행합니다"). 빈 디렉토리는 사용자 데이터가
@@ -484,4 +489,150 @@ function _renameWithRetry(from, to) {
 function append(p, s) { _dryCheck(p); mkdirp(path.dirname(p)); fs.appendFileSync(p, s, 'utf8'); }
 function rel(root, p) { return path.relative(root, p).replace(/\\/g, '/') || '.'; }
 
-module.exports = { log, ok, warn, fail, failJson, setQuiet, today, now, absRoot, exists, read, readBuf, mkdirp, writeUtf8, writeBufferIfUnchanged, append, rel, setDryRunGuard, mkdirpRaw };
+function _hardLinkIdentityEqual(a, b) {
+  return !!(a && b)
+    && String(a.dev) === String(b.dev)
+    && String(a.ino) === String(b.ino);
+}
+
+function _lstatState(p) {
+  try { return { exists: true, stat: fs.lstatSync(p), error: null }; }
+  catch (error) {
+    if (error && error.code === 'ENOENT') return { exists: false, stat: null, error: null };
+    return { exists: null, stat: null, error };
+  }
+}
+
+// A failed alias detach means the caller must not observe success. Remove the
+// just-installed canonical name only when both names still identify the exact
+// committed inode and its bytes are unchanged. Existing-file callers can then
+// restore their captured predecessor; create callers leave the canonical path
+// absent. A random quarantine rename is the last exact-path fallback when a
+// platform refuses both unlink spellings.
+function _rollbackCommittedHardLink(alias, live, expected) {
+  const liveState = _lstatState(live);
+  if (liveState.exists === false) return { ok: true, canonicalState: 'absent', artifact: null };
+  const aliasState = _lstatState(alias);
+  if (liveState.exists !== true || aliasState.exists !== true
+    || liveState.stat.isSymbolicLink() || !liveState.stat.isFile()
+    || aliasState.stat.isSymbolicLink() || !aliasState.stat.isFile()
+    || !_hardLinkIdentityEqual(liveState.stat, aliasState.stat)) {
+    return { ok: false, canonicalState: 'unknown', artifact: null, error: liveState.error || aliasState.error || null };
+  }
+  if (expected) {
+    try {
+      if (!fs.readFileSync(live).equals(expected) || !fs.readFileSync(alias).equals(expected)) {
+        return { ok: false, canonicalState: 'changed', artifact: null, error: null };
+      }
+    } catch (error) {
+      return { ok: false, canonicalState: 'unknown', artifact: null, error };
+    }
+  }
+
+  let removalError = null;
+  try { fs.unlinkSync(live); }
+  catch (error) { removalError = error; }
+  if (_lstatState(live).exists === true) {
+    try { fs.rmSync(live, { force: true }); }
+    catch (error) { removalError = removalError || error; }
+  }
+  if (_lstatState(live).exists === true) {
+    const quarantine = `${live}.rollback-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+    try {
+      fs.renameSync(live, quarantine);
+      try { fs.unlinkSync(quarantine); }
+      catch {
+        try { fs.rmSync(quarantine, { force: true }); } catch {}
+      }
+      const postRename = _lstatState(live);
+      return postRename.exists === false
+        ? { ok: true, canonicalState: 'absent', artifact: _lstatState(quarantine).exists === true ? quarantine : null }
+        : { ok: false, canonicalState: 'present', artifact: quarantine, error: removalError };
+    } catch (error) {
+      removalError = removalError || error;
+    }
+  }
+  const after = _lstatState(live);
+  if (after.exists === false) return { ok: true, canonicalState: 'absent', artifact: null };
+  if (after.exists === true && !after.stat.isSymbolicLink() && after.stat.isFile()
+    && Number(after.stat.nlink) === 1
+    && (!expected || fs.readFileSync(live).equals(expected))) {
+    return { ok: true, canonicalState: 'detached', artifact: null };
+  }
+  return { ok: false, canonicalState: after.exists === true ? 'present' : 'unknown', artifact: null, error: after.error || removalError };
+}
+
+// An exclusive hard-link install is useful when rename-without-replace is not
+// available, but the live inode must not depend on successfully unlinking the
+// prepared alias. If unlink fails after commit, atomically replace that alias
+// with a different inode; this drops the live inode back to nlink=1 even when
+// the harmless replacement artifact cannot itself be removed.
+function detachCommittedHardLink(aliasPath, livePath, expectedBytes) {
+  const alias = path.resolve(aliasPath);
+  const live = path.resolve(livePath);
+  let firstCleanupError = null;
+  try {
+    fs.unlinkSync(alias);
+  } catch (error) {
+    firstCleanupError = error;
+    // Some transient/platform wrappers fail unlink but permit the equivalent
+    // exact-path removal. This is only the random prepared alias, never user data.
+    try { fs.rmSync(alias, { force: true }); } catch {}
+    if (fs.existsSync(alias)) {
+      const detacher = `${alias}.detach-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+      let detacherExists = false;
+      try {
+        fs.writeFileSync(detacher, Buffer.alloc(0), { flag: 'wx', mode: 0o600 });
+        detacherExists = true;
+        // Replacing the alias unlinks it from the committed inode as part of
+        // rename, while leaving the live pathname and its bytes untouched.
+        fs.renameSync(detacher, alias);
+        detacherExists = false;
+      } catch (detachError) {
+        try { if (detacherExists) fs.rmSync(detacher, { force: true }); } catch {}
+        const expected = Buffer.isBuffer(expectedBytes) ? expectedBytes : null;
+        const rollback = _rollbackCommittedHardLink(alias, live, expected);
+        // Another actor may have detached the alias between our failed rename
+        // and rollback probe. A valid nlink=1 live file already satisfies the
+        // commit contract, so this narrow state remains a successful recovery.
+        if (rollback.ok && rollback.canonicalState === 'detached') {
+          return { cleanupRecovered: true, cleanupArtifact: fs.existsSync(alias) ? alias : null };
+        }
+        const failure = new Error(`committed hard-link alias could not be detached: ${alias}`);
+        failure.code = 'E_HARDLINK_DETACH_FAILED';
+        failure.cleanupError = (detachError && detachError.message) || String(detachError);
+        failure.canonicalRolledBack = rollback.ok && rollback.canonicalState === 'absent';
+        failure.rollbackState = rollback.canonicalState;
+        failure.rollbackArtifact = rollback.artifact || null;
+        failure.rollbackError = rollback.error && (rollback.error.message || String(rollback.error));
+        failure.cause = firstCleanupError;
+        throw failure;
+      }
+      // The path now names an unrelated empty inode. Failure to remove this
+      // cleanup artifact is non-fatal and cannot poison the committed file.
+      try { fs.rmSync(alias, { force: true }); } catch {}
+    }
+  }
+  let stat;
+  try { stat = fs.lstatSync(live); }
+  catch (error) {
+    const failure = new Error(`committed file disappeared while detaching its prepared alias: ${live}`);
+    failure.code = 'E_HARDLINK_DETACH_FAILED';
+    failure.cause = error;
+    throw failure;
+  }
+  const expected = Buffer.isBuffer(expectedBytes) ? expectedBytes : null;
+  if (stat.isSymbolicLink() || !stat.isFile() || Number(stat.nlink) !== 1
+      || (expected && !fs.readFileSync(live).equals(expected))) {
+    const failure = new Error(`committed file failed post-detach validation: ${live}`);
+    failure.code = 'E_HARDLINK_DETACH_FAILED';
+    failure.cleanupError = firstCleanupError && firstCleanupError.message;
+    throw failure;
+  }
+  return {
+    cleanupRecovered: !!firstCleanupError,
+    cleanupArtifact: fs.existsSync(alias) ? alias : null,
+  };
+}
+
+module.exports = { log, ok, warn, fail, failJson, setQuiet, today, now, absRoot, exists, read, readBuf, mkdirp, writeUtf8, writeBufferIfUnchanged, append, rel, setDryRunGuard, assertWriteAllowed, mkdirpRaw, detachCommittedHardLink };