remote-cmd-manager 2.6.0__tar.gz → 2.8.0__tar.gz

{remote_cmd_manager-2.6.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.6.0
+Version: 2.8.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
@@ -89,32 +89,37 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.6.0 Release Highlights
+## v2.8.0 Release Highlights
 
-v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
-moved out of `core` (eliminating the `core → service` dependency) and a process-wide
-live-connection budget was added for fleet-scale resource control. Public APIs remain
-backward compatible. See the [full migration notes](./CHANGELOG.md).
+v2.8.0 adds the first P3 user-facing features: **connection profiles** and
+**machine-readable CLI output**. Public APIs remain backward compatible; the
+default CLI output and all existing commands behave exactly as before. See the
+[full migration notes](./CHANGELOG.md).
 
-### Architecture
+### Connection Profiles
 
-- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
-- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
-- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
+- New `HostProfile` (exported from `remote_cmd`): reusable connection defaults — username, port, key file, tags, description — stored by both JSON and SQLite repositories via the optional `ProfileStore` capability (the `HostRepository` ABC is unchanged).
+- Hosts reference a profile (`host add --profile aws`); values merge at connect time (reference model): port when the host uses the default 22, key file when unset, description when empty, tags as a union, username when the host stores none (live default — later profile username changes propagate).
+- Changing a profile applies to every referencing host; unknown profiles fail with a clear `ConfigError` (batch execution reports them per host).
+- `ProfileService` CRUD + `remote-cmd profile add/list/show/remove`, with deletion protection for profiles still referenced by hosts.
 
-### Global Connection Budget
+### Machine-Readable Output
 
-- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
-- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
-- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
+- `remote-cmd run` and `remote-cmd batch-run` accept `--format rich|json|table` (default `rich` = byte-compatible with previous output).
+- JSON uses a stable schema with sorted result keys; table output is plain aligned text. Machine formats suppress the progress bar/header so stdout stays parseable.
+- The formatter layer lives in `remote_cmd/cli/formatters/` and never touches the execution kernels.
 
-### Compatibility
+### Try It
 
-- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
+```bash
+remote-cmd profile add aws -u ec2-user -k ~/.ssh/aws.pem -t cloud
+remote-cmd host add web-01 10.0.0.10 --profile aws
+remote-cmd batch-run web-01 web-02 "uptime" --format json | jq .
+```
 
 ## Table of Contents
 
-- [v2.6.0 Release Highlights](#v260-release-highlights)
+- [v2.8.0 Release Highlights](#v280-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -261,7 +266,9 @@ with SSHClient(config) as client:
 | **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 |
-| **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
+| **Connection Profiles** | Reusable username/port/key/tag defaults referenced by hosts (`ProfileService`, `--profile`); never stores credentials |
+| **Output Formats** | `--format rich\|json\|table` for `run` / `batch-run` (stable JSON schema, parseable stdout) |
+| **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`); profile tags participate in filtering |
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.8.0}/README.md

@@ -36,32 +36,37 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.6.0 Release Highlights
+## v2.8.0 Release Highlights
 
-v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
-moved out of `core` (eliminating the `core → service` dependency) and a process-wide
-live-connection budget was added for fleet-scale resource control. Public APIs remain
-backward compatible. See the [full migration notes](./CHANGELOG.md).
+v2.8.0 adds the first P3 user-facing features: **connection profiles** and
+**machine-readable CLI output**. Public APIs remain backward compatible; the
+default CLI output and all existing commands behave exactly as before. See the
+[full migration notes](./CHANGELOG.md).
 
-### Architecture
+### Connection Profiles
 
-- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
-- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
-- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
+- New `HostProfile` (exported from `remote_cmd`): reusable connection defaults — username, port, key file, tags, description — stored by both JSON and SQLite repositories via the optional `ProfileStore` capability (the `HostRepository` ABC is unchanged).
+- Hosts reference a profile (`host add --profile aws`); values merge at connect time (reference model): port when the host uses the default 22, key file when unset, description when empty, tags as a union, username when the host stores none (live default — later profile username changes propagate).
+- Changing a profile applies to every referencing host; unknown profiles fail with a clear `ConfigError` (batch execution reports them per host).
+- `ProfileService` CRUD + `remote-cmd profile add/list/show/remove`, with deletion protection for profiles still referenced by hosts.
 
-### Global Connection Budget
+### Machine-Readable Output
 
-- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
-- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
-- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
+- `remote-cmd run` and `remote-cmd batch-run` accept `--format rich|json|table` (default `rich` = byte-compatible with previous output).
+- JSON uses a stable schema with sorted result keys; table output is plain aligned text. Machine formats suppress the progress bar/header so stdout stays parseable.
+- The formatter layer lives in `remote_cmd/cli/formatters/` and never touches the execution kernels.
 
-### Compatibility
+### Try It
 
-- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
+```bash
+remote-cmd profile add aws -u ec2-user -k ~/.ssh/aws.pem -t cloud
+remote-cmd host add web-01 10.0.0.10 --profile aws
+remote-cmd batch-run web-01 web-02 "uptime" --format json | jq .
+```
 
 ## Table of Contents
 
-- [v2.6.0 Release Highlights](#v260-release-highlights)
+- [v2.8.0 Release Highlights](#v280-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -208,7 +213,9 @@ with SSHClient(config) as client:
 | **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 |
-| **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
+| **Connection Profiles** | Reusable username/port/key/tag defaults referenced by hosts (`ProfileService`, `--profile`); never stores credentials |
+| **Output Formats** | `--format rich\|json\|table` for `run` / `batch-run` (stable JSON schema, parseable stdout) |
+| **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`); profile tags participate in filtering |
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.8.0}/pyproject.toml

@@ -122,6 +122,10 @@ ignore = [
 "__init__.py" = ["E402"]
 # 测试中 pytest fixture 参数未直接引用属于正常模式（如 patch 装饰器触发副作用）
 "tests/test_async_ssh_client.py" = ["ARG002"]
+# mock_paramiko fixture 以 patch 副作用生效，线程模型测试不直接引用其返回值
+"tests/test_ssh_client.py" = ["ARG002"]
+# Profile 合并测试中的 BareRepo stub 需保留与 HostRepository ABC 一致的签名
+"tests/test_profile_merge.py" = ["ARG002"]
 "tests/test_async_batch_executor.py" = ["ARG001", "ARG002"]
 # 连接池测试中 patched_client fixture 触发 patch 副作用，factory 保留 cfg 参数以匹配真实签名
 "tests/test_sync_connection_pool.py" = ["ARG001", "ARG002"]

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.8.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.6.0（单一真相源见 remote_cmd._version）
+Version: 2.8.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -59,24 +59,26 @@ __author__ = "Vae-Scrooge"
 __email__ = "vae-scrooge@example.com"
 __license__ = "MIT"
 
+import importlib.util
 import logging
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
-# 异步原生模块依赖 asyncssh（optional extra [async]），未安装时优雅降级，
-# 避免 `import remote_cmd` 直接失败
-try:
+# 异步原生模块依赖 asyncssh（optional extra [async]）。v2.7（P2.2）起用
+# find_spec 显式探测可选依赖：仅当 asyncssh 缺失时才降级；若 asyncssh 已
+# 安装而我们自己的异步模块 import 失败（代码缺陷/依赖损坏），import
+# 错误会向上传播，不再被静默误判为"未安装 asyncssh"。
+_HAS_ASYNC = importlib.util.find_spec("asyncssh") is not None
+
+if _HAS_ASYNC:
     from remote_cmd.core.async_connection_pool import AsyncConnectionPool
     from remote_cmd.core.async_ssh_client import AsyncSSHClient
     from remote_cmd.service.async_batch_executor import AsyncBatchExecutor
 
-    _HAS_ASYNC = True
-except ImportError:  # pragma: no cover - 依赖 asyncssh，未安装时不导出异步符号
-    _HAS_ASYNC = False
-
 from remote_cmd.api.host_manager import HostManager
 from remote_cmd.core.budget import ConnectionBudget
 from remote_cmd.core.host import Host
+from remote_cmd.core.profile import HostProfile
 from remote_cmd.core.ssh_client import SSHClient
 from remote_cmd.core.sync_connection_pool import SyncConnectionPool
 
@@ -104,6 +106,7 @@ from remote_cmd.service.batch_executor import (
     OutputPolicy,
 )
 from remote_cmd.service.credential_provider import KeyringCredentialProvider
+from remote_cmd.service.profile_service import ProfileService
 from remote_cmd.service.task_runner import Task, TaskRunner, TaskStatus
 from remote_cmd.utils.crypto import CredentialEncryption
 from remote_cmd.utils.exceptions import BudgetTimeoutError, PlaintextCredentialWarning
@@ -123,11 +126,13 @@ if _HAS_ASYNC:
         "AsyncConnectionPool",
         "AsyncBatchExecutor",
         "Host",
+        "HostProfile",
         "HostManager",
         # 新架构导出
         "HostRepository",
         "JsonHostRepository",
         "HostService",
+        "ProfileService",
         "SSHService",
         "CredentialProvider",
         "EnvCredentialProvider",
@@ -160,11 +165,13 @@ else:
         # 原有导出（向后兼容，不含异步符号）
         "SSHClient",
         "Host",
+        "HostProfile",
         "HostManager",
         # 新架构导出
         "HostRepository",
         "JsonHostRepository",
         "HostService",
+        "ProfileService",
         "SSHService",
         "CredentialProvider",
         "EnvCredentialProvider",

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.8.0}/remote_cmd/_version.py

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

remote_cmd_manager-2.8.0/remote_cmd/cli/formatters/__init__.py

@@ -0,0 +1,27 @@
+"""
+执行结果格式化层（CLI，v2.8）
+
+职责边界：
+- 本层只消费 ``CommandResult`` / ``BatchResult`` 数据对象并渲染字符串，
+  **绝不进入执行内核**（BatchExecutor / 连接池等不感知输出格式）。
+- ``rich`` 格式（默认）保留在 CLI 原有渲染路径（含颜色与进度条），
+  本包提供 ``json`` / ``table`` 两种机器友好格式。
+- JSON 输出为稳定 schema（字段与顺序固定），便于脚本消费。
+
+用法:
+    >>> from remote_cmd.cli.formatters import format_batch_result
+    >>> text = format_batch_result(batch_result, fmt="json")  # doctest: +SKIP
+"""
+
+from remote_cmd.cli.formatters.base import format_batch_result, format_single_result
+from remote_cmd.cli.formatters.json import render_batch_json, render_single_json
+from remote_cmd.cli.formatters.table import render_batch_table, render_single_table
+
+__all__ = [
+    "format_batch_result",
+    "format_single_result",
+    "render_batch_json",
+    "render_batch_table",
+    "render_single_json",
+    "render_single_table",
+]

remote_cmd_manager-2.8.0/remote_cmd/cli/formatters/base.py

@@ -0,0 +1,71 @@
+"""
+格式化器分发与校验（CLI，v2.8）
+"""
+
+from typing import Optional
+
+from remote_cmd.cli.formatters.json import render_batch_json, render_single_json
+from remote_cmd.cli.formatters.table import render_batch_table, render_single_table
+from remote_cmd.core.ssh_client import CommandResult
+from remote_cmd.service._types import BatchResult
+from remote_cmd.utils.exceptions import ValidationError
+
+#: CLI ``--format`` 可选值（rich 由 CLI 默认渲染路径处理）
+MACHINE_FORMATS = ("json", "table")
+FORMAT_CHOICES = ("rich", "json", "table")
+
+
+def format_single_result(
+    host_name: str,
+    command: str,
+    result: CommandResult,
+    fmt: str,
+    duration: Optional[float] = None,
+) -> str:
+    """渲染单主机执行结果为 ``fmt`` 字符串。
+
+    Args:
+        host_name: 主机名
+        command: 执行的命令
+        result: 命令结果
+        fmt: ``json`` 或 ``table``
+        duration: 可选耗时（秒），JSON 中作为 ``duration`` 字段
+
+    Raises:
+        ValidationError: fmt 不是机器格式
+    """
+    if fmt == "json":
+        return render_single_json(host_name, command, result, duration)
+    if fmt == "table":
+        return render_single_table(host_name, command, result, duration)
+    raise ValidationError(f"unsupported machine format: {fmt!r} (expected json/table)")
+
+
+def format_batch_result(
+    result: BatchResult,
+    fmt: str,
+    show_failures: bool = False,
+) -> str:
+    """渲染批量执行结果为 ``fmt`` 字符串。
+
+    Args:
+        result: 批量结果
+        fmt: ``json`` 或 ``table``
+        show_failures: table 格式下仅显示失败主机（JSON 始终完整）
+
+    Raises:
+        ValidationError: fmt 不是机器格式
+    """
+    if fmt == "json":
+        return render_batch_json(result)
+    if fmt == "table":
+        return render_batch_table(result, show_failures=show_failures)
+    raise ValidationError(f"unsupported machine format: {fmt!r} (expected json/table)")
+
+
+__all__ = [
+    "FORMAT_CHOICES",
+    "MACHINE_FORMATS",
+    "format_batch_result",
+    "format_single_result",
+]

remote_cmd_manager-2.8.0/remote_cmd/cli/formatters/json.py

@@ -0,0 +1,82 @@
+"""
+JSON 格式化器（稳定 schema，机器友好；v2.8）
+"""
+
+import json
+from typing import Any, Optional
+
+from remote_cmd.core.ssh_client import CommandResult
+from remote_cmd.service._types import BatchResult
+
+
+def _single_payload(
+    host_name: str,
+    command: str,
+    result: CommandResult,
+    duration: Optional[float],
+) -> dict[str, Any]:
+    return {
+        "host": host_name,
+        "command": command,
+        "success": result.success,
+        "exit_code": result.exit_code,
+        "duration": duration,
+        "stdout": result.stdout,
+        "stderr": result.stderr,
+    }
+
+
+def render_single_json(
+    host_name: str,
+    command: str,
+    result: CommandResult,
+    duration: Optional[float] = None,
+) -> str:
+    """渲染单主机结果为 JSON（字段顺序固定，ensure_ascii=False）。"""
+    return json.dumps(
+        _single_payload(host_name, command, result, duration),
+        ensure_ascii=False,
+        indent=2,
+    )
+
+
+def render_batch_json(result: BatchResult) -> str:
+    """渲染批量结果为 JSON。
+
+    schema（稳定）::
+
+        {
+          "total": 3, "success": 2, "failed": 1, "duration": 1.42,
+          "results": {
+            "web1": {"success": true, "exit_code": 0, "duration": 0.1,
+                      "stdout": "...", "stderr": "", "error": null,
+                      "command": "uptime"},
+            ...
+          }
+        }
+
+    ``results`` 按主机名排序，保证与完成顺序无关的确定性输出。
+    """
+    results: dict[str, Any] = {}
+    for host in sorted(result.results):
+        host_result = result.results[host]
+        results[host] = {
+            "success": host_result.success,
+            "exit_code": host_result.exit_code,
+            "duration": host_result.duration,
+            "stdout": host_result.stdout,
+            "stderr": host_result.stderr,
+            "error": host_result.error,
+            "command": host_result.command,
+        }
+    payload = {
+        "total": result.total,
+        "success": result.success,
+        "failed": result.failed,
+        "duration": result.duration,
+        "results": results,
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+__all__ = ["render_batch_json", "render_single_json"]

remote_cmd_manager-2.8.0/remote_cmd/cli/formatters/table.py

@@ -0,0 +1,84 @@
+"""
+Table 格式化器（纯文本对齐，无颜色；v2.8）
+"""
+
+from typing import Optional
+
+from remote_cmd.core.ssh_client import CommandResult
+from remote_cmd.service._types import BatchResult
+
+# 单元格最大宽度（字符）；超出截断并追加省略号
+_MAX_CELL = 60
+_ELLIPSIS = "…"
+
+
+def _shorten(text: str, limit: int = _MAX_CELL) -> str:
+    """单元格内容单行化 + 截断（表格不展开多行输出）。"""
+    first_line = (text or "").splitlines()[0] if text else ""
+    if len(first_line) <= limit:
+        return first_line
+    return first_line[: limit - 1] + _ELLIPSIS
+
+
+def _render_rows(headers: list[str], rows: list[list[str]]) -> str:
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+    lines = ["  ".join(h.ljust(widths[i]) for i, h in enumerate(headers)).rstrip()]
+    for row in rows:
+        lines.append("  ".join(c.ljust(widths[i]) for i, c in enumerate(row)).rstrip())
+    return "\n".join(lines)
+
+
+def render_single_table(
+    host_name: str,
+    command: str,
+    result: CommandResult,
+    duration: Optional[float] = None,
+) -> str:
+    """渲染单主机结果：摘要表 + stdout/stderr 分节。"""
+    duration_text = f"{duration:.2f}s" if duration is not None else "-"
+    summary = _render_rows(
+        ["HOST", "COMMAND", "STATUS", "EXIT", "DURATION"],
+        [[host_name, _shorten(command), "ok" if result.success else "fail", str(result.exit_code), duration_text]],
+    )
+    parts = [summary, "", "--- stdout ---", result.stdout.rstrip("\n"), "", "--- stderr ---", result.stderr.rstrip("\n")]
+    return "\n".join(parts)
+
+
+def render_batch_table(result: BatchResult, show_failures: bool = False) -> str:
+    """渲染批量结果表：HOST/STATUS/EXIT/DURATION/OUTPUT。
+
+    输出列优先展示错误信息（失败主机），否则展示 stdout 首行；
+    ``show_failures=True`` 时仅渲染失败主机。
+    """
+    hosts = sorted(result.results)
+    if show_failures:
+        hosts = [h for h in hosts if not result.results[h].success]
+
+    rows: list[list[str]] = []
+    for host in hosts:
+        r = result.results[host]
+        output = r.error if (r.error and not r.success) else r.stdout
+        rows.append(
+            [
+                host,
+                "ok" if r.success else "fail",
+                str(r.exit_code),
+                f"{r.duration:.2f}s",
+                _shorten(output or ""),
+            ]
+        )
+
+    header = _render_rows(["HOST", "STATUS", "EXIT", "DURATION", "OUTPUT"], rows)
+    summary = (
+        f"Total: {result.total}  Succeeded: {result.success}  "
+        f"Failed: {result.failed}  Duration: {result.duration:.2f}s"
+    )
+    if not rows and not show_failures:
+        return f"{header}\n\nNo hosts.\n{summary}"
+    return f"{header}\n\n{summary}"
+
+
+__all__ = ["render_batch_table", "render_single_table"]