hostctl 0.1.0__tar.gz

hostctl-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+*.egg-info/
+.venv/
+dist/
+build/
+site/
+
+# Private agent working area (dotagents link is a symlink; a directory-only
+# `.agents/` pattern would not match it, so this must stay slashless).
+.agents
+CLAUDE*
+.claude

hostctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-27
+
+First release. Alpha: the public surface is deliberately small (66 exported
+names) and may still change, but everything documented here is covered by the
+test suite on Python 3.9 through 3.14.
+
+### Added
+
+- Protocol-agnostic `Host` contracts with secret-safe `HostConfig` URI
+  dispatch, lifecycle management, normalized host information, and explicit
+  capability reporting.
+- Local, SSH, WinRM, Docker Engine container, and QEMU Guest Agent hosts with
+  buffered command execution and `pathlib_next.Path` filesystem backends where
+  the transport supports them. WinRM includes a Windows-semantic PowerShell
+  path backend; container and QEMU paths use archive and guest-agent file RPCs.
+- Explicit and auto-detected shell dialects (POSIX, Bash, Zsh, Fish, CMD, and
+  PowerShell), shared structured quoting, environment/cwd helpers, operators,
+  and persistent SSH/container sessions with optional terminals.
+- Raw serial and QEMU serial-console transports with validated UART settings,
+  exclusive process leases, stream lifecycle controls, and explicit
+  non-shell semantics until a console profile is supplied.
+- A dependency-free `hostctl` command with run, path inspection/copy,
+  host-info, and interactive shell subcommands; passwords are accepted only
+  from the environment or a hidden prompt.
+- Optional native integrations: AsyncSSH/SFTP, pywinrm, Docker SDK, PySerial,
+  pypsrp, and libvirt QGA, each isolated behind a matching package extra.
+- Cross-host `pathlib_next.Path.copy()`/`PathSyncer` support with streaming
+  remote readers, executor-side checksums, fast stat checksums, and an explicit
+  progress-reader recipe.
+- Transport-independent POSIX, Windows, and IOS host semantics with ordered
+  executor/path provider selection and capability-safe fallback behavior.
+  Providers declare per-operation capabilities, so a read-only backend rejects
+  a mutation explicitly instead of falling through to another provider.
+  Selection traces record the candidates, probe result, chosen provider,
+  generation, policy, and pin, with credential-like values redacted. Composite
+  paths keep their provider collection and optional `.via()` pin through `/`,
+  `joinpath`, `parent`/`parents`, `with_name`/`with_suffix`, `iterdir`,
+  `glob`/`rglob`/`walk`, and open streams. See the "Systems and providers"
+  guide for the no-replay safety rule and provider-authoring contract.
+- Symbolic-link support on every path backend whose transport provides it.
+  `symlink_to(target, target_is_directory=False)` and `readlink()` follow the
+  `pathlib.Path` signatures, `readlink()` reports the stored target verbatim,
+  and `stat(follow_symlinks=...)` stays consistent with `is_symlink()`. Local
+  paths delegate to `os.symlink`, SFTP uses the SSH backend's
+  `symlink`/`readlink`, WinRM issues `New-Item -ItemType SymbolicLink`
+  (normalizing the Windows elevation/Developer-Mode requirement to
+  `PermissionError`), and container paths ship a `SYMTYPE` tar member through
+  `put_archive()`. QGA paths raise `NotImplementedError` because the guest
+  agent exposes no symlink RPC. Container reads now follow a symlink member to
+  its target instead of failing, without giving up streaming laziness.
+- Subprocess-shaped execution options, normalized transport errors, bounded
+  buffered file transfers, and Python 3.9+ typing support (Python 3.14 is the
+  default development interpreter).
+- `Shell` is a context manager: `with host.shell as session:` opens one
+  default session and closes it on exit, the no-argument shorthand for
+  `shell.session()`. Re-entering a shell whose session is still open raises
+  rather than sharing or leaking a process.
+- `Shell` carries defaults. `host.shell(cwd=..., env=..., encoding=...,
+  errors=...)` returns a shell applying them to every later `run`/`session`
+  that omits its own value; `configure(...)` derives a further-configured copy
+  without mutating the original. `cwd`/`encoding`/`errors` are replaced by a
+  per-call value, `env` merges per key so one variable can change without
+  restating the rest, and `env=None` declines the shell's environment while
+  keeping whatever the host itself provides.
+- Connection URIs may carry credentials. `scheme://user:password@host` is
+  accepted: the password is extracted into the credential arguments and
+  stripped from the parsed authority, so it never reaches a field that
+  `connection_uri` or `repr()` renders. `redact_uri()` removes a password and
+  returns a valid, reusable URI rather than masking it, so a rendered form can
+  never round-trip a wrong credential.
+- `parse_credentials()` splits a password field on a newline into the password
+  and trailing `key:value` extras, so an OTP or other second factor travels
+  through a single field. A bare name is a flag equivalent to `name:`. Inside
+  a URI the separator may be written raw — tab, CR, and LF are percent-encoded
+  before parsing, since `urlsplit` deletes them silently. A control character
+  in the *host* is rejected, because deletion there rewrites the target.
+- `ssh_providers()` and `winrm_providers()` return an executor/path provider
+  pair sharing one transport, for composing a transport into a host you
+  assemble yourself. `strict_uri_credentials`, `strict_uri_query`, and
+  `uri_host` are public for configs implementing `_from_parsed_uri`.
+- A `HostConfig` subclass may declare `uri_credentials`; dispatch then rejects
+  any other credential before construction, so a typo fails loudly instead of
+  silently producing a config with no password.
+- SSH execution now sends EOF for omitted stdin, rejects unsupported zero
+  buffering, normalizes missing exit statuses to `-1`, performs best-effort
+  timeout cleanup (with `TimeoutExpired.orphaned`), and normalizes persistent
+  process I/O failures. SFTP backends are reused per host and invalidated on
+  close; auto-dialect probes preserve the discovered shell executable.
+- Container archive paths now accept normal absolute and relative symlink
+  targets, resolve links with a bounded hop count, preserve hardlink/file
+  semantics, use Docker's header stat metadata where available, and reject
+  traversal names without buffering directory archives unnecessarily. Docker
+  exec streams return available data promptly, detect truncated frames,
+  preserve merged output ordering, and map missing containers to
+  `ConnectionError`.
+- QEMU Guest Agent transports now share one framed-session implementation with
+  split-read buffering, parse-error correlation, safe timeout/disconnect
+  cleanup, and loop-bound SSH writes. QEMU serial consoles and raw serial
+  processes use incremental text decoding and the common `read(-1)` contract
+  (up to 64 KiB available data); serial ownership and QEMU URI/lifecycle edge
+  cases are normalized consistently.
+
+### Fixed
+
+- `run(input=<bytes>, encoding=...)` no longer hangs. Handing bytes to a
+  text-mode `subprocess` stdin killed its writer thread, and the call then
+  blocked forever because the child never saw EOF — `timeout=` did not fire.
+  `input` is now normalized to the stream mode each executor uses, by a helper
+  the local, SSH, and QGA executors share, so the same call behaves
+  identically whichever provider a `SystemHost` selects.
+- Composite host paths kept their provider, selector, and pin through
+  `pathlib.PurePath` derivations (`parents`, `with_name`, `with_suffix`,
+  `relative_to`). Those results were previously built without any routing
+  state, which made `glob()`, `rglob()`, and `walk()` fail outright.
+- A path provider that declined before dispatch is remembered for the
+  connection generation instead of being re-attempted by every later
+  operation; `invalidate()` clears the record along with cached probes.
+- `SystemHost` serializes its connection bookkeeping under a reentrant lock.
+  Concurrent `run()` calls previously raced the check-then-append in
+  `_ensure_provider_connected`, so every caller repeated the connect
+  round-trip and appended a duplicate entry to `_connected_providers`, which
+  grew without bound. Provider membership is now tested by identity.
+- Capability vocabularies agree. `ExecutorCapability` members subclass `str`,
+  so the enum published by executors and the strings published by providers
+  and hosts compare equal. `Shell` previously tested `ExecutorCapability.CWD`
+  against a set of strings — always false — so a host with native `cwd`/`env`
+  still had `cd`/`export` rendered into the script and the native values
+  dropped.
+- `SystemConfig` no longer fails with `AttributeError`. It is explicitly
+  abstract: `_create_host()` raises `TypeError` naming the concrete
+  configurations, and it no longer advertises a `system://` URI that
+  `HostConfig` rejected as an unsupported scheme.
+- `scheme` is a URI-derived property across the whole `HostConfig` hierarchy.
+  The system configurations shadowed it with a plain string and `SystemHost`
+  assigned to it; a config-less host now builds its own family configuration
+  instead.
+
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/hostctl/releases/tag/v0.1.0

hostctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hostctl-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: hostctl
+Version: 0.1.0
+Summary: Run commands and access files on a host, local or remote, protocol-agnostic
+Project-URL: Homepage, https://github.com/jose-pr/hostctl/
+Project-URL: Documentation, https://jose-pr.github.io/hostctl/
+Project-URL: Issues, https://github.com/jose-pr/hostctl/issues
+Author: Jose A.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: pathlib,remote,ssh,subprocess,sysadmin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pathlib-next<0.9,>=0.8.6
+Provides-Extra: container
+Requires-Dist: docker<8,>=7.1; extra == 'container'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: psrp
+Requires-Dist: pypsrp<1,>=0.9; (python_version >= '3.10') and extra == 'psrp'
+Provides-Extra: qemu-libvirt
+Requires-Dist: libvirt-python; extra == 'qemu-libvirt'
+Provides-Extra: serial
+Requires-Dist: pyserial<4,>=3.5; extra == 'serial'
+Provides-Extra: ssh
+Requires-Dist: asyncssh; extra == 'ssh'
+Requires-Dist: pathlib-next[sftp-async]<0.9,>=0.8.4; extra == 'ssh'
+Provides-Extra: winrm
+Requires-Dist: pywinrm<0.6,>=0.5.0; extra == 'winrm'
+Provides-Extra: winrm-credssp
+Requires-Dist: pywinrm[credssp]<0.6,>=0.5.0; extra == 'winrm-credssp'
+Provides-Extra: winrm-kerberos
+Requires-Dist: pywinrm[kerberos]<0.6,>=0.5.0; extra == 'winrm-kerberos'
+Description-Content-Type: text/markdown
+
+[![Version](https://img.shields.io/pypi/v/hostctl.svg)](https://pypi.org/project/hostctl/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/hostctl/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/hostctl/release.yml?label=release%20gate)](https://github.com/jose-pr/hostctl/actions/workflows/release.yml)
+
+A **protocol-agnostic way to run commands and access files on a host**.
+`Host` defines operations; `HostConfig` owns secret-safe connection identity,
+extensible URI dispatch, and lifecycle. Local and application hosts can compose
+SSH, WinRM, serial, container, and QEMU providers while exposing only the
+capabilities those providers actually support.
+
+## Features
+
+- **`Host.run(...)`** — subprocess-compatible results from local shells,
+  SSH (`asyncssh`), or PowerShell over WinRM (`pywinrm`). Unsupported transport
+  options raise `NotImplementedError`.
+- **`Host.path(...)`** — a `pathlib_next.Path` filesystem view: local,
+  remote SFTP, Windows over WinRM, container archives, or QEMU Guest Agent.
+- **Cross-host copy and sync** — use `Path.copy()`/`PathSyncer` directly;
+  `host_checksum()` computes unchanged-file digests beside remote data.
+- **`with host.shell as session:`** — a persistent shell over SSH or a
+  container, closed on exit; `host.shell.session(...)` takes a starting
+  command, TTY, `cwd`, `env`, or encoding. `send(*cmds)` uses the same
+  structured quoting rules.
+- **Serial console hosts.** `SerialConfig` accepts opaque native/PySerial URLs;
+  raw profiles provide exclusive sessions, while an explicitly configured
+  prompt profile can add safely framed `run()` results. Serial consoles never
+  imply a filesystem or PTY and RFC 2217 has no encryption.
+- **Explicit or detected SSH shells.** Use a concrete dialect for deterministic
+  behavior or `dialect="auto"` for positive POSIX/Windows probing.
+- **Extensible shell languages.** Select a registered string, a
+  `ShellFlavour` subclass, or a configured flavour instance.
+- **Extension point, not a closed abstraction.** Override `Host.path()` in a
+  subclass to add a project-specific backend (see `docs/guide/extending.md`).
+
+## Installation
+
+```bash
+pip install hostctl
+```
+
+Optional features/extras:
+
+| Extra/flag | Adds | Needed for |
+| --- | --- | --- |
+| `ssh` | `asyncssh`, `pathlib_next[sftp-async]` | `run()`/`path()` over SSH |
+| `winrm` | `pywinrm` | PowerShell `run()` over WinRM |
+| `psrp` | `pypsrp` on Python 3.10+ | persistent typed PowerShell runspaces |
+| `container` | Docker SDK for Python | Docker Engine `run()`/`path()`/sessions |
+| `serial` | PySerial | raw native/RFC 2217/socket serial sessions |
+| `qemu-libvirt` | libvirt Python bindings | local libvirt QGA transport |
+
+## Quick start
+
+```python
+from hostctl import (
+    Host,
+    HostConfig,
+    ContainerConfig,
+    QemuConfig,
+    LocalConfig,
+    POWERSHELL,
+    SshConfig,
+    WinRMConfig,
+)
+from pathlib_next import WindowsPathname
+
+# Local
+with LocalConfig() as host:
+    result = host.run("echo hello")
+    print(result.stdout)
+
+# SSH to a POSIX target (needs the `ssh` extra)
+with SshConfig(host="nas.example.com", username="admin", password="secret") as host:
+    result = host.run("df -h")
+    for line in host.path("/etc").iterdir():
+        print(line)
+
+# SSH to Windows is explicit, not inferred from the transport.
+windows_ssh = SshConfig(
+    host="windows.example.com",
+    username="admin",
+    password="secret",
+    dialect=POWERSHELL,
+    path_flavor=WindowsPathname,
+)
+
+# WinRM supports PowerShell execution and Windows filesystem paths.
+with WinRMConfig("windows.example.com", "admin", "secret", ssl=True) as windows:
+    windows.run(["Write-Output", "hello"])
+    windows.path(r"C:\Temp\hello.txt").write_text("hello", encoding="utf-8")
+
+# An existing running container (needs the `container` extra).
+with ContainerConfig("application") as container:
+    container.run(["printf", "%s\n", "hello"])
+    print(container.path("/etc/os-release").read_text())
+    with container.shell.session(terminal=True, encoding="utf-8") as session:
+        session.send(["printf", "%s\n", "hello from the session"])
+        print(session.read())
+
+# A QEMU guest through its QGA Unix socket tunneled over SSH.
+with QemuConfig(
+    "vm-id",
+    transport="ssh",
+    ssh=SshConfig("hypervisor.example", username="root"),
+) as guest:
+    print(guest.info())
+    print(guest.run(["echo", "hello"], encoding="utf-8").stdout)
+    print(guest.path("/etc/os-release").read_text())
+
+# A canonical connection URI carries configuration, never a password.
+with Host(windows_ssh.connection_uri, password="secret") as same_host:
+    same_host.run(["Write-Output", "hello"])
+
+# A `user:password@host` URI is still valid input: the password is extracted
+# and used, and never rendered back out. Use `redact_uri` to display one.
+with Host("ssh://admin:secret@nas.example.com") as same_host:
+    same_host.run("uptime")
+```
+
+A URI may carry `user:password@host` on the way *in* — it is a valid URI, so
+hostctl accepts it, extracts the password into the credentials, and keeps it
+out of every rendered form. Passing the same password both in the URI and as an
+argument is an error rather than a silent precedence rule. `redact_uri(uri)`
+strips the password and returns a valid, reusable URI — it is removed rather
+than masked, so a rendered form can never round-trip a wrong credential.
+
+Shell `env` defaults merge per key; `env=None` declines them, leaving whatever
+environment the host itself provides.
+
+A password field may also carry extra credentials, one per line after it:
+`parse_credentials("hunter2\notp:123456")` yields `("hunter2", {"otp":
+"123456"})`. A bare name is a flag meaning the same as `name:`. This lets an
+OTP or other second factor reach a transport through a single field — a URI's
+userinfo, an environment variable, a prompt — without each caller inventing an
+encoding. Inside a URI the separator may be written raw — hostctl encodes it
+before parsing, since `urlsplit` would otherwise delete it and silently merge
+the extras into the password. A control character in the *host* is still
+rejected: no encoding makes a hostname containing one meaningful, and allowing
+it would let a URI that reads as one target resolve to another.
+
+`str(config)` is the same canonical, secret-free connection string as
+`config.connection_uri`. `HostConfig(str(config), **secrets)` reconstructs the
+concrete configuration without creating or connecting a host.
+
+Install `hostctl[winrm-kerberos]` or `hostctl[winrm-credssp]` when selecting
+those WinRM authentication transports. Certificate authentication is not
+exposed until its required certificate/key configuration is part of the API.
+
+### Composable system hosts
+
+Use `PosixHost`, `WindowsHost`, or `IosHost` when system semantics should be
+independent of the transport. Providers are tried in declaration order during
+preflight; a provider may be retried only when it raises
+`OperationNotStarted`, which guarantees that no remote operation was sent.
+Paths retain their selected provider and expose it through `.provider` and
+`.via(name)`:
+
+```python
+from hostctl import ExecutorProvider, PathProvider, PosixHost, LocalExecutor, HostPath
+
+host = PosixHost(
+    executor_providers=(ExecutorProvider("ssh", ssh_executor),
+                        ExecutorProvider("local", LocalExecutor())),
+    path_providers=(PathProvider("sftp", sftp_path),
+                    PathProvider("rpc", lambda *p: HostPath(*p))),
+)
+path = host.path("etc", "hosts")
+print(path.provider.name)
+```
+
+Application-specific adapters can follow the SFTP/RPC/download pattern in
+[`examples/application_provider.py`](examples/application_provider.py). The
+[Systems and providers](https://jose-pr.github.io/hostctl/guide/providers/)
+guide covers selection traces, backend pinning, per-operation capabilities,
+provider authoring, and the no-replay safety rule in full.
+
+Existing transport URIs remain compatible.  To opt into system semantics while
+retaining those URI/configuration objects, compose them explicitly:
+
+```python
+from hostctl import PosixHost, SshConfig, WindowsHost, WinRMConfig
+
+posix = PosixHost.from_ssh(SshConfig("server.example", username="root"))
+windows = WindowsHost.from_winrm(WinRMConfig("server.example", "admin"))
+```
+
+SSH and WinRM transport implementations are private providers; QEMU's SSH
+tunnel continues to consume `SshConfig` directly.
+
+## Command line
+
+The installed `hostctl` command is a thin wrapper over the library:
+
+```console
+hostctl run local: -- python -c "print('hello')"
+hostctl info ssh://server
+hostctl cp ./artifact ssh://server:/tmp/artifact
+```
+
+Secrets never belong in argv. Use `HOSTCTL_PASSWORD` or the subcommand's
+`--ask-password` option. See the
+[CLI guide](https://jose-pr.github.io/hostctl/guide/cli/) for all subcommands
+and exit statuses.
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `hostctl.host` | Shared contracts and built-in host providers |
+| `hostctl.host.container` | `ContainerConfig`, `ContainerHost` |
+| `hostctl.host.qemu` | `QemuConfig`, `QemuHost` |
+| `hostctl.host.serial` | `SerialConfig`, `SerialHost` |
+| `hostctl.provider` | Ordered executor/path provider composition |
+| `hostctl.executor` | Transport-specific command executors |
+| `hostctl.shell` | Shell flavours and persistent sessions |
+| `hostctl.sync` | Remote checksum and byte-progress helpers for `pathlib_next` |
+| `hostctl._cli` | Dependency-free command-line entry point |
+
+## Development
+
+```bash
+py -3.14 -m venv .venv/3.14-nt-amd64
+.venv/3.14-nt-amd64/Scripts/python -m pip install -e ".[dev,ssh,winrm,container,serial]"
+.venv/3.14-nt-amd64/Scripts/python -m pytest -q
+```
+
+Python 3.14 is the default development interpreter. Python 3.9 remains the
+supported compatibility floor and should be selected explicitly with
+`py -3.9` when running floor-specific checks.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build → publish → docs deploy.
+
+To prepare a release, update `pyproject.toml` and move the complete
+`[Unreleased]` section to `## [X.Y.Z] - YYYY-MM-DD` in the same commit. Keep
+the package version PEP 440-compatible and use the corresponding SemVer tag
+(`vX.Y.Z`, or `vX.Y.Z-rc.N` for a prerelease). Then push the commit and tag;
+the workflow extracts that changelog section for the GitHub release and
+publishes the built artifacts. Leave a fresh empty `[Unreleased]` section for
+the next cycle.
+
+## License
+
+MIT — see [LICENSE](LICENSE).