rrun-cli 0.2.2__tar.gz → 0.2.4__tar.gz

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrun-cli
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -64,19 +64,13 @@ brew install hudochenkov/sshpass/sshpass        # macOS (sshpass is not in homeb
 
 ## Quickstart
 
-Create `~/.rrun/machines.json` (full format in [Configuration](#configuration-machinesjson)):
-
-```json
-{
-  "machines": [
-    { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows", "user": "admin", "password": "secret" }
-  ]
-}
-```
-
-Then:
+Scaffold the machine inventory, fill in your machines, verify:
 
 ```bash
+rrun config init                         # create ~/.rrun/machines.json from the bundled template (mode 600)
+rrun config edit                         # open it in $EDITOR — replace the my-* example entries
+# or: rrun config add                    # interactive wizard that appends one machine
+
 rrun machines                            # verify the inventory is picked up (redacted)
 printf 'Write-Output "hello 中文"\n' > demo.ps1
 rrun exec my-win-box demo.ps1            # powershell, inferred from .ps1
@@ -100,7 +94,7 @@ The full set of hard-won conventions and internals: [docs/remote-exec-convention
 |---|---|
 | `rrun exec <host> <script\|-c ...>` | Execute a local script / inline content remotely |
 | `rrun machines [--json]` | List merged machines (redacted, with source) |
-| `rrun config` | Diagnose the machines.json source chain |
+| `rrun config [init\|add\|edit]` | Manage the user inventory (`init` scaffolds from the bundled template, `add` appends via wizard/flags, `edit` opens `$EDITOR`); bare `config` diagnoses the 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) |
@@ -118,7 +112,7 @@ Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`/`--env K=V` (n
 
 ## Configuration: machines.json
 
-Credentials live in local `machines.json` files — see [machines.template.json](machines.template.json):
+Credentials live in local `machines.json` files. `rrun config init` writes the bundled template to `~/.rrun/machines.json` (also browsable at [src/rrun/machines.template.json](src/rrun/machines.template.json)):
 
 ```json
 {
@@ -140,7 +134,7 @@ Sources are merged by machine name, highest priority first (all optional, failur
 2. `$REMOTE_MACHINE_CONFIG` (legacy name, still honored)
 3. `./machines.json` (current working directory)
 4. `~/.rrun/machines.json`
-5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink)
+5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink; `rrun config init` creates this directory with a README inside)
 6. Legacy: `~/.remote-machine/machines.json` (POSIX) / `C:\tools\remote-machine\machines.json` (Windows)
 
 Per-file `defaults` sections (keyed by `os`, lowercased) are applied before merging. Inspect the chain with `rrun config`; list machines (redacted) with `rrun machines`.
@@ -157,7 +151,7 @@ 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 — or leave `password` empty and use key-based auth instead.
+- `machines.json` stores **plaintext passwords**. Keep it local and never commit it — `rrun config init`/`add` already write the user inventory with mode `600` — 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.
 

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/README.md

@@ -36,19 +36,13 @@ brew install hudochenkov/sshpass/sshpass        # macOS (sshpass is not in homeb
 
 ## Quickstart
 
-Create `~/.rrun/machines.json` (full format in [Configuration](#configuration-machinesjson)):
-
-```json
-{
-  "machines": [
-    { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows", "user": "admin", "password": "secret" }
-  ]
-}
-```
-
-Then:
+Scaffold the machine inventory, fill in your machines, verify:
 
 ```bash
+rrun config init                         # create ~/.rrun/machines.json from the bundled template (mode 600)
+rrun config edit                         # open it in $EDITOR — replace the my-* example entries
+# or: rrun config add                    # interactive wizard that appends one machine
+
 rrun machines                            # verify the inventory is picked up (redacted)
 printf 'Write-Output "hello 中文"\n' > demo.ps1
 rrun exec my-win-box demo.ps1            # powershell, inferred from .ps1
@@ -72,7 +66,7 @@ The full set of hard-won conventions and internals: [docs/remote-exec-convention
 |---|---|
 | `rrun exec <host> <script\|-c ...>` | Execute a local script / inline content remotely |
 | `rrun machines [--json]` | List merged machines (redacted, with source) |
-| `rrun config` | Diagnose the machines.json source chain |
+| `rrun config [init\|add\|edit]` | Manage the user inventory (`init` scaffolds from the bundled template, `add` appends via wizard/flags, `edit` opens `$EDITOR`); bare `config` diagnoses the 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) |
@@ -90,7 +84,7 @@ Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`/`--env K=V` (n
 
 ## Configuration: machines.json
 
-Credentials live in local `machines.json` files — see [machines.template.json](machines.template.json):
+Credentials live in local `machines.json` files. `rrun config init` writes the bundled template to `~/.rrun/machines.json` (also browsable at [src/rrun/machines.template.json](src/rrun/machines.template.json)):
 
 ```json
 {
@@ -112,7 +106,7 @@ Sources are merged by machine name, highest priority first (all optional, failur
 2. `$REMOTE_MACHINE_CONFIG` (legacy name, still honored)
 3. `./machines.json` (current working directory)
 4. `~/.rrun/machines.json`
-5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink)
+5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink; `rrun config init` creates this directory with a README inside)
 6. Legacy: `~/.remote-machine/machines.json` (POSIX) / `C:\tools\remote-machine\machines.json` (Windows)
 
 Per-file `defaults` sections (keyed by `os`, lowercased) are applied before merging. Inspect the chain with `rrun config`; list machines (redacted) with `rrun machines`.
@@ -129,7 +123,7 @@ 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 — or leave `password` empty and use key-based auth instead.
+- `machines.json` stores **plaintext passwords**. Keep it local and never commit it — `rrun config init`/`add` already write the user inventory with mode `600` — 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.
 

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rrun-cli"
-version = "0.2.2"
+version = "0.2.4"
 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"
@@ -45,7 +45,7 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-rrun = ["remote-requirements.txt"]
+rrun = ["remote-requirements.txt", "machines.template.json", "machines.d.README.md"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/src/rrun/__init__.py

@@ -11,7 +11,7 @@ try:
 
     __version__ = _pkg_version("rrun-cli")
 except Exception:  # noqa: BLE001 - 未安装（源码直跑）时回退
-    __version__ = "0.2.2"
+    __version__ = "0.2.4"
 
 from .doctor import DoctorResult, check_machine
 from .executor import (

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/src/rrun/__main__.py

@@ -14,6 +14,7 @@ Usage:
     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 config init|add|edit           # scaffold / append / edit ~/.rrun/machines.json
     rrun close [<host>|--all]           # close ssh multiplexed connections
 
 Conventions:
@@ -42,9 +43,10 @@ import time
 from pathlib import Path
 
 from . import __version__
+from .config_cmd import cmd_config_add, cmd_config_chain, cmd_config_edit, cmd_config_init
 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 .registry import EMPTY_INVENTORY_HINT, load_machines, resolve_machine
 from .setup import setup_machine, venv_python_or_die
 
 INLINE_DROP_DIR = RRUN_HOME / "drops"
@@ -138,29 +140,12 @@ def cmd_machines(ns) -> int:
     machines = load_machines()
     if ns.json:
         print(json.dumps([m.public_dict() for m in machines], ensure_ascii=False, indent=2))
-        return 0
-    for m in machines:
-        desc = f"  # {m.description}" if m.description else ""
-        print(f"{m.name:<24} {m.ip:<16} {m.os:<8} {m.user:<12} {m.default_lang:<11} {_short_source(m.source)}{desc}")
-    return 0
-
-
-def cmd_config(ns) -> int:
-    infos = scan_sources()
-    print("machines.json source chain (high -> low priority; same-name machines are")
-    print("overridden by higher-priority sources):")
-    raw_total = 0
-    for i, info in enumerate(infos, 1):
-        if not info.exists:
-            state = "- missing"
-        elif info.error:
-            state = f"x read failed: {info.error}"
-        else:
-            state = f"ok, {info.machine_count} machines"
-            raw_total += info.machine_count
-        print(f"  [{i}] {info.label:<22} {info.path}  {state}")
-    merged = load_machines()
-    print(f"{len(merged)} machines total ({raw_total} across all sources before same-name overrides)")
+    else:
+        for m in machines:
+            desc = f"  # {m.description}" if m.description else ""
+            print(f"{m.name:<24} {m.ip:<16} {m.os:<8} {m.user:<12} {m.default_lang:<11} {_short_source(m.source)}{desc}")
+    if not machines:
+        print(f"[machines] {EMPTY_INVENTORY_HINT}", file=sys.stderr)
     return 0
 
 
@@ -303,8 +288,34 @@ def main() -> None:
     mp.add_argument("--json", action="store_true")
     mp.set_defaults(func=cmd_machines)
 
-    cf = sub.add_parser("config", help="show the machines.json source chain (which files apply, how many machines each)")
-    cf.set_defaults(func=cmd_config)
+    cf = sub.add_parser("config", help="manage the machine inventory (init/add/edit); "
+                                       "bare 'config' diagnoses the machines.json source chain")
+    cf.set_defaults(func=cmd_config_chain)
+    cfsub = cf.add_subparsers(dest="config_cmd")
+
+    ci = cfsub.add_parser("init", help="create ~/.rrun/machines.json from the bundled template (mode 600)")
+    ci.add_argument("--force", action="store_true", help="overwrite an existing inventory file")
+    ci.set_defaults(func=cmd_config_init)
+
+    ca = cfsub.add_parser("add", help="append a machine to ~/.rrun/machines.json "
+                                      "(interactive wizard when neither --name nor --ip is given)")
+    ca.add_argument("--name", help="unique machine name (no spaces)")
+    ca.add_argument("--ip", help="ip address of the machine")
+    ca.add_argument("--hostname", help="optional hostname (also resolvable)")
+    ca.add_argument("--os", choices=["Windows", "Mac", "Linux"], help="remote OS (default: Windows)")
+    ca.add_argument("--user", help="ssh login user")
+    ca.add_argument("--password", help="plaintext password (visible in shell history — prefer the wizard); "
+                                       "omit for key-based auth")
+    ca.add_argument("--identity-file", dest="identity_file", help="ssh private key path (key auth only)")
+    ca.add_argument("--port", type=int, help="ssh port (default: 22)")
+    ca.add_argument("--python", dest="python", help="explicit remote python path (skips auto-detection)")
+    ca.add_argument("--description", help="free-form description")
+    ca.add_argument("-i", "--interactive", action="store_true", help="force the interactive wizard")
+    ca.set_defaults(func=cmd_config_add)
+
+    ce = cfsub.add_parser("edit", help="open ~/.rrun/machines.json in $EDITOR "
+                                       "(creates it from the template first if missing)")
+    ce.set_defaults(func=cmd_config_edit)
 
     sp = sub.add_parser("setup", help="provision the unified remote python environment (3.12 venv)")
     sp.add_argument("host", nargs="?", help="machine name/ip; use --all for every machine")

rrun_cli-0.2.4/src/rrun/config_cmd.py

@@ -0,0 +1,283 @@
+"""`rrun config` 子命令组：机器清单的初始化 / 追加 / 编辑 + 来源链诊断。
+
+设计要点：
+- init/add/edit 只操作「用户级主清单」，路径取 registry.user_inventory_path()（单一
+  真相源）；不得在来源链上按 label 反查——cwd/env 来源与之同路径时去重会丢弃
+  user 条目。其他来源（env/cwd/machines.d/legacy）只读不动。
+- init 顺带创建 machines.d/ 并内置 README.md（.d 模式的可发现性传统：目录自带说明）。
+- 模板与 README 内嵌为 package data，离线可用、随发行版本锁定；写盘即收紧权限
+  （目录 700 / 文件 600，明文密码场景，Windows chmod 语义有限跳过）。
+- add 双模式：不给 --name/--ip → 交互向导（getpass 隐藏密码，旗帜值作预填默认）；
+  给了 → 纯旗帜模式（可脚本化）；-i 强制向导。
+- edit 走 $VISUAL/$EDITOR（Windows 回退 notepad，POSIX 回退 vi），退出后校验 JSON；
+  文件缺失时先按模板创建（crontab -e 风格）。
+- 无子命令时（bare `rrun config`）保持 v0.2.x 行为：诊断来源链；空清单附 init 引导。
+"""
+
+import getpass
+import json
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from .registry import (
+    EMPTY_INVENTORY_HINT,
+    _load_file,
+    load_machines,
+    resolve_machine,
+    scan_sources,
+    user_inventory_path,
+)
+
+TEMPLATE_FILE = Path(__file__).resolve().with_name("machines.template.json")
+MACHINES_D_README = Path(__file__).resolve().with_name("machines.d.README.md")
+
+_OS_ALIASES = {
+    "w": "Windows", "windows": "Windows",
+    "m": "Mac", "mac": "Mac", "macos": "Mac", "osx": "Mac", "darwin": "Mac",
+    "l": "Linux", "linux": "Linux",
+}
+
+
+def _shorten(path: Path) -> str:
+    """显示用：home 前缀折叠为 ~。"""
+    s = str(path)
+    home = str(Path.home())
+    return "~" + s[len(home):] if s.startswith(home) else s
+
+
+def _write_secure(path: Path, text: str) -> None:
+    """写清单并收紧权限（目录 700 / 文件 600；Windows 上跳过 chmod）。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    if os.name != "nt":
+        os.chmod(path.parent, 0o700)
+        os.chmod(path, 0o600)
+
+
+def _build_entry(name: str, ip: str, os_name: str, user: str, *,
+                 password: str = "", hostname: str = "", identity_file: str = "",
+                 port: int = 22, python: str = "", description: str = "") -> dict:
+    """组装机器条目并校验必填（空可选字段不落盘，保持清单干净）。"""
+    if not name or any(c.isspace() for c in name):
+        raise SystemExit("[config] machine name must be non-empty and contain no whitespace (--name)")
+    if not ip:
+        raise SystemExit("[config] ip is required (--ip, or run with no flags for the interactive wizard)")
+    if not user:
+        raise SystemExit("[config] ssh user is required (--user, or run with no flags for the interactive wizard)")
+    if not 1 <= port <= 65535:
+        raise SystemExit(f"[config] port must be 1-65535, got {port}")
+    entry = {"name": name, "ip": ip, "os": os_name, "user": user}
+    if password:
+        entry["password"] = password
+    if identity_file:
+        entry["identity_file"] = identity_file
+    if port != 22:
+        entry["port"] = port
+    if hostname:
+        entry["hostname"] = hostname
+    if python:
+        entry["python"] = python
+    if description:
+        entry["description"] = description
+    return entry
+
+
+def _append_machine(path: Path, entry: dict) -> None:
+    """追加机器到清单文件；文件已存在但损坏时拒绝写入（绝不覆盖用户数据）。"""
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as e:
+            raise SystemExit(f"[config] {path} is not valid JSON ({e}); fix it first with 'rrun config edit'") from None
+        if not isinstance(data, dict):
+            raise SystemExit(f"[config] {path} must contain a JSON object; fix it first with 'rrun config edit'")
+    else:
+        data = {}
+    machines = data.setdefault("machines", [])
+    if not isinstance(machines, list):
+        raise SystemExit(f"[config] {path} has a non-list 'machines' field; fix it first with 'rrun config edit'")
+    if any(isinstance(m, dict) and m.get("name") == entry["name"] for m in machines):
+        raise SystemExit(f"[config] machine [{entry['name']}] already exists in {_shorten(path)}"
+                         " — edit it with 'rrun config edit'")
+    machines.append(entry)
+    _write_secure(path, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+
+
+def _report_added(path: Path, name: str) -> None:
+    """成功提示 + 高优先级来源遮蔽预警。"""
+    print(f"[config] added [{name}] to {_shorten(path)}")
+    try:
+        m = resolve_machine(name)
+    except KeyError:
+        return
+    if m.source != str(path):
+        print(f"[config] warning: higher-priority source {m.source} also defines [{name}]"
+              " and shadows this entry", file=sys.stderr)
+    print(f"[config] next: rrun doctor {name}   # connectivity + python check")
+
+
+def _ensure_machines_d() -> Path:
+    """创建 machines.d/ 并内置 README（幂等；README 已存在不覆盖——用户可能改过）。"""
+    d = user_inventory_path().parent / "machines.d"
+    d.mkdir(parents=True, exist_ok=True)
+    if os.name != "nt":
+        os.chmod(d, 0o700)
+    readme = d / "README.md"
+    if not readme.exists():
+        _write_secure(readme, MACHINES_D_README.read_text(encoding="utf-8"))
+    return d
+
+
+def cmd_config_init(ns) -> int:
+    """按内嵌模板创建用户级主清单 + machines.d/；已存在时拒绝覆盖（--force 除外）。"""
+    path = user_inventory_path()
+    if path.exists() and not ns.force:
+        print(f"[config] {_shorten(path)} already exists (use --force to overwrite)", file=sys.stderr)
+        return 1
+    _write_secure(path, TEMPLATE_FILE.read_text(encoding="utf-8"))
+    d = _ensure_machines_d()
+    perms = "" if os.name == "nt" else ", mode 600"
+    print(f"[config] created {_shorten(path)} from the bundled template{perms}")
+    print(f"[config] machines.d ready at {_shorten(d)}/ — drop extra *.json inventories there"
+          " (see its README.md)")
+    print("[config] next: replace the my-* example entries with your machines"
+          " — 'rrun config edit' or 'rrun config add'")
+    print("[config] then: rrun machines   # verify the inventory is picked up (redacted)")
+    return 0
+
+
+def _ask(label: str, default: str = "", secret: bool = False) -> str:
+    suffix = f" [{default}]" if default else ""
+    prompt = f"  {label}{suffix}: "
+    value = getpass.getpass(prompt) if secret else input(prompt)
+    return value.strip() or default
+
+
+def _ask_required(label: str, default: str = "") -> str:
+    while True:
+        value = _ask(label, default)
+        if value:
+            return value
+        print("    (required)")
+
+
+def _ask_name(default: str = "") -> str:
+    while True:
+        value = _ask_required("name (unique, no spaces)", default)
+        if not any(c.isspace() for c in value):
+            return value
+        print("    name must not contain whitespace")
+
+
+def _ask_os(default: str = "Windows") -> str:
+    while True:
+        value = _ask("os (Windows/Mac/Linux)", default).lower()
+        if value in _OS_ALIASES:
+            return _OS_ALIASES[value]
+        print("    please answer Windows, Mac or Linux (w/m/l)")
+
+
+def _ask_port(default: int = 22) -> int:
+    while True:
+        try:
+            port = int(_ask("ssh port", str(default)))
+        except ValueError:
+            print("    port must be a number")
+            continue
+        if 1 <= port <= 65535:
+            return port
+        print("    port must be 1-65535")
+
+
+def _wizard(ns, path: Path) -> "dict | None":
+    """交互问答收集机器信息（旗帜值作预填默认）；用户放弃时返回 None。"""
+    if not sys.stdin.isatty():
+        raise SystemExit("[config] interactive add needs a TTY; use flags instead: "
+                         "rrun config add --name N --ip A --user U [--os Windows] [--password ...]")
+    print(f"Add a machine to {_shorten(path)} (Ctrl-C to abort):")
+    name = _ask_name(ns.name or "")
+    ip = _ask_required("ip", ns.ip or "")
+    hostname = _ask("hostname (optional, also resolvable)", ns.hostname or "")
+    os_name = _ask_os(ns.os or "Windows")
+    user = _ask_required("ssh user", ns.user or "")
+    password = _ask("password (empty = key auth)", ns.password or "", secret=True)
+    identity_file = ""
+    if not password:
+        identity_file = _ask("identity_file (optional; empty = default key chain)", ns.identity_file or "")
+    port = ns.port if ns.port is not None else _ask_port()
+    python = _ask("remote python path (optional, skips auto-detection)", ns.python or "")
+    description = _ask("description (optional)", ns.description or "")
+    entry = _build_entry(name, ip, os_name, user,
+                         password=password, hostname=hostname, identity_file=identity_file,
+                         port=port, python=python, description=description)
+    auth = "password" if password else "key"
+    print(f"\n  {name}: {user}@{ip}:{port} os={os_name} auth={auth}")
+    if _ask(f"append to {_shorten(path)}?", "Y").lower() not in ("y", "yes"):
+        print("[config] aborted, nothing written")
+        return None
+    return entry
+
+
+def cmd_config_add(ns) -> int:
+    """追加一台机器：无 --name/--ip 时走交互向导，否则纯旗帜模式。"""
+    path = user_inventory_path()
+    if ns.interactive or (not ns.name and not ns.ip):
+        entry = _wizard(ns, path)
+        if entry is None:
+            return 1
+    else:
+        entry = _build_entry(
+            ns.name or "", ns.ip or "", ns.os or "Windows", ns.user or "",
+            password=ns.password or "", hostname=ns.hostname or "",
+            identity_file=ns.identity_file or "", port=ns.port if ns.port is not None else 22,
+            python=ns.python or "", description=ns.description or "",
+        )
+    _append_machine(path, entry)
+    _report_added(path, entry["name"])
+    return 0
+
+
+def cmd_config_edit(ns) -> int:
+    """用 $VISUAL/$EDITOR 打开用户级主清单（缺失时先按模板创建），退出后校验 JSON。"""
+    path = user_inventory_path()
+    if not path.exists():
+        _write_secure(path, TEMPLATE_FILE.read_text(encoding="utf-8"))
+        print(f"[config] created {_shorten(path)} from the bundled template")
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR") or ("notepad" if os.name == "nt" else "vi")
+    rc = subprocess.call(shlex.split(editor) + [str(path)])
+    if rc:
+        raise SystemExit(f"[config] editor exited with code {rc}")
+    try:
+        machines = _load_file(path)
+    except Exception as e:  # noqa: BLE001 - 校验场景需要把原始解析错误带给用户
+        print(f"[config] warning: {_shorten(path)} does not parse: {e}", file=sys.stderr)
+        return 1
+    print(f"[config] {_shorten(path)} ok — {len(machines)} machines")
+    return 0
+
+
+def cmd_config_chain(ns) -> int:
+    """无子命令时的默认行为：诊断来源链（即 v0.2.x 的 bare `rrun config`）。"""
+    infos = scan_sources()
+    print("machines.json source chain (high -> low priority; same-name machines are")
+    print("overridden by higher-priority sources):")
+    raw_total = 0
+    for i, info in enumerate(infos, 1):
+        if info.path.is_dir():
+            state = "dir exists, no *.json files"
+        elif not info.exists:
+            state = "- missing"
+        elif info.error:
+            state = f"x read failed: {info.error}"
+        else:
+            state = f"ok, {info.machine_count} machines"
+            raw_total += info.machine_count
+        print(f"  [{i}] {info.label:<22} {info.path}  {state}")
+    merged = load_machines()
+    print(f"{len(merged)} machines total ({raw_total} across all sources before same-name overrides)")
+    if not merged:
+        print(f"hint: {EMPTY_INVENTORY_HINT}")
+    return 0

rrun_cli-0.2.4/src/rrun/machines.d.README.md

@@ -0,0 +1,16 @@
+# machines.d — additional machine inventories
+
+Drop extra inventories here as `*.json` files (same format as
+`~/.rrun/machines.json`). They are merged with the main inventory
+by machine name:
+
+- `~/.rrun/machines.json` wins on name conflicts (higher priority).
+- Among `machines.d` files, filename order decides
+  (`10-*.json` beats `90-*.json`).
+
+Symlinks are welcome — one inventory per file, e.g.:
+
+    ln -s ~/src/bot_home/config/machines.json ~/.rrun/machines.d/bot_home.json
+
+Only `*.json` files are read; this README is ignored.
+Full format: https://github.com/waqiju/rrun#configuration-machinesjson

rrun_cli-0.2.4/src/rrun/machines.template.json

@@ -0,0 +1,43 @@
+{
+  "defaults": {
+    "windows": { "os": "Windows" },
+    "mac": { "os": "Mac" },
+    "linux": { "os": "Linux" }
+  },
+  "_hint": "more inventories: drop *.json into ~/.rrun/machines.d/ (see its README.md); docs: https://github.com/waqiju/rrun",
+  "machines": [
+    {
+      "name": "my-win-box",
+      "ip": "192.168.1.10",
+      "os": "Windows",
+      "user": "admin",
+      "password": "secret",
+      "description": "Windows build box"
+    },
+    {
+      "name": "my-mac-mini",
+      "hostname": "mac-mini.local",
+      "ip": "192.168.1.20",
+      "os": "Mac",
+      "user": "admin",
+      "password": "secret"
+    },
+    {
+      "name": "my-linux",
+      "ip": "192.168.1.30",
+      "os": "Linux",
+      "user": "ubuntu",
+      "password": "secret",
+      "python": "/usr/bin/python3.12"
+    },
+    {
+      "name": "cloud-vm-key-auth",
+      "ip": "1.2.3.4",
+      "port": 2222,
+      "os": "Linux",
+      "user": "root",
+      "identity_file": "~/.ssh/id_ed25519",
+      "description": "password omitted -> key auth (BatchMode); port overrides 22"
+    }
+  ]
+}

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/src/rrun/registry.py

@@ -23,6 +23,10 @@ from pathlib import Path
 ENV_MACHINES_JSON = "RRUN_CONFIG"
 ENV_MACHINES_JSON_LEGACY = "REMOTE_MACHINE_CONFIG"
 
+# 空清单引导：首次安装（无任何来源）时指给用户的下一步。CLI 多处复用。
+EMPTY_INVENTORY_HINT = ("no machines configured yet — run 'rrun config init' "
+                        "to create ~/.rrun/machines.json from a bundled template")
+
 _KNOWN_KEYS = {"name", "ip", "user", "password", "os", "hostname", "description", "python", "port", "identity_file"}
 
 
@@ -72,6 +76,15 @@ class SourceInfo:
     error: str = ""
 
 
+def user_inventory_path() -> Path:
+    """用户级主清单路径（单一真相源：candidate_sources 的 user 条目、config init/add/edit 共用）。
+
+    注意：不要从 candidate_sources() 的结果里按 label 反查这个路径——当 cwd 恰好是
+    ~/.rrun 或 $RRUN_CONFIG 指向同一文件时，去重会丢弃 user 条目（v0.2.3 的教训）。
+    """
+    return Path.home() / ".rrun" / "machines.json"
+
+
 def candidate_sources() -> "list[tuple[str, Path]]":
     """返回 (标签, 路径) 有序来源链（高→低优先级），按 resolved path 去重。"""
     cands: list[tuple[str, Path]] = []
@@ -82,12 +95,14 @@ def candidate_sources() -> "list[tuple[str, Path]]":
             label = f"${env_name}" if i == 0 else f"${env_name}[{i}]"
             cands.append((label, Path(p).expanduser()))
     cands.append(("cwd", Path.cwd() / "machines.json"))
-    rrun_home = Path.home() / ".rrun"
-    cands.append(("user", rrun_home / "machines.json"))
-    machines_d = rrun_home / "machines.d"
+    cands.append(("user", user_inventory_path()))
+    machines_d = user_inventory_path().parent / "machines.d"
     if machines_d.is_dir():
-        for p in sorted(machines_d.glob("*.json")):
-            cands.append(("user.d", p))
+        files = sorted(machines_d.glob("*.json"))
+        if files:
+            cands.extend(("user.d", p) for p in files)
+        else:
+            cands.append(("user.d", machines_d))  # 空目录也入链：让诊断能看到它存在（merge 时 is_file 跳过）
     if os.name == "nt":
         cands.append(("legacy", Path(r"C:\tools\remote-machine\machines.json")))
     else:
@@ -146,7 +161,9 @@ def scan_sources() -> "list[SourceInfo]":
     infos = []
     for label, p in candidate_sources():
         info = SourceInfo(label=label, path=p)
-        if p.is_file():
+        if p.is_dir():
+            info.exists = True  # 目录型来源（空 machines.d）：无可读机器，仅示意存在
+        elif p.is_file():
             info.exists = True
             try:
                 info.machine_count = len(_load_file(p))
@@ -164,4 +181,7 @@ def resolve_machine(host: str, path: "str | os.PathLike | None" = None) -> Machi
             return m
     available = ", ".join(f"{m.name}({m.ip})" for m in machines) or "<none>"
     sources = ", ".join(str(p) for _lbl, p in candidate_sources() if p.is_file()) or "<no sources available>"
-    raise KeyError(f"machine [{host}] not found. Scanned sources: {sources}. Available: {available}")
+    msg = f"machine [{host}] not found. Scanned sources: {sources}. Available: {available}"
+    if not machines:
+        msg += f" Hint: {EMPTY_INVENTORY_HINT}"
+    raise KeyError(msg)

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/src/rrun_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrun-cli
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -64,19 +64,13 @@ brew install hudochenkov/sshpass/sshpass        # macOS (sshpass is not in homeb
 
 ## Quickstart
 
-Create `~/.rrun/machines.json` (full format in [Configuration](#configuration-machinesjson)):
-
-```json
-{
-  "machines": [
-    { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows", "user": "admin", "password": "secret" }
-  ]
-}
-```
-
-Then:
+Scaffold the machine inventory, fill in your machines, verify:
 
 ```bash
+rrun config init                         # create ~/.rrun/machines.json from the bundled template (mode 600)
+rrun config edit                         # open it in $EDITOR — replace the my-* example entries
+# or: rrun config add                    # interactive wizard that appends one machine
+
 rrun machines                            # verify the inventory is picked up (redacted)
 printf 'Write-Output "hello 中文"\n' > demo.ps1
 rrun exec my-win-box demo.ps1            # powershell, inferred from .ps1
@@ -100,7 +94,7 @@ The full set of hard-won conventions and internals: [docs/remote-exec-convention
 |---|---|
 | `rrun exec <host> <script\|-c ...>` | Execute a local script / inline content remotely |
 | `rrun machines [--json]` | List merged machines (redacted, with source) |
-| `rrun config` | Diagnose the machines.json source chain |
+| `rrun config [init\|add\|edit]` | Manage the user inventory (`init` scaffolds from the bundled template, `add` appends via wizard/flags, `edit` opens `$EDITOR`); bare `config` diagnoses the 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) |
@@ -118,7 +112,7 @@ Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`/`--env K=V` (n
 
 ## Configuration: machines.json
 
-Credentials live in local `machines.json` files — see [machines.template.json](machines.template.json):
+Credentials live in local `machines.json` files. `rrun config init` writes the bundled template to `~/.rrun/machines.json` (also browsable at [src/rrun/machines.template.json](src/rrun/machines.template.json)):
 
 ```json
 {
@@ -140,7 +134,7 @@ Sources are merged by machine name, highest priority first (all optional, failur
 2. `$REMOTE_MACHINE_CONFIG` (legacy name, still honored)
 3. `./machines.json` (current working directory)
 4. `~/.rrun/machines.json`
-5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink)
+5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink; `rrun config init` creates this directory with a README inside)
 6. Legacy: `~/.remote-machine/machines.json` (POSIX) / `C:\tools\remote-machine\machines.json` (Windows)
 
 Per-file `defaults` sections (keyed by `os`, lowercased) are applied before merging. Inspect the chain with `rrun config`; list machines (redacted) with `rrun machines`.
@@ -157,7 +151,7 @@ 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 — or leave `password` empty and use key-based auth instead.
+- `machines.json` stores **plaintext passwords**. Keep it local and never commit it — `rrun config init`/`add` already write the user inventory with mode `600` — 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.
 

{rrun_cli-0.2.2 → rrun_cli-0.2.4}/src/rrun_cli.egg-info/SOURCES.txt

@@ -3,8 +3,11 @@ README.md
 pyproject.toml
 src/rrun/__init__.py
 src/rrun/__main__.py
+src/rrun/config_cmd.py
 src/rrun/doctor.py
 src/rrun/executor.py
+src/rrun/machines.d.README.md
+src/rrun/machines.template.json
 src/rrun/registry.py
 src/rrun/remote-requirements.txt
 src/rrun/setup.py
@@ -15,6 +18,7 @@ src/rrun_cli.egg-info/entry_points.txt
 src/rrun_cli.egg-info/requires.txt
 src/rrun_cli.egg-info/top_level.txt
 tests/test_cli.py
+tests/test_config_cmd.py
 tests/test_executor.py
 tests/test_registry.py
 tests/test_setup.py

rrun_cli-0.2.4/tests/test_config_cmd.py

@@ -0,0 +1,316 @@
+"""config 子命令测试：init 模板落盘/权限、add 旗帜与向导模式、edit、空态引导。"""
+
+import argparse
+import getpass
+import json
+import os
+import stat
+from types import SimpleNamespace
+
+import pytest
+
+from rrun import config_cmd
+from rrun.config_cmd import (
+    cmd_config_add,
+    cmd_config_chain,
+    cmd_config_edit,
+    cmd_config_init,
+    user_inventory_path,
+)
+from rrun.registry import load_machines, resolve_machine
+
+
+@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.mkdir()
+    monkeypatch.setenv("HOME", str(home))  # POSIX 下 Path.home() 读 HOME
+    cwd = tmp_path / "cwd"
+    cwd.mkdir()
+    monkeypatch.chdir(cwd)
+    return tmp_path
+
+
+def _ns(**kw):
+    return argparse.Namespace(**kw)
+
+
+def _flag_ns(**kw):
+    base = dict(name=None, ip=None, hostname=None, os=None, user=None, password=None,
+                identity_file=None, port=None, python=None, description=None, interactive=False)
+    base.update(kw)
+    return _ns(**base)
+
+
+def _read_inventory():
+    return json.loads(user_inventory_path().read_text(encoding="utf-8"))
+
+
+class TestInit:
+    def test_creates_template_with_secure_perms(self, isolated, capsys):
+        assert cmd_config_init(_ns(force=False)) == 0
+        path = user_inventory_path()
+        assert path == isolated / "home" / ".rrun" / "machines.json"
+        data = _read_inventory()
+        assert any(m["name"] == "my-win-box" for m in data["machines"])
+        if os.name != "nt":
+            assert stat.S_IMODE(path.stat().st_mode) == 0o600
+            assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700
+        assert "config edit" in capsys.readouterr().out
+
+    def test_refuses_overwrite_without_force(self, isolated, capsys):
+        cmd_config_init(_ns(force=False))
+        assert cmd_config_init(_ns(force=False)) == 1
+        assert "--force" in capsys.readouterr().err
+
+    def test_force_overwrites(self, isolated):
+        cmd_config_init(_ns(force=False))
+        user_inventory_path().write_text('{"machines": []}', encoding="utf-8")
+        assert cmd_config_init(_ns(force=True)) == 0
+        assert _read_inventory()["machines"]  # 模板非空
+
+    def test_template_machines_visible_to_loader(self, isolated):
+        cmd_config_init(_ns(force=False))
+        assert "my-win-box" in [m.name for m in load_machines()]
+
+
+class TestAddFlags:
+    def test_append_creates_skeleton_file(self, isolated):
+        assert cmd_config_add(_flag_ns(name="box", ip="1.2.3.4", user="admin", password="pw")) == 0
+        (m,) = _read_inventory()["machines"]
+        assert m == {"name": "box", "ip": "1.2.3.4", "os": "Windows", "user": "admin", "password": "pw"}
+        if os.name != "nt":
+            assert stat.S_IMODE(user_inventory_path().stat().st_mode) == 0o600
+
+    def test_requires_name_ip_user(self, isolated):
+        with pytest.raises(SystemExit, match="--user"):
+            cmd_config_add(_flag_ns(name="box", ip="1.2.3.4"))
+        with pytest.raises(SystemExit, match="--ip"):
+            cmd_config_add(_flag_ns(name="box", user="u"))
+
+    def test_whitespace_name_rejected(self, isolated):
+        with pytest.raises(SystemExit, match="whitespace"):
+            cmd_config_add(_flag_ns(name="my box", ip="1.2.3.4", user="u"))
+
+    def test_bad_port_rejected(self, isolated):
+        with pytest.raises(SystemExit, match="1-65535"):
+            cmd_config_add(_flag_ns(name="x", ip="1.1.1.1", user="u", port=70000))
+
+    def test_duplicate_name_rejected(self, isolated):
+        cmd_config_add(_flag_ns(name="box", ip="1.2.3.4", user="u"))
+        with pytest.raises(SystemExit, match="already exists"):
+            cmd_config_add(_flag_ns(name="box", ip="9.9.9.9", user="u"))
+
+    def test_appends_to_template_preserving_entries(self, isolated):
+        cmd_config_init(_ns(force=False))
+        cmd_config_add(_flag_ns(name="real", ip="1.2.3.4", user="root", os="Linux",
+                                port=2222, identity_file="~/.ssh/id_ed25519", description="vm"))
+        data = _read_inventory()
+        names = [m["name"] for m in data["machines"]]
+        assert "my-win-box" in names and "real" in names
+        assert data["defaults"]  # 模板原有段落保留
+        m = next(x for x in data["machines"] if x["name"] == "real")
+        assert m == {"name": "real", "ip": "1.2.3.4", "os": "Linux", "user": "root",
+                     "identity_file": "~/.ssh/id_ed25519", "port": 2222, "description": "vm"}
+        # 注册表视角：key 认证 + 端口生效
+        resolved = resolve_machine("real")
+        assert resolved.port == 2222 and resolved.public_dict()["auth"] == "key"
+
+    def test_port_22_not_written(self, isolated):
+        cmd_config_add(_flag_ns(name="x", ip="1.1.1.1", user="u", port=22))
+        assert "port" not in _read_inventory()["machines"][0]
+
+    def test_broken_target_file_refused(self, isolated):
+        path = user_inventory_path()
+        path.parent.mkdir(parents=True)
+        path.write_text("{broken", encoding="utf-8")
+        with pytest.raises(SystemExit, match="not valid JSON"):
+            cmd_config_add(_flag_ns(name="x", ip="1.1.1.1", user="u"))
+        assert path.read_text(encoding="utf-8") == "{broken"  # 未被覆盖
+
+    def test_shadow_warning_when_cwd_defines_same_name(self, isolated, capsys):
+        (isolated / "cwd" / "machines.json").write_text(
+            json.dumps({"machines": [{"name": "box", "ip": "9.9.9.9", "user": "cwd"}]}), encoding="utf-8")
+        assert cmd_config_add(_flag_ns(name="box", ip="1.2.3.4", user="u")) == 0
+        assert "shadows" in capsys.readouterr().err
+
+
+class TestWizard:
+    def _feed(self, monkeypatch, inputs, password=""):
+        it = iter(inputs)
+        monkeypatch.setattr("builtins.input", lambda prompt="": next(it))
+        monkeypatch.setattr(getpass, "getpass", lambda prompt="": password)
+        monkeypatch.setattr(config_cmd.sys, "stdin", SimpleNamespace(isatty=lambda: True))
+
+    def test_full_flow_password_auth(self, isolated, monkeypatch):
+        self._feed(monkeypatch, [
+            "mybox",      # name
+            "10.0.0.1",   # ip
+            "",           # hostname
+            "l",          # os -> Linux
+            "ubuntu",     # user
+                          # password 走 getpass mock
+            "",           # port -> 22
+            "",           # python
+            "test box",   # description
+            "Y",          # confirm
+        ], password="sekret")
+        assert cmd_config_add(_flag_ns()) == 0
+        m = _read_inventory()["machines"][0]
+        assert m == {"name": "mybox", "ip": "10.0.0.1", "os": "Linux", "user": "ubuntu",
+                     "password": "sekret", "description": "test box"}
+
+    def test_key_auth_prompts_identity_file(self, isolated, monkeypatch):
+        self._feed(monkeypatch, [
+            "vm", "1.2.3.4", "", "w", "admin",
+            "~/.ssh/id_ed25519",  # 密码为空才问这一项
+            "2222", "", "", "y",
+        ], password="")
+        assert cmd_config_add(_flag_ns()) == 0
+        m = _read_inventory()["machines"][0]
+        assert m["identity_file"] == "~/.ssh/id_ed25519" and m["port"] == 2222
+        assert "password" not in m
+
+    def test_flags_prefill_wizard_defaults(self, isolated, monkeypatch):
+        # name/ip/hostname/os/user 由旗帜预填或回车，port 先输非法值触发重问再回车
+        self._feed(monkeypatch, ["", "", "", "", "", "s3cr3t-port", "", "", "", "y"], password="pw")
+        ns = _flag_ns(name="prefilled", ip="2.2.2.2", os="Mac", user="macuser")
+        assert cmd_config_add(ns) == 0
+        m = _read_inventory()["machines"][0]
+        assert m["name"] == "prefilled" and m["os"] == "Mac" and m["user"] == "macuser"
+        # port 交互输入非法值 -> 重问？"s3cr3t-port" 非数字会触发重问，下一个输入 "" -> 22
+        assert "port" not in m
+
+    def test_abort_writes_nothing(self, isolated, monkeypatch):
+        self._feed(monkeypatch, ["x", "1.1.1.1", "", "w", "u", "", "", "", "n"], password="pw")
+        assert cmd_config_add(_flag_ns()) == 1
+        assert not user_inventory_path().exists()
+
+    def test_non_tty_requires_flags(self, isolated, monkeypatch):
+        monkeypatch.setattr(config_cmd.sys, "stdin", SimpleNamespace(isatty=lambda: False))
+        with pytest.raises(SystemExit, match="TTY"):
+            cmd_config_add(_flag_ns())
+
+    def test_os_reprompts_on_garbage(self, isolated, monkeypatch):
+        self._feed(monkeypatch, ["x", "1.1.1.1", "", "solaris", "m", "u", "", "", "", "", "y"], password="")
+        assert cmd_config_add(_flag_ns()) == 0
+        assert _read_inventory()["machines"][0]["os"] == "Mac"
+
+
+class TestEdit:
+    def test_missing_file_bootstraps_template(self, isolated, monkeypatch, capsys):
+        calls = []
+        monkeypatch.setattr(config_cmd.subprocess, "call", lambda cmd: calls.append(cmd) or 0)
+        monkeypatch.delenv("VISUAL", raising=False)
+        monkeypatch.setenv("EDITOR", "my-editor --wait")
+        assert cmd_config_edit(_ns()) == 0
+        path = user_inventory_path()
+        assert path.exists() and calls == [["my-editor", "--wait", str(path)]]
+        assert "created" in capsys.readouterr().out
+
+    def test_invalid_json_after_edit_warns(self, isolated, monkeypatch, capsys):
+        path = user_inventory_path()
+
+        def fake_editor(cmd):
+            path.write_text("{oops", encoding="utf-8")
+            return 0
+
+        monkeypatch.setattr(config_cmd.subprocess, "call", fake_editor)
+        monkeypatch.delenv("VISUAL", raising=False)
+        monkeypatch.setenv("EDITOR", "true")
+        assert cmd_config_edit(_ns()) == 1
+        assert "does not parse" in capsys.readouterr().err
+
+    def test_editor_nonzero_exit(self, isolated, monkeypatch):
+        monkeypatch.setattr(config_cmd.subprocess, "call", lambda cmd: 130)
+        monkeypatch.delenv("VISUAL", raising=False)
+        monkeypatch.setenv("EDITOR", "true")
+        with pytest.raises(SystemExit, match="130"):
+            cmd_config_edit(_ns())
+
+
+class TestEmptyStateHints:
+    def test_chain_diagnose_hint(self, isolated, capsys):
+        assert cmd_config_chain(_ns()) == 0
+        assert "rrun config init" in capsys.readouterr().out
+
+    def test_machines_hint(self, isolated, capsys):
+        import rrun.__main__ as cli
+        assert cli.cmd_machines(_ns(json=False)) == 0
+        assert "rrun config init" in capsys.readouterr().err
+
+    def test_resolve_machine_hint(self, isolated):
+        with pytest.raises(KeyError, match="rrun config init"):
+            resolve_machine("nope")
+
+
+class TestInventoryPathCollision:
+    """v0.2.3 回归：cwd == ~/.rrun 或 $RRUN_CONFIG 指向用户清单时，来源链去重会丢弃
+    user 标签——user_inventory_path() 不得受此影响。"""
+
+    def test_cwd_inside_rrun_home(self, isolated, monkeypatch):
+        cmd_config_init(_ns(force=False))
+        monkeypatch.chdir(isolated / "home" / ".rrun")
+        assert cmd_config_add(_flag_ns(name="x", ip="1.1.1.1", user="u")) == 0
+        assert resolve_machine("x").ip == "1.1.1.1"
+        assert cmd_config_init(_ns(force=False)) == 1  # 仍能正确识别已存在
+
+    def test_env_points_at_user_file(self, isolated, monkeypatch):
+        cmd_config_init(_ns(force=False))
+        monkeypatch.setenv("RRUN_CONFIG", str(user_inventory_path()))
+        assert cmd_config_add(_flag_ns(name="x", ip="1.1.1.1", user="u")) == 0
+        assert resolve_machine("x").ip == "1.1.1.1"
+
+
+class TestMachinesD:
+    def test_init_creates_dir_and_readme(self, isolated):
+        cmd_config_init(_ns(force=False))
+        d = user_inventory_path().parent / "machines.d"
+        readme = d / "README.md"
+        assert readme.is_file() and "ln -s" in readme.read_text(encoding="utf-8")
+        if os.name != "nt":
+            assert stat.S_IMODE(d.stat().st_mode) == 0o700
+
+    def test_readme_not_treated_as_inventory(self, isolated):
+        cmd_config_init(_ns(force=False))
+        assert all("README" not in m.name for m in load_machines())
+
+    def test_ensure_machines_d_idempotent(self, isolated):
+        cmd_config_init(_ns(force=False))
+        readme = user_inventory_path().parent / "machines.d" / "README.md"
+        readme.write_text("user customized", encoding="utf-8")
+        cmd_config_init(_ns(force=True))
+        assert readme.read_text(encoding="utf-8") == "user customized"  # 不覆盖用户改动
+
+    def test_chain_shows_empty_dir(self, isolated, capsys):
+        cmd_config_init(_ns(force=False))
+        capsys.readouterr()
+        cmd_config_chain(_ns())
+        assert "no *.json files" in capsys.readouterr().out
+
+    def test_chain_lists_json_files_when_present(self, isolated, capsys):
+        cmd_config_init(_ns(force=False))
+        d = user_inventory_path().parent / "machines.d"
+        (d / "10-x.json").write_text(
+            json.dumps({"machines": [{"name": "deep", "ip": "1.1.1.1", "user": "u"}]}),
+            encoding="utf-8")
+        capsys.readouterr()
+        cmd_config_chain(_ns())
+        out = capsys.readouterr().out
+        assert "10-x.json" in out and "no *.json" not in out
+        assert "deep" in [m.name for m in load_machines()]
+
+
+class TestTemplateHint:
+    def test_hint_present_and_ignored_by_loader(self, isolated):
+        cmd_config_init(_ns(force=False))
+        assert "_hint" in _read_inventory()
+        assert load_machines()  # _hint 不影响加载
+
+    def test_hint_preserved_after_add(self, isolated):
+        cmd_config_init(_ns(force=False))
+        cmd_config_add(_flag_ns(name="z", ip="1.1.1.1", user="u"))
+        assert "_hint" in _read_inventory()