hostctl 0.2.7__tar.gz → 0.3.1__tar.gz

hostctl-0.3.1/.gitignore

@@ -0,0 +1,51 @@
+__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
+
+# Unshared per-machine overrides. `AGENTS.local.md` is the dangerous one: it
+# sits beside an `AGENTS.md` that is *supposed* to ship, under a nearly
+# identical name and with the opposite destination, and it carries local
+# paths, hostnames and sometimes credentials. The manifest excludes the same
+# pattern; both teeth are needed, and neither is automatic.
+*.local.*
+
+# Root dotfiles only. Unanchored, `.*` also matched every nested dotfile and
+# dot-directory -- a `tests/.golden/` fixture or a vendored `.config` would
+# have been ignored with nothing to say so. The slashless `.agents`,
+# `CLAUDE*` and `.claude` rules above are deliberately NOT anchored, because
+# a nested copy of those is exactly what must not be committed.
+/.*
+!/.gitignore
+!/.gitattributes
+# Directory form: git cannot re-include a file below an excluded directory,
+# so `.github/` itself has to be un-ignored, not just the files under it.
+!/.github/
+
+# Run logs. `summarize_run.py` writes `run.log` into the working directory,
+# and the sdist target excludes only dotfiles -- so a test run from the repo
+# root followed by `python -m build` published that log once already.
+run.log
+*.log
+
+# OS and editor droppings.
+.DS_Store
+Thumbs.db
+*.swp
+*~
+

hostctl-0.3.1/AGENTS.md

@@ -0,0 +1,72 @@
+# Working in this checkout
+
+Contributor orientation. The **shipped API header** is
+[`src/hostctl/AGENTS.md`](src/hostctl/AGENTS.md) — that one goes in the wheel and
+describes the public surface for a consumer. This one describes the repository,
+and is not published anywhere.
+
+## Layout
+
+| path | what lives there |
+| ---- | ---------------- |
+| `src/hostctl/host/` | `Host`, `HostConfig`, URI dispatch, per-transport hosts, composite paths |
+| `src/hostctl/executor/` | one buffered command executor per transport |
+| `src/hostctl/process/` | persistent process adapters (`spawn`, sessions, consoles) |
+| `src/hostctl/shell/` | shell flavours: quoting, script assembly, invocation |
+| `src/hostctl/provider/` | the provider/selector contracts every transport plugs into |
+| `src/hostctl/serial/` | console profiles (prompt, login, status framing) |
+| `src/hostctl/sync/` | checksum and byte-progress helpers for `pathlib_next` |
+| `tests/conformance/` | the cross-transport battery: one contract, every provider |
+| `examples/` | runnable examples; deliberately not packaged |
+| `docs/` | the guide published to GitHub Pages |
+
+`tests/conformance/` is where a behaviour that must hold **everywhere** belongs.
+A test there is parametrized over every registered provider and skips itself
+when a provider does not advertise the capability, so a transport whose
+capabilities drift silently stops being tested — which is why
+`tests/conformance/test_registry.py` exists to check the registry itself.
+
+## Environments
+
+```bash
+py -3.14 -m venv .venv/3.14-nt-amd64
+.venv/3.14-nt-amd64/Scripts/python -m pip install -e ".[dev,docs]"
+.venv/3.14-nt-amd64/Scripts/python -m pytest -q
+```
+
+3.14 is the development interpreter; **3.9 is the supported floor** and a change
+is not done until it passes there too (`.venv/3.9-nt-amd64`). The `dev` extra
+pulls every transport, so `".[dev]"` is the whole list — do not re-spell the
+extras anywhere.
+
+Before committing: `python -m black src tests` (CI checks it) and
+`python -m mkdocs build --strict` if you touched docs.
+
+## CI — three workflows, one per concern
+
+- `test.yml` — `workflow_dispatch` (with a `ref` input) and throwaway `ci-*`
+  tags, plus a Linux job that runs the conformance battery against **live**
+  sshd, Docker and serial loopback legs.
+- `release.yml` — on a `v*` tag: test gate → build → GitHub release → PyPI,
+  plus a strict docs **build** that gates the release without deploying.
+- `docs.yml` — owns every Pages deploy: on a published release, on a push to
+  `main` touching docs sources, and on manual dispatch.
+
+Pushing a `ci-*` tag is routine; delete it afterwards. **Pushing a `v*` tag is
+a release and needs the maintainer's explicit consent for that version** —
+publishing is irreversible.
+
+## Conventions that are not obvious from the source
+
+- **Files are LF-only**, every file, including on Windows.
+- **A divergence is documented or it is a bug.** Where a transport cannot
+  honour the common contract, add a row to `docs/guide/contracts.md`'s ledger
+  saying what differs and *why the transport cannot do otherwise* — not a
+  sentence saying it differs.
+- **Composite paths forward the method that was called.** Adding an operation
+  is a row in `_FORWARDED`, not a method body; decomposing a call into
+  primitives discards transport-native implementations.
+- **Capabilities are strings**, and a provider may declare one this package's
+  enum does not know.
+- Measure before claiming. Several comments in this tree cite a measured
+  number because the intuitive answer was wrong.

{hostctl-0.2.7 → hostctl-0.3.1}/CHANGELOG.md

@@ -7,6 +7,237 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-22
+
+### Fixed
+
+- **A composite path falls back when SFTP cannot connect.** Nothing on the
+  path route connected the provider first: pathlib_next dialled SFTP inside
+  the operation, so an untrusted host key (`HostKeyNotVerifiable`) or a
+  refused port escaped raw and the next path provider was never tried --
+  while `run()` on the same host fell back. A composite path now calls the
+  provider's `connect()` before dispatch, and SFTP maps asyncssh's connect
+  errors the way the SSH leg already did. Most likely to fire since 0.3.0
+  started verifying the SFTP host key: any host not yet in `known_hosts`.
+- **`run()` no longer re-dials a declined provider on every call.** 0.3.0
+  cleared every decline per call, so a dead primary cost a full connect
+  attempt (~9 s against a refused port) on each `run()` while the fallback
+  served. A decline now lasts for the generation again, and is re-admitted
+  only when no other provider can serve -- which keeps a single-provider
+  host from bricking on one transient refusal, for paths as well as `run()`.
+- A path refusal with nothing left to try names why ("no path provider
+  completed read (...: Host key is not trusted ...)") and keeps the cause.
+
+## [0.3.0] - 2026-09-22
+
+### Added
+
+- **QGA paths have metadata and namespace operations.** `QemuHost.path()`
+  now supports `stat`, `iterdir`, `mkdir`, `unlink`, `rename` and `chmod`
+  through a guest-side helper built during discovery -- hostctl previously
+  shipped none, so a caller had to write one and every QGA path reported
+  `degraded`. The helper is POSITIVELY PROBED: GNU `stat -c`/`find -printf`
+  on a POSIX guest, PowerShell on a Windows one. A guest that fails the
+  probe keeps content access and loses only what genuinely needs a helper.
+  `QemuConfig(path_helper=...)` still overrides.
+- **`SshConfig(login_shell="auto"|"cmd"|"powershell"|"posix")`** says what
+  parses the command string on arrival. Windows OpenSSH's stock server
+  hands it to `cmd.exe /c`, so a `cmd`-dialect command line is parsed by cmd
+  twice; unescaped, 4 of 8 adversarial values survived and two of the
+  failures were command injection. `auto` reads the dialect.
+- **`ShellFlavour.argument(value, *, target=ShellTarget...)`** separates
+  quoting for the shell's parser from quoting for whatever reads the token
+  next -- a cmd builtin, a child's argv parser, PowerShell's binder, or the
+  program slot. `quote()` remains the syntactic layer.
+
+### Removed
+
+- **`SerialTransport`** and its `hostctl.executor` export. It duplicated
+  `SerialProcess`'s locked, deadline-clamping byte path and had no caller
+  outside its own tests, so the two could drift with nothing to notice.
+  `SerialProcess` keeps the job -- it is what every console profile reads
+  through -- and gained the `write(timeout=)` it lacked.
+- **`SerialConfig.username` and `SerialConfig.password`.** They were stored,
+  whitelisted for URI dispatch, and read by nothing: console credentials live
+  in the profile's `login=` steps. An explicit one is now refused rather than
+  silently ignored, and `HOSTCTL_PASSWORD` is no longer offered to a `serial:`
+  URI.
+
+### Changed
+
+- The `pathlib_next` floor moves to `>=0.9.10` in both `dependencies` and
+  the `ssh` extra. **0.9.4 through 0.9.9 cannot be used**: those releases
+  decide "same file" and "overlapping trees" by falling back to path
+  equality, which compares `(type, segments)` and knows nothing about
+  hosts, so copying `/etc/app.conf` from one host to the same path on
+  another was refused with `OSError [Errno 22] Source and target are the
+  same file` (and `PathSyncer` with "source and target overlap"). 0.9.10
+  adds the `_same_filesystem()` hook this release answers.
+- **`LocalExecutor` merges `env` over the inherited environment** instead of
+  replacing it, so the documented cross-transport rule -- "`env` is additive
+  to the provider's environment" -- now holds locally too. A child no longer
+  starts without `PATH`, `HOME` or `SystemRoot` because one variable was set.
+- **A serial `run()` frames each command as its own profile exchange** and
+  refuses a structured (argv) command: a serial host names no shell flavour,
+  so it has no quoting rule to apply, and joining commands with `;` put two
+  on one line where most device consoles read a single malformed one.
+  `stdin=` and `bufsize=` raise instead of being ignored, as `input=` already
+  did.
+- **A serial `spawn(encoding=...)` reads text**, matching the SSH and QEMU
+  console adapters; without either text keyword it still reads bytes.
+- **QEMU `dialect="auto"`/`path_flavor="auto"` need positive evidence** of the
+  guest's family -- `guest-get-osinfo`, or a family-exclusive command in
+  `guest-info` -- and raise naming the explicit settings when neither is
+  available. An agent with `guest-get-osinfo` blocklisted used to be read as
+  POSIX, silently, including on Windows.
+- **`QemuHost.info().os_family` is a family** (`linux`, `windows`,
+  `freebsd`), taken from `kernel-name`. It carried `guest-get-osinfo`'s `id`,
+  so the same machine reported `linux` over SSH and `ubuntu` over QGA.
+- **Each guest-agent request is bounded by `agent_timeout`**, separately from
+  a command's own `timeout=`: an agent that stops answering is a
+  `ConnectionError` saying so, not a command timeout ten minutes later.
+- **A truncated QGA `run()` result warns.** `stdout_truncated`/
+  `stderr_truncated` were set and documented nowhere, so a shortened
+  transcript looked complete.
+- **`hostctl shell` opens a console that cannot allocate a terminal**, so a
+  `serial:` URI works; **`hostctl cp local:/tmp/x`** is accepted, the
+  spelling every other subcommand documents; and `hostctl --help` carries the
+  URI forms, the `URI:PATH` grammar, the `HOSTCTL_PASSWORD` rule and the exit
+  codes.
+- **`asyncssh` and `libvirt-python` are bounded** (`>=2.14,<3`, `>=9.0,<12`);
+  the `dev` extra now pulls every transport, so `pip install -e ".[dev]"` is
+  the whole development environment.
+- **`LocalHost` is a `SystemHost`.** It duplicated the provider selection,
+  failover loop, capability computation and dispatch ladder, and the two
+  copies diverged. Two consequences for callers:
+  **`LocalHost().path()` with no segments no longer returns the absolute
+  working directory** -- it returns a path with no segments added, like
+  every other transport, which still resolves against the process's working
+  directory. A local path is still a plain `pathlib_next` path, not a
+  composite.
+
+### Fixed
+
+- **A transfer between two hosts is no longer mistaken for a file copied
+  onto itself.** `CompositePosixPath`/`CompositeWindowsPath` now answer
+  `pathlib_next`'s `_same_filesystem()` with the host's provider set, so
+  two hosts are two namespaces even when a path is spelled identically on
+  both, while two paths on one host still are one — which keeps the guard
+  that refuses `copy()` of a file onto itself. A `.via()` pin selects a
+  route to the host, not a different host, and answers accordingly.
+- **The SFTP leg verifies the server's host key.** `SshConfig.connect_opts()`
+  omitted `known_hosts` whenever it held its `()` default. asyncssh reads a
+  missing key as "resolve known_hosts the usual way", so `run()` verified the
+  server — but `pathlib_next`'s SFTP connect seeds `known_hosts=None`
+  (verification off) for options it is not handed, so `path()` accepted any
+  host key, including an actively substituted one, and sent it the configured
+  password. Opting out is still possible and now explicit: `known_hosts=None`.
+- **`ConnectionString` parses `user:password@host`.** A scheme-shaped username
+  made `urlsplit` read `root:hunter2@nas` as the scheme `root`, so the password
+  was never recognised: it stayed in the path, where `str()` and `repr()`
+  rendered it verbatim, the host came out empty, and `is_local` reported a
+  remote machine as local. Without a scheme to assume, a target carrying
+  credentials is now refused rather than guessed at, and both error messages
+  redact (`root:<redacted>@nas`).
+- **An args-capable executor gets one shell layer, not two.** `SystemHost`
+  fed a finished shell command line back into `flavour.invocation()`, which
+  takes a script. On Windows the outer PowerShell re-parsed the inner
+  `-Command` string, so `windows://node?executor=local` reported 0 for
+  `cmd /c exit 3` — `check=True` passed for a failing command — and quoted
+  text and variables came back mangled or empty.
+- **cmd.exe builtin operands are quoted, and `set` no longer escapes inside
+  quotes.** cmd splits a builtin's operands on `,`, `;` and `=` as well as
+  whitespace, so `del /q a b.txt` deleted `a` and `b.txt` and left the named
+  file. Separately, `set "KEY=VALUE"` caret-escaped inside a quoted span,
+  where cmd does not process carets: `100%` reached the child as `100^%`,
+  `%OS%` still expanded, and a `"` in the value ended the assignment early.
+  An empty value remains inexpressible in cmd, and is now documented as such.
+- **PowerShell 5 native arguments survive the C runtime.** PS 5.1 rebuilds the
+  command line for a native program and leaves embedded quotes alone, so
+  `run(("robocopy", src, dst, name))` with `name = 'my file" /MIR "z'` handed
+  robocopy `/MIR` — mirror mode, which deletes files in the destination. Empty
+  arguments were dropped and a trailing backslash swallowed the next argument.
+  PowerShell 7 is unaffected and keeps the plain literal.
+- **A transfer to another backend no longer renames inside the source host.**
+  `ssh_host.path('/srv/export.csv').move(LocalPath('/home/op/export.csv'))`
+  issued an SFTP rename on the server: the file left `/srv`, never arrived,
+  and no error was raised. A `str` destination — documented by `pathlib_next`
+  — also raised `TypeError` on every transport, and a cross-provider `move()`
+  aborted instead of falling back to copy + remove. All three now work.
+- **Docker file modes are translated.** The archive stat header carries Go's
+  `os.FileMode`, used verbatim as a POSIX `st_mode`: `is_file()` was False for
+  every ordinary file and `is_dir()` raised `OverflowError: mode out of range`
+  for a directory, which also killed any recursive copy.
+- **An unreachable QGA socket is reported as a transport failure.** It escaped
+  as a bare `FileNotFoundError`, indistinguishable from the guest file being
+  absent — so an append across a guest reboot staged an empty buffer and
+  truncated the guest file when the agent came back.
+- **Native WinRM reports the remote exit status.** The provider did not
+  declare `manages_status`, so PowerShell's `; exit $LASTEXITCODE` epilogue was
+  appended and its `exit` ended the remote pipeline before the
+  `__HOSTCTL_LASTEXITCODE__` marker could be emitted. A command that failed by
+  exit status reported 0 and `check=True` passed.
+- **One unsupported operation no longer takes a path provider out of
+  service.** A `NotImplementedError` from a retry-safe call was recorded as
+  a decline on the host's shared provider selector, which every later
+  operation then consulted: after a backend refused `samefile()` — it needs
+  `st_dev`/`st_ino`, which many remote stats lack — the next read on any
+  path of that host failed with `no path provider supports open_read`. The
+  refusal is now scoped to the call that raised it. `OperationNotStarted`
+  still declines the provider for the generation, as before.
+- **A `cmd.exe` at a path containing a space is launchable.** The program
+  slot of a Windows command line is read by `CreateProcess`, not by cmd, and
+  rendering it with cmd's caret quoting made Windows look for a program named
+  `^` -- measured as `FileNotFoundError: [WinError 2]`.
+- **A structured PowerShell command can bind a named parameter.**
+  `["Remove-Item", "-LiteralPath", path]` rendered every token as a quoted
+  string, which PowerShell's binder reads positionally: measured against a
+  real `powershell.exe`, it returned 1 and left the file in place. A token
+  that is exactly a parameter name is now unquoted.
+- **`ShellSession.send()` does not append a separator the text already has**,
+  so `send("echo hi;")` is not `echo hi;;` and `send("sleep 5 &")` is not
+  `sleep 5 &;`.
+- **`zsh` quoting covers a leading `=`**, which zsh expands to a program path
+  where POSIX `sh` leaves it alone.
+- **`PowerShellFlavour(7, executable=...)` is named `pwsh`.** The name was
+  derived only when no executable was given, so an explicit path left the
+  flavour identifying as `powershell`.
+- **`Shell(..., env={})` forwards no environment**, rather than an empty one
+  that starts a child with nothing.
+- **`normalize_input` covers `bytearray` and `memoryview`** -- the deadlock
+  it exists to prevent, for the two buffer types it did not check.
+- **Container archive reads no longer lie about links, sizes or errors**: a
+  single-member hardlink archive raises `OSError(ENOENT)` instead of
+  `tarfile.StreamError`, a hardlinked file in a listing reports its real
+  size, the archive root (`"."`) is listable, and every Docker status code
+  maps through one helper that populates `errno`.
+- **A container exec stream no longer returns `''` mid-character**, and a
+  closed container process reads EOF instead of raising the operating
+  system's raw socket error.
+- **QGA failures speak one error vocabulary**: a guest error is classified on
+  the `strerror` tail (a file named `notfound.log` was reported missing
+  whatever actually failed), `host.run()` of a missing guest program raises
+  `FileNotFoundError`, libvirt-relayed guest errors stay guest errors, and a
+  guest error no longer tears down and re-handshakes the connection.
+- **One transport per QEMU host.** Lazy initialisation was unguarded:
+  measured with six threads, six transports were built where one was wanted,
+  each SSH one opening a connection nobody owned. A path handed out before
+  `close()` now refuses instead of silently reconnecting.
+- **A serial login failure raises `ConsoleProtocolError`**, not a bare
+  `TimeoutError` that slipped past every documented handler, and a transcript
+  attached to an error has `secret=True` login values redacted -- consoles
+  echo what they are sent.
+- **A QGA reader is seekable** where the agent advertises `guest-file-seek`,
+  so `zipfile` and `tarfile` work against a guest path, and an exclusive
+  `open("x")` is refused at `open()` rather than after the whole payload has
+  been staged.
+- **A `cmd`-dialect command sent over SSH to Windows is escaped for the
+  login shell that receives it.** Two of the eight adversarial values were
+  command injection, not corruption.
+- **`SshConfig("ssh://host")` raises** instead of making the URI the
+  hostname, which surfaced much later as an unresolvable name. The
+  constructor takes a host; `HostConfig(uri)` takes a URI.
+
 ## [0.2.7] - 2026-08-16
 
 ### Changed
@@ -27,6 +258,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   composite `symlink_to` could never work. `netimps` needs nothing past
   `0.2.0` and floors at the series start.
 
+## [0.2.6] - 2026-08-16
+
 ### Added
 
 - `wants_text(text, encoding, errors)` is exported from `hostctl.executor`,
@@ -529,7 +762,9 @@ test suite on Python 3.9 through 3.14.
   assigned to it; a config-less host now builds its own family configuration
   instead.
 
-[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.7...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/jose-pr/hostctl/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/jose-pr/hostctl/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/jose-pr/hostctl/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/jose-pr/hostctl/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/jose-pr/hostctl/compare/v0.2.4...v0.2.5

{hostctl-0.2.7 → hostctl-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hostctl
-Version: 0.2.7
+Version: 0.3.1
 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/
@@ -24,14 +24,20 @@ Classifier: Topic :: System :: Filesystems
 Classifier: Topic :: System :: Systems Administration
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
-Requires-Dist: netimps<0.3,>=0.2.0
-Requires-Dist: pathlib-next<0.10,>=0.9.1
+Requires-Dist: netimps<0.4,>=0.3.0
+Requires-Dist: pathlib-next<0.10,>=0.9.10
 Provides-Extra: container
 Requires-Dist: docker<8,>=7.1; extra == 'container'
 Provides-Extra: dev
+Requires-Dist: asyncssh<3,>=2.14; extra == 'dev'
 Requires-Dist: black; extra == 'dev'
 Requires-Dist: build; extra == 'dev'
+Requires-Dist: docker<8,>=7.1; extra == 'dev'
+Requires-Dist: pathlib-next[sftp-async]<0.10,>=0.9.10; extra == 'dev'
+Requires-Dist: pypsrp<1,>=0.9; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: pyserial<4,>=3.5; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pywinrm<0.6,>=0.5.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs; extra == 'docs'
 Requires-Dist: mkdocs-material; extra == 'docs'
@@ -39,12 +45,12 @@ 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'
+Requires-Dist: libvirt-python<12,>=9.0; 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.10,>=0.9.1; extra == 'ssh'
+Requires-Dist: asyncssh<3,>=2.14; extra == 'ssh'
+Requires-Dist: pathlib-next[sftp-async]<0.10,>=0.9.10; extra == 'ssh'
 Provides-Extra: winrm
 Requires-Dist: pywinrm<0.6,>=0.5.0; extra == 'winrm'
 Provides-Extra: winrm-credssp
@@ -54,7 +60,8 @@ 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)
+[![Python versions](https://img.shields.io/pypi/pyversions/hostctl.svg)](https://pypi.org/project/hostctl/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/hostctl/blob/main/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)
 
@@ -67,8 +74,9 @@ 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`.
+  SSH (`asyncssh`), or PowerShell over WinRM (`pywinrm`). Two defaults differ
+  from `subprocess.run` deliberately: `check` and `capture_output` are both
+  `True`. 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;
@@ -147,10 +155,10 @@ with WinRMConfig("windows.example.com", "admin", "secret", ssl=True) as windows:
 
 # An existing running container (needs the `container` extra).
 with ContainerConfig("application") as container:
-    container.run(["printf", "%s\n", "hello"])
+    container.run(["printf", "%s", "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"])
+        session.send(["printf", "%s", "hello from the session"])
         print(session.read())
 
 # A QEMU guest through its QGA Unix socket tunneled over SSH.
@@ -224,6 +232,11 @@ 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.
+`IosHost` is deliberately session- and command-only: it configures no shell
+flavour and no path grammar, so commands must be `Exec(...)` (or raw text the
+device understands) and `path()` raises `NotImplementedError` until an IOS
+path grammar exists.
+
 Paths retain their selected provider and expose it through `.provider` and
 `.via(name)`:
 
@@ -241,7 +254,7 @@ print(path.provider.name)
 ```
 
 Application-specific adapters can follow the SFTP/RPC/download pattern in
-[`examples/application_provider.py`](examples/application_provider.py). The
+[`examples/application_provider.py`](https://github.com/jose-pr/hostctl/blob/main/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.
@@ -292,19 +305,37 @@ and exit statuses.
 
 ```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 pip install -e ".[dev,docs]"
 .venv/3.14-nt-amd64/Scripts/python -m pytest -q
+# The docs gate the release runs, locally:
+.venv/3.14-nt-amd64/Scripts/python -m mkdocs build --strict
 ```
 
+Every extra, so the documented environment is a superset of CI's: without
+`psrp` a capability test skips silently, and without `docs` the gate that can
+block a release cannot be run at all.
+
 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.
+`py -3.9` when running floor-specific checks; name that environment
+`.venv/3.9-nt-amd64` so the two agree.
+
+The venv names carry the platform `sysconfig.get_platform()` reports, so a
+checkout on an ARM64 Windows machine still names them `amd64`: `cryptography`
+publishes no `win_arm64` wheel and building it from source needs a Rust
+toolchain, so `asyncssh` -- and with it the whole `ssh` extra -- cannot be
+installed under a native ARM64 interpreter. If that changes, the native
+interpreter is `py -V:3.14-arm64` and the environment should be named
+`.venv/3.14-nt-arm64`.
 
 ### 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.
+[`CHANGELOG.md`](https://github.com/jose-pr/hostctl/blob/main/CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build → publish, with a strict docs build as a gate.
+The docs site itself is deployed by `docs.yml`, which also redeploys on a push
+to `main` touching docs sources and on manual dispatch -- so a docs fix reaches
+the site without cutting a tag.
 
 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
@@ -316,4 +347,4 @@ the next cycle.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/jose-pr/hostctl/blob/main/LICENSE).

{hostctl-0.2.7 → hostctl-0.3.1}/README.md

@@ -1,5 +1,6 @@
 [![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)
+[![Python versions](https://img.shields.io/pypi/pyversions/hostctl.svg)](https://pypi.org/project/hostctl/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/hostctl/blob/main/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)
 
@@ -12,8 +13,9 @@ 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`.
+  SSH (`asyncssh`), or PowerShell over WinRM (`pywinrm`). Two defaults differ
+  from `subprocess.run` deliberately: `check` and `capture_output` are both
+  `True`. 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;
@@ -92,10 +94,10 @@ with WinRMConfig("windows.example.com", "admin", "secret", ssl=True) as windows:
 
 # An existing running container (needs the `container` extra).
 with ContainerConfig("application") as container:
-    container.run(["printf", "%s\n", "hello"])
+    container.run(["printf", "%s", "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"])
+        session.send(["printf", "%s", "hello from the session"])
         print(session.read())
 
 # A QEMU guest through its QGA Unix socket tunneled over SSH.
@@ -169,6 +171,11 @@ 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.
+`IosHost` is deliberately session- and command-only: it configures no shell
+flavour and no path grammar, so commands must be `Exec(...)` (or raw text the
+device understands) and `path()` raises `NotImplementedError` until an IOS
+path grammar exists.
+
 Paths retain their selected provider and expose it through `.provider` and
 `.via(name)`:
 
@@ -186,7 +193,7 @@ print(path.provider.name)
 ```
 
 Application-specific adapters can follow the SFTP/RPC/download pattern in
-[`examples/application_provider.py`](examples/application_provider.py). The
+[`examples/application_provider.py`](https://github.com/jose-pr/hostctl/blob/main/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.
@@ -237,19 +244,37 @@ and exit statuses.
 
 ```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 pip install -e ".[dev,docs]"
 .venv/3.14-nt-amd64/Scripts/python -m pytest -q
+# The docs gate the release runs, locally:
+.venv/3.14-nt-amd64/Scripts/python -m mkdocs build --strict
 ```
 
+Every extra, so the documented environment is a superset of CI's: without
+`psrp` a capability test skips silently, and without `docs` the gate that can
+block a release cannot be run at all.
+
 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.
+`py -3.9` when running floor-specific checks; name that environment
+`.venv/3.9-nt-amd64` so the two agree.
+
+The venv names carry the platform `sysconfig.get_platform()` reports, so a
+checkout on an ARM64 Windows machine still names them `amd64`: `cryptography`
+publishes no `win_arm64` wheel and building it from source needs a Rust
+toolchain, so `asyncssh` -- and with it the whole `ssh` extra -- cannot be
+installed under a native ARM64 interpreter. If that changes, the native
+interpreter is `py -V:3.14-arm64` and the environment should be named
+`.venv/3.14-nt-arm64`.
 
 ### 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.
+[`CHANGELOG.md`](https://github.com/jose-pr/hostctl/blob/main/CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build → publish, with a strict docs build as a gate.
+The docs site itself is deployed by `docs.yml`, which also redeploys on a push
+to `main` touching docs sources and on manual dispatch -- so a docs fix reaches
+the site without cutting a tag.
 
 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
@@ -261,4 +286,4 @@ the next cycle.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/jose-pr/hostctl/blob/main/LICENSE).