@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/argent-datadir.mjs

@@ -0,0 +1,16 @@
+/**
+ * 脚本侧入口 → **唯一判据在内核** `core/lib/argent-datadir.mjs`。
+ *
+ * ⚠️ 本文件**不含任何判据**，只是一行再导出（别名）：`scripts/**` 用 `./argent-datadir.mjs`
+ * 更顺手，而实现必须只有一份 —— 三级链/安全阀的判据、注释、测试都在内核那份里。
+ * 改判据请改内核文件，**不要**在这里补逻辑（那就会出现第二份判据）。
+ *
+ * 为什么判据放内核（而不是直接放 `scripts/lib/`）：
+ *   · `plugins/**`（L2 宿主壳）在 profile 里是 `node_modules/<pkg>` 下的独立包，
+ *     按契约**不能 import scripts/**（`scripts/` 是引擎侧），而"壳 import 内核"正是
+ *     分层要的方向（`docs/Argent-宿主适配契约.md`）；
+ *   · `core/**` 只用 node 内建，可被任何宿主复用（hermes/Android 同样要用这条链）。
+ *
+ * 跑法（回归）：`node scripts/tests/argent-datadir.test.mjs`
+ */
+export * from '../../core/lib/argent-datadir.mjs'

package/engine/scripts/lib/argent_datadir.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Argent 数据目录 —— **Python 侧唯一实现，勿在别处复制判据**。
+
+══════════════════════════════════════════════════════════════════════════
+〇、这份文件是什么（以及为什么必须有它）
+══════════════════════════════════════════════════════════════════════════
+JS 内核 `core/lib/argent-datadir.mjs` 是**唯一判据**（三级链 + 隔离安全阀）。
+但引擎的 Python/shell 面（`scripts/flow_*.py`、`scripts/*.sh`、cron 直跑路径）
+**没法 import 一个 .mjs**，此前各自写着**两级**链：
+
+    ARGENT_DATA_DIR  →  ~/.dsh/argent          ← 旧写法（**不认 DSH_HOME**）
+
+于是以 `DSH_HOME=<隔离 home>` 起的实例里：插件（JS）写隔离目录、
+CLI/cron（Python/shell）写**生产**目录 —— 正是 2026-10-01 桌面端隔离事故的形态。
+本模块把 Python/shell 面收敛到与 JS 内核**同语义**的一份实现上：
+
+    ARGENT_DATA_DIR  →  $DSH_HOME/argent  →  ~/.dsh/argent
+
+⚠️ **不允许**在任何 `.py`/`.sh` 里再写一遍这条链（哪怕只有两级）。
+   直跑脚本要用数据目录 ⇒ `from argent_datadir import resolve_data_dir`；
+   shell 用 `"$PY" scripts/argent-datadir.py`（CLI 包装）。
+   漂移由门禁 `scripts/tests/argent-datadir-parity.test.mjs` 守住（JS 与 Python **逐字段**比对）。
+
+══════════════════════════════════════════════════════════════════════════
+一、与 JS 内核的语义对齐（**逐条**，改这里必须同步改内核，反之亦然）
+══════════════════════════════════════════════════════════════════════════
+  · 三级链优先级：`ARGENT_DATA_DIR` > `$DSH_HOME/argent` > `~/.dsh/argent`；
+  · `defaultDir` **锚在 OS home**（只认 `$HOME`，**故意不认 `DSH_HOME`**）——
+    否则隔离实例会把自己当成"默认"，安全阀失效；
+  · **默认目录两步走**（实施方案 P1③ / §6.2 Q6 选项 B，2026-10-03）：**老机器**（`~/.dsh/argent`
+    **已存在**）**存在即沿用**；不存在（新装、无宿主）⇒ `~/.argent`。判据锚在 OS home，
+    优先级链**不变**（只改"默认"这一级的取值）。本文件与 JS 内核**同批**改、**同夹具**对拍；
+  · `isolated = (解析结果 ≠ defaultDir)`：`ARGENT_DATA_DIR` 指回默认目录**不算隔离**
+    （不误伤"只是显式写了默认值"的部署）；
+  · 安全阀：隔离且 `ARGENT_ALLOW_ISOLATED_PUMP` **精确等于 `1`** 才放行（`true`/`01`/空 都不算）；
+  · fail-closed：解析器不可用（`None` / `dir` 为空）⇒ **暂停**，绝不猜目录；
+  · 空串按**未设**处理（`''` 不覆盖下一级）；`source` 只在**非空**时才报该级；
+  · 相对路径 / 尾部斜杠 / `..`：`os.path.abspath` 与 JS `path.resolve` 语义一致
+    （都按 cwd 解析 + 规范化 + 去尾斜杠，都**不**解符号链接）；
+  · `~` **不做展开**：JS `path.resolve('~/x')` = `<cwd>/~/x`，这里必须一致
+    （shell 里不加引号的 `~` 本来就由 shell 展开；加了引号就应当与 JS 同解，
+    否则同一个值在插件里和在 cron 里会解析成**两个不同目录** ＝ 又一处劈叉）。
+  · 返回 **camelCase 键**（`dir/source/isolated/defaultDir/dshHome`）：这是与 JS 内核的
+    **数据契约**，键名必须逐字相同（门禁按字段比对，改名即红）。
+
+分层：本文件是 **L1 内核**（只用 stdlib，不 import 宿主模块）。
+跑法（回归）：`node scripts/tests/argent-datadir-parity.test.mjs`（由 run-tests.sh 收录）
+"""
+
+from __future__ import annotations
+
+import os
+import os.path as _p
+
+__all__ = [
+    "ENV_DATA_DIR", "ENV_DSH_HOME", "ENV_ALLOW_ISOLATED_PUMP", "DATA_DIR_SEGMENTS",
+    "os_home", "dsh_home_of", "legacy_data_dir", "legacy_data_dir_exists",
+    "default_data_dir", "resolve_data_dir",
+    "describe_data_dir", "loop_gate_for_dir", "loop_gate",
+]
+
+#: 显式数据目录（最高优先级）。
+ENV_DATA_DIR = "ARGENT_DATA_DIR"
+#: 宿主 home（dsh 多实例隔离开关）。
+ENV_DSH_HOME = "DSH_HOME"
+#: 隔离目录下**显式**放开失败回路的开关（必须精确等于 `1`）。
+ENV_ALLOW_ISOLATED_PUMP = "ARGENT_ALLOW_ISOLATED_PUMP"
+
+#: **老机器**的数据目录（`~/.dsh/argent`）：存在即沿用 —— 这一级同时是"客户机现状"。
+DATA_DIR_SEGMENTS = (".dsh", "argent")
+#: **新装（无宿主）**的默认目录：`~/.argent`（§6.2 Q6 选项 B）；只在老位置不存在时生效。
+NO_HOST_DATA_DIR_SEGMENTS = (".argent",)
+
+
+def _env(env=None):
+    """夹具注入点：`env=None` ⇒ 进程环境（与 JS `opts.env || process.env` 同义）。"""
+    return os.environ if env is None else env
+
+
+def _get(env, key) -> str:
+    """取环境变量的**真值口径**（与 JS 一致）：缺失 / `None` / 空串 ⇒ `''`，其余 `str()`。"""
+    v = env.get(key) if hasattr(env, "get") else None
+    return str(v) if v else ""
+
+
+def _join(*parts) -> str:
+    """JS `path.join()` 的等价物（**不是** `os.path.join`）。
+
+    为什么要单独包一层（门禁夹具 ⑥e 抓出来的真实漂移）：
+      `os.path.join('/a/iso//', 'argent')` = `'/a/iso//argent'`（**不折叠重复斜杠**），
+      而 JS `path.join('/a/iso//', 'argent')` = `'/a/iso/argent'` ⇒ `raw` 字段两边不同。
+      `dir/defaultDir` 因为都过了一遍 resolve/abspath 而看不出差别，`raw` 会。
+    """
+    return _p.normpath(_p.join(*parts))
+
+
+def _homedir_fallback() -> str:
+    """`os.homedir()` 的 Python 等价（只给"`HOME` 未定义"的兜底用）。
+
+    与 node/libuv 同口径：`HOME` **已定义**（哪怕空串）就用它的值；**未定义**才查 passwd。
+    """
+    if "HOME" in os.environ:
+        return str(os.environ.get("HOME") or "")
+    try:
+        import pwd  # POSIX only；仓库只跑 macOS/Linux
+        return pwd.getpwuid(os.getuid()).pw_dir
+    except Exception:                                   # noqa: BLE001
+        return os.path.expanduser("~")
+
+
+def os_home(env=None) -> str:
+    """OS 用户 home（只认 `$HOME`，**故意不认 `DSH_HOME`**）。
+
+    判据"是否偏离默认目录"必须锚在 OS home 上，否则隔离实例会把自己当成默认。
+    """
+    h = _get(_env(env), "HOME")
+    return h if h else _homedir_fallback()
+
+
+def dsh_home_of(env=None, home=None) -> str:
+    """宿主 home：`$DSH_HOME` → `~/.dsh`（dsh 多实例隔离：每个实例独立 home）。
+
+    注意这不是数据目录，是**数据目录的父目录**。
+    """
+    e = _env(env)
+    return _get(e, ENV_DSH_HOME) or _join(home or os_home(e), ".dsh")
+
+
+def legacy_data_dir(env=None, home=None) -> str:
+    """**老位置** `~/.dsh/argent`（**只算路径，不看存在性**）。"""
+    e = _env(env)
+    return _join(home or os_home(e), *DATA_DIR_SEGMENTS)
+
+
+def legacy_data_dir_exists(env=None, home=None) -> bool:
+    """**"存在即沿用"的判据本体**：老位置 `~/.dsh/argent` 在不在？
+
+    与 JS `legacyDataDirExists()`（`fs.existsSync`）**逐字同解**：用 `os.path.exists`
+    （**不是** `os.path.isdir` —— 存在性判据不许两边各写一套；文件也算"存在"）。
+    """
+    return os.path.exists(legacy_data_dir(env, home))
+
+
+def default_data_dir(env=None, home=None) -> str:
+    """默认数据目录（**两步走**，实施方案 P1③ / §6.2 Q6 选项 B，2026-10-03 已批准）：
+      · ① **存在即沿用**：`~/.dsh/argent` **已存在** ⇒ 它就是默认目录（**老机器永不被误判隔离**）；
+      · ② 不存在（**新装、无宿主**）⇒ `~/.argent`。
+    与 JS 内核 `core/lib/argent-datadir.mjs#defaultDataDir` **同批、同夹具**对拍
+    （`scripts/tests/argent-datadir-parity.test.mjs`）；优先级链**不变**。
+    """
+    if legacy_data_dir_exists(env, home):
+        return legacy_data_dir(env, home)                                  # ① 存在即沿用（老机器）
+    return _join(home or os_home(_env(env)), *NO_HOST_DATA_DIR_SEGMENTS)   # ② 新装（无宿主）⇒ ~/.argent
+
+
+def resolve_data_dir(env=None, home=None) -> dict:
+    """三级链解析（**唯一实现**）。
+
+    :param env:  环境映射（缺省 `os.environ`；测试夹具传 dict）
+    :param home: OS home 覆盖（缺省由 `os_home(env)` 推出）
+    :returns: `{"dir", "raw", "source", "isolated", "defaultDir", "dshHome"}`
+        · `dir`       解析结果（绝对路径；相对值按 **cwd** 解析）
+        · `source`    命中链上的哪一级（日志/面板用）
+        · `isolated`  `dir` **不等于**默认目录（`default_data_dir()`：老机器 = `~/.dsh/argent`）⇒ 隔离态
+    """
+    e = _env(env)
+    home_ = home or os_home(e)
+    default_dir = default_data_dir(e, home_)
+    dsh_home = dsh_home_of(e, home_)
+    explicit = _get(e, ENV_DATA_DIR)
+    if explicit:
+        raw = explicit
+    elif _get(e, ENV_DSH_HOME):
+        raw = _join(dsh_home, "argent")
+    else:
+        raw = default_dir
+    directory = _p.abspath(raw)
+    return {
+        "dir": directory,
+        "raw": raw,
+        "source": ENV_DATA_DIR if explicit else (ENV_DSH_HOME if _get(e, ENV_DSH_HOME) else "default"),
+        "isolated": directory != _p.abspath(default_dir),
+        "defaultDir": _p.abspath(default_dir),
+        "dshHome": dsh_home,
+    }
+
+
+def describe_data_dir(resolved) -> str:
+    """解析结果的单行描述（日志用）。**文案与 JS 内核逐字相同**（两边日志能对着读）。"""
+    if not resolved or not resolved.get("dir"):
+        return "数据目录未解析（内核解析器不可用）"
+    return f"{resolved['dir']}（来源={resolved.get('source')}{'，隔离' if resolved.get('isolated') else ''}）"
+
+
+def loop_gate_for_dir(directory, env=None, home=None) -> dict:
+    """对**任意**数据目录求安全阀（宿主把 `dataDir` 放在配置里显式指定时用）。
+
+    判据仍在内核：这里只把"配置里的目录"包装成与 `resolve_data_dir()` 同形的结果，
+    隔离判定**不**在调用方重写。
+    """
+    e = _env(env)
+    home_ = home or os_home(e)
+    raw = str(directory or "")
+    if not raw:
+        return loop_gate(None, env=e)
+    default_dir = _p.abspath(default_data_dir(e, home_))
+    abs_dir = _p.abspath(raw)
+    return loop_gate({
+        "dir": abs_dir,
+        "raw": raw,
+        "source": "config",
+        "isolated": abs_dir != default_dir,
+        "defaultDir": default_dir,
+        "dshHome": dsh_home_of(e, home_),
+    }, env=e)
+
+
+def loop_gate(resolved, env=None) -> dict:
+    """**隔离安全阀**：失败回路该不该跑。
+
+    规则（唯一判据，调用方不得自行判断）：
+      · 解析器不可用（`resolved` 为空 / `dir` 为空）⇒ **暂停**（fail-closed）；
+      · `isolated`（数据目录 ≠ 默认目录，判据 = `default_data_dir()`）且未显式
+        `ARGENT_ALLOW_ISOLATED_PUMP=1` ⇒ **暂停**，并给出可照做的开启提示；
+      · 其余 ⇒ 允许运行。
+
+    :returns: `{"enabled", "paused", "reason", "isolated", "dir", "notice"}`
+    """
+    e = _env(env)
+    allow = _get(e, ENV_ALLOW_ISOLATED_PUMP) == "1"
+    enabled_text = f"设 {ENV_ALLOW_ISOLATED_PUMP}=1 可开启"
+    if not resolved or not resolved.get("dir"):
+        return {
+            "enabled": False,
+            "paused": True,
+            "reason": "datadir-unresolved",
+            "isolated": True,
+            "dir": "",
+            "notice": "失败回路保持暂停：内核数据目录解析器不可用（core/lib/argent-datadir.mjs 没找到）"
+                      "⇒ 不敢猜目录。修好后重启即可。",
+        }
+    if resolved.get("isolated") and not allow:
+        return {
+            "enabled": False,
+            "paused": True,
+            "reason": "isolated-data-dir",
+            "isolated": True,
+            "dir": resolved["dir"],
+            "notice": f"失败回路因隔离数据目录而默认暂停（{describe_data_dir(resolved)}）；"
+                      f"隔离目录通常没有 PAUSE_FLOW_WATCH，默认运行会误扫/派发生产流程 ⇒ {enabled_text}",
+        }
+    isolated = bool(resolved.get("isolated"))
+    return {
+        "enabled": True,
+        "paused": False,
+        "reason": "isolated-allowed" if isolated else "default-dir",
+        "isolated": isolated,
+        "dir": resolved["dir"],
+        "notice": (f"失败回路已按 {ENV_ALLOW_ISOLATED_PUMP}=1 在隔离数据目录上开启"
+                   f"（{describe_data_dir(resolved)}）——请确认它扫的是隔离源，不是生产")
+                  if isolated else "",
+    }