MailUI4Agents/plugins/pi-mail-bridge/test/lib/tmp-space.mjs

/**
 * 临时目录空间：**测量与判据分开**。
 *
 * # 为什么要有这个东西
 *
 * 2026-09-14 实测（本机）：`/tmp` 是 tmpfs，9.8G 被占满，`bavail` 只剩
 * **0.70 MiB**（`statfs` 实读）。此时跑 `npm test` 会红一条
 * `★巨大的 message 行不进内存也不影响解析`，报 `ENOSPC`。
 *
 * 那条红**看起来像内存缺陷**（用例名里就写着"不进内存"，而它恰好是往临时目录
 * 写文件的用例）。下一次踩到的人会去读 `session-scan.mjs` 找内存 bug —— 找的是
 * 一个**不存在**的东西。环境不足伪装成断言失败，是这个文件存在的全部理由。
 *
 * # 判据的形状（与仓库既有约定一致）
 *
 * - 这里只有**纯函数**：喂进"还剩多少字节"，吐出"够不够"。测量在
 *   `measureAvailBytes()`（同文件导出，因为它要能被喂"不存在的目录"做反面样本），
 *   纯函数才可被反面样本喂。
 * - **读不到不判红**：`availBytes` 为 `null`（`statfsSync` 抛错 / 平台不支持 /
 *   `statfs.bsize` 为 0 ⇒ 测量层返回 `null`）时返回 `ok: true` 并注明"不据此判定"。
 *   **不知道 ≠ 不对** —— 不确定就放行，否则会在不认识的文件系统上制造一条总在亮的
 *   红灯，而"总在亮的红灯"会被人学会忽略（`deploy/check-deploy-drift.mjs` 文件头骂过）。
 * - ★ 但**可用字节数为 0 不是"没测到"**，是"真的没有"：它必须判红。第一版把
 *   `<= 0` 一并当"不知道"，于是 `bavail` 只剩 712 字节时前置自检放行、紧接着
 *   17 条用例 ENOSPC 全红 —— 守卫装在最该拦的时候放行，等于没装。
 *   （2026-09-14 踩的；这条注释写错过一次，pi 读第一遍就误读成了"0 也算不知道"，
 *   所以这里把两个 case 分开写死。）
 */

import { statfsSync } from 'node:fs';

/** 单条用例的最大临时写入量（实测）：`test/session-scan.test.mjs` 那条用例
 *  写 3 条 3 MiB 的行（两条巨行 + 一条正常行）⇒ 约 12 MiB。 */
export const MEASURED_MAX_CASE_WRITE = 12 * 1024 * 1024;

/**
 * 前置自检要求的最小可用空间。
 *
 * 取"实测用例写入量 × 2 + 8 MiB 机动"＝ 32 MiB，**不是**总容量的百分比：
 * 百分比在 9.8G 的 tmpfs 上会给出一个和这套测试毫无关系的数，而这里要挡的是
 * "一条 12 MiB 的用例写不进去"。×2 是因为临时目录可能同时有别的写入方
 * （本机 `npm test` 之外还跑着 agent 的会话文件）。
 */
export const MIN_FREE_BYTES = MEASURED_MAX_CASE_WRITE * 2 + 8 * 1024 * 1024;

const mib = (n) => `${(n / 1048576).toFixed(1)} MiB`;

/**
 * 测量：进程**实际能写**的字节数。读不到返回 `null`。
 *
 * 放在这里（而不是 `test/env-preflight.mjs` 里）的唯一理由是**可被反面样本喂**：
 * `measureAvailBytes('/definitely/not/here')` 这条判据在任何机器上都跑得了，
 * 而"读不到 ⇒ null ⇒ 放行"这一支否则就没有不依赖机器状态的判据覆盖
 * —— 端到端那条一旦因 `/tmp` 被清空而跳过，就没人管这一支了。
 *
 * @param {string} dir 要量的目录，默认 `os.tmpdir()`
 * @returns {number|null} 可用字节数；读不到/不支持/`bsize` 为 0 ⇒ `null`
 */
export function measureAvailBytes(dir) {
  try {
    if (typeof statfsSync !== 'function') return null;   // Node < 18.15
    if (typeof dir !== 'string' || dir === '') return null;
    const s = statfsSync(dir);
    if (!s || !s.bsize) return null;                     // bsize=0 ⇒ 量不出字节数
    // 用 `bavail`（非特权进程可用的块数），**不是** `bfree`（含 root 保留块）：
    // 这里回答的是"我写不写得进去"，不是"机器上空闲多少"。
    return s.bavail * s.bsize;
  } catch {
    return null;                                         // 不知道 ≠ 不对
  }
}

/**
 * @param {{ availBytes: number|null, needBytes?: number }} args
 *   `availBytes` 为 `null` 表示"没测到"（读不到、平台不支持、`bsize` 为 0）。
 * @returns {{ ok: boolean, known: boolean, note: string }}
 */
export function judgeSpace({ availBytes, needBytes = MIN_FREE_BYTES }) {
  // `null` / `NaN` 才是"没测到"。**注意 0 不是"没测到"** ——
  // `statfsSync` 说不出话时会抛（已在测量层转成 null），它若返回 0，
  // 意思就是"真的一点空间都没有"（实测踩过：把 `<= 0` 一并当"不知道"，
  // 于是 `bavail` 只剩 712 字节时前置自检放行，接着 17 条用例 ENOSPC 全红）。
  if (availBytes === null || availBytes === undefined || Number.isNaN(availBytes)) {
    return { ok: true, known: false, note: '没测到可用空间（读不到或平台不支持）—— 不据此判定' };
  }
  if (availBytes >= needBytes) {
    return { ok: true, known: true, note: `可用 ${mib(availBytes)} ≥ 需要 ${mib(needBytes)}` };
  }
  return {
    ok: false,
    known: true,
    note: `可用 ${mib(availBytes)} < 需要 ${mib(needBytes)}`,
  };
}