hostctl 0.1.2__tar.gz → 0.2.0__tar.gz

{hostctl-0.1.2 → hostctl-0.2.0}/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-28
+
+### Added
+
+- `Exec(program, *args)` marks one command for direct execution: the program
+  runs with that argv and no shell layer renders. The program and every
+  argument may be a `str`, `bytes`, or a path object — all reach the transport
+  as text, so the spelling records how the caller held the value rather than
+  changing what runs. A **bare program name is now possible**
+  (`Exec("ls", "-l")`), resolved through the target's `PATH`; it previously had
+  no spelling at all, because a plain string command is always shell text.
+- The full `run()` command syntax is documented in the "Running commands"
+  guide: the varargs rule, the three command forms, operators, validation, and
+  the PowerShell rendering.
+
+### Changed
+
+- **Breaking.** Direct execution is marked by `Exec`, not by position. A path
+  in the first argument used to mean "this is the executable, the rest is
+  argv"; a path is now an ordinary value that stringifies wherever it appears.
+
+  ```python
+  host.run(Path("/bin/ls"), "-l")   # before: direct execution
+  host.run(Exec("/bin/ls", "-l"))   # now
+  ```
+
+  This is a **silent** change for the old spelling: `run(Path(...), *args)`
+  still succeeds, but the values become several `;`-joined shell commands
+  instead of one program and its argv, so arguments are subject to shell
+  quoting and word-splitting. Anything passing a leading path must be updated;
+  there is no deprecation shim.
+
+  What it buys, both unspellable before: several path commands in one call
+  (`run(p1, p2)` is two commands), and direct execution of a `PATH`-resolved
+  name.
+
+  An `Exec` cannot be combined with other commands in one call — there is no
+  shell to join them with, and running only one would silently drop the rest.
+  It raises `TypeError` rather than choosing.
+- `hostctl run` passes its operand as a single `Exec`, so the program is used
+  verbatim. It no longer converts the operand through the target shell's path
+  flavour, which means a bare name now resolves through the target's `PATH`
+  instead of being treated as a relative path.
+
 ## [0.1.2] - 2026-07-28
 
 Supersedes 0.1.1, which was tagged but never published: a release-gate test
@@ -186,6 +230,7 @@ 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.1.2...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jose-pr/hostctl/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/jose-pr/hostctl/compare/v0.1.0...v0.1.2
 [0.1.0]: https://github.com/jose-pr/hostctl/releases/tag/v0.1.0

{hostctl-0.1.2 → hostctl-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hostctl
-Version: 0.1.2
+Version: 0.2.0
 Summary: Run commands and access files on a host, local or remote, protocol-agnostic
 Project-URL: Homepage, https://github.com/jose-pr/hostctl/
 Project-URL: Documentation, https://jose-pr.github.io/hostctl/
@@ -172,6 +172,22 @@ with Host("ssh://admin:secret@nas.example.com") as same_host:
     same_host.run("uptime")
 ```
 
+`run()` takes one positional argument per command, so a `list` is a single
+command whose elements are each quoted, not a list of commands:
+
+```python
+host.run(["chmod", "755", target])                          # one command
+host.run(["chmod", "755", target], ["chown", "u", target])  # two commands
+host.run("chmod", "755", target)                            # WRONG: three commands
+```
+
+A raw string is verbatim shell text, and `Exec(program, *args)` is direct
+execution — one program plus argv, with no shell layer, where the program may
+be an absolute path or a bare name resolved through the target's `PATH`. A
+`ShellOperator` between two commands joins them conditionally. See the
+[running commands guide](https://jose-pr.github.io/hostctl/guide/run/) for the
+full rules.
+
 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

{hostctl-0.1.2 → hostctl-0.2.0}/README.md

@@ -118,6 +118,22 @@ with Host("ssh://admin:secret@nas.example.com") as same_host:
     same_host.run("uptime")
 ```
 
+`run()` takes one positional argument per command, so a `list` is a single
+command whose elements are each quoted, not a list of commands:
+
+```python
+host.run(["chmod", "755", target])                          # one command
+host.run(["chmod", "755", target], ["chown", "u", target])  # two commands
+host.run("chmod", "755", target)                            # WRONG: three commands
+```
+
+A raw string is verbatim shell text, and `Exec(program, *args)` is direct
+execution — one program plus argv, with no shell layer, where the program may
+be an absolute path or a bare name resolved through the target's `PATH`. A
+`ShellOperator` between two commands joins them conditionally. See the
+[running commands guide](https://jose-pr.github.io/hostctl/guide/run/) for the
+full rules.
+
 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

{hostctl-0.1.2 → hostctl-0.2.0}/docs/api/reference.md

@@ -39,6 +39,7 @@ without a deprecation cycle.
 
 ## Executors and processes
 
+::: hostctl.Exec
 ::: hostctl.Executor
 ::: hostctl.ExecutionOptions
 ::: hostctl.LocalExecutor

{hostctl-0.1.2 → hostctl-0.2.0}/docs/guide/run.md

@@ -12,10 +12,113 @@ result = host.run("echo hello")
 print(result.stdout)
 ```
 
+## Command syntax
+
+`run(*cmds, **options)` takes **one positional argument per command** — it is
+varargs, not a list of commands. This is the distinction to get right:
+
+```python
+host.run(["chmod", "755", target])                      # ONE command
+host.run(["chmod", "755", target], ["chown", "u", target])  # TWO commands
+```
+
+A list is *one* command whose elements are quoted individually. Wrapping
+commands in an outer list does not produce several commands — the inner lists
+are stringified into a single nonsensical argument:
+
+```python
+host.run([["chmod", "755", target]])   # WRONG: one command, mangled
+```
+
+The mirror mistake is passing an argv as separate positionals, which makes each
+element its own command:
+
+```python
+host.run("chmod", "755", target)       # WRONG: runs chmod;755;/path
+```
+
+### The three forms a command may take
+
+| Form | Example | Result |
+| --- | --- | --- |
+| Structured `list`/`tuple` | `["chmod", "755", p]` | `chmod 755 '/tmp/a b'` — every element quoted as data |
+| Raw `str` | `"echo $HOME"` | verbatim shell text; globs, pipes, and `$VAR` are interpreted |
+| `Exec(...)` | `Exec("/bin/ls", "-l", p)` | direct execution: one program plus argv, no shell |
+
+Prefer the structured form. It quotes each element, so a value containing a
+space, quote, `$`, or `;` is passed as data instead of changing the command.
+Use a raw string only when you want the shell to interpret the text.
+
+Elements may be `str`, `bytes`, `int`, or path objects; all are normalized and
+quoted. `["echo", 42, b"by", PurePosixPath("/p q")]` renders as
+`echo 42 by '/p q'`.
+
+### Joining and operators
+
+Commands are joined with the flavour's separator (`;` on POSIX). Pass a
+`ShellOperator` *between* two commands to join them conditionally instead:
+
+```python
+from hostctl import ShellOperator
+
+host.run(["test", "-f", target], ShellOperator.AND, ["rm", target])
+```
+
+`ShellOperator` provides `AND`, `OR`, `PIPE`, `REDIRECT`, `APPEND`, and
+`SEQUENCE`. An operator that is leading, trailing, or adjacent to another
+raises `ValueError`, and a flavour may reject one it cannot represent
+portably — PowerShell 5 rejects `AND`/`OR`, while PowerShell 7 accepts them.
+
+### `Exec` is direct execution
+
+`Exec(program, *args)` runs one program with an argv, with no shell layer
+rendered — nothing quotes, splits, or interprets the values:
+
+```python
+from hostctl import Exec
+
+host.run(Exec("/bin/ls", "-l", target))   # absolute path
+host.run(Exec("ls", "-l"))                # resolved through the target's PATH
+```
+
+The program and each argument may be a `str`, `bytes`, or a path object. All
+of them reach the transport as text, so the spelling records how you happened
+to hold the value rather than changing what runs. A bare name is only possible
+here: a plain string command is always shell text.
+
+Arguments are argv values, never nested commands — a list or tuple raises
+`TypeError` rather than blurring the two.
+
+Direct execution replaces the whole call, so an `Exec` cannot be combined with
+other commands: there is no shell to join them with, and running just one
+would silently drop the rest. Give each its own call, or use structured
+commands if you want them joined.
+
+Everything else is an ordinary value. A path is just a value that
+stringifies, wherever it appears:
+
+```python
+host.run(["chmod", "755", Path("/srv/app")])   # a quoted argument
+host.run(Path("/bin/a"), Path("/bin/b"))       # two shell commands
+```
+
+### Validation
+
+An empty structured command and any control character (including a newline
+inside a value, which could otherwise smuggle in a second command) raise
+`ValueError`. An empty raw string is skipped when joining.
+
+### PowerShell targets
+
+PowerShell flavours render a structured command through the `&` call operator
+and append `; exit $LASTEXITCODE` so the remote status propagates:
+
+```
+& 'Get-Item' 'C:/a b'; exit $LASTEXITCODE
+```
+
 `run()` returns a `subprocess.CompletedProcess`. Highlights:
 
-- Multiple positional commands are joined with `;`. A command given as a
-  `list`/`tuple` is shell-quoted piece by piece.
 - `capture_output` may be `True` (both streams), `"stdout"`, `"stderr"`, or
   `False`.
 - SSH `input=`, `cwd=`, `env=`, `check=`, `timeout=`, and

{hostctl-0.1.2 → hostctl-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.1.2"
+version = "0.2.0"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"

{hostctl-0.1.2 → hostctl-0.2.0}/src/hostctl/AGENTS.md

@@ -57,9 +57,20 @@ 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.
+`Exec(program, *args)` is the direct-execution marker for `Host.run()`: one
+program plus argv, no shell layer. The program may be a `str`, `bytes`, or a
+path — all reach the transport as text, so a bare name resolves through the
+target's `PATH`. Direct execution replaces the whole call, so an `Exec`
+combined with any other command raises. Everything else is an ordinary value:
+a path is a value that stringifies wherever it appears, so `run(p1, p2)` is two
+shell commands. `Exec` is a deliberately non-iterable frozen dataclass --
+`ShellFlavour.command_text` dispatches structured commands on `Iterable`, and
+an iterable marker would be quoted into an argv instead of taking the direct
+branch; `command_text` raises if an `Exec` reaches it.
+`Shell.execute(command, *args)` keeps its own program-plus-argv signature and
+wraps into an `Exec` only when dispatching to a host `run(*cmds)` and only when
+argv values are present -- `Shell.run` renders every command into one script
+and dispatches it with no args, and that script is shell text, not a program.
 
 ## Configuration and lifecycle
 

{hostctl-0.1.2 → hostctl-0.2.0}/src/hostctl/__init__.py

@@ -34,6 +34,7 @@ from .executor import (
 from .host import (
     ContainerConfig as ContainerConfig,
     ContainerHost as ContainerHost,
+    Exec as Exec,
     Host as Host,
     HostConfig as HostConfig,
     HostInfo as HostInfo,
@@ -146,6 +147,7 @@ __all__ = [
     "IosConfig",
     "IosHost",
     # Executors and processes
+    "Exec",
     "Executor",
     "ExecutionOptions",
     "ExecutorCapability",

{hostctl-0.1.2 → hostctl-0.2.0}/src/hostctl/_cli.py

@@ -8,7 +8,6 @@ import dataclasses
 import getpass
 import json
 import os
-from pathlib import PurePath
 import re
 import subprocess
 import sys
@@ -17,7 +16,7 @@ import typing
 
 from pathlib_next import Path as NextPath
 
-from .host import Host, HostPath
+from .host import Exec, Host, HostPath
 
 _URI_OPERAND = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 
@@ -81,13 +80,11 @@ def _command_run(args: argparse.Namespace, stdout, stderr) -> int:
     if not command:
         raise ValueError("run requires a command after --")
     with Host(args.uri, **_credentials(args)) as host:
-        try:
-            command_path = host.shell_flavour.command_path(command[0])
-        except NotImplementedError:
-            command_path = PurePath(command[0])
+        # `Exec` marks direct execution and takes the program verbatim, so the
+        # operand needs no path flavour: a bare name resolves through the
+        # target's PATH and an absolute path is used as given.
         result = host.run(
-            command_path,
-            *command[1:],
+            Exec(command[0], *command[1:]),
             check=False,
             capture_output=True,
         )

{hostctl-0.1.2 → hostctl-0.2.0}/src/hostctl/host/__init__.py

@@ -1,6 +1,7 @@
 """Host contracts and built-in host implementations."""
 
 from ._common import (
+    Exec as Exec,
     Host as Host,
     HostConfig as HostConfig,
     HostInfo as HostInfo,

{hostctl-0.1.2 → hostctl-0.2.0}/src/hostctl/host/_common.py

@@ -35,30 +35,81 @@ if _ty.TYPE_CHECKING:
     from ..process import Process, TerminalRequest
     from ..shell import Shell, ShellFlavour
 
-Command = _ty.Union[str, PathLike, _ty.Sequence[object]]
+#: One argv value. Everything reaching a transport is text, so a program or
+#: argument may be spelled as a string, bytes, or a path object
+#: interchangeably -- the spelling records how the caller held the value, not
+#: what crosses the wire.
+ExecValue = _ty.Union[str, bytes, _PurePath, _Pathname]
+
+
+@_dc.dataclass(frozen=True)
+class Exec:
+    """One command executed directly, with no shell layer.
+
+    ``Exec(program, *args)`` names a program and its argv. The program may be
+    an absolute path or a bare name the target resolves through ``PATH``; a
+    bare name has no other spelling, since a plain string is always shell text.
+
+    This is the explicit marker for direct execution. A path used anywhere
+    else is an ordinary value that stringifies, so several commands can be
+    written without one of them silently becoming an executable::
+
+        host.run(Exec("/bin/ls", "-l"))       # one direct command
+        host.run(Exec("ls", "-l"))            # PATH-resolved, no shell
+        host.run(Exec("/bin/a"), Exec("/bin/b"))   # two direct commands
+        host.run(PurePosixPath("/bin/a"), PurePosixPath("/bin/b"))
+                                              # two ordinary shell commands
+
+    Arguments are argv values, never nested commands: a list or tuple raises
+    ``TypeError`` rather than blurring argv and shell semantics.
+
+    A deliberately non-iterable container. `ShellFlavour.command_text`
+    dispatches structured commands on ``Iterable``, so an iterable marker
+    would be quoted into an argv string instead of taking the direct branch.
+    """
+
+    program: ExecValue
+    args: _ty.Tuple[ExecValue, ...]
+
+    def __init__(self, program: ExecValue, *args: ExecValue) -> None:
+        if not isinstance(program, (str, bytes, _PurePath, _Pathname)):
+            raise TypeError("Exec program must be a str, bytes, or path value")
+        for value in args:
+            if isinstance(value, (tuple, list)):
+                raise TypeError("direct command arguments must be scalar values")
+            if not isinstance(value, (str, bytes, _PurePath, _Pathname)):
+                raise TypeError(
+                    "direct command arguments must be str, bytes, or path values"
+                )
+        object.__setattr__(self, "program", program)
+        object.__setattr__(self, "args", tuple(args))
+
+
+Command = _ty.Union[str, PathLike, Exec, _ty.Sequence[object]]
 
 
 def starts_direct_command(
     cmds: _ty.Sequence[Command],
-) -> _ty.Optional[_ty.Tuple[_ty.Union[_PurePath, _Pathname], _ty.Tuple[object, ...]]]:
-    """Split a path-led call into one executable and its argv arguments.
+) -> _ty.Optional[_ty.Tuple[ExecValue, _ty.Tuple[object, ...]]]:
+    """Split an :class:`Exec` call into one executable and its argv arguments.
 
-    A leading path object is the explicit direct-execution marker.  Every
-    trailing value is an argv scalar; nested command sequences are rejected so
-    callers cannot accidentally mix shell-command and argv semantics.
+    Returns ``None`` unless the call is exactly one `Exec`. Direct execution
+    replaces the whole command list rather than joining with anything, so an
+    `Exec` alongside other commands is rejected: there is no shell to join
+    them with, and silently running only one would lose the rest.
     """
-    if not cmds or not isinstance(cmds[0], (_PurePath, _Pathname)):
+    if not cmds:
         return None
-    command = cmds[0]
-    argv = tuple(cmds[1:])
-    for value in argv:
-        if isinstance(value, (tuple, list)):
-            raise TypeError("direct command arguments must be scalar values")
-        if not isinstance(value, (str, bytes, _PurePath, _Pathname)):
-            raise TypeError(
-                "direct command arguments must be str, bytes, or path values"
-            )
-    return command, argv
+    marked = [value for value in cmds if isinstance(value, Exec)]
+    if not marked:
+        return None
+    if len(cmds) > 1:
+        raise TypeError(
+            "a direct Exec command cannot be combined with other commands; "
+            "run it in its own call"
+        )
+    command = marked[0]
+    return command.program, command.args
 
 
 @_dc.dataclass(frozen=True)

{hostctl-0.1.2 → hostctl-0.2.0}/src/hostctl/shell/_common.py

@@ -24,6 +24,7 @@ from ..host._common import (
     CaptureOutput,
     Command,
     Environment,
+    Exec,
     FileHandle,
     Input,
     PathLike,
@@ -197,6 +198,15 @@ class ShellFlavour(abc.ABC):
         return self.command_separator.join(assignments)
 
     def command_text(self, value: Command) -> str:
+        if isinstance(value, Exec):
+            # Direct execution bypasses the shell entirely, so an `Exec` that
+            # reaches here means a transport did not take its direct branch.
+            # Rendering it as a quoted argv would silently reintroduce the
+            # shell layer the caller asked to skip.
+            raise TypeError(
+                "Exec is executed directly and cannot be rendered into a shell "
+                "script; this host does not support direct execution"
+            )
         if isinstance(value, (bytes, PurePath, Path, os.PathLike)):
             return self.quote(value)
         if isinstance(value, str):
@@ -340,6 +350,24 @@ class Shell(Executor[_Result], typing.Generic[_Result]):
             item.kind is inspect.Parameter.VAR_KEYWORD
             for item in self._executor_parameters.values()
         )
+        # A host `run(*cmds)` takes several *commands*; an executor
+        # `__call__(command, *args)` takes one command and its argv. Only the
+        # former needs the program and argv bundled into one `Exec`, since
+        # otherwise each argument would become a separate command. The shapes
+        # differ in their first parameter: VAR_POSITIONAL vs a named one.
+        positional = [
+            item
+            for item in self._executor_parameters.values()
+            if item.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                inspect.Parameter.VAR_POSITIONAL,
+            )
+        ]
+        self._execute_takes_commands = bool(positional) and (
+            positional[0].kind is inspect.Parameter.VAR_POSITIONAL
+        )
         published = getattr(executor, "executor_capabilities", None)
         if published is None:
             inferred = set()
@@ -467,6 +495,14 @@ class Shell(Executor[_Result], typing.Generic[_Result]):
         ]
         if unsupported:
             raise TypeError(f"executor does not accept {sorted(unsupported)[0]}")
+        if executor_args and self._execute_takes_commands:
+            # A host `run(*cmds)` treats several positionals as several
+            # commands, so a program and its argv must arrive as one `Exec`
+            # rather than relying on position to mark direct execution.
+            # Only when there *are* argv values: `Shell.run` renders every
+            # command into one script and dispatches it here with no args, and
+            # that script is shell text to interpret, not a program to exec.
+            return self._execute(Exec(command, *executor_args), **options)
         return self._execute(command, *executor_args, **options)
 
     __call__ = execute

{hostctl-0.1.2 → hostctl-0.2.0}/tests/conformance/test_live.py

@@ -13,6 +13,8 @@ from pathlib import Path
 
 import pytest
 
+from hostctl import Exec
+
 from .providers import live_providers, provider_context
 
 
@@ -22,7 +24,7 @@ def test_live_provider_direct_command(provider):
         pytest.skip(f"{provider.name} does not advertise run")
     with provider_context(provider) as host:
         if provider.name == "local":
-            result = host.run(Path(sys.executable), "-c", "print('live')")
+            result = host.run(Exec(sys.executable, "-c", "print('live')"))
         else:
             command = (
                 "Write-Output live"

{hostctl-0.1.2 → hostctl-0.2.0}/tests/conformance/test_run_contract.py

@@ -10,6 +10,8 @@ from pathlib import Path
 
 import pytest
 
+from hostctl import Exec
+
 from .providers import fake_providers, live_providers, provider_context
 
 
@@ -24,10 +26,12 @@ def test_direct_argv_and_capture(provider):
         pytest.skip(f"{provider.name} has no run capability")
     with provider_context(provider) as host:
         result = host.run(
-            Path(sys.executable),
-            "-c",
-            "import sys; print(sys.argv[1]); print('err', file=sys.stderr)",
-            "a & b",
+            Exec(
+                sys.executable,
+                "-c",
+                "import sys; print(sys.argv[1]); print('err', file=sys.stderr)",
+                "a & b",
+            )
         )
     assert result.returncode == 0
     assert result.stdout == b"a & b\r\n" if os.name == "nt" else b"a & b\n"
@@ -48,19 +52,17 @@ def test_text_env_and_nonzero_check(provider):
         environment["SystemRoot"] = os.environ["SystemRoot"]
     with provider_context(provider) as host:
         result = host.run(
-            Path(sys.executable),
-            "-c",
-            code,
+            Exec(sys.executable, "-c", code),
             env=environment,
             text=True,
         )
         assert result.stdout.splitlines()[0] == "42"
         failed = host.run(
-            Path(sys.executable), "-c", "raise SystemExit(3)", check=False
+            Exec(sys.executable, "-c", "raise SystemExit(3)"), check=False
         )
         assert failed.returncode == 3
         with pytest.raises(subprocess.CalledProcessError):
-            host.run(Path(sys.executable), "-c", "raise SystemExit(4)")
+            host.run(Exec(sys.executable, "-c", "raise SystemExit(4)"))
 
 
 @pytest.mark.parametrize("provider", fake_providers(), ids=lambda p: p.name)
@@ -71,9 +73,7 @@ def test_cwd_is_applied_only_when_supported(provider, tmp_path):
         pytest.skip(f"{provider.name} does not support cwd")
     with provider_context(provider) as host:
         result = host.run(
-            Path(sys.executable),
-            "-c",
-            "import pathlib; print(pathlib.Path.cwd())",
+            Exec(sys.executable, "-c", "import pathlib; print(pathlib.Path.cwd())"),
             cwd=tmp_path,
             text=True,
         )
@@ -85,7 +85,7 @@ def test_silent_capture_is_empty_bytes(provider):
     if "run" not in provider.capabilities:
         pytest.skip(f"{provider.name} has no run capability")
     with provider_context(provider) as host:
-        result = host.run(Path(sys.executable), "-c", "pass")
+        result = host.run(Exec(sys.executable, "-c", "pass"))
     assert result.stdout == b""
     assert result.stderr == b""
 
@@ -118,14 +118,12 @@ def test_timeout_and_input_are_subprocess_compatible(provider):
         pytest.skip(f"{provider.name} does not support {', '.join(sorted(missing))}")
     with provider_context(provider) as host:
         result = host.run(
-            Path(sys.executable),
-            "-c",
-            "import sys; print(sys.stdin.read())",
+            Exec(sys.executable, "-c", "import sys; print(sys.stdin.read())"),
             input="payload",
             text=True,
         )
         assert result.stdout.strip() == "payload"
         with pytest.raises(subprocess.TimeoutExpired):
             host.run(
-                Path(sys.executable), "-c", "import time; time.sleep(2)", timeout=0.01
+                Exec(sys.executable, "-c", "import time; time.sleep(2)"), timeout=0.01
             )

{hostctl-0.1.2 → hostctl-0.2.0}/tests/test_cli.py

@@ -2,10 +2,9 @@ import io
 import json
 import subprocess
 import types
-from pathlib import PurePosixPath
-
 import pytest
 
+from hostctl import Exec
 from hostctl._cli import _parser, main
 
 
@@ -36,7 +35,7 @@ def test_run_propagates_status_and_streams():
     assert stderr.getvalue().strip() == b"err"
 
 
-def test_run_marks_direct_command_with_target_shell_path_flavour(monkeypatch):
+def test_run_marks_the_operand_as_one_direct_command(monkeypatch):
     seen = []
 
     class _Host:
@@ -56,8 +55,11 @@ def test_run_marks_direct_command_with_target_shell_path_flavour(monkeypatch):
 
     monkeypatch.setattr("hostctl._cli.Host", lambda *args, **kwargs: _Host())
 
+    # One `Exec`, not a leading path plus positionals: the operand is a single
+    # direct command, and the program is passed verbatim so a bare name
+    # resolves through the target's PATH.
     assert main(["run", "ssh://host", "--", "/bin/sh", "-c", "true"]) == 0
-    assert seen == [(PurePosixPath("/bin/sh"), "-c", "true")]
+    assert seen == [(Exec("/bin/sh", "-c", "true"),)]
 
 
 def test_cat_ls_cp_and_info(tmp_path):

hostctl-0.2.0/tests/test_exec_command.py

@@ -0,0 +1,122 @@
+"""`Exec` marks direct execution explicitly, rather than by position."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import PurePosixPath
+
+import pytest
+from pathlib_next import PosixPathname
+
+from hostctl import Exec, LocalHost, POSIX_SHELL, POWERSHELL
+from hostctl.host._common import starts_direct_command
+
+
+def test_exec_accepts_str_bytes_and_path_programs():
+    # Everything reaching a transport is text, so how the caller held the
+    # value is not meant to change what runs.
+    for program in (
+        "/bin/ls",
+        b"/bin/ls",
+        PurePosixPath("/bin/ls"),
+        PosixPathname("/bin/ls"),
+    ):
+        command = Exec(program, "-l")
+        assert command.program == program
+        assert command.args == ("-l",)
+
+
+def test_exec_is_not_iterable_so_a_shell_cannot_quote_it_as_argv():
+    # `ShellFlavour.command_text` dispatches structured commands on Iterable.
+    # An iterable marker would be silently rendered into a quoted argv,
+    # reintroducing the shell layer the caller asked to skip.
+    import collections.abc
+
+    assert not isinstance(Exec("ls"), collections.abc.Iterable)
+
+
+def test_exec_reaching_a_shell_script_raises_rather_than_being_rendered():
+    with pytest.raises(TypeError, match="executed directly"):
+        POSIX_SHELL.script([Exec("ls", "-l")])
+
+
+def test_exec_rejects_nested_commands_and_non_scalar_values():
+    with pytest.raises(TypeError, match="scalar values"):
+        Exec("ls", ["nested"])
+    with pytest.raises(TypeError, match="program must be"):
+        Exec(["ls"])
+    with pytest.raises(TypeError, match="program must be"):
+        Exec(42)
+
+
+def test_exec_dispatches_as_one_direct_command():
+    assert starts_direct_command([Exec("/bin/ls", "-l")]) == ("/bin/ls", ("-l",))
+
+
+def test_exec_cannot_be_combined_with_other_commands():
+    # There is no shell to join them with, and running only one would
+    # silently drop the rest.
+    with pytest.raises(TypeError, match="cannot be combined"):
+        starts_direct_command([Exec("/bin/a"), Exec("/bin/b")])
+    with pytest.raises(TypeError, match="cannot be combined"):
+        starts_direct_command([Exec("/bin/a"), "echo hi"])
+
+
+def test_a_bare_path_is_an_ordinary_value_not_an_executable():
+    # The change this makes possible: several paths are several commands,
+    # because no position is special any more.
+    assert (
+        starts_direct_command([PurePosixPath("/bin/a"), PurePosixPath("/bin/b")])
+        is None
+    )
+    assert (
+        POSIX_SHELL.script([PurePosixPath("/bin/a"), PurePosixPath("/bin/b")])
+        == "/bin/a;/bin/b"
+    )
+
+
+def test_a_path_inside_a_structured_command_stays_a_quoted_argument():
+    assert (
+        POSIX_SHELL.script([["chmod", "755", PurePosixPath("/srv/a b")]])
+        == "chmod 755 '/srv/a b'"
+    )
+
+
+def test_local_exec_runs_the_program_without_a_shell():
+    result = LocalHost().run(
+        Exec(sys.executable, "-c", "import sys; print(sys.argv[1])", "a & b"),
+        text=True,
+    )
+
+    # `a & b` survives verbatim: no shell interpreted the `&`.
+    assert result.stdout.strip() == "a & b"
+
+
+def test_local_exec_resolves_a_bare_program_name_through_path():
+    # Previously unspellable: a bare string is always shell text, so direct
+    # execution required knowing an absolute path.
+    name = "cmd.exe" if sys.platform == "win32" else "echo"
+    args = ("/c", "echo", "hi") if sys.platform == "win32" else ("hi",)
+
+    result = LocalHost().run(Exec(name, *args), text=True)
+
+    assert result.stdout.strip() == "hi"
+
+
+def test_local_exec_reports_status_like_subprocess():
+    failed = LocalHost().run(
+        Exec(sys.executable, "-c", "raise SystemExit(3)"), check=False
+    )
+    assert failed.returncode == 3
+
+    with pytest.raises(subprocess.CalledProcessError):
+        LocalHost().run(Exec(sys.executable, "-c", "raise SystemExit(4)"))
+
+
+def test_powershell_structured_command_still_renders_through_the_call_operator():
+    # `Exec` changes direct execution only; structured commands are untouched.
+    assert (
+        POWERSHELL.script([["Get-Item", "C:/a b"]])
+        == "& 'Get-Item' 'C:/a b'; exit $LASTEXITCODE"
+    )

{hostctl-0.1.2 → hostctl-0.2.0}/tests/test_host_container.py

@@ -8,6 +8,7 @@ from pathlib import PurePosixPath
 
 import pytest
 
+from hostctl import Exec
 from hostctl.host._common import HostConfig
 from hostctl.executor.container import normalize_container_error
 from hostctl.host.container import ContainerConfig, ContainerHost
@@ -124,8 +125,7 @@ def test_container_auto_shell_uses_inspected_os(os_name, flavour):
 def test_container_direct_argv_preserves_arguments_and_context():
     host, _, container = _host(user="1000", workdir="/default")
     result = host.run(
-        PurePosixPath("/opt/my tool"),
-        "value with spaces",
+        Exec(PurePosixPath("/opt/my tool"), "value with spaces"),
         cwd="/override",
         env={"COUNT": 3},
         text=True,

{hostctl-0.1.2 → hostctl-0.2.0}/tests/test_system_hosts.py

@@ -5,6 +5,7 @@ import pytest
 from pathlib_next.mempath import MemPath, MemPathBackend
 
 from hostctl import (
+    Exec,
     HostConfig,
     OperationNotStarted,
     PathProvider,
@@ -168,7 +169,7 @@ def test_direct_path_command_without_argv_capability_renders_one_quoted_command(
         return subprocess.CompletedProcess((command, *args), 0, b"ok", b"")
 
     host = PosixHost(executor_providers=(ExecutorProvider("shell", execute),))
-    host.run(HostPath("printf"), "a & b", check=False)
+    host.run(Exec("printf", "a & b"), check=False)
 
     assert len(calls) == 1
     rendered, args = calls[0]
@@ -191,7 +192,7 @@ def test_executor_fallback_replans_capabilities_before_retrying():
     first = ExecutorProvider("first", declined, capabilities=("args", "cwd"))
     second = ExecutorProvider("second", selected)
     host = PosixHost(executor_providers=(first, second))
-    host.run(HostPath("printf"), "a & b", cwd="/tmp", check=False)
+    host.run(Exec("printf", "a & b"), cwd="/tmp", check=False)
 
     assert calls[0][0] == "first"
     assert calls[1][0] == "second"