remote-cmd-manager 2.0.0__tar.gz → 2.2.0__tar.gz

{remote_cmd_manager-2.0.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.0.0
-Summary: SSH 远程服务器管理工具 / Python SSH remote server management tool
+Version: 2.2.0
+Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/Vae-Scrooge/remote-cmd
@@ -9,8 +9,8 @@ Project-URL: Repository, https://github.com/Vae-Scrooge/remote-cmd
 Project-URL: Documentation, https://github.com/Vae-Scrooge/remote-cmd#readme
 Project-URL: Bug Tracker, https://github.com/Vae-Scrooge/remote-cmd/issues
 Project-URL: Download, https://pypi.org/project/remote_cmd_manager/
-Keywords: ssh,remote,server-management,sysadmin,devops
-Classifier: Development Status :: 4 - Beta
+Keywords: ssh,remote,server-management,sysadmin,devops,cross-platform
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
@@ -21,6 +21,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: System :: Networking
 Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -42,7 +45,7 @@ Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: keyring>=24.0; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: pdoc<16,>=15; extra == "docs"
+Requires-Dist: pdoc==15.0.4; extra == "docs"
 Dynamic: license-file
 
 <p align="center">
@@ -54,6 +57,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
 
+<p align="center"><strong>Tested on Linux, macOS, and Windows</strong></p>
 <h1 align="center">Remote CMD — SSH Server Management<br><small>Without the Overhead</small></h1>
 
 <p align="center">
@@ -71,15 +75,9 @@ Dynamic: license-file
   <a href="#contributing">Contributing</a>
 </p>
 
-<p align="center">
-  <a href="https://asciinema.org/a/9yLeYj73muPUuAQY" target="_blank">
-    <img src="https://asciinema.org/a/9yLeYj73muPUuAQY.svg" width="720" alt="Demo">
-  </a>
-</p>
-
 ---
 
-**Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and target groups by tags — no Ansible DSL or shell loops required.
+**Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.
 
 ```bash
 # One command to get started
@@ -88,8 +86,27 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
+## v2.2.0 Release Highlights
+
+v2.2.0 bounds batch-execution resource usage, makes concurrent SQLite writers safe, tightens
+retry classification, and hardens the release pipeline. See the
+[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+
+### Resource & Reliability
+
+- Internal batch pools are now created lazily per host, capped at one connection, and closed as soon as that host (including all retries) finishes; batch-wide live internal connections are bounded by `max_concurrency` instead of retaining one idle connection per host until the batch ends.
+- SQLite writes now use `BEGIN IMMEDIATE` with a configurable `busy_timeout` (default 5000 ms), and the initial `journal_mode=WAL` switch is retried; concurrent `remote-cmd` processes writing the same `hosts.db` no longer fail with `database is locked` or lose updates. Schema and `db_version` are unchanged.
+- Pool closure raises the new `PoolClosedError` (still catchable as `RuntimeError`); retry classification is corrected so bare `RuntimeError` is retryable again (v2.0 behavior) while pool closure remains non-retryable. Typed permanent and transient errors are unchanged.
+
+### Release Engineering
+
+- Publish workflow: artifact actions aligned, run-scoped artifact names, duplicate version publication now fails instead of being skipped, `twine check` validates distributions, and the release tag is verified against the package version. Trusted Publishing and the GitHub Release → PyPI flow are unchanged.
+- CI documentation drift detection: `docs/api` is regenerated and compared on relevant changes, failing when tracked generated docs are stale (`pdoc` pinned to `15.0.4` on Python 3.12).
+- Release metadata validation: a lightweight gate checks the single-source version, the `pyproject.toml` dynamic-version attribute, `[Unreleased]` and matching `[x.y.z]` CHANGELOG headings, and (on release) that the git tag matches the package version.
+
 ## Table of Contents
 
+- [v2.2.0 Release Highlights](#v220-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -132,8 +149,8 @@ remote-cmd host add web-01 192.168.1.10 ubuntu --key ~/.ssh/id_rsa
 # 3. Run a command
 remote-cmd run web-01 "uptime"
 
-# 4. Run across all production servers
-remote-cmd batch-run -t production "df -h /"
+# 4. Run across named production servers
+remote-cmd batch-run web-01 web-02 db-01 "df -h /"
 ```
 
 ---
@@ -143,7 +160,7 @@ remote-cmd batch-run -t production "df -h /"
 ### 🖥️ System Administrators — Check disk across 20 servers in one command
 
 ```bash
-remote-cmd batch-run -t production "df -h / | tail -1"
+remote-cmd batch-run web-01 web-02 db-01 "df -h / | tail -1"
 # Output:
 #   ✓ web-01  → /dev/sda1  32G  12G  19G  40% /
 #   ✓ web-02  → /dev/sda1  32G  28G   3G  90% /   ⚠️
@@ -167,7 +184,7 @@ for host in service.list_hosts(tag="staging"):
 ### 🔥 Incident Response — Check logs across all servers
 
 ```bash
-remote-cmd batch-run -t web "journalctl -xe -n 50 | grep -i error"
+remote-cmd batch-run web-01 web-02 "journalctl -xe -n 50 | grep -i error"
 ```
 
 ### 🔧 Config Update — Upload and reload nginx across tagged hosts
@@ -190,10 +207,10 @@ All operations are available from the terminal:
 | `remote-cmd host show <name>` | Show one host's details |
 | `remote-cmd host test <name>` | Test connectivity to a host |
 | `remote-cmd host remove <name>` | Remove a host |
-| `remote-cmd run <name> "<cmd>"` | Run a command on one host |
+| `remote-cmd run <name> "<cmd>" [-T SECONDS]` | Run a command on one host (`--timeout/-T` sets the wall-clock limit) |
 | `remote-cmd upload <name> <local> <remote>` | Upload a file via SFTP |
 | `remote-cmd download <name> <remote> <local>` | Download a file via SFTP |
-| `remote-cmd batch-run -t <tag> "<cmd>"` | Run across all hosts in a tag (`-C` concurrency, `-T` timeout, `--async`, `--show-failures`) |
+| `remote-cmd batch-run <name>... "<cmd>"` | Run across named hosts (`-C` concurrency, `-T` timeout, `-r` retries, `--async`, `--show-failures`) |
 
 ---
 
@@ -221,7 +238,7 @@ with SSHClient(config) as client:
 
     # List remote directory
     for entry in client.list_remote_directory("/var/log"):
-        print(f"{entry['name']}: {entry['size']} bytes")
+        print(f"{entry.name}: {entry.size} bytes")
 ```
 
 ---
@@ -232,7 +249,7 @@ with SSHClient(config) as client:
 |---|---|
 | **SSH Auth** | Password + key file + ssh-agent, with pluggable credential providers |
 | **Credential Chain** | Source passwords from environment, keyring, or arbitrary providers, in priority order |
-| **Credential Encryption** | AES-encrypt secrets at rest (`CredentialEncryption`) |
+| **Credential Encryption** | Fernet-encrypt secrets at rest (`CredentialEncryption`) |
 | **Commands** | Single, multi-line, sudo with password |
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
@@ -240,12 +257,26 @@ with SSHClient(config) as client:
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
-| **Connection Test** | Ping all hosts and report status |
+| **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |
 | **Type Safety** | Full type annotations + mypy strict |
 
 ---
 
+## Cross-Platform Support
+
+`remote-cmd` is a pure-Python client, **tested and supported on Linux, macOS, and Windows**. No native dependencies or platform-specific builds are required.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Fully tested | Primary development platform |
+| macOS | ✅ Supported | Use `brew install openssh` for a newer OpenSSH |
+| Windows | ✅ Supported | PowerShell / CMD / WSL all work |
+
+> **Note on Windows file permissions:** Credential encryption keys are protected with `0600` permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.
+
+---
+
 ## Installation
 
 ```bash
@@ -263,8 +294,9 @@ pip install -e ".[dev]"
 
 The `[async]` extra installs `asyncssh` and enables the native async execution
 kernel: `AsyncSSHClient`, `AsyncConnectionPool` and `AsyncBatchExecutor`
-(also available via `BatchExecutor(use_async=True)`). Without it, `import remote_cmd`
-still works — the async symbols are simply not exported.
+(also available via `BatchExecutor(use_async=True)`). `BatchExecutor(use_async=True)`
+also requires this extra. Without it, `import remote_cmd` still works — the async symbols
+are simply not exported.
 
 ---
 
@@ -284,14 +316,14 @@ still works — the async symbols are simply not exported.
 | [Changelog](./CHANGELOG.md) | Release history |
 | [Mobile Remote Guide](./MOBILE-REMOTE-GUIDE.md) | Manage servers from your phone |
 
-> **Note:** The documentation center and tutorials are maintained in **Chinese**. See
+> **Note:** The documentation center and tutorials are maintained in **English**. See
 > [README.zh-CN.md](./README.zh-CN.md) for the Chinese version of this page.
 
 ---
 
 ## Project Status
 
-**Beta.** The core API is stable. Breaking changes will be communicated via semantic versioning.
+**Stable.** The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.
 
 **Roadmap:**
 - [x] Async SSH operations (parallel execution) — v1.1.0

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/README.md

@@ -7,6 +7,7 @@
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
 
+<p align="center"><strong>Tested on Linux, macOS, and Windows</strong></p>
 <h1 align="center">Remote CMD — SSH Server Management<br><small>Without the Overhead</small></h1>
 
 <p align="center">
@@ -24,15 +25,9 @@
   <a href="#contributing">Contributing</a>
 </p>
 
-<p align="center">
-  <a href="https://asciinema.org/a/9yLeYj73muPUuAQY" target="_blank">
-    <img src="https://asciinema.org/a/9yLeYj73muPUuAQY.svg" width="720" alt="Demo">
-  </a>
-</p>
-
 ---
 
-**Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and target groups by tags — no Ansible DSL or shell loops required.
+**Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.
 
 ```bash
 # One command to get started
@@ -41,8 +36,27 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
+## v2.2.0 Release Highlights
+
+v2.2.0 bounds batch-execution resource usage, makes concurrent SQLite writers safe, tightens
+retry classification, and hardens the release pipeline. See the
+[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+
+### Resource & Reliability
+
+- Internal batch pools are now created lazily per host, capped at one connection, and closed as soon as that host (including all retries) finishes; batch-wide live internal connections are bounded by `max_concurrency` instead of retaining one idle connection per host until the batch ends.
+- SQLite writes now use `BEGIN IMMEDIATE` with a configurable `busy_timeout` (default 5000 ms), and the initial `journal_mode=WAL` switch is retried; concurrent `remote-cmd` processes writing the same `hosts.db` no longer fail with `database is locked` or lose updates. Schema and `db_version` are unchanged.
+- Pool closure raises the new `PoolClosedError` (still catchable as `RuntimeError`); retry classification is corrected so bare `RuntimeError` is retryable again (v2.0 behavior) while pool closure remains non-retryable. Typed permanent and transient errors are unchanged.
+
+### Release Engineering
+
+- Publish workflow: artifact actions aligned, run-scoped artifact names, duplicate version publication now fails instead of being skipped, `twine check` validates distributions, and the release tag is verified against the package version. Trusted Publishing and the GitHub Release → PyPI flow are unchanged.
+- CI documentation drift detection: `docs/api` is regenerated and compared on relevant changes, failing when tracked generated docs are stale (`pdoc` pinned to `15.0.4` on Python 3.12).
+- Release metadata validation: a lightweight gate checks the single-source version, the `pyproject.toml` dynamic-version attribute, `[Unreleased]` and matching `[x.y.z]` CHANGELOG headings, and (on release) that the git tag matches the package version.
+
 ## Table of Contents
 
+- [v2.2.0 Release Highlights](#v220-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -85,8 +99,8 @@ remote-cmd host add web-01 192.168.1.10 ubuntu --key ~/.ssh/id_rsa
 # 3. Run a command
 remote-cmd run web-01 "uptime"
 
-# 4. Run across all production servers
-remote-cmd batch-run -t production "df -h /"
+# 4. Run across named production servers
+remote-cmd batch-run web-01 web-02 db-01 "df -h /"
 ```
 
 ---
@@ -96,7 +110,7 @@ remote-cmd batch-run -t production "df -h /"
 ### 🖥️ System Administrators — Check disk across 20 servers in one command
 
 ```bash
-remote-cmd batch-run -t production "df -h / | tail -1"
+remote-cmd batch-run web-01 web-02 db-01 "df -h / | tail -1"
 # Output:
 #   ✓ web-01  → /dev/sda1  32G  12G  19G  40% /
 #   ✓ web-02  → /dev/sda1  32G  28G   3G  90% /   ⚠️
@@ -120,7 +134,7 @@ for host in service.list_hosts(tag="staging"):
 ### 🔥 Incident Response — Check logs across all servers
 
 ```bash
-remote-cmd batch-run -t web "journalctl -xe -n 50 | grep -i error"
+remote-cmd batch-run web-01 web-02 "journalctl -xe -n 50 | grep -i error"
 ```
 
 ### 🔧 Config Update — Upload and reload nginx across tagged hosts
@@ -143,10 +157,10 @@ All operations are available from the terminal:
 | `remote-cmd host show <name>` | Show one host's details |
 | `remote-cmd host test <name>` | Test connectivity to a host |
 | `remote-cmd host remove <name>` | Remove a host |
-| `remote-cmd run <name> "<cmd>"` | Run a command on one host |
+| `remote-cmd run <name> "<cmd>" [-T SECONDS]` | Run a command on one host (`--timeout/-T` sets the wall-clock limit) |
 | `remote-cmd upload <name> <local> <remote>` | Upload a file via SFTP |
 | `remote-cmd download <name> <remote> <local>` | Download a file via SFTP |
-| `remote-cmd batch-run -t <tag> "<cmd>"` | Run across all hosts in a tag (`-C` concurrency, `-T` timeout, `--async`, `--show-failures`) |
+| `remote-cmd batch-run <name>... "<cmd>"` | Run across named hosts (`-C` concurrency, `-T` timeout, `-r` retries, `--async`, `--show-failures`) |
 
 ---
 
@@ -174,7 +188,7 @@ with SSHClient(config) as client:
 
     # List remote directory
     for entry in client.list_remote_directory("/var/log"):
-        print(f"{entry['name']}: {entry['size']} bytes")
+        print(f"{entry.name}: {entry.size} bytes")
 ```
 
 ---
@@ -185,7 +199,7 @@ with SSHClient(config) as client:
 |---|---|
 | **SSH Auth** | Password + key file + ssh-agent, with pluggable credential providers |
 | **Credential Chain** | Source passwords from environment, keyring, or arbitrary providers, in priority order |
-| **Credential Encryption** | AES-encrypt secrets at rest (`CredentialEncryption`) |
+| **Credential Encryption** | Fernet-encrypt secrets at rest (`CredentialEncryption`) |
 | **Commands** | Single, multi-line, sudo with password |
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
@@ -193,12 +207,26 @@ with SSHClient(config) as client:
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
-| **Connection Test** | Ping all hosts and report status |
+| **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |
 | **Type Safety** | Full type annotations + mypy strict |
 
 ---
 
+## Cross-Platform Support
+
+`remote-cmd` is a pure-Python client, **tested and supported on Linux, macOS, and Windows**. No native dependencies or platform-specific builds are required.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Fully tested | Primary development platform |
+| macOS | ✅ Supported | Use `brew install openssh` for a newer OpenSSH |
+| Windows | ✅ Supported | PowerShell / CMD / WSL all work |
+
+> **Note on Windows file permissions:** Credential encryption keys are protected with `0600` permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.
+
+---
+
 ## Installation
 
 ```bash
@@ -216,8 +244,9 @@ pip install -e ".[dev]"
 
 The `[async]` extra installs `asyncssh` and enables the native async execution
 kernel: `AsyncSSHClient`, `AsyncConnectionPool` and `AsyncBatchExecutor`
-(also available via `BatchExecutor(use_async=True)`). Without it, `import remote_cmd`
-still works — the async symbols are simply not exported.
+(also available via `BatchExecutor(use_async=True)`). `BatchExecutor(use_async=True)`
+also requires this extra. Without it, `import remote_cmd` still works — the async symbols
+are simply not exported.
 
 ---
 
@@ -237,14 +266,14 @@ still works — the async symbols are simply not exported.
 | [Changelog](./CHANGELOG.md) | Release history |
 | [Mobile Remote Guide](./MOBILE-REMOTE-GUIDE.md) | Manage servers from your phone |
 
-> **Note:** The documentation center and tutorials are maintained in **Chinese**. See
+> **Note:** The documentation center and tutorials are maintained in **English**. See
 > [README.zh-CN.md](./README.zh-CN.md) for the Chinese version of this page.
 
 ---
 
 ## Project Status
 
-**Beta.** The core API is stable. Breaking changes will be communicated via semantic versioning.
+**Stable.** The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.
 
 **Roadmap:**
 - [x] Async SSH operations (parallel execution) — v1.1.0

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/examples/basic_usage.py

@@ -107,8 +107,8 @@ def example_file_transfer():
         entries = client.list_remote_directory("/tmp")
         print("\n/tmp 目录内容:")
         for entry in entries:
-            type_str = "D" if entry["is_dir"] else "F"
-            print(f"  [{type_str}] {entry['name']:30} {entry['size']:>10} bytes")
+            type_str = "D" if entry.is_dir else "F"
+            print(f"  [{type_str}] {entry.name:30} {entry.size:>10} bytes")
 
 
 def example_sudo_command():

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/pyproject.toml

@@ -5,16 +5,16 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "remote_cmd_manager"
 dynamic = ["version"]
-description = "SSH 远程服务器管理工具 / Python SSH remote server management tool"
+description = "Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
 authors = [
     { name = "Vae-Scrooge", email = "vaescrooge@gmail.com" },
 ]
-keywords = ["ssh", "remote", "server-management", "sysadmin", "devops"]
+keywords = ["ssh", "remote", "server-management", "sysadmin", "devops", "cross-platform"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: MIT License",
@@ -25,6 +25,9 @@ classifiers = [
     "Topic :: System :: Systems Administration",
     "Topic :: System :: Networking",
     "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
 ]
 dependencies = [
     "paramiko>=3.0",
@@ -50,8 +53,10 @@ dev = [
     # 测试 keyring 凭据提供者（生产为可选依赖，测试环境固定安装）
     "keyring>=24.0",
 ]
-# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）
-docs = ["pdoc>=15,<16"]
+# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）。
+# 精确 pin 15.0.4：pdoc HTML 输出随版本/解释器变化，docs/api 漂移门禁
+# （scripts/check_docs_drift.py）要求生成结果可复现。
+docs = ["pdoc==15.0.4"]
 
 [project.urls]
 Homepage = "https://github.com/Vae-Scrooge/remote-cmd"

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 1.2.3
+Version: 2.2.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/remote_cmd/_version.py

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/remote_cmd/cli/main.py

@@ -310,19 +310,27 @@ def host_test(ctx: click.Context, name: str) -> None:
 @cli.command()
 @click.argument("host_name", required=True)
 @click.argument("command", required=True)
+@click.option(
+    "--timeout",
+    "-T",
+    default=None,
+    type=int,
+    help="Command timeout in seconds (default: no timeout)",
+)
 @click.pass_context
-def run(ctx: click.Context, host_name: str, command: str) -> None:
+def run(ctx: click.Context, host_name: str, command: str, timeout: Optional[int]) -> None:
     """
     Execute a command on a remote host
 
     HOST_NAME: host name
+
     COMMAND: command to execute
     """
     service: HostService = ctx.obj["service"]
 
     try:
         with service.connect_to_host(host_name) as client:
-            result = client.execute(command)
+            result = client.execute(command, timeout=timeout)
 
             if result.stdout:
                 click.echo(result.stdout)
@@ -397,7 +405,12 @@ def download(ctx: click.Context, host_name: str, local_path: str, remote_path: s
 @click.option("--concurrency", "-C", default=10, help="Max concurrency (default: 10)")
 @click.option("--timeout", "-T", default=30, help="Command timeout in seconds (default: 30)")
 @click.option("--retry", "-r", default=0, help="Failure retry count (default: 0)")
-@click.option("--retry-delay", default=1.0, help="Retry delay in seconds (default: 1.0)")
+@click.option(
+    "--retry-delay",
+    default=1.0,
+    help="Base retry delay in seconds; actual wait is exponential "
+    "backoff with jitter (default: 1.0)",
+)
 @click.option("--async", "use_async", is_flag=True, help="Use async execution engine (asyncssh)")
 @click.option("--show-failures", is_flag=True, help="Show only failed hosts")
 @click.pass_context

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/remote_cmd/core/async_connection_pool.py

@@ -26,6 +26,7 @@ from remote_cmd.service._pool_policy import (
     lifetime_expired,
     should_close,
 )
+from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
 
@@ -48,12 +49,25 @@ class AsyncConnectionPool:
         max_lifetime: int = 3600,
         idle_timeout: int = 300,
         health_check_interval: int = 60,
+        client_factory: Optional[Any] = None,
     ) -> None:
+        """
+        Args:
+            config: 用于建立 SSH 连接的配置
+            max_connections: 同一最大连接数（同一配置可复用）
+            max_lifetime: 连接最大生命周期（秒），超过自动关闭
+            idle_timeout: 空闲超时（秒），超过自动关闭
+            health_check_interval: 后台清理任务周期（秒）
+            client_factory: 客户端工厂，默认为 AsyncSSHClient；测试可注入
+                mock（与 SyncConnectionPool 对齐）
+        """
         self.config = config
         self._max = max_connections
         self._max_lifetime = max_lifetime
         self._idle_timeout = idle_timeout
         self._health_check_interval = health_check_interval
+        # 客户端工厂：默认为 AsyncSSHClient；测试可注入 mock
+        self._client_factory = client_factory or AsyncSSHClient
 
         # 容器
         self._connections: list[AsyncSSHClient] = []
@@ -107,11 +121,18 @@ class AsyncConnectionPool:
 
         Raises:
             SSHConnectionError: 创建连接失败
-            RuntimeError: 连接池已关闭（close_all 之后）
+            PoolClosedError: 连接池已关闭（close_all 之后），
+                同时是 RuntimeError 子类（既有捕获行为不变）
         """
         if self._closed:
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         await self._semaphore.acquire()
+        # 竞态守卫：等待信号量期间 close_all() 可能已完成——
+        # 取得槽位后必须复查，已关闭则归还槽位并抛出既有错误，
+        # 否则会向调用方发放来自已关闭池的连接
+        if self._closed:
+            self._semaphore.release()
+            raise PoolClosedError("connection pool is closed")
         try:
             # 优先复用空闲连接
             while not self._free.empty():
@@ -168,7 +189,7 @@ class AsyncConnectionPool:
     # 内部
     # ------------------------------------------------------------------
     async def _create_connection(self) -> AsyncSSHClient:
-        client = AsyncSSHClient(self.config)
+        client = self._client_factory(self.config)
         try:
             await client.connect()
         except Exception:  # noqa: BLE001

{remote_cmd_manager-2.0.0 → remote_cmd_manager-2.2.0}/remote_cmd/core/async_ssh_client.py

@@ -22,11 +22,18 @@ from typing import Any, Optional
 
 import asyncssh
 
-from remote_cmd.core.ssh_client import CommandResult, ConnectionConfig, RemoteFileEntry
+from remote_cmd.core.ssh_client import (
+    CommandResult,
+    ConnectionConfig,
+    RemoteFileEntry,
+    validate_environment,
+)
 from remote_cmd.utils.exceptions import (
+    SSHAuthenticationError,
     SSHCommandError,
     SSHConnectionError,
     SSHFileTransferError,
+    SSHTimeoutError,
 )
 
 logger = logging.getLogger(__name__)
@@ -94,11 +101,12 @@ class AsyncSSHClient:
         try:
             self._conn = await asyncssh.connect(**connect_kwargs)
         except asyncssh.PermissionDenied as e:
-            raise SSHConnectionError(f"authentication failed: {e}") from e
+            # 永久性错误：重试同一凭据只会加剧账号锁定（见 service/retry_policy.py）
+            raise SSHAuthenticationError(f"authentication failed: {e}") from e
         except (OSError, asyncssh.Error) as e:
             msg = str(e).lower()
             if "timed out" in msg or "timeout" in msg or isinstance(e, asyncssh.TimeoutError):
-                raise SSHConnectionError(f"connection timeout: {self.config.hostname}") from e
+                raise SSHTimeoutError(f"connection timeout: {self.config.hostname}") from e
             raise SSHConnectionError(f"connection error: {e}") from e
 
         logger.info(f"connected to {self.config.hostname}")
@@ -187,6 +195,8 @@ class AsyncSSHClient:
             SSHConnectionError: 未连接时抛出
         """
         conn = await self._get_conn()
+        # 安全：键必须为合法 shell 标识符（与同步实现一致，防止命令注入）
+        validate_environment(environment)
         # 安全：对 value 做 shlex.quote 转义，防止 shell 元字符注入
         env_str = ""
         if environment:
@@ -198,11 +208,13 @@ class AsyncSSHClient:
         # 安全：不记录命令全文（可能含敏感参数），仅记录执行事件
         logger.debug("executing remote command")
         try:
+            # 环境变量仅通过命令前缀的 export 注入（与同步 SSHClient 行为
+            # 一致）：conn.run(env=...) 依赖服务端 AcceptEnv 且语义分叉，
+            # 不再重复传递
             result = await conn.run(
                 full_command,
                 timeout=timeout,
                 check=False,
-                env={k: str(v) for k, v in (environment or {}).items()},
             )
         except (OSError, asyncssh.Error) as e:
             raise SSHCommandError(f"command execution failed: {e}") from e