"""KHY OS 裸机内核：pip 侧的 ISO 预置助手。

ISO 预置的唯一事实来源在 Node 层（`@khy/shared/runtime/khyos`，经由
`khy os provision` 暴露）。本模块只是一层薄封装，让 pip CLI 能在把终端
交给交互式 TUI **之前**，先在控制台完成内核 ISO 的下载 / SHA256 校验
（或本地定位）——否则数秒的下载会发生在 TUI 挂载期间，看起来像“假死”。
"""
from __future__ import annotations

import subprocess
import sys
from pathlib import Path
from typing import Mapping


def ensure_khyos_iso(node: str, cli_script: Path, env: Mapping[str, str]) -> int:
    """委派 Node 预置 KHY OS 内核 ISO。

    以准备好的环境运行 `node bin/khy.js os provision`，使 ISO 被下载并通过
    SHA256 校验（或在本地构建产物中定位）一次，且发生在实际命令执行之前的
    控制台中。返回子进程退出码（0 表示成功）。
    """
    cmd = [str(node), str(cli_script), "os", "provision"]
    try:
        result = subprocess.run(cmd, env=dict(env))
    except OSError as exc:
        print(f"khy os: 预置内核 ISO 失败：{exc}", file=sys.stderr)
        return 1
    return int(result.returncode or 0)