rrun-cli 0.1.2__tar.gz → 0.2.0__tar.gz

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrun-cli
-Version: 0.1.2
+Version: 0.2.0
 Summary: Run local scripts on remote machines over SSH via stdin pipes — no escaping/encoding hell. Supports python/powershell/bash, with a unified remote Python 3.12 venv provisioner.
 Author: waqiju
 License-Expression: MIT
@@ -21,6 +21,9 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
 Dynamic: license-file
 
 # rrun
@@ -100,6 +103,7 @@ The full set of hard-won conventions and internals: [docs/remote-exec-convention
 | `rrun config` | Diagnose the machines.json source chain |
 | `rrun setup <host\|--all> [--force]` | Provision the unified remote Python 3.12 venv (idempotent) |
 | `rrun pip <host> -- list` | Run pip inside the remote unified venv |
+| `rrun doctor <host\|--all>` | Health-check ssh + auth + remote python (`--all` opens real connections to every machine) |
 | `rrun close [<host>\|--all]` | Close ssh ControlMaster multiplexed connections |
 
 Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`, `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
@@ -121,11 +125,15 @@ Credentials live in local `machines.json` files — see [machines.template.json]
   "defaults": { "windows": { "os": "Windows" } },
   "machines": [
     { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows",
-      "user": "admin", "password": "secret" }
+      "user": "admin", "password": "secret" },
+    { "name": "cloud-vm", "ip": "1.2.3.4", "port": 2222, "os": "Linux",
+      "user": "root", "identity_file": "~/.ssh/id_ed25519" }
   ]
 }
 ```
 
+Per-machine fields: `name`/`ip`/`user` are required; `password` (plaintext, via sshpass) or leave it empty for **key-based auth** (`identity_file` optional — the default ssh key chain / agent / `~/.ssh/config` applies, with `BatchMode=yes` so a missing key fails fast instead of prompting); `port` (default `22`); `os` (`Windows` / `Mac` / `Linux`); optional `hostname` (also resolvable), `description`, `python` (explicit remote interpreter, skips auto-detection).
+
 Sources are merged by machine name, highest priority first (all optional, failures skipped silently):
 
 1. `$RRUN_CONFIG` (os.pathsep-separated, multiple files allowed)
@@ -149,8 +157,8 @@ If none match, run `rrun setup <host>`. It is idempotent and non-destructive: if
 
 ## Security
 
-- `machines.json` stores **plaintext passwords**. Keep it local, `chmod 600`, never commit it.
-- rrun authenticates with passwords via `sshpass`; **key-based authentication is not supported yet** (on the roadmap).
+- `machines.json` stores **plaintext passwords**. Keep it local, `chmod 600`, never commit it — or leave `password` empty and use key-based auth instead.
+- Key-based auth runs ssh with `BatchMode=yes` (no interactive prompts; a missing/unauthorized key fails fast instead of eating the script from stdin).
 - The audit log never records passwords, and `--env` values are logged as keys only.
 
 ## Auditing & state
@@ -168,7 +176,7 @@ pipx uninstall rrun-cli
 
 ## Contributing
 
-Issues and PRs are welcome. Development setup: clone → `python3.12 -m venv .venv && .venv/bin/pip install -e .` → hack → smoke-test with `rrun machines`. Releases are cut by pushing a `vX.Y.Z` tag; CI builds and publishes to PyPI via trusted publishing. See [CHANGELOG.md](CHANGELOG.md).
+Issues and PRs are welcome. Development setup: clone → `python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"` → hack → `pytest` + `ruff check .` → smoke-test with `rrun machines`. CI runs unit tests, ruff, and an end-to-end suite against a real sshd container. Releases are cut by pushing a `vX.Y.Z` tag; CI builds and publishes to PyPI via trusted publishing. See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/README.md

@@ -75,6 +75,7 @@ The full set of hard-won conventions and internals: [docs/remote-exec-convention
 | `rrun config` | Diagnose the machines.json source chain |
 | `rrun setup <host\|--all> [--force]` | Provision the unified remote Python 3.12 venv (idempotent) |
 | `rrun pip <host> -- list` | Run pip inside the remote unified venv |
+| `rrun doctor <host\|--all>` | Health-check ssh + auth + remote python (`--all` opens real connections to every machine) |
 | `rrun close [<host>\|--all]` | Close ssh ControlMaster multiplexed connections |
 
 Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`, `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
@@ -96,11 +97,15 @@ Credentials live in local `machines.json` files — see [machines.template.json]
   "defaults": { "windows": { "os": "Windows" } },
   "machines": [
     { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows",
-      "user": "admin", "password": "secret" }
+      "user": "admin", "password": "secret" },
+    { "name": "cloud-vm", "ip": "1.2.3.4", "port": 2222, "os": "Linux",
+      "user": "root", "identity_file": "~/.ssh/id_ed25519" }
   ]
 }
 ```
 
+Per-machine fields: `name`/`ip`/`user` are required; `password` (plaintext, via sshpass) or leave it empty for **key-based auth** (`identity_file` optional — the default ssh key chain / agent / `~/.ssh/config` applies, with `BatchMode=yes` so a missing key fails fast instead of prompting); `port` (default `22`); `os` (`Windows` / `Mac` / `Linux`); optional `hostname` (also resolvable), `description`, `python` (explicit remote interpreter, skips auto-detection).
+
 Sources are merged by machine name, highest priority first (all optional, failures skipped silently):
 
 1. `$RRUN_CONFIG` (os.pathsep-separated, multiple files allowed)
@@ -124,8 +129,8 @@ If none match, run `rrun setup <host>`. It is idempotent and non-destructive: if
 
 ## Security
 
-- `machines.json` stores **plaintext passwords**. Keep it local, `chmod 600`, never commit it.
-- rrun authenticates with passwords via `sshpass`; **key-based authentication is not supported yet** (on the roadmap).
+- `machines.json` stores **plaintext passwords**. Keep it local, `chmod 600`, never commit it — or leave `password` empty and use key-based auth instead.
+- Key-based auth runs ssh with `BatchMode=yes` (no interactive prompts; a missing/unauthorized key fails fast instead of eating the script from stdin).
 - The audit log never records passwords, and `--env` values are logged as keys only.
 
 ## Auditing & state
@@ -143,7 +148,7 @@ pipx uninstall rrun-cli
 
 ## Contributing
 
-Issues and PRs are welcome. Development setup: clone → `python3.12 -m venv .venv && .venv/bin/pip install -e .` → hack → smoke-test with `rrun machines`. Releases are cut by pushing a `vX.Y.Z` tag; CI builds and publishes to PyPI via trusted publishing. See [CHANGELOG.md](CHANGELOG.md).
+Issues and PRs are welcome. Development setup: clone → `python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"` → hack → `pytest` + `ruff check .` → smoke-test with `rrun machines`. CI runs unit tests, ruff, and an end-to-end suite against a real sshd container. Releases are cut by pushing a `vX.Y.Z` tag; CI builds and publishes to PyPI via trusted publishing. See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rrun-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "Run local scripts on remote machines over SSH via stdin pipes — no escaping/encoding hell. Supports python/powershell/bash, with a unified remote Python 3.12 venv provisioner."
 readme = "README.md"
 license = "MIT"
@@ -24,6 +24,9 @@ classifiers = [
 # 纯标准库实现，零第三方依赖。控制端仅需本机有 ssh + sshpass。
 dependencies = []
 
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
 [project.urls]
 Homepage = "https://github.com/waqiju/rrun"
 Repository = "https://github.com/waqiju/rrun"
@@ -43,3 +46,16 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 rrun = ["remote-requirements.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "BLE"]
+# E501 交给格式化宽限：项目内大量中文注释 + 单行 wrapper 模板，硬限 120 收益低
+ignore = ["E501"]

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun/__init__.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """rrun — 远程机器执行模块（Run Remote）。
 
 约定：read/write/edit 等文件操作始终发生在本地；任何远程执行都是
@@ -12,8 +11,9 @@ try:
 
     __version__ = _pkg_version("rrun-cli")
 except Exception:  # noqa: BLE001 - 未安装（源码直跑）时回退
-    __version__ = "0.1.2"
+    __version__ = "0.2.0"
 
+from .doctor import DoctorResult, check_machine
 from .executor import (
     AUDIT_LOG,
     EXIT_TIMEOUT,
@@ -30,7 +30,7 @@ from .setup import SetupResult, load_requirements, setup_machine
 
 __all__ = [
     "AUDIT_LOG", "EXIT_TIMEOUT", "EXIT_TRANSPORT_ERROR", "RRUN_HOME",
-    "ExecResult", "Machine", "SetupResult", "SourceInfo",
-    "build_ps_wrapper", "candidate_sources", "close_mux", "detect_remote_python",
+    "DoctorResult", "ExecResult", "Machine", "SetupResult", "SourceInfo",
+    "build_ps_wrapper", "candidate_sources", "check_machine", "close_mux", "detect_remote_python",
     "load_machines", "load_requirements", "resolve_machine", "run", "scan_sources", "setup_machine",
 ]

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun/__main__.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """rrun CLI — run local scripts on remote machines over SSH stdin pipes.
 
 Core contract: script content (UTF-8, CJK welcome) is piped to the remote
@@ -12,6 +11,7 @@ Usage:
     rrun exec mac_mini --lang python temp/x.py
     rrun setup <host|--all> [--force]   # provision the unified python env (3.12 venv)
     rrun pip <host> -- list             # run pip in the unified venv
+    rrun doctor <host|--all>            # health-check ssh + auth + remote python
     rrun machines                       # list machines (redacted, with source)
     rrun config                         # diagnose the machines.json source chain
     rrun close [<host>|--all]           # close ssh multiplexed connections
@@ -29,6 +29,8 @@ Conventions:
       255=ssh transport error; 124=local timeout.
     - Inline -c content is archived under ~/.rrun/drops/ for replay.
     - Audit: every execution appends to ~/.rrun/log/remote-exec.jsonl.
+    - Auth: machines.json "password" => sshpass; leave it empty for key-based
+      ssh ("identity_file" optional); "port" overrides the default ssh port 22.
 
 Remote stdout -> local stdout, stderr -> stderr; the exit code is the remote one.
 """
@@ -39,6 +41,7 @@ import sys
 import time
 from pathlib import Path
 
+from .doctor import check_machine
 from .executor import RRUN_HOME, _check_ascii, _ssh_run, close_mux, run
 from .registry import load_machines, resolve_machine, scan_sources
 from .setup import setup_machine, venv_python_or_die
@@ -69,7 +72,7 @@ def cmd_exec(ns) -> int:
     try:
         machine = resolve_machine(ns.host)
     except KeyError as e:
-        raise SystemExit(f"[remote-exec] {e}")
+        raise SystemExit(f"[remote-exec] {e}") from None
 
     content = ns.content
     file = ns.script or ""
@@ -98,7 +101,7 @@ def cmd_exec(ns) -> int:
             mux=not ns.no_mux,
         )
     except (ValueError, RuntimeError) as e:
-        raise SystemExit(f"[remote-exec] {e}")
+        raise SystemExit(f"[remote-exec] {e}") from None
 
     if not ns.quiet:
         via = script_for_log or "<stdin>"
@@ -113,7 +116,7 @@ def cmd_exec(ns) -> int:
     if result.timed_out:
         print(f"[remote-exec] local timeout ({ns.timeout}s), ssh client killed", file=sys.stderr)
     elif result.transport_error:
-        print(f"[remote-exec] ssh transport error (unreachable / auth failure / dropped), exit=255", file=sys.stderr)
+        print("[remote-exec] ssh transport error (unreachable / auth failure / dropped), exit=255", file=sys.stderr)
     if not ns.quiet:
         print(f"[remote-exec] exit={result.exit_code} took {result.duration:.1f}s", file=sys.stderr)
     return result.exit_code
@@ -199,7 +202,7 @@ def cmd_pip(ns) -> int:
     try:
         machine = resolve_machine(ns.host)
     except KeyError as e:
-        raise SystemExit(f"[pip] {e}")
+        raise SystemExit(f"[pip] {e}") from None
     args = list(ns.pargs or []) + list(getattr(ns, "args", []) or [])
     if not args:
         raise SystemExit("[pip] missing pip args, e.g.: rrun pip <host> -- list")
@@ -207,7 +210,7 @@ def cmd_pip(ns) -> int:
         _check_ascii(args, "pip args")
         py = venv_python_or_die(ns.host)
     except (ValueError, RuntimeError) as e:
-        raise SystemExit(f"[pip] {e}")
+        raise SystemExit(f"[pip] {e}") from None
     joined = " ".join(args)
     if machine.is_windows:
         remote_cmd = f'"{py}" -m pip {joined}'
@@ -223,6 +226,35 @@ def cmd_pip(ns) -> int:
     return rc
 
 
+def cmd_doctor(ns) -> int:
+    if ns.all:
+        hosts = [m.name for m in load_machines()]
+    elif ns.host:
+        hosts = [ns.host]
+    else:
+        raise SystemExit("[doctor] specify a host, or --all to check every machine")
+    results = []
+    if len(hosts) == 1:
+        print(f"[doctor] checking {hosts[0]} ...", file=sys.stderr)
+        results.append(check_machine(hosts[0]))
+    else:
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+        with ThreadPoolExecutor(max_workers=ns.jobs) as pool:
+            futs = {pool.submit(check_machine, h): h for h in hosts}
+            for f in as_completed(futs):
+                r = f.result()
+                results.append(r)
+                print(f"[doctor] {r.host}: {'ok' if r.ok else 'FAIL'} ({r.latency_s:.1f}s)", file=sys.stderr)
+    print(f"\n{'host':<24} {'result':<6} {'ssh':<5} {'python':<10} {'via':<14} note")
+    for r in sorted(results, key=lambda x: x.host):
+        ssh = "ok" if r.ssh_ok else "FAIL"
+        ver = r.python_version or "-"
+        via = ("unified venv" if r.is_unified_venv else ("fallback" if r.python_path else "-"))
+        note = "; ".join(r.checks) if r.ok else r.message
+        print(f"{r.host:<24} {'ok' if r.ok else 'FAIL':<6} {ssh:<5} {ver:<10} {via:<14} {note[:90]}")
+    return 0 if all(r.ok for r in results) else 1
+
+
 def cmd_close(ns) -> int:
     if ns.all:
         hosts = [m.name for m in load_machines()]
@@ -285,6 +317,12 @@ def main() -> None:
     pp.add_argument("--timeout", type=float, default=300.0, help="local timeout in seconds (default 300)")
     pp.set_defaults(func=cmd_pip)
 
+    dp = sub.add_parser("doctor", help="health-check a machine (ssh + auth + remote python)")
+    dp.add_argument("host", nargs="?", help="machine name/ip; omit with --all")
+    dp.add_argument("--all", action="store_true", help="check every machine (opens real ssh connections)")
+    dp.add_argument("--jobs", type=int, default=6, help="concurrency for --all (default 6)")
+    dp.set_defaults(func=cmd_doctor)
+
     cp = sub.add_parser("close", help="close ssh ControlMaster multiplexed connections")
     cp.add_argument("host", nargs="?", help="machine name/ip; omit with --all")
     cp.add_argument("--all", action="store_true", help="close connections for all machines")
@@ -293,7 +331,7 @@ def main() -> None:
     # argparse 对 -- 的处理与子解析器/位置参数组合有 quirk，手动切分更可靠：
     # 第一个 -- 之后的全部内容原样作为脚本参数
     argv = sys.argv[1:]
-    passthrough: "list[str] | None" = None
+    passthrough: list[str] | None = None
     if "--" in argv:
         i = argv.index("--")
         argv, passthrough = argv[:i], argv[i + 1:]

rrun_cli-0.2.0/src/rrun/doctor.py

@@ -0,0 +1,88 @@
+"""doctor：单机健康检查（ssh 连通性 + 认证 + 远端 python 环境）。
+
+默认只查显式指定的一台机器——检查会产生真实 ssh 连接（副作用），
+连全部机器必须显式 --all。
+"""
+
+import time
+from dataclasses import dataclass, field
+
+from .executor import (
+    POSIX_PYTHON_CANDIDATES,
+    PS_REMOTE_CMD,
+    VENV_PY_POSIX,
+    VENV_PY_WIN,
+    WINDOWS_PYTHON_CANDIDATES,
+    _ssh_run,
+    build_ps_wrapper,
+    probe_python,
+)
+from .registry import resolve_machine
+
+
+@dataclass
+class DoctorResult:
+    host: str
+    ok: bool = False
+    ssh_ok: bool = False
+    latency_s: float = 0.0
+    python_path: str = ""
+    python_version: str = ""
+    is_unified_venv: bool = False
+    checks: "list[str]" = field(default_factory=list)  # 已通过的检查项描述
+    message: str = ""                                   # 失败原因 / 建议
+
+
+def check_machine(host: str, mux: bool = True, timeout: float = 30.0) -> DoctorResult:
+    """检查单台机器：ssh 回显 → 远端 python 探测。不抛异常，结果全部汇入 DoctorResult。"""
+    try:
+        machine = resolve_machine(host)
+    except KeyError as e:
+        return DoctorResult(host=host, message=str(e))
+    r = DoctorResult(host=machine.name)
+
+    # 1) ssh 连通 + 认证（一个最小回显脚本）
+    t0 = time.time()
+    try:
+        if machine.is_windows:
+            rc, out, err, _ = _ssh_run(machine, PS_REMOTE_CMD,
+                                       build_ps_wrapper("Write-Output rrun-ok"), timeout, mux)
+        else:
+            rc, out, err, _ = _ssh_run(machine, "bash -s", b"echo rrun-ok\n", timeout, mux)
+    except RuntimeError as e:
+        r.message = str(e)
+        return r
+    r.latency_s = time.time() - t0
+    if rc != 0 or b"rrun-ok" not in out:
+        detail = err.decode("utf-8", "replace").strip()[:200]
+        r.message = (f"ssh check failed (exit={rc})"
+                     + (f": {detail}" if detail else ""))
+        return r
+    r.ssh_ok = True
+    r.checks.append(f"ssh ok ({r.latency_s:.2f}s)")
+
+    # 2) 远端 python 探测（exec 热路径同款候选链；不命中不算 ssh 失败）
+    venv_py = VENV_PY_WIN if machine.is_windows else VENV_PY_POSIX
+    candidates = WINDOWS_PYTHON_CANDIDATES if machine.is_windows else POSIX_PYTHON_CANDIDATES
+    try:
+        hit = probe_python(machine, candidates, mux)
+    except RuntimeError as e:
+        r.message = str(e)
+        return r
+    if hit:
+        r.python_path, r.python_version = hit
+        # POSIX 候选含 $HOME，远端展开后回显的是绝对路径，不能与常量直接等值比较；
+        # 用后缀判定（Windows 候选是绝对路径常量，等值即可）。
+        if machine.is_windows:
+            r.is_unified_venv = r.python_path.lower() == venv_py.lower()
+        else:
+            r.is_unified_venv = r.python_path == venv_py or r.python_path.endswith(
+                "/.remote-machine/venv/bin/python")
+        tag = "unified venv" if r.is_unified_venv else "fallback (not the unified venv)"
+        r.checks.append(f"python {r.python_version} at {r.python_path} [{tag}]")
+        if not r.is_unified_venv:
+            r.message = f"unified venv missing; run: rrun setup {machine.name}"
+    else:
+        r.message = f"no python 3.12 found; run: rrun setup {machine.name}"
+    r.ok = r.ssh_ok and bool(hit) and r.is_unified_venv
+    return r

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun/executor.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """远程执行核心：本地脚本 → ssh stdin 管道 → 远端解释器执行。
 
 设计要点（Phase 0 spike 实测验证）：
@@ -164,18 +163,35 @@ def build_bash_command(args=(), workdir: str = "", env: "dict | None" = None) ->
     return cmd
 
 
-def _ssh_run(machine: Machine, remote_cmd: str, stdin: bytes, timeout: "float | None",
-             mux: bool) -> "tuple[int, bytes, bytes, bool]":
-    """返回 (exit_code, stdout, stderr, timed_out)。exit 255 即传输层错误。"""
-    sshpass = shutil.which("sshpass")
-    if not sshpass:
-        raise RuntimeError("sshpass not found on this machine (install: sudo apt install sshpass / brew install hudochenkov/sshpass/sshpass)")
+def _ssh_args(machine: Machine, mux: bool) -> "list[str]":
+    """组装 ssh/sshpass 参数：认证（密码走 sshpass，否则 key 链 + BatchMode）、端口、mux。"""
+    args: list[str] = []
+    if machine.password:
+        sshpass = shutil.which("sshpass")
+        if not sshpass:
+            raise RuntimeError("sshpass not found on this machine (install: sudo apt install sshpass / brew install hudochenkov/sshpass/sshpass)")
+        args += [sshpass, "-p", machine.password]
+    args.append("ssh")
+    if machine.password:
+        args += ["-o", "NumberOfPasswordPrompts=1"]  # 密码错误快速失败，不反复提示
+    else:
+        # key 认证：禁交互提示（防密码 prompt 把 stdin 脚本吃掉/挂起）
+        args += ["-o", "BatchMode=yes"]
+    if machine.identity_file:
+        args += ["-i", str(Path(machine.identity_file).expanduser())]
+    args += SSH_BASE_OPTS
+    if machine.port != 22:
+        args += ["-p", str(machine.port)]
     if mux:
         CONTROL_PATH_DIR.mkdir(mode=0o700, exist_ok=True)
-    args = [sshpass, "-p", machine.password, "ssh", *SSH_BASE_OPTS]
-    if mux:
         args += MUX_OPTS
-    args += [machine.target, remote_cmd]
+    return args
+
+
+def _ssh_run(machine: Machine, remote_cmd: str, stdin: bytes, timeout: "float | None",
+             mux: bool) -> "tuple[int, bytes, bytes, bool]":
+    """返回 (exit_code, stdout, stderr, timed_out)。exit 255 即传输层错误。"""
+    args = [*_ssh_args(machine, mux), machine.target, remote_cmd]
     try:
         p = subprocess.run(args, input=stdin, capture_output=True,
                            timeout=timeout if timeout and timeout > 0 else None)
@@ -356,7 +372,11 @@ def _write_audit(result: ExecResult, args, workdir: str, env: "dict | None",
 def close_mux(host: str) -> "tuple[int, str]":
     """关闭某台机器的 ControlMaster 复用连接。"""
     machine = resolve_machine(host)
-    p = subprocess.run(
-        ["ssh", "-O", "exit", "-o", f"ControlPath={CONTROL_PATH}", machine.target],
-        capture_output=True, text=True, timeout=15)
+    args = ["ssh", "-O", "exit", "-o", f"ControlPath={CONTROL_PATH}"]
+    if machine.port != 22:
+        args += ["-p", str(machine.port)]
+    if machine.identity_file:
+        args += ["-i", str(Path(machine.identity_file).expanduser())]
+    args.append(machine.target)
+    p = subprocess.run(args, capture_output=True, text=True, timeout=15)
     return p.returncode, (p.stdout + p.stderr).strip()

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun/registry.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """机器注册表：多来源加载 machines.json，按优先级 merge，解析 name/ip/hostname → Machine。
 
 来源链（高 → 低优先级；同名机器高优先级覆盖；同名/ip 冲突静默处理，不刷警告）：
@@ -24,7 +23,7 @@ from pathlib import Path
 ENV_MACHINES_JSON = "RRUN_CONFIG"
 ENV_MACHINES_JSON_LEGACY = "REMOTE_MACHINE_CONFIG"
 
-_KNOWN_KEYS = {"name", "ip", "user", "password", "os", "hostname", "description", "python"}
+_KNOWN_KEYS = {"name", "ip", "user", "password", "os", "hostname", "description", "python", "port", "identity_file"}
 
 
 @dataclass
@@ -32,11 +31,13 @@ class Machine:
     name: str
     ip: str
     user: str
-    password: str = field(repr=False)  # 凭据不进 repr/日志
+    password: str = field(repr=False, default="")  # 凭据不进 repr/日志；留空 = 走 key 认证
     os: str = "Windows"                # 原样取值：Windows / Mac / Linux
     hostname: str = ""
     description: str = ""
     python: str = ""                   # 可选：显式指定远端 python 路径，跳过自动探测
+    port: int = 22                     # SSH 端口
+    identity_file: str = ""            # 可选：私钥路径（password 为空时走默认 key 链/agent）
     source: str = ""                   # 来源文件路径（多来源 merge 时记录出处）
 
     @property
@@ -56,6 +57,7 @@ class Machine:
         return {
             "name": self.name, "ip": self.ip, "os": self.os, "user": self.user,
             "hostname": self.hostname, "description": self.description,
+            "port": self.port, "auth": "password" if self.password else "key",
             "default_lang": self.default_lang, "source": self.source,
         }
 
@@ -72,7 +74,7 @@ class SourceInfo:
 
 def candidate_sources() -> "list[tuple[str, Path]]":
     """返回 (标签, 路径) 有序来源链（高→低优先级），按 resolved path 去重。"""
-    cands: "list[tuple[str, Path]]" = []
+    cands: list[tuple[str, Path]] = []
     for env_name in (ENV_MACHINES_JSON, ENV_MACHINES_JSON_LEGACY):
         env = os.environ.get(env_name, "")
         env_paths = [x for x in env.split(os.pathsep) if x.strip()]
@@ -90,8 +92,8 @@ def candidate_sources() -> "list[tuple[str, Path]]":
         cands.append(("legacy", Path(r"C:\tools\remote-machine\machines.json")))
     else:
         cands.append(("legacy", Path.home() / ".remote-machine" / "machines.json"))
-    seen: "set[str]" = set()
-    uniq: "list[tuple[str, Path]]" = []
+    seen: set[str] = set()
+    uniq: list[tuple[str, Path]] = []
     for label, p in cands:
         try:
             key = os.path.normcase(str(p.resolve()))
@@ -113,6 +115,8 @@ def _load_file(path: Path) -> "list[Machine]":
         base = defaults.get(str(m.get("os", "")).lower()) or {}
         merged = {**base, **m}  # 机器自身字段优先于 defaults
         kwargs = {k: v for k, v in merged.items() if k in _KNOWN_KEYS}
+        if "port" in kwargs:
+            kwargs["port"] = int(kwargs["port"])
         machine = Machine(**kwargs)
         machine.source = str(path)
         result.append(machine)
@@ -123,7 +127,7 @@ def load_machines(path: "str | os.PathLike | None" = None) -> "list[Machine]":
     """加载机器清单。显式传 path = 单文件模式；否则按来源链 merge（同名高优先级胜）。"""
     if path:
         return _load_file(Path(path))
-    merged: "dict[str, Machine]" = {}
+    merged: dict[str, Machine] = {}
     for _label, p in candidate_sources():
         if not p.is_file():
             continue

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun/setup.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """setup：初始化远端统一 python 环境（基线 3.12 + 统一 venv + 阿里云 pip 源）。
 
 布局（幂等，可重复执行）：

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrun-cli
-Version: 0.1.2
+Version: 0.2.0
 Summary: Run local scripts on remote machines over SSH via stdin pipes — no escaping/encoding hell. Supports python/powershell/bash, with a unified remote Python 3.12 venv provisioner.
 Author: waqiju
 License-Expression: MIT
@@ -21,6 +21,9 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
 Dynamic: license-file
 
 # rrun
@@ -100,6 +103,7 @@ The full set of hard-won conventions and internals: [docs/remote-exec-convention
 | `rrun config` | Diagnose the machines.json source chain |
 | `rrun setup <host\|--all> [--force]` | Provision the unified remote Python 3.12 venv (idempotent) |
 | `rrun pip <host> -- list` | Run pip inside the remote unified venv |
+| `rrun doctor <host\|--all>` | Health-check ssh + auth + remote python (`--all` opens real connections to every machine) |
 | `rrun close [<host>\|--all]` | Close ssh ControlMaster multiplexed connections |
 
 Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`, `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
@@ -121,11 +125,15 @@ Credentials live in local `machines.json` files — see [machines.template.json]
   "defaults": { "windows": { "os": "Windows" } },
   "machines": [
     { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows",
-      "user": "admin", "password": "secret" }
+      "user": "admin", "password": "secret" },
+    { "name": "cloud-vm", "ip": "1.2.3.4", "port": 2222, "os": "Linux",
+      "user": "root", "identity_file": "~/.ssh/id_ed25519" }
   ]
 }
 ```
 
+Per-machine fields: `name`/`ip`/`user` are required; `password` (plaintext, via sshpass) or leave it empty for **key-based auth** (`identity_file` optional — the default ssh key chain / agent / `~/.ssh/config` applies, with `BatchMode=yes` so a missing key fails fast instead of prompting); `port` (default `22`); `os` (`Windows` / `Mac` / `Linux`); optional `hostname` (also resolvable), `description`, `python` (explicit remote interpreter, skips auto-detection).
+
 Sources are merged by machine name, highest priority first (all optional, failures skipped silently):
 
 1. `$RRUN_CONFIG` (os.pathsep-separated, multiple files allowed)
@@ -149,8 +157,8 @@ If none match, run `rrun setup <host>`. It is idempotent and non-destructive: if
 
 ## Security
 
-- `machines.json` stores **plaintext passwords**. Keep it local, `chmod 600`, never commit it.
-- rrun authenticates with passwords via `sshpass`; **key-based authentication is not supported yet** (on the roadmap).
+- `machines.json` stores **plaintext passwords**. Keep it local, `chmod 600`, never commit it — or leave `password` empty and use key-based auth instead.
+- Key-based auth runs ssh with `BatchMode=yes` (no interactive prompts; a missing/unauthorized key fails fast instead of eating the script from stdin).
 - The audit log never records passwords, and `--env` values are logged as keys only.
 
 ## Auditing & state
@@ -168,7 +176,7 @@ pipx uninstall rrun-cli
 
 ## Contributing
 
-Issues and PRs are welcome. Development setup: clone → `python3.12 -m venv .venv && .venv/bin/pip install -e .` → hack → smoke-test with `rrun machines`. Releases are cut by pushing a `vX.Y.Z` tag; CI builds and publishes to PyPI via trusted publishing. See [CHANGELOG.md](CHANGELOG.md).
+Issues and PRs are welcome. Development setup: clone → `python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"` → hack → `pytest` + `ruff check .` → smoke-test with `rrun machines`. CI runs unit tests, ruff, and an end-to-end suite against a real sshd container. Releases are cut by pushing a `vX.Y.Z` tag; CI builds and publishes to PyPI via trusted publishing. See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

{rrun_cli-0.1.2 → rrun_cli-0.2.0}/src/rrun_cli.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 src/rrun/__init__.py
 src/rrun/__main__.py
+src/rrun/doctor.py
 src/rrun/executor.py
 src/rrun/registry.py
 src/rrun/remote-requirements.txt
@@ -11,4 +12,9 @@ src/rrun_cli.egg-info/PKG-INFO
 src/rrun_cli.egg-info/SOURCES.txt
 src/rrun_cli.egg-info/dependency_links.txt
 src/rrun_cli.egg-info/entry_points.txt
-src/rrun_cli.egg-info/top_level.txt
+src/rrun_cli.egg-info/requires.txt
+src/rrun_cli.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_executor.py
+tests/test_registry.py
+tests/test_setup.py

rrun_cli-0.2.0/src/rrun_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8
+ruff>=0.6

rrun_cli-0.2.0/tests/test_cli.py

@@ -0,0 +1,29 @@
+"""CLI 辅助函数测试：--env 解析、inline 落盘。"""
+
+import pytest
+
+import rrun.__main__ as cli
+
+
+class TestParseEnv:
+    def test_pairs(self):
+        assert cli._parse_env(["A=1", "B=x=y"]) == {"A": "1", "B": "x=y"}
+
+    def test_none(self):
+        assert cli._parse_env(None) == {}
+
+    def test_bad_pair(self):
+        with pytest.raises(SystemExit):
+            cli._parse_env(["NO_EQUALS"])
+
+
+class TestDropInline:
+    def test_drop_by_lang(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(cli, "INLINE_DROP_DIR", tmp_path / "drops")
+        p = cli._drop_inline("mac1", "python", "print('你好')\n")
+        assert p.suffix == ".py" and "mac1" in p.name
+        assert p.read_text(encoding="utf-8") == "print('你好')\n"
+
+    def test_unknown_lang_txt(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(cli, "INLINE_DROP_DIR", tmp_path / "drops")
+        assert cli._drop_inline("h", "weird", "x").suffix == ".txt"

rrun_cli-0.2.0/tests/test_executor.py

@@ -0,0 +1,129 @@
+"""executor 纯函数测试：PS wrapper、bash 命令、ASCII 校验、ssh 参数组装。"""
+
+import base64
+
+import pytest
+
+from rrun.executor import (
+    _check_ascii,
+    _posix_prefix,
+    _ps_quote,
+    _ssh_args,
+    build_bash_command,
+    build_ps_wrapper,
+)
+from rrun.registry import Machine
+
+
+def _win(**kw):
+    kw.setdefault("os", "Windows")
+    return Machine(name="w", ip="1.1.1.1", user="u", **kw)
+
+
+class TestCheckAscii:
+    def test_ascii_ok(self):
+        _check_ascii(["abc", "x=1"], "args")
+
+    @pytest.mark.parametrize("bad", ["中文", "café", "a​b"])
+    def test_non_ascii_rejected(self, bad):
+        with pytest.raises(ValueError, match="ASCII"):
+            _check_ascii([bad], "args")
+
+
+class TestPsWrapper:
+    def test_pure_ascii_single_line(self):
+        payload = build_ps_wrapper('Write-Output "你好，世界"')
+        assert payload.count(b"\n") == 1
+        payload.decode("ascii")  # 必须纯 ASCII
+
+    def test_script_content_roundtrips_via_base64(self):
+        code = 'Write-Output "你好 $HOME `n"'
+        line = build_ps_wrapper(code).decode("ascii")
+        b64 = line.split("FromBase64String('")[1].split("'")[0]
+        assert base64.b64decode(b64).decode("utf-8") == code
+
+    def test_args_workdir_env(self):
+        line = build_ps_wrapper("x", args=["a", "b'c"], workdir="C:\\work",
+                                env={"K": "v"}).decode("ascii")
+        assert "Set-Location 'C:\\work'" in line
+        assert "$env:K='v'" in line
+        assert "'b''c'" in line  # PS 单引号转义
+        assert "$__args=@('a','b''c')" in line
+
+    def test_non_ascii_args_rejected(self):
+        with pytest.raises(ValueError, match="ASCII"):
+            build_ps_wrapper("x", args=["中文"])
+
+    def test_exit_code_passthrough_tail(self):
+        line = build_ps_wrapper("x").decode("ascii")
+        assert "exit $LASTEXITCODE" in line
+        assert "ScriptBlock" in line
+
+
+class TestBashCommand:
+    def test_plain(self):
+        assert build_bash_command() == "bash -s"
+
+    def test_args_workdir_env(self):
+        cmd = build_bash_command(args=["a b", "c"], workdir="/tmp/x y", env={"K": "v v"})
+        assert cmd.startswith("cd '/tmp/x y' && env K='v v' bash -s -- ")
+        assert "'a b'" in cmd and cmd.endswith(" c")
+
+    def test_non_ascii_args_rejected(self):
+        with pytest.raises(ValueError, match="ASCII"):
+            build_bash_command(args=["中文"])
+
+
+class TestPosixPrefix:
+    def test_empty(self):
+        assert _posix_prefix() == ""
+
+    def test_quoting(self):
+        assert _posix_prefix(workdir="a b") == "cd 'a b' && "
+        assert _posix_prefix(env={"K": "v v"}) == "env K='v v' "
+
+
+class TestPsQuote:
+    def test_escape(self):
+        assert _ps_quote("a'b") == "'a''b'"
+
+
+class TestSshArgs:
+    def test_password_uses_sshpass(self, monkeypatch):
+        monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/sshpass" if name == "sshpass" else None)
+        args = _ssh_args(_win(password="pw"), mux=False)
+        assert args[:3] == ["/usr/bin/sshpass", "-p", "pw"]
+        assert "NumberOfPasswordPrompts=1" in args
+        assert "BatchMode=yes" not in args
+
+    def test_password_without_sshpass_raises(self, monkeypatch):
+        monkeypatch.setattr("shutil.which", lambda name: None)
+        with pytest.raises(RuntimeError, match="sshpass not found"):
+            _ssh_args(_win(password="pw"), mux=False)
+
+    def test_key_auth_needs_no_sshpass(self, monkeypatch):
+        monkeypatch.setattr("shutil.which", lambda name: None)  # 无 sshpass 也能走 key
+        args = _ssh_args(_win(password="", identity_file="~/.ssh/id_ed25519"), mux=False)
+        assert args[0] == "ssh"
+        assert "BatchMode=yes" in args
+        i = args.index("-i")
+        assert args[i + 1].endswith(".ssh/id_ed25519")
+
+    def test_custom_port(self, monkeypatch):
+        monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/sshpass")
+        args = _ssh_args(_win(password="pw", port=2222), mux=False)
+        i = args.index("-p", 2)  # 跳过 sshpass -p
+        assert args[i + 1] == "2222"
+
+    def test_default_port_no_flag(self, monkeypatch):
+        monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/sshpass")
+        args = _ssh_args(_win(password="pw"), mux=False)
+        assert "-p" not in args[3:]  # sshpass 的 -p 之后不再有 -p
+
+    def test_mux_adds_control_opts(self, monkeypatch, tmp_path):
+        monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/sshpass")
+        import rrun.executor as ex
+        monkeypatch.setattr(ex, "CONTROL_PATH_DIR", tmp_path / ".ssh")
+        args = _ssh_args(_win(password="pw"), mux=True)
+        assert "ControlMaster=auto" in " ".join(args)
+        assert (tmp_path / ".ssh").is_dir()

rrun_cli-0.2.0/tests/test_registry.py

@@ -0,0 +1,131 @@
+"""registry 纯函数测试：来源链、merge 优先级、defaults、端口/key 字段。"""
+
+import json
+import os
+
+import pytest
+
+from rrun import registry
+from rrun.registry import Machine, _load_file, load_machines, resolve_machine
+
+
+def _write(path, machines, defaults=None):
+    data = {"machines": machines}
+    if defaults:
+        data["defaults"] = defaults
+    path.write_text(json.dumps(data), encoding="utf-8")
+    return path
+
+
+@pytest.fixture()
+def isolated(monkeypatch, tmp_path):
+    """隔离全部来源：HOME 指向临时目录、cwd 切换、两个 env var 清空。"""
+    monkeypatch.setenv("RRUN_CONFIG", "")
+    monkeypatch.setenv("REMOTE_MACHINE_CONFIG", "")
+    home = tmp_path / "home"
+    (home / ".rrun").mkdir(parents=True)
+    monkeypatch.setenv("HOME", str(home))  # POSIX 下 Path.home() 读 HOME
+    cwd = tmp_path / "cwd"
+    cwd.mkdir()
+    monkeypatch.chdir(cwd)
+    return tmp_path
+
+
+class TestMachine:
+    def test_defaults(self):
+        m = Machine(name="a", ip="1.1.1.1", user="u")
+        assert m.port == 22 and m.identity_file == "" and m.password == ""
+        assert m.os == "Windows" and m.is_windows and m.default_lang == "powershell"
+
+    def test_public_dict_redacts_password(self):
+        m = Machine(name="a", ip="1.1.1.1", user="u", password="secret")
+        d = m.public_dict()
+        assert "secret" not in json.dumps(d)
+        assert d["auth"] == "password"
+        m2 = Machine(name="b", ip="2.2.2.2", user="u")
+        assert m2.public_dict()["auth"] == "key"
+
+    def test_password_not_in_repr(self):
+        assert "secret" not in repr(Machine(name="a", ip="1.1.1.1", user="u", password="secret"))
+
+
+class TestLoadFile:
+    def test_defaults_applied_per_os(self, tmp_path):
+        p = _write(
+            tmp_path / "m.json",
+            [{"name": "w1", "ip": "1.1.1.1", "os": "Windows"},
+             {"name": "m1", "ip": "2.2.2.2", "os": "Mac", "user": "macuser"}],
+            defaults={"windows": {"user": "winuser", "password": "wpw"},
+                      "mac": {"password": "mpw"}},
+        )
+        machines = {m.name: m for m in _load_file(p)}
+        assert machines["w1"].user == "winuser" and machines["w1"].password == "wpw"
+        assert machines["m1"].user == "macuser" and machines["m1"].password == "mpw"
+
+    def test_port_and_identity_file(self, tmp_path):
+        p = _write(tmp_path / "m.json",
+                   [{"name": "a", "ip": "1.1.1.1", "user": "u", "port": 2222,
+                     "identity_file": "~/.ssh/id_ed25519"}])
+        (m,) = _load_file(p)
+        assert m.port == 2222 and m.identity_file == "~/.ssh/id_ed25519"
+
+    def test_port_string_cast_to_int(self, tmp_path):
+        p = _write(tmp_path / "m.json", [{"name": "a", "ip": "1.1.1.1", "user": "u", "port": "2222"}])
+        assert _load_file(p)[0].port == 2222
+
+    def test_unknown_keys_ignored(self, tmp_path):
+        p = _write(tmp_path / "m.json", [{"name": "a", "ip": "1.1.1.1", "user": "u", "zzz": 1}])
+        assert _load_file(p)[0].name == "a"
+
+
+class TestSourceChain:
+    def test_cwd_beats_user(self, isolated):
+        _write(isolated / "cwd" / "machines.json",
+               [{"name": "a", "ip": "1.1.1.1", "user": "cwd_user"}])
+        _write(isolated / "home" / ".rrun" / "machines.json",
+               [{"name": "a", "ip": "1.1.1.1", "user": "home_user"}])
+        (m,) = load_machines()
+        assert m.user == "cwd_user"
+
+    def test_env_beats_cwd_and_multi_path(self, isolated, monkeypatch):
+        f1 = _write(isolated / "env1.json", [{"name": "a", "ip": "1.1.1.1", "user": "env_user"}])
+        f2 = _write(isolated / "env2.json", [{"name": "b", "ip": "2.2.2.2", "user": "u2"}])
+        _write(isolated / "cwd" / "machines.json", [{"name": "a", "ip": "1.1.1.1", "user": "cwd"}])
+        monkeypatch.setenv("RRUN_CONFIG", os.pathsep.join([str(f1), str(f2)]))
+        machines = {m.name: m for m in load_machines()}
+        assert machines["a"].user == "env_user" and "b" in machines
+
+    def test_machines_d_sorted_and_below_user(self, isolated):
+        rrun_home = isolated / "home" / ".rrun"
+        (rrun_home / "machines.d").mkdir(parents=True)
+        _write(rrun_home / "machines.json", [{"name": "a", "ip": "1.1.1.1", "user": "user_main"}])
+        _write(rrun_home / "machines.d" / "10-x.json",
+               [{"name": "a", "ip": "1.1.1.1", "user": "from_d"}, {"name": "b", "ip": "2.2.2.2", "user": "u"}])
+        machines = {m.name: m for m in load_machines()}
+        assert machines["a"].user == "user_main" and machines["b"].user == "u"
+
+    def test_broken_source_skipped(self, isolated):
+        (isolated / "cwd" / "machines.json").write_text("{not json", encoding="utf-8")
+        _write(isolated / "home" / ".rrun" / "machines.json",
+               [{"name": "a", "ip": "1.1.1.1", "user": "u"}])
+        assert [m.name for m in load_machines()] == ["a"]
+        errors = [i for i in registry.scan_sources() if i.error]
+        assert len(errors) == 1
+
+    def test_explicit_path_single_file_mode(self, isolated, tmp_path):
+        _write(isolated / "cwd" / "machines.json", [{"name": "cwd", "ip": "1.1.1.1", "user": "u"}])
+        p = _write(tmp_path / "pinned.json", [{"name": "pinned", "ip": "2.2.2.2", "user": "u"}])
+        assert [m.name for m in load_machines(p)] == ["pinned"]
+
+
+class TestResolve:
+    def test_by_name_ip_hostname(self, tmp_path):
+        p = _write(tmp_path / "m.json",
+                   [{"name": "a", "ip": "1.1.1.1", "user": "u", "hostname": "host-a"}])
+        for key in ("a", "1.1.1.1", "host-a"):
+            assert resolve_machine(key, p).name == "a"
+
+    def test_not_found_lists_available(self, tmp_path):
+        p = _write(tmp_path / "m.json", [{"name": "a", "ip": "1.1.1.1", "user": "u"}])
+        with pytest.raises(KeyError, match="a\\(1.1.1.1\\)"):
+            resolve_machine("nope", p)

rrun_cli-0.2.0/tests/test_setup.py

@@ -0,0 +1,50 @@
+"""setup 纯函数测试：依赖解析、装机脚本生成。"""
+
+import rrun.setup as st
+from rrun.setup import _build_bash_setup, _build_ps_setup, _req_import_name, load_requirements
+
+
+class TestReqImportName:
+    def test_plain(self):
+        assert _req_import_name("requests") == "requests"
+
+    def test_version_specs(self):
+        assert _req_import_name("requests>=2.31") == "requests"
+        assert _req_import_name("urllib3<2") == "urllib3"
+        assert _req_import_name("pip==24.0") == "pip"
+
+    def test_extras(self):
+        assert _req_import_name("requests[socks]>=2") == "requests"
+
+
+class TestLoadRequirements:
+    def test_builtin_default(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(st, "REQUIREMENTS_OVERRIDE", tmp_path / "nope.txt")
+        reqs = load_requirements()
+        assert reqs and all(not r.startswith("#") for r in reqs)
+
+    def test_user_override_wins(self, tmp_path, monkeypatch):
+        p = tmp_path / "reqs.txt"
+        p.write_text("# comment\nfoo>=1\n\nbar\n", encoding="utf-8")
+        monkeypatch.setattr(st, "REQUIREMENTS_OVERRIDE", p)
+        assert load_requirements() == ["foo>=1", "bar"]
+
+
+class TestSetupScripts:
+    def test_bash_setup(self):
+        s = _build_bash_setup("/usr/bin/python3.12", ["requests>=2", "foo"], force=False)
+        assert '"/usr/bin/python3.12" -m venv "$venv"' in s
+        assert "pip install" in s and "requests>=2 foo" in s
+        assert "import requests;import foo" in s
+        assert "[ \"0\" = \"1\" ]" in s  # force off
+
+    def test_bash_setup_force(self):
+        assert "[ \"1\" = \"1\" ]" in _build_bash_setup("p", ["requests"], force=True)
+
+    def test_ps_setup_ascii_and_content(self):
+        s = _build_ps_setup("C:\\py\\python.exe", ["requests"], force=False)
+        assert "$true" not in s and "$false" in s
+        assert "pip.ini" in s and "requests" in s and "import requests" in s
+
+    def test_ps_setup_force(self):
+        assert "if($true" in _build_ps_setup("C:\\py\\python.exe", ["requests"], force=True)