rrun-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{rrun_cli-0.2.1 → rrun_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrun-cli
-Version: 0.2.1
+Version: 0.2.3
 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,13 +94,13 @@ 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) |
 | `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`.
+Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`/`--env K=V` (not for Windows+python), `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
 
 ### Exit codes
 
@@ -118,7 +112,7 @@ Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`,
 
 ## 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
 {
@@ -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.1 → rrun_cli-0.2.3}/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,13 +66,13 @@ 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) |
 | `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`.
+Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`/`--env K=V` (not for Windows+python), `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
 
 ### Exit codes
 
@@ -90,7 +84,7 @@ Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`,
 
 ## 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
 {
@@ -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.1 → rrun_cli-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rrun-cli"
-version = "0.2.1"
+version = "0.2.3"
 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"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{rrun_cli-0.2.1 → rrun_cli-0.2.3}/src/rrun/__init__.py

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

{rrun_cli-0.2.1 → rrun_cli-0.2.3}/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:
@@ -41,9 +42,11 @@ import sys
 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"
@@ -137,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
 
 
@@ -277,6 +263,7 @@ def main() -> None:
     ap = argparse.ArgumentParser(
         prog="rrun",
         description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     sub = ap.add_subparsers(dest="subcmd", required=True)
 
     ep = sub.add_parser("exec", help="execute a local script / inline content on a remote machine")
@@ -287,9 +274,9 @@ def main() -> None:
     ep.add_argument("-c", "--content", help="inline script content (archived to ~/.rrun/drops/)")
     ep.add_argument("args", nargs="*",
                     help="script arguments (ASCII only; use -- to separate from options)")
-    ep.add_argument("--workdir", help="remote working directory (bash/powershell only)")
+    ep.add_argument("--workdir", help="remote working directory (not for Windows+python)")
     ep.add_argument("--env", action="append", metavar="KEY=VAL",
-                    help="remote environment variable (repeatable; ASCII only)")
+                    help="remote environment variable (repeatable; ASCII only; not for Windows+python)")
     ep.add_argument("--timeout", type=float, help="local timeout in seconds (exit=124 on expiry)")
     ep.add_argument("--python", dest="python", help="remote python path (skips auto-detection)")
     ep.add_argument("--no-utf8", action="store_true", help="do not pass -X utf8 to remote python")
@@ -301,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.3/src/rrun/config_cmd.py

@@ -0,0 +1,272 @@
+"""`rrun config` 子命令组：机器清单的初始化 / 追加 / 编辑 + 来源链诊断。
+
+设计要点：
+- init/add/edit 只操作「用户级主清单」（registry 来源链中的 user 位），路径从
+  candidate_sources() 派生而非写死 ~/.rrun，保证写入位置就是加载位置；
+  其他来源（env/cwd/machines.d/legacy）只读不动。
+- 模板内嵌为 package data（src/rrun/machines.template.json），离线可用、随发行版本
+  锁定；写盘即收紧权限（目录 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,
+    candidate_sources,
+    load_machines,
+    resolve_machine,
+    scan_sources,
+)
+
+TEMPLATE_FILE = Path(__file__).resolve().with_name("machines.template.json")
+
+_OS_ALIASES = {
+    "w": "Windows", "windows": "Windows",
+    "m": "Mac", "mac": "Mac", "macos": "Mac", "osx": "Mac", "darwin": "Mac",
+    "l": "Linux", "linux": "Linux",
+}
+
+
+def user_inventory_path() -> Path:
+    """用户级主清单路径（从来源链派生，不写死 ~/.rrun）。"""
+    for label, p in candidate_sources():
+        if label == "user":
+            return p
+    raise RuntimeError("unreachable: candidate_sources() always includes the user source")  # pragma: no cover
+
+
+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 cmd_config_init(ns) -> int:
+    """按内嵌模板创建用户级主清单；已存在时拒绝覆盖（--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"))
+    perms = "" if os.name == "nt" else ", mode 600"
+    print(f"[config] created {_shorten(path)} from the bundled template{perms}")
+    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 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.1 → rrun_cli-0.2.3}/src/rrun/executor.py

@@ -352,7 +352,7 @@ def run(host: str, lang: str = "", file: str = "", content: str = "", args=(),
             py_cmd += " " + " ".join(shlex.quote(a) for a in args)
         if env or workdir:
             if machine.is_windows:
-                raise ValueError("workdir/env are not supported for Windows+python yet; use os.chdir/os.environ inside the script")
+                raise ValueError("workdir/env are not supported for Windows+python (by design); use os.chdir/os.environ inside the script")
             remote_cmd = _posix_prefix(workdir, env) + py_cmd
         else:
             remote_cmd = py_cmd

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

@@ -0,0 +1,42 @@
+{
+  "defaults": {
+    "windows": { "os": "Windows" },
+    "mac": { "os": "Mac" },
+    "linux": { "os": "Linux" }
+  },
+  "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.1 → rrun_cli-0.2.3}/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"}
 
 
@@ -164,4 +168,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.1 → rrun_cli-0.2.3}/src/rrun_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrun-cli
-Version: 0.2.1
+Version: 0.2.3
 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,13 +94,13 @@ 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) |
 | `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`.
+Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`/`--env K=V` (not for Windows+python), `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
 
 ### Exit codes
 
@@ -118,7 +112,7 @@ Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`,
 
 ## 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
 {
@@ -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.1 → rrun_cli-0.2.3}/src/rrun_cli.egg-info/SOURCES.txt

@@ -3,8 +3,10 @@ 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.template.json
 src/rrun/registry.py
 src/rrun/remote-requirements.txt
 src/rrun/setup.py
@@ -15,6 +17,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.1 → rrun_cli-0.2.3}/tests/test_cli.py

@@ -1,7 +1,10 @@
-"""CLI 辅助函数测试：--env 解析、inline 落盘。"""
+"""CLI 辅助函数测试：--env 解析、inline 落盘、--version。"""
+
+import sys
 
 import pytest
 
+import rrun
 import rrun.__main__ as cli
 
 
@@ -27,3 +30,13 @@ class TestDropInline:
     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"
+
+
+class TestVersion:
+    def test_version_flag(self, monkeypatch, capsys):
+        # argparse version action 打印到 stdout 并以 0 退出
+        monkeypatch.setattr(sys, "argv", ["rrun", "--version"])
+        with pytest.raises(SystemExit) as e:
+            cli.main()
+        assert e.value.code == 0
+        assert capsys.readouterr().out.strip() == f"rrun {rrun.__version__}"

rrun_cli-0.2.3/tests/test_config_cmd.py

@@ -0,0 +1,247 @@
+"""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")