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

{remote_cmd_manager-2.7.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.7.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,36 +89,37 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.7.0 Release Highlights
+## v2.8.0 Release Highlights
 
-v2.7.0 is a runtime-efficiency and error-semantics release: credential-layer
-exceptions are narrowed so real bugs surface, SQLite no longer truncates its WAL
-on every write, and the global connection budget waits on a true async queue
-instead of polling. Public APIs remain backward compatible. See the
+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).
 
-### Error Semantics
+### Connection Profiles
 
-- Keyring, encryption, and host-service decrypt paths now catch only expected failure classes; programming errors propagate instead of being silently swallowed.
-- Background pool monitor loops keep their catch-all guard but log full stack traces.
-- Optional `asyncssh` detection uses `find_spec`, so a defect in the async modules themselves can no longer masquerade as "dependency not installed".
+- 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.
 
-### SQLite WAL Efficiency
+### Machine-Readable Output
 
-- `flush()` now runs a **PASSIVE** checkpoint instead of `TRUNCATE` — no more writer waits or WAL rewrites on every host add/update/remove.
-- New explicit `repo.checkpoint("TRUNCATE")` (also `PASSIVE`/`FULL`/`RESTART`) for deliberate WAL compaction.
+- `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.
 
-### Connection Budget
+### Try It
 
-- `ConnectionBudget.acquire_async()` now waits on a real queue (`asyncio.Future` woken via `call_soon_threadsafe`), removing the v2.6 polling loop; cancellation-safe and FIFO among async waiters.
-
-### Benchmark Data (P2.4)
-
-- The sync Paramiko path costs ~100 µs per command in thread create/join and peaks at ≈ 3× sustained concurrency in live threads. A centralized channel-reader rewrite is a v2.7.x decision based on these measurements.
+```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.7.0 Release Highlights](#v270-release-highlights)
+- [v2.8.0 Release Highlights](#v280-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -265,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.7.0 → remote_cmd_manager-2.8.0}/README.md

@@ -36,36 +36,37 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.7.0 Release Highlights
+## v2.8.0 Release Highlights
 
-v2.7.0 is a runtime-efficiency and error-semantics release: credential-layer
-exceptions are narrowed so real bugs surface, SQLite no longer truncates its WAL
-on every write, and the global connection budget waits on a true async queue
-instead of polling. Public APIs remain backward compatible. See the
+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).
 
-### Error Semantics
+### Connection Profiles
 
-- Keyring, encryption, and host-service decrypt paths now catch only expected failure classes; programming errors propagate instead of being silently swallowed.
-- Background pool monitor loops keep their catch-all guard but log full stack traces.
-- Optional `asyncssh` detection uses `find_spec`, so a defect in the async modules themselves can no longer masquerade as "dependency not installed".
+- 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.
 
-### SQLite WAL Efficiency
+### Machine-Readable Output
 
-- `flush()` now runs a **PASSIVE** checkpoint instead of `TRUNCATE` — no more writer waits or WAL rewrites on every host add/update/remove.
-- New explicit `repo.checkpoint("TRUNCATE")` (also `PASSIVE`/`FULL`/`RESTART`) for deliberate WAL compaction.
+- `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.
 
-### Connection Budget
+### Try It
 
-- `ConnectionBudget.acquire_async()` now waits on a real queue (`asyncio.Future` woken via `call_soon_threadsafe`), removing the v2.6 polling loop; cancellation-safe and FIFO among async waiters.
-
-### Benchmark Data (P2.4)
-
-- The sync Paramiko path costs ~100 µs per command in thread create/join and peaks at ≈ 3× sustained concurrency in live threads. A centralized channel-reader rewrite is a v2.7.x decision based on these measurements.
+```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.7.0 Release Highlights](#v270-release-highlights)
+- [v2.8.0 Release Highlights](#v280-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -212,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.7.0 → remote_cmd_manager-2.8.0}/pyproject.toml

@@ -124,6 +124,8 @@ ignore = [
 "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.7.0 → remote_cmd_manager-2.8.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.7.0（单一真相源见 remote_cmd._version）
+Version: 2.8.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -78,6 +78,7 @@ if _HAS_ASYNC:
 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
 
@@ -105,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
@@ -124,11 +126,13 @@ if _HAS_ASYNC:
         "AsyncConnectionPool",
         "AsyncBatchExecutor",
         "Host",
+        "HostProfile",
         "HostManager",
         # 新架构导出
         "HostRepository",
         "JsonHostRepository",
         "HostService",
+        "ProfileService",
         "SSHService",
         "CredentialProvider",
         "EnvCredentialProvider",
@@ -161,11 +165,13 @@ else:
         # 原有导出（向后兼容，不含异步符号）
         "SSHClient",
         "Host",
+        "HostProfile",
         "HostManager",
         # 新架构导出
         "HostRepository",
         "JsonHostRepository",
         "HostService",
+        "ProfileService",
         "SSHService",
         "CredentialProvider",
         "EnvCredentialProvider",

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

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.7.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"]