hostctl 0.1.0__py3-none-any.whl

hostctl/AGENTS.md

@@ -0,0 +1,292 @@
+# hostctl — API header
+
+Protocol-independent host execution and filesystem paths. Core requires
+`pathlib_next`; transport integrations are optional extras.
+
+The dependency-free CLI entry point is `hostctl._cli:main`. Commands are
+`run`, `ls`, `cat`, `cp`, `info`, and `shell`; passwords come only from
+`HOSTCTL_PASSWORD` or `--ask-password`, never argv values.
+
+`hostctl.__all__` is the stable surface: hosts and configs you construct,
+exceptions you catch, types you annotate with, and the provider/shell contracts
+you implement. Concrete backends, transport adapters, and objects the library
+only hands back (`QgaPathBackend`, `WinRMPathBackend`, `ContainerPathBackend`,
+the `Posix*`/`Windows*` path classes, the concrete `*Executor`s, `*Process`
+classes, and `hostctl.provider.transports`) stay importable from their defining
+module but are **not** exported from `hostctl` and may change without notice.
+
+Host implementations are grouped under `hostctl.host`: shared contracts are
+re-exported from the package, with concrete implementations in private
+modules (`hostctl.host._local`, `._ssh`, and `._winrm`) plus the other provider
+modules. WinRM paths live with `_winrm`; QGA paths live with `qemu`.
+The private `hostctl.executor._qga` module owns QGA framing and its Unix,
+libvirt, and SSH transports; it is consumed by the QEMU executor and host.
+Shell construction is transport-independent under `hostctl.shell`:
+`_common.py` owns shared contracts, while `posix.py` and `powershell.py` own
+their concrete flavours. Executor code follows the same layout under
+`hostctl.executor`: `_common.py` owns contracts and option types; `ssh.py` and
+`winrm.py` own `SshExecutor` and `WinRMExecutor`. Each package re-exports its
+own contracts; only the stable subset above reaches top-level `hostctl`.
+`hostctl.sync` adds `stat_checksum(entry)`, `host_checksum(*hosts,
+algorithm="md5", chunk_size=1048576)`, and `ProgressReader`; these plug into
+`pathlib_next.utils.sync.PathSyncer` and the existing path copy machinery.
+
+`SystemHost`, `PosixHost`, and `WindowsHost` compose ordered executor/path
+providers. `PosixHost.from_ssh(SshConfig(...))` and
+`WindowsHost.from_winrm(WinRMConfig(...))` retain the original connection URI
+and lifecycle while exposing transport operations through provider adapters;
+transport implementations remain private.
+`register_system_provider(name, resolver)` extends logical system URI
+descriptors. Built-ins include `local`, `ssh`, `sftp`, and `winrm`; transport
+descriptors require matching objects in `SystemConfig(provider_options=...)` and
+never serialize credentials into the canonical URI.
+
+`Executor(command, *, stdin=None, stdout=None, stderr=None, cwd=None, env=None,
+capture_output=None, check=None, encoding=None, errors=None, input=None,
+timeout=None, text=None, **options)` defines the shared shell-agnostic option
+surface. `ExecutionOptions` is the corresponding total-false `TypedDict`;
+executor-specific extensions remain keyword options.
+`ExecutorCommand` is `str | pathlib.PurePath | pathlib_next.Pathname`; paths
+remain path objects until the concrete executor converts them for transport.
+`ExecutorCapability.ARGS`, `.CWD`, and `.ENV` declare native executor support.
+`Shell.execute(path, *args)` preserves path/args for an `ARGS` executor;
+otherwise the flavour safely renders them into one script. `cwd` and `env`
+follow the same native-or-embed rule.
+`Shell`, `SshExecutor`, and `WinRMExecutor` inherit the `Executor` protocol so
+shared protocol implementations can be added once; `Shell.__call__` delegates
+to `Shell.execute()`.
+`Host` itself supplies the multi-command `run()` provider contract; there is no
+duplicate host-executor protocol or unused host-options wrapper.
+`Shell.execute(path_like)` preserves the path, while string input remains a
+string. Executors and hosts distinguish direct commands from shell scripts by
+that value type; no duplicate command-kind flag is carried.
+
+## Configuration and lifecycle
+
+- `Host(connection_string, **secrets) -> Host` dispatches a secret-safe URI
+  through config implementations and the `hostctl.configs` entry-point group.
+- `HostConfig(connection_string, **secrets) -> HostConfig` performs the same
+  dispatch without creating a host. `str(config)` is its canonical,
+  secret-free connection string and can be passed back to `HostConfig`.
+- A `scheme://user:password@host` URI is valid *input*: 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. Supplying a password both in the URI and as an argument raises.
+  `redact_uri(uri)` STRIPS a password and returns a valid, reusable URI (not a
+  masked one, so a rendered form can never round-trip a wrong credential), for
+  logs, reprs, and error messages.
+- A connection URI may carry a raw tab, CR, or LF in its **userinfo**: those
+  are percent-encoded before `urlsplit` sees them, which would otherwise
+  delete them silently (`ssh://u:pw<LF>otp:1@host` would authenticate with
+  `pwotp:1`). So the credential-extras separator can be written naturally.
+  A control character in the **host** is REJECTED -- deletion there rewrites
+  the target (`ssh://host<LF>.other.example/` would resolve to
+  `host.other.example`), and no encoding makes it meaningful.
+  `redact_uri` never raises on either -- it is for diagnostics.
+- `parse_credentials(password) -> (password, extras)` splits a password field
+  on a newline: the first line is the password, each later line is a
+  credential extra. `name:value` sets a value, a bare `name` is a flag
+  equivalent to `name:` (empty string). Names are casefolded and stripped,
+  values keep everything after the first `:`, blank lines are ignored, and
+  CRLF is handled. URI dispatch runs the password field through it, so an OTP
+  or other second factor travels in the same field; an extra a config does not
+  declare is rejected by name rather than dropped.
+- `config.connection_uri` never includes passwords or private keys;
+  `config.scheme` matches its URI scheme.
+- `with config as host:` and `with config.open() as host:` connect and always
+  close. Re-entering the same active config raises `RuntimeError`.
+- External config implementations declare `schemes=(...)`; registry hooks and
+  caches are protected implementation details.
+
+`LocalConfig`, `SshConfig`, `WinRMConfig`, and `ContainerConfig` produce their
+corresponding hosts.
+
+## Shell contract
+
+- `Shell(flavour, executor)` binds a `ShellFlavour` to either a command
+  callable or an object exposing `run(command, **options)`. The command is
+  always one string. If its inspected signature accepts `cwd` and/or `env`,
+  `Shell.run()` forwards those separately; otherwise the flavour embeds that
+  context into the script. Shell-agnostic subprocess options (`stdin`,
+  `stdout`, `stderr`, `capture_output`, `check`, `encoding`, `errors`, `input`,
+  `timeout`, `text`) pass through only to the executor. `Shell.execute(command)`
+  passes strings unchanged and converts path-like commands with `str(path)`.
+- `ShellFlavour.script(cmds, *, cwd=None, env=None) -> str` constructs a script
+  in one target shell language.
+- `ShellFlavour.environment_script(env) -> str` is a reusable standalone
+  environment-mapping renderer. The base normalizes/validates variable names
+  and joins each flavour's `environment_assignment(key, value)` output.
+  Values remain objects so a flavour can preserve meaningful types; built-ins
+  decode bytes and stringify ordinary values.
+- `ShellOperator.PIPE`, `.AND`, `.OR`, `.REDIRECT`, `.APPEND`, and `.SEQUENCE`
+  are explicit infix tokens between top-level commands. Flavours own their
+  spelling and may reject operators they cannot represent portably.
+- Raw strings stay verbatim; tuple/list commands quote each item as data;
+  standalone and structured paths are quoted; top-level commands otherwise
+  use the flavour's `command_separator`.
+- `ShellFlavour.command(cmds, *, executable=None, cwd=None, env=None) ->
+  ShellCommand` wraps that script for an SSH exec channel.
+- Structured values are normalized through the base class (including bytes and
+  iterable argv sequences); empty structured commands and control characters
+  are rejected. Raw empty command strings are skipped when joining.
+- Environment assignments embedded by a shell are additive to the inherited
+  remote environment. This intentionally differs from local
+  `subprocess.run(env=...)`, which replaces the environment; a clear-env mode
+  remains a separate future contract.
+- `POSIX_SHELL` and `POWERSHELL` are the built-in strategies;
+  common built-ins also include `BASH`, `ZSH`, `FISH`, `CMD`, and PowerShell 7
+  `PWSH`. PowerShell 5 rejects `AND`/`OR`; PowerShell 7 supports them.
+- `shell_flavour(selection)` accepts a registered string, configured
+  `ShellFlavour` instance, or no-argument `ShellFlavour` subclass.
+  `register_shell_flavour()` adds application-defined string selections.
+- `ShellCommand.command` is transport-ready text; `.environment` is the
+  environment sent out of band, or `None` when embedded into the script.
+- `Shell(flavour, executor, cwd=None, env=None, encoding=None, errors=None)`
+  accepts defaults applied to every `run`/`session` call that omits them.
+  `host.shell(cwd=..., env=...)` returns such a shell; bare `host.shell` has
+  none. `cwd`/`encoding`/`errors` are replaced by a per-call value, `env`
+  merges per key, and `Shell.configure(...)` returns a configured copy without
+  mutating the original.
+- A custom `HostConfig` should declare `uri_credentials = ("password", ...)`.
+  Dispatch then rejects any other credential BEFORE construction, so a typo
+  (`passwrd=`) fails loudly instead of silently building a config with no
+  password. `None` (default) skips the check for configs that validate
+  themselves. `strict_uri_credentials`, `strict_uri_query`, and `uri_host`
+  are public for configs writing `_from_parsed_uri` by hand.
+- `ssh_providers(SshConfig)` and `winrm_providers(WinRMConfig)` return an
+  `(executor_provider, path_provider)` pair sharing ONE transport, for
+  composing a transport into a host you assemble yourself rather than taking
+  the finished host `_create_host()` builds. They return a pair instead of
+  exposing the transport because both providers must share it -- building them
+  separately silently opens two connections, only one of which is closed.
+- `input=` is normalized to the stream mode every executor is about to use, by
+  `executor/_common.normalize_input`. Under a text mode (`encoding`/`errors`/
+  `text`) bytes are decoded; under a binary mode str is encoded. This is not
+  cosmetic: handing bytes to a text-mode `subprocess` stdin kills its writer
+  thread, and the call then blocks forever because the child never sees EOF --
+  `timeout=` does not fire. All executors share the helper so the same call
+  behaves identically whichever provider a `SystemHost` selects.
+- `env` on `run`/`session`/`configure` accepts `EnvironmentSelection`: a
+  mapping merges over the shell's default per key, the default empty mapping
+  merges nothing and inherits it, and `None` runs without the shell's
+  configured environment -- keeping whatever the host provides on its own,
+  since nothing is sent to override it. `None` does NOT mean an empty
+  environment. Declining `env` does not affect `cwd`.
+- `Shell.session(*cmds, terminal=False, cwd=None, env=None, ...) -> ShellSession`
+  opens a persistent provider process. `Shell` is also a context manager:
+  `with host.shell as session:` opens a default session and closes it on exit,
+  which is the no-argument shorthand for `with host.shell.session() as ...`.
+  Re-entering a shell whose session is still open raises `RuntimeError`.
+  `ShellSession.send(*cmds, cwd=None,
+  env=None)` uses the same command grammar, writes the flavour terminator and
+  a line terminator, and mutates the live shell context. This newline is
+  required for interactive shells to submit each command.
+  TTY stderr is merged into stdout.
+
+## Host contract
+
+- `Host` is abstract. Base `run()` and `path()` raise `NotImplementedError`.
+- Hosts expose delegated `scheme`/`connection_uri`, explicit `capabilities`,
+  `info() -> HostInfo`, and `connect()`/`close()` plus context management.
+- `host.shell_flavour` is the explicitly known target-shell strategy;
+  `host.shell` builds `Shell(host.shell_flavour, host)`. SSH uses its configured
+  or positively detected flavour, WinRM uses PowerShell, and local execution
+  selects POSIX sh or Windows PowerShell from the local platform.
+- SSH provider run renders through its shell flavour and delegates the finalized
+  command to `SshExecutor`; WinRM provider run delegates its finalized
+  PowerShell script to `WinRMExecutor`.
+- `HostInfo` fields are optional; unknown system values remain `None`.
+- A usable `path()` returns `HostPath` (`pathlib_next.Path`).
+- A usable `run()` returns `subprocess.CompletedProcess`; `check=True` raises
+  `subprocess.CalledProcessError`, and command timeouts raise
+  `subprocess.TimeoutExpired`.
+- `Host.spawn()` is the low-level persistent `Process` contract. Providers
+  advertise `spawn` and `tty` separately.
+
+## SSH
+
+`SshConfig(host, port=22, username="root", password=None, client_keys=None,
+executable=None, known_hosts=(), dialect=POSIX_SHELL,
+path_flavor=pathlib_next.PosixPathname)`.
+
+Authentication fields are explicit and excluded from repr. `dialect` selects
+POSIX or PowerShell command construction independently of the POSIX/Windows
+SFTP path flavor. `dialect` is a `ShellFlavour` strategy. `path_flavor` is a concrete
+`pathlib_next.Pathname` or `pathlib.PurePath` subclass; bare `PurePath` is
+rejected because it would infer the local OS. SSH implies neither an OS nor a
+shell. `dialect="auto"` performs positive cached probing and raises rather than
+guessing. The SSH executor provider closes its AsyncSSH connection and waits for closure.
+AsyncSSH authentication failures are exposed as `PermissionError`; SSH
+host-key, key-exchange, disconnect, connection-loss, protocol, and channel
+failures are exposed as `ConnectionError`. The original AsyncSSH exception is
+retained as `__cause__`.
+The SFTP path provider reuses one `AsyncsshSftpBackend` per host and invalidates its
+cached sources during `close()`; each path call does not create another SFTP
+connection. Provider close performs all AsyncSSH operations through the
+shared bridge. Omitted `run()` stdin is an explicit EOF stream, `bufsize=0` is
+rejected, and a missing remote exit status is reported as return code `-1`.
+Timeouts raise `subprocess.TimeoutExpired` with an `orphaned` flag indicating
+whether a process/channel termination hook was available. `dialect="auto"`
+retains the executable path reported by the successful probe. Persistent SSH
+process reads, writes, EOF, and close operations use the same transport-error
+normalization as `wait()`.
+
+## Containers
+
+`ContainerConfig(container, engine_url=None, user=None, workdir=None,
+executable=None, dialect="auto", path_flavor="auto")` uses the optional
+`container` extra and Docker Engine API. Inspection selects Linux/POSIX or
+Windows/PowerShell semantics. `ContainerHost` supports buffered exec,
+persistent sessions/TTYs, and archive-backed POSIX or Windows paths. Archive
+paths support stat/traversal/read/write/append/exclusive-create; archive-only
+mkdir/remove/rename/chmod raise `NotImplementedError`.
+
+## QEMU Guest Agent
+
+`QemuConfig(domain, transport="libvirt", connection=None, socket_path=None,
+ssh=None, agent_timeout=10, dialect="auto", path_flavor="auto")` creates a
+`QemuHost`. Transports are local libvirt (`qemu-libvirt` extra), direct Unix
+socket, or an AsyncSSH-tunneled remote Unix socket. Discovery positively probes
+QGA and its enabled command list.
+
+`QemuExecutor` uses buffered `guest-exec`/`guest-exec-status`. QGA cannot cancel
+timed-out processes; `TimeoutExpired.orphaned` is true and `.pid` is retained
+when known. `QgaPathBackend` uses bounded file-handle RPCs; metadata/mutations
+without a positively available helper raise `NotImplementedError`.
+An injected `QemuSerialConsole` adds the `serial` capability and
+`QemuHost.open_serial()`. It is raw, exclusive, and makes no shell/status claim.
+
+## WinRM
+
+`WinRMConfig(host, username, password=None, transport="ntlm", port=None,
+ssl=False, server_cert_validation="validate", message_encryption="auto",
+operation_timeout_sec=20, read_timeout_sec=30, provider="auto")`. `auto`
+selects PSRP when `hostctl[psrp]` is installed on Python 3.10+, otherwise
+pywinrm; `provider="psrp"` requires the extra.
+
+The WinRM executor provider supports PowerShell `run()` and Windows-semantic `WinRMPath`.
+Password-free configs on Windows use current-context native PowerShell
+remoting; explicit credentials use pywinrm. `WinRMPath.open("rb")` fetches
+bounded ranges; writable modes stage content and transfer Base64 chunks on
+close. WinRM stdin and command
+deadlines remain unsupported. Transport timeouts are not a total command
+deadline. pywinrm Session has no guaranteed close API; hostctl calls `close()`
+only when a provided session exposes it.
+PSRP runspaces are exposed separately through the WinRM transport provider and
+`RunspaceSession.invoke()`. They retain typed PowerShell streams and state, and
+are not advertised as a byte-oriented `spawn`/TTY process.
+
+## Local and utilities
+
+`LocalHost.path()` and `LocalHost.run()` work on POSIX and Windows.
+`LocalExecutor` provides native argv, cwd, environment, stream, encoding,
+check, and timeout behavior through `subprocess.run`.
+
+`SerialConfig`/`SerialHost` provide an opaque `serial:///...` URI and one
+exclusive byte-stream lease. `RawConsoleProfile` supports sessions only;
+`PromptConsoleProfile` adds bounded login/prompt framing and advertises
+`run` only when `reliable_status=True` and a completion marker is configured.
+Streams are merged, PTY/path/status semantics are absent unless the profile
+explicitly supplies them. Optional PySerial support is the `serial` extra and
+injected serial objects remain caller-owned. Break, DTR, and RTS are available
+on `SerialProcess`/`SerialConsoleProcess`; RFC 2217 URLs are not encrypted.

hostctl/README.md

@@ -0,0 +1,248 @@
+[![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).