hostctl 0.2.5__tar.gz → 0.2.7__tar.gz

{hostctl-0.2.5 → hostctl-0.2.7}/.gitignore

@@ -19,4 +19,8 @@ CLAUDE*
 .claude
 .*
 !.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/
 

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

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.7] - 2026-08-16
+
+### Changed
+
+- Dependency floors now name versions hostctl is actually tested against.
+  `pathlib_next` moves to `>=0.9.1,<0.10` and `netimps` to `>=0.2.0,<0.3`
+  (the `ssh` extra's `pathlib_next[sftp-async]` moves from `>=0.8.4` to the
+  same `>=0.9.1`). Both ceilings are unchanged, and no API hostctl calls has
+  moved — this only stops resolvers from choosing an install that does not
+  work.
+
+  The `pathlib_next` floor is above the start of its minor series for one
+  measured reason: `Path.symlink_to()` — and with it the `force=` keyword —
+  first exists in **0.9.1**. The composite path forwards `symlink_to` to
+  whichever backend path it was handed, so against a stock 0.9.0 `Path` the
+  whole chain raises `AttributeError` rather than linking anything. The
+  previous `>=0.8.6` floor therefore advertised support for installs where
+  composite `symlink_to` could never work. `netimps` needs nothing past
+  `0.2.0` and floors at the series start.
+
+### Added
+
+- `wants_text(text, encoding, errors)` is exported from `hostctl.executor`,
+  joining the four stream helpers made public in 0.2.5 for the same reason:
+  an executor implemented outside hostctl must reach the same conclusions as
+  the built-in ones, because a `SystemHost` chooses the provider.
+
+### Fixed
+
+- Direct execution no longer raises `NameError` on two dispatch paths.
+  `ContainerHost.spawn(Exec(...))` raised on *every* direct spawn, and
+  `SystemHost.run(Exec(program))` raised whenever the selected executor
+  provider advertised neither `args` nor `script` — the shape a bare
+  `ExecutorProvider("name", callable)` has, which is the documented minimal
+  form of that public authoring contract. Both modules used `command_text`
+  without importing it.
+
+- `hostctl cp` no longer mistakes a URI port colon for the `URI:PATH`
+  separator. `ssh://host:2222/tmp/x` split into `ssh://host` plus the relative
+  path `2222/tmp/x` — the default port and the wrong file, with no message. A
+  split that lands on the authority's port colon is now rejected with the
+  grammar error, so the required spelling `ssh://host:2222:/tmp/x` is the only
+  one that runs. Userinfo colons and IPv6 literals are excluded from the check.
+
+- Native current-context WinRM now honours `server_cert_validation="ignore"`.
+  It was spliced into the rendered wrapper with `str.replace`, which matched
+  nothing without a port (the setting vanished) and produced an
+  `Invoke-Command` parameter-binding error with one, since `SkipCACheck`
+  belongs to `New-PSSessionOption`. The option is now built explicitly and
+  passed as `-SessionOption`, skipping both the CA and CN checks to match
+  pywinrm's `ignore`.
+
+- Native current-context WinRM now reports remote exit codes.
+  `Invoke-Command` does not copy the remote `$LASTEXITCODE` into the calling
+  session, so a command that failed only by status — a native executable
+  exiting non-zero without throwing — returned 0 locally and `check=True`
+  never fired. The remote script block now emits the code as a
+  `__HOSTCTL_LASTEXITCODE__` marker line, which the local wrapper consumes
+  and exits with. **Behaviour change**: calls that silently succeeded against
+  a failing remote command now raise `CalledProcessError` under the default
+  `check=True`.
+
+- Every provider now agrees on when output is text. `errors=` alone selected
+  text mode on the local, WinRM, container, and QEMU executors and binary
+  mode on SSH, PSRP, and the serial host, so the identical call returned
+  `str` or `bytes` depending on which provider a `SystemHost` selected — the
+  exact divergence the shared stream helpers exist to prevent. All seven
+  sites now call `wants_text`. **Behaviour change**: `run(cmd,
+  errors="replace")` returns `str` from SSH, PSRP, and serial where it
+  previously returned `bytes`.
+
+- SFTP paths percent-encode the remote path before embedding it in the
+  `sftp://` URI. `pathlib_next` parses that URI and uridecodes its parts, so
+  a filename containing `?` or `#` was truncated into a query or fragment and
+  a literal `%xx` was decoded into a different name — reading and writing the
+  wrong file with no error. Encoding is minimal (RFC 3986 `pchar`), so a
+  Windows-flavoured remote path still reads as `sftp://host:22/C:/Temp`.
+
+- `RunspaceSession` no longer closes a pool it was given. `_owns_pool` was
+  recorded at construction and never read, so a pool injected to be shared
+  across sessions was closed by whichever session finished first. An injected
+  pool is now left open and retained, which also leaves the session
+  reopenable; a pool the session created is still closed.
+
+- An abandoned container or QGA write stream no longer uploads from the
+  garbage collector. The staged write-back stream existed as three
+  byte-identical copies of which only the WinRM one had a `__del__` guard;
+  `io.IOBase.__del__` calls `close()`, and `close()` is what commits, so a
+  write stream that went out of scope unclosed performed its network
+  transfer at an arbitrary GC point with any error printed and swallowed by
+  the interpreter. One `hostctl.host._staged_io` now serves all three, and
+  the abandonment case warns instead of uploading. The `open()` mode
+  validators were deduplicated with it, so `"rt"` is accepted on the
+  container and QGA backends as it always was on WinRM.
+
+- `SerialHost.run(capture_output=False)` no longer discards the console
+  transcript. It reimplemented the output contract and treated a `None`
+  stdout target as "discard"; the shared `dispatch_output` — and every other
+  transport, and `subprocess` — treats it as `sys.stdout`. Serial now routes
+  through the shared helper. `stdout=subprocess.DEVNULL` remains the way to
+  discard deliberately.
+
 ## [0.2.5] - 2026-08-05
 
 ### Added
@@ -427,7 +529,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.5...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.7...HEAD
+[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
 [0.2.4]: https://github.com/jose-pr/hostctl/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/jose-pr/hostctl/compare/v0.2.2...v0.2.3

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hostctl
-Version: 0.2.5
+Version: 0.2.7
 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,8 +24,8 @@ Classifier: Topic :: System :: Filesystems
 Classifier: Topic :: System :: Systems Administration
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
-Requires-Dist: netimps<0.3,>=0.1
-Requires-Dist: pathlib-next<0.10,>=0.8.6
+Requires-Dist: netimps<0.3,>=0.2.0
+Requires-Dist: pathlib-next<0.10,>=0.9.1
 Provides-Extra: container
 Requires-Dist: docker<8,>=7.1; extra == 'container'
 Provides-Extra: dev
@@ -44,7 +44,7 @@ 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.8.4; extra == 'ssh'
+Requires-Dist: pathlib-next[sftp-async]<0.10,>=0.9.1; extra == 'ssh'
 Provides-Extra: winrm
 Requires-Dist: pywinrm<0.6,>=0.5.0; extra == 'winrm'
 Provides-Extra: winrm-credssp

{hostctl-0.2.5 → hostctl-0.2.7}/docs/guide/cli.md

@@ -22,7 +22,10 @@ interactive hidden prompt. Transport extras remain optional and produce their
 normal actionable import error when absent.
 
 `cp` accepts local paths or `URI:PATH` operands and delegates to
-`pathlib_next.Path.copy()`. Use `--overwrite` and `--recursive` explicitly.
+`pathlib_next.Path.copy()`. The colon before the path is required even when the
+URI carries a port — `ssh://host:2222:/tmp/x`, never `ssh://host:2222/tmp/x`,
+which is rejected rather than read as port-less host plus a relative path.
+Use `--overwrite` and `--recursive` explicitly.
 The copy is therefore only as streaming and atomic as the two selected path
 backends; see the filesystem and transfer guides for provider-specific limits.
 

{hostctl-0.2.5 → hostctl-0.2.7}/docs/guide/contracts.md

@@ -14,9 +14,9 @@ stderr by default.  Captured streams are bytes unless `text=True` or an
 - A string is shell source and remains verbatim (operators such as `&&`, pipes,
   and redirects are not quoted).
 - A tuple/list is argv data and each item is quoted by the selected shell.
-- A leading `pathlib.PurePath` or `pathlib_next.Path` selects direct argv
-  execution; following values are arguments and are never interpreted by a
-  shell.
+- `Exec(program, *args)` is the only direct-execution spelling: one program
+  with an argv, never interpreted by a shell, and never combined with other
+  commands. A path anywhere else is an ordinary value that stringifies.
 - Multiple top-level commands are joined with the shell's sequence separator.
 - `env` is additive to the provider's environment. `cwd` is the process working
   directory. `check=True` raises `CalledProcessError` for every non-zero status;

{hostctl-0.2.5 → hostctl-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.2.5"
+version = "0.2.7"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"
@@ -34,19 +34,23 @@ classifiers = [
 # them. Transport implementations remain extras, so importing hostctl never
 # requires them.
 #
-# Both ranges span two minors deliberately: hostctl uses no API added in
-# pathlib_next 0.9 or netimps 0.2, so raising the floor would exclude working
-# installs for nothing. The ceilings stay at the next major-ish boundary
+# Each floor is the `.0` of the dependency's current minor series, raised
+# above it only where hostctl needs a later patch. pathlib_next is that
+# exception: `Path.symlink_to()` -- and with it the `force=` keyword -- first
+# exists in 0.9.1, and the composite path forwards `symlink_to` to whichever
+# backend path it was handed, so against a stock 0.9.0 `Path` the call raises
+# `AttributeError` (measured on 3.9 and 3.14). netimps has no such case and
+# floors at the series start. The ceilings stay at the next major-ish boundary
 # because both projects are pre-1.0, where a minor may break. Composite kwargs
-# passthrough does not change this: forwarding is signature-aware, so `force=`
-# is forwarded when the installed pathlib_next provides it and rejected at the
-# boundary when it does not (verified against 0.9.0 and 0.9.1).
-dependencies = ["pathlib_next>=0.8.6,<0.10", "netimps>=0.1,<0.3"]
+# passthrough does not change this: forwarding is signature-aware, so a
+# `force=` the installed pathlib_next does not declare is rejected at the
+# composite boundary rather than inside a transport.
+dependencies = ["pathlib_next>=0.9.1,<0.10", "netimps>=0.2.0,<0.3"]
 
 [project.optional-dependencies]
 # SSH-backed run()/path(): asyncssh for shell exec, pathlib_next's SftpPath
 # (asyncssh-only since 0.8.2) for the remote path backend.
-ssh = ["asyncssh", "pathlib_next[sftp-async]>=0.8.4,<0.10"]
+ssh = ["asyncssh", "pathlib_next[sftp-async]>=0.9.1,<0.10"]
 # Windows Remote Management command execution.
 winrm = ["pywinrm>=0.5.0,<0.6"]
 # PowerShell Remoting Protocol runspaces (Python 3.10+ only).  The marker

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/AGENTS.md

@@ -177,6 +177,13 @@ corresponding hosts.
   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.
+- Output is `str` when ANY of `text`, `encoding`, or `errors` is given, and
+  `bytes` otherwise -- `subprocess.run`'s rule, decided by the exported
+  `wants_text(text, encoding, errors)`. `text=False` does not veto an
+  `encoding`. An executor implemented outside hostctl must use the same
+  helper, for the same reason as `normalize_input`: a `SystemHost` picks the
+  provider, so a caller cannot write one correct invocation if providers
+  disagree about the result type.
 - `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
@@ -277,7 +284,11 @@ 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
+remoting; explicit credentials use pywinrm. On that native path
+`server_cert_validation="ignore"` becomes `New-PSSessionOption -SkipCACheck
+-SkipCNCheck` (both checks, matching pywinrm), and the remote exit code is
+carried back explicitly, so a native command failing only by status is
+reported as a failure rather than as success. `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

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/_cli.py

@@ -49,6 +49,22 @@ def _open_host(stack: contextlib.ExitStack, uri: str, credentials: dict[str, obj
     return stack.enter_context(Host(uri, **credentials))
 
 
+def _port_colon(value: str, scheme_end: int, authority_end: int) -> int:
+    """Index of the authority's port colon, or ``-1`` when it has none.
+
+    The port colon is the first colon of the host part: userinfo colons sit
+    before the ``@``, and an IPv6 literal keeps its colons inside brackets.
+    """
+    userinfo_end = value.rfind("@", scheme_end, authority_end)
+    host_start = scheme_end if userinfo_end < 0 else userinfo_end + 1
+    if value[host_start : host_start + 1] == "[":
+        bracket_end = value.find("]", host_start, authority_end)
+        if bracket_end < 0:
+            return -1
+        host_start = bracket_end + 1
+    return value.find(":", host_start, authority_end)
+
+
 def _path_operand(
     stack: contextlib.ExitStack,
     value: str,
@@ -58,10 +74,21 @@ def _path_operand(
     if not _URI_OPERAND.match(value) or re.match(r"^[A-Za-z]:[\\/]", value):
         return HostPath(value)
     if "://" in value:
-        authority_end = value.find("/", value.find("://") + 3)
+        scheme_end = value.find("://") + 3
+        authority_end = value.find("/", scheme_end)
         search_end = len(value) if authority_end < 0 else authority_end
         separator = value.rfind(":", 0, search_end)
-        if separator <= value.find("://") + 2:
+        if separator < scheme_end:
+            raise ValueError("remote path operand must be URI:PATH")
+        if (
+            separator == _port_colon(value, scheme_end, search_end)
+            and value[separator + 1 : search_end].isdigit()
+        ):
+            # `ssh://host:2222/x` has no path colon, so the last colon before
+            # the authority's slash is the port's. Splitting there yields
+            # `ssh://host` plus the relative path `2222/x` -- the wrong host
+            # and the wrong file, with nothing said. The grammar wants
+            # `ssh://host:2222:/x`.
             raise ValueError("remote path operand must be URI:PATH")
     else:
         separator = value.find(":", value.find(":") + 1)

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/__init__.py

@@ -16,6 +16,7 @@ from ._common import (
     dispatch_output as dispatch_output,
     normalize_input as normalize_input,
     reject_stdin_conflict as reject_stdin_conflict,
+    wants_text as wants_text,
     write_output as write_output,
 )
 from .container import (
@@ -71,6 +72,7 @@ __all__ = [
     "dispatch_output",
     "normalize_input",
     "reject_stdin_conflict",
+    "wants_text",
     "write_output",
     "normalize_serial_error",
     "SerialExecutor",

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/_common.py

@@ -94,6 +94,26 @@ def normalize_input(
     return input
 
 
+def wants_text(
+    text: typing.Optional[bool],
+    encoding: typing.Optional[str],
+    errors: typing.Optional[str],
+) -> bool:
+    """Decide whether one call's output is `str` rather than `bytes`.
+
+    `subprocess.run`'s rule, and the only one hostctl has: any of `text`,
+    `encoding`, or `errors` selects text mode. `text=False` does not veto an
+    `encoding` -- `subprocess` does not treat it as one either.
+
+    This exists as a shared function because the answer must not depend on
+    which provider a `SystemHost` happened to select. Four executors inferred
+    it as `bool(encoding or errors or text)` while SSH, PSRP, and the serial
+    host each ignored `errors`, so `run(cmd, errors="replace")` returned
+    `str` or `bytes` depending on which transport won the fallback.
+    """
+    return bool(text or encoding or errors)
+
+
 def command_text(
     value: object, *, encoding: str = "utf-8", errors: str = "strict"
 ) -> str:

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/container.py

@@ -19,6 +19,7 @@ from ._common import (
     dispatch_output,
     normalize_environment,
     capture_streams,
+    wants_text,
 )
 
 
@@ -119,7 +120,7 @@ class ContainerExecutor(Executor[subprocess.CompletedProcess]):
             out = b""
         if err is None and not merge_stderr:
             err = b""
-        if text or encoding is not None or errors is not None:
+        if wants_text(text, encoding, errors):
             codec = encoding or "utf-8"
             out = (
                 out.decode(codec, errors or "strict") if isinstance(out, bytes) else out

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/local.py

@@ -20,6 +20,7 @@ from ._common import (
     normalize_input,
     capture_streams,
     reject_stdin_conflict,
+    wants_text,
 )
 
 
@@ -69,7 +70,7 @@ class LocalExecutor(Executor[subprocess.CompletedProcess]):
             # where bytes would kill the writer thread and hang the call.
             input=normalize_input(
                 input,
-                text_mode=bool(encoding or errors or text),
+                text_mode=wants_text(text, encoding, errors),
                 encoding=encoding,
                 errors=errors,
             ),

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/psrp.py

@@ -18,6 +18,7 @@ from ._common import (
     Input,
     capture_streams,
     dispatch_output,
+    wants_text,
 )
 
 if typing.TYPE_CHECKING:
@@ -97,35 +98,20 @@ class PsrpExecutor(Executor[subprocess.CompletedProcess]):
             command_text(command), raw=False, capture_exit=True
         )
         codec = encoding or "utf-8"
+        # `invoke(capture_exit=True)` already consumed the
+        # `__HOSTCTL_LASTEXITCODE__` line and folded it into `returncode`;
+        # this used to re-parse the same marker out of output that no longer
+        # contained it, which is two implementations of one convention.
+        returncode = result.returncode
         # Preserve PowerShell's object-pipeline line orientation when
         # projecting objects to subprocess-compatible text.
-        projected_output = []
-        returncode = result.returncode
-        marker = "__HOSTCTL_LASTEXITCODE__:"
-        for item in result.output:
-            value = str(item)
-            if value.startswith(marker):
-                try:
-                    parsed_returncode = int(value[len(marker) :])
-                    returncode = (
-                        1
-                        if result.had_errors and parsed_returncode == 0
-                        else parsed_returncode
-                    )
-                except ValueError:
-                    returncode = 1
-                continue
-            projected_output.append(item)
-        out_text = "\n".join(str(item) for item in projected_output)
+        out_text = "\n".join(str(item) for item in result.output)
         err_text = "\n".join(str(item) for item in result.streams.error)
         if out_text:
             out_text += "\n"
-        out: typing.Union[str, bytes] = (
-            out_text if text or encoding else out_text.encode(codec)
-        )
-        err: typing.Union[str, bytes] = (
-            err_text if text or encoding else err_text.encode(codec)
-        )
+        as_text = wants_text(text, encoding, errors)
+        out: typing.Union[str, bytes] = out_text if as_text else out_text.encode(codec)
+        err: typing.Union[str, bytes] = err_text if as_text else err_text.encode(codec)
         if stderr is subprocess.STDOUT:
             out = out + err
             err = None

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/qemu.py

@@ -25,6 +25,7 @@ from ._common import (
     normalize_input,
     capture_streams,
     reject_stdin_conflict,
+    wants_text,
 )
 
 
@@ -180,7 +181,7 @@ class QemuExecutor(Executor[subprocess.CompletedProcess]):
                     "completed guest-exec status has no integer exit code or signal"
                 )
 
-        if text or encoding is not None or errors is not None:
+        if wants_text(text, encoding, errors):
             codec = encoding or "utf-8"
             out = out.decode(codec, errors or "strict")
             err = err.decode(codec, errors or "strict")

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/ssh.py

@@ -23,6 +23,7 @@ from ._common import (
     normalize_input,
     capture_streams,
     reject_stdin_conflict,
+    wants_text,
 )
 
 
@@ -138,7 +139,9 @@ class SshExecutor(Executor[subprocess.CompletedProcess]):
             raise ValueError("bufsize=0 is unsupported by the buffered SSH executor")
         command = command_text(command)
         reject_stdin_conflict(input, stdin)
-        if text and encoding is None:
+        if wants_text(text, encoding, errors) and encoding is None:
+            # AsyncSSH returns `bytes` unless it is given an encoding, so
+            # text mode has to be expressed as one.
             encoding = "utf-8"
         env = normalize_environment(env)
 

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/executor/winrm.py

@@ -18,6 +18,7 @@ from ._common import (
     Input,
     dispatch_output,
     capture_streams,
+    wants_text,
 )
 
 
@@ -38,6 +39,24 @@ class _NativeResponse:
     std_err: bytes
 
 
+#: Emitted by the remote script block and consumed by the local wrapper.
+#: `Invoke-Command` does not copy the remote `$LASTEXITCODE` into the calling
+#: session, so a native command that fails only by exit code would otherwise
+#: report success locally.  Same convention as the PSRP runspace session.
+NATIVE_EXIT_MARKER = "__HOSTCTL_LASTEXITCODE__"
+
+#: Runs *inside* the remote script block, appended on its own line so that the
+#: payload's last statement -- comment, `}` or bare expression alike -- cannot
+#: swallow it.
+_NATIVE_EXIT_EPILOGUE = (
+    f"Write-Output ('{NATIVE_EXIT_MARKER}:' + [string]([int]$LASTEXITCODE))"
+)
+
+
+def _b64(value: str) -> str:
+    return base64.b64encode(value.encode("utf-8")).decode("ascii")
+
+
 class NativeWinRMSession:
     """Current-context Windows PowerShell remoting session adapter."""
 
@@ -76,38 +95,60 @@ class NativeWinRMSession:
         else:
             self._skip_ca_check = False
 
-    def run_ps(self, script: str) -> _NativeResponse:
-        host = base64.b64encode(self.host.encode("utf-8")).decode("ascii")
-        payload = base64.b64encode(script.encode("utf-8")).decode("ascii")
-        wrapper = (
+    def _wrapper(self, script: str) -> str:
+        """Build the local PowerShell program that performs one remote call.
+
+        Everything variable is base64 -- the host, the payload, and the exit
+        epilogue -- so no caller-supplied text is ever spliced into PowerShell
+        source.  The connection options are assembled as a list rather than
+        patched into rendered text afterwards: the previous `str.replace`
+        approach silently did nothing without a port and produced a hashtable
+        `Invoke-Command` rejects with one.
+        """
+        options = [
+            "ComputerName=$h",
+            "Authentication='Negotiate'",
+            f"UseSSL=${str(self.ssl).lower()}",
+        ]
+        if self.port is not None:
+            options.append(f"Port={self.port}")
+        prelude = ""
+        if self._skip_ca_check:
+            # `SkipCACheck` is a `New-PSSessionOption` parameter, not an
+            # `Invoke-Command` one.  Both checks are skipped together to match
+            # pywinrm's `server_cert_validation="ignore"`.
+            prelude = "$so=New-PSSessionOption -SkipCACheck -SkipCNCheck;"
+            options.append("SessionOption=$so")
+        return (
             "$OutputEncoding=[Console]::OutputEncoding="
             "[Text.UTF8Encoding]::new($false);"
             "$ErrorActionPreference='Stop';"
             "$h=[Text.Encoding]::UTF8.GetString("
-            f"[Convert]::FromBase64String('{host}'));"
+            f"[Convert]::FromBase64String('{_b64(self.host)}'));"
             "$s=[Text.Encoding]::UTF8.GetString("
-            f"[Convert]::FromBase64String('{payload}'));"
-            "$o=@{ComputerName=$h;Authentication='Negotiate';"
-            f"UseSSL=${str(self.ssl).lower()}"
-            + (f";Port={self.port}" if self.port is not None else "")
+            f"[Convert]::FromBase64String('{_b64(script)}'));"
+            "$e=[Text.Encoding]::UTF8.GetString("
+            f"[Convert]::FromBase64String('{_b64(_NATIVE_EXIT_EPILOGUE)}'));"
+            + prelude
+            + "$o=@{"
+            + ";".join(options)
             + "};"
             "try{$global:LASTEXITCODE=0;"
-            "$r=Invoke-Command @o -ScriptBlock ([ScriptBlock]::Create($s));"
-            "$r;exit ([int]$global:LASTEXITCODE)}"
+            "$b=[ScriptBlock]::Create($s+[Environment]::NewLine+$e);"
+            "$r=Invoke-Command @o -ScriptBlock $b;"
+            "$c=[int]$global:LASTEXITCODE;$out=@();"
+            "foreach($v in $r){$t=[string]$v;"
+            f"if($t.StartsWith('{NATIVE_EXIT_MARKER}:'))"
+            "{$c=[int]($t.Split(':')[1])}else{$out+=$v}};"
+            "$out;exit $c}"
             "catch{$c=[string]$_.CategoryInfo.Category;"
             "$m=[Convert]::ToBase64String("
             "[Text.Encoding]::UTF8.GetBytes($_.Exception.Message));"
             "[Console]::Error.Write('HOSTCTL_NATIVE_ERROR:'+$c+':'+$m);exit 1}"
         )
-        if self._skip_ca_check:
-            wrapper = wrapper.replace(
-                ";Port=" + str(self.port) if self.port is not None else ";};",
-                (
-                    ";SkipCACheck=$true;Port=" + str(self.port)
-                    if self.port is not None
-                    else ";SkipCACheck=$true;};"
-                ),
-            )
+
+    def run_ps(self, script: str) -> _NativeResponse:
+        wrapper = self._wrapper(script)
         try:
             result = subprocess.run(
                 (
@@ -197,7 +238,7 @@ class WinRMExecutor(Executor[subprocess.CompletedProcess]):
             # Remote errors are represented as a normal non-zero completion;
             # check=False must be able to inspect them.
             err = detail.encode(encoding or "utf-8", errors or "replace")
-        if text or encoding is not None or errors is not None:
+        if wants_text(text, encoding, errors):
             codec = encoding or "utf-8"
             out = out.decode(codec, errors or "strict")
             err = err.decode(codec, errors or "strict")

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/host/_common.py

@@ -834,9 +834,10 @@ class Host(_abc.ABC, metaclass=_HostMeta):
         """Run commands and return a subprocess-compatible result.
 
         A string is verbatim shell text.  A tuple/list is one quoted argv
-        command.  A leading :class:`pathlib.PurePath`/``pathlib_next`` path is
-        a direct executable and all trailing values are its argv arguments.
-        Otherwise multiple top-level commands are joined by the selected
+        command.  :class:`Exec` is the only direct-execution spelling: it runs
+        one program with an argv and no shell layer, and it cannot be combined
+        with other commands.  A path anywhere else is an ordinary value that
+        stringifies.  Multiple top-level commands are joined by the selected
         shell's command separator.
         """
         raise NotImplementedError(

{hostctl-0.2.5 → hostctl-0.2.7}/src/hostctl/host/_ssh.py

@@ -24,6 +24,13 @@ from ..provider import (
 )
 
 log = logging.getLogger("hostctl.host.ssh")
+
+#: RFC 3986 `pchar`, plus `/`.  Everything legal in a URI path segment is
+#: left as written -- including `:` so a Windows-flavoured remote path still
+#: reads as `sftp://host:22/C:/Temp` -- while `%`, `?`, `#`, space, and
+#: non-ASCII are percent-encoded, because those are what a URI parser would
+#: otherwise take for syntax.
+_URI_PATH_SAFE = "/:@-._~!$&'()*+,;="
 from ..process import Process, SshProcess, TerminalRequest
 from ._common import (
     CaptureOutput,
@@ -392,8 +399,14 @@ class _SshTransport:
                 self._sftp_backend = AsyncsshSftpBackend(
                     connect_opts=self.config.connect_opts()
                 )
+            # The remote path becomes part of a URI, so it has to be encoded
+            # as one. `pathlib_next` parses with `uritools.urisplit` and then
+            # uridecodes the components: a raw `?` or `#` in a filename was
+            # taken as the start of the query or fragment and truncated the
+            # path, and a genuine `%xx` was decoded into a different name.
             path = SftpPath(
-                f"sftp://{uri_host(self.config.host)}:{self.config.port or 22}{remote_path}",
+                f"sftp://{uri_host(self.config.host)}:{self.config.port or 22}"
+                f"{quote(remote_path, safe=_URI_PATH_SAFE)}",
                 backend=self._sftp_backend,
             )
             self._sftp_sources.add(path.source)