shellsafe 0.1.1__tar.gz → 0.2.0__tar.gz

shellsafe-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+Keep a Changelog; versioning follows SemVer.
+
+## [0.2.0] - 2026-08-27
+
+### Added
+
+- Shell-mode execution: `shx()` runs pipes, redirections, and globs via
+  `/bin/sh -c` on Linux and macOS; interpolated values are `shlex`-quoted
+  automatically
+- Shell-mode payload corpus: 15 injection cases verified as single tokens via
+  `shlex.split` round-trip
+- Shell-mode property tests: arbitrary values stay single shell tokens under
+  pipe templates
+- Cyclomatic complexity lint (`C901`, max-complexity 10) enabled in CI
+
+### Changed
+
+- `run()` now rejects templates that contain shell metacharacters with guidance
+  to use `shx()` instead
+- CLI version matrix shows shell-mode availability
+
+### Removed
+
+- Dead `METACHARACTERS` constant from render.py (platforms.py owns it)
+
+## [0.1.1] - 2026-08-24
+
+### Changed
+
+- Project description rewritten
+- README restructured for PyPI: package page now leads with the why, usage and
+  limits; contributing details stay in the repository only
+
+## [0.1.0] - 2026-08-24
+
+### Added
+
+- Argv-mode rendering and execution via template strings
+- RAW trust marker with argv splicing
+- capture() helper with utf-8 stdout/stderr
+- plan() helper for inspecting commands before execution
+- Injection payload corpus as a release gate; all cases render inert

{shellsafe-0.1.1 → shellsafe-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.1.1
+Version: 0.2.0
 Summary: Run shell commands safely using Python 3.14 template strings. Values can never turn into commands.
 Project-URL: Repository, https://github.com/rahulXs/shellsafe
 Project-URL: Issues, https://github.com/rahulXs/shellsafe/issues
@@ -110,7 +110,10 @@ to find in code review, so trust is never hidden.
 
 ## Limits
 
-- On Windows, commands with pipes do not work. Plain commands work fully.
+- Shell features (pipes, redirections) work on Linux and macOS only. Windows
+  supports plain commands only.
+- `run()` refuses templates that contain shell metacharacters. Use `shx()` for
+  those.
 - Byte values are rejected. Decode them first.
 - We keep your command safe to build and run. Testing what your command does is
   still your job.

{shellsafe-0.1.1 → shellsafe-0.2.0}/README.md

@@ -88,7 +88,10 @@ to find in code review, so trust is never hidden.
 
 ## Limits
 
-- On Windows, commands with pipes do not work. Plain commands work fully.
+- Shell features (pipes, redirections) work on Linux and macOS only. Windows
+  supports plain commands only.
+- `run()` refuses templates that contain shell metacharacters. Use `shx()` for
+  those.
 - Byte values are rejected. Decode them first.
 - We keep your command safe to build and run. Testing what your command does is
   still your job.

{shellsafe-0.1.1 → shellsafe-0.2.0}/pyproject.toml

@@ -45,7 +45,10 @@ target-version = "py314"
 line-length = 100
 
 [tool.ruff.lint]
-select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF", "C901"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
 
 [tool.mypy]
 strict = true

shellsafe-0.2.0/src/shellsafe/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{shellsafe-0.1.1 → shellsafe-0.2.0}/src/shellsafe/cli.py

@@ -24,7 +24,7 @@ def _print_version_matrix() -> None:
     py = platform.python_version()
     print(f"shellsafe {__version__} · python {py} · {sys.platform}")
     print("argv-mode: available")
-    print("shell-mode: arriving in 0.2")
+    print("shell-mode: available (posix)")
     print("audit: arriving in 0.3")
 
 

{shellsafe-0.1.1 → shellsafe-0.2.0}/src/shellsafe/execute.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import subprocess
+import sys
 from dataclasses import dataclass
 from typing import Any, cast
 
@@ -10,11 +11,6 @@ from .errors import ArgvOnlyError, ShellSafeError
 from .raw import Raw  # noqa: F401  (re-exported through the package root)
 from .render import ExecutionPlan
 
-_SHELL_MODE_PENDS = (
-    "shell-mode execution arrives in shellsafe 0.2; "
-    "this release covers argv-mode commands"
-)
-
 _ALLOWED_KWARGS = frozenset(
     {
         "check",
@@ -36,8 +32,8 @@ _ALLOWED_KWARGS = frozenset(
 def _validate_kwargs(kwargs: dict[str, object]) -> None:
     if "shell" in kwargs:
         raise ShellSafeError(
-            "shellsafe never passes shell=True; use shx() on posix for pipes and "
-            "redirections"
+            "shellsafe never passes shell=True; use shx() for pipes and "
+            "redirections on posix"
         )
     unknown = set(kwargs) - _ALLOWED_KWARGS
     if unknown:
@@ -54,6 +50,14 @@ def plan(template: object) -> ExecutionPlan:
     return render_plan(template)
 
 
+def _pass_through(kwargs: dict[str, object]) -> dict[str, Any]:
+    """Filter kwargs to the allowed subprocess.run set."""
+    return cast(
+        "dict[str, Any]",
+        {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS},
+    )
+
+
 def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
     """Render the template and execute it.
 
@@ -64,14 +68,17 @@ def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[st
     _validate_kwargs(kwargs)
     rendered = plan(template)
     if rendered.mode == "shell":
-        raise ShellSafeError(_SHELL_MODE_PENDS)
+        if sys.platform.startswith("win"):
+            raise ShellSafeError(
+                "shell mode is posix-only; restructure the command without "
+                "pipes or redirections, or run under wsl"
+            )
+        raise ShellSafeError(
+            "this command contains shell metacharacters; use shx() instead of "
+            "run() to execute pipes and redirections"
+        )
     assert rendered.argv is not None
-    # passthrough boundary: values are caller-owned subprocess kwargs
-    typed_kwargs = cast(
-        "dict[str, Any]",
-        {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS},
-    )
-    result = subprocess.run(rendered.argv, **typed_kwargs)
+    result = subprocess.run(rendered.argv, **_pass_through(kwargs))
     return cast("subprocess.CompletedProcess[str]", result)
 
 
@@ -101,12 +108,12 @@ def capture(template: object, /, **kwargs: object) -> CaptureResult:
     )
 
 
-def shx(template: object, /, **kwargs: object) -> object:
-    """Shell-route alias for templates that need pipes or redirections.
+def shx(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
+    """Execute a shell-routed template (pipes, redirections, globs).
 
-    Raises ArgvOnlyError when the template needs no shell at all, so a missing
-    pipe is never silently ignored. Full shell execution ships in shellsafe 0.2;
-    rendering and inspection work today via shellsafe.plan().
+    Interpolated values are POSIX shell-quoted automatically. The rendered line
+    runs under /bin/sh -c. Raises ArgvOnlyError when the template has no shell
+    metacharacters (use run() instead).
     """
     _validate_kwargs(kwargs)
     rendered = plan(template)
@@ -114,4 +121,9 @@ def shx(template: object, /, **kwargs: object) -> object:
         raise ArgvOnlyError(
             "template contains no shell metacharacters; use run() instead"
         )
-    raise ShellSafeError(_SHELL_MODE_PENDS)
+    assert rendered.shell_line is not None
+    result = subprocess.run(
+        ["/bin/sh", "-c", rendered.shell_line],
+        **_pass_through(kwargs),
+    )
+    return cast("subprocess.CompletedProcess[str]", result)

{shellsafe-0.1.1 → shellsafe-0.2.0}/src/shellsafe/render.py

@@ -19,11 +19,6 @@ from .raw import Raw
 
 _NUL = "\x00"
 
-# Static-text characters that require shell semantics (pipes, redirection,
-# substitution, globs, comments). Whitespace is absent here: it splits words
-# in argv mode rather than forcing a shell.
-METACHARACTERS: frozenset[str] = frozenset("|&;()<>$`\"'*?!#\n\r\t\\")
-
 
 @dataclass(frozen=True, slots=True)
 class ExecutionPlan:
@@ -189,4 +184,7 @@ def _render_shell(parts: list[Segment]) -> ExecutionPlan:
             resolved = _resolve(part)
             _reject_nul(resolved)
             line_parts.append(shlex.quote(resolved))
-    return ExecutionPlan(mode="shell", shell_line="".join(line_parts))
+    line = "".join(line_parts).strip()
+    if not line:
+        raise ShellSafeTypeError("empty command")
+    return ExecutionPlan(mode="shell", shell_line=line)

shellsafe-0.2.0/tests/integration/test_exec_posix.py

@@ -0,0 +1,100 @@
+"""Real-execution integration tests (posix). Proves the end-to-end path."""
+
+import sys
+
+import pytest
+
+from shellsafe import capture, run, shx
+from shellsafe.errors import ArgvOnlyError, ShellSafeError, UnsupportedPlatformError
+
+# --- argv mode ---
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_capture_round_trip():
+    res = capture(t"echo hello")
+    assert res.returncode == 0
+    assert res.stdout == "hello\n"
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_injection_payload_arrives_as_text():
+    payload = "hello; echo PWNED"
+    res = capture(t"echo {payload}")
+    # argv mode: echo receives the whole payload as ONE argument; no second
+    # command can exist. The output is the payload text itself.
+    assert res.stdout.strip() == payload
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_interpolation_with_spaces_stays_one_argument():
+    value = "two words"
+    res = capture(t"echo {value}")
+    assert res.stdout.strip() == "two words"
+
+
+# --- shell mode execution ---
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_shx_pipe_execution():
+    res = shx(t"echo hello | wc -w", capture_output=True, text=True)
+    assert res.returncode == 0
+    assert res.stdout.strip() == "1"
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_shx_interpolation_is_quoted():
+    """Spaces in interpolated values do not split into separate tokens."""
+    res = shx(t"echo {['a', 'b']} | wc -w", capture_output=True, text=True)
+    assert res.returncode == 0
+    # echo ['a', 'b'] outputs the list repr as one argument; wc counts words
+    # in that output. The important thing: no shell error, no split.
+    assert res.returncode == 0
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_shx_injection_payload_is_quoted():
+    payload = "hello; echo PWNED"
+    res = shx(t"echo {payload} | cat", capture_output=True, text=True)
+    assert res.returncode == 0
+    assert res.stdout.strip() == payload
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_shx_output_capture():
+    res = shx(t"echo world | tr a-z A-Z", capture_output=True, text=True)
+    assert res.returncode == 0
+    assert res.stdout.strip() == "WORLD"
+
+
+# --- run() rejects shell mode ---
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_run_rejects_shell_metacharacters():
+    with pytest.raises(ShellSafeError, match="shx"):
+        run(t"echo hello | wc -l")
+
+
+# --- shx rejects argv-only templates ---
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
+def test_shx_rejects_argv_only_template():
+    with pytest.raises(ArgvOnlyError):
+        shx(t"echo hello")
+
+
+# --- Windows policy ---
+
+
+def test_shell_mode_execution_not_yet_available_on_windows():
+    p = t"cat /etc/hostname | wc -l"
+    if sys.platform == "win32":
+        with pytest.raises(UnsupportedPlatformError):
+            shx(p)
+    else:
+        # on posix, shell mode works; this test verifies the Windows refusal
+        # path is wired correctly via monkeypatch (see test_render.py)
+        pass

shellsafe-0.2.0/tests/property/test_invariants.py

@@ -0,0 +1,78 @@
+"""Property tests: invariants that must hold for arbitrary inputs."""
+
+import shlex
+import sys
+from string.templatelib import Interpolation, Template
+
+import pytest
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from shellsafe.render import plan
+
+# NUL bytes are refused at resolution; everything else must render safely.
+text_values = st.text(st.characters(blacklist_characters="\x00"), max_size=200)
+
+
+# --- argv mode invariants ---
+
+
+@settings(max_examples=300)
+@given(value=text_values)
+def test_one_interpolation_is_exactly_one_argument(value: str):
+    p = plan(Template("run ", Interpolation(value, "v", None, "")))
+    assert p.argv == ("run", value)
+
+
+@settings(max_examples=200)
+@given(a=text_values, b=text_values)
+def test_two_interpolations_stay_separate(a: str, b: str):
+    p = plan(
+        Template("copy ", Interpolation(a, "x", None, ""), " ", Interpolation(b, "y", None, ""))
+    )
+    assert p.argv == ("copy", a, b)
+
+
+@settings(max_examples=200)
+@given(value=text_values)
+def test_repr_round_trip_is_byte_stable(value: str):
+    p1 = plan(Template("run ", Interpolation(value, "v", None, "")))
+    p2 = plan(Template("run ", Interpolation(value, "v", None, "")))
+    assert repr(p1) == repr(p2)
+
+
+# --- shell mode invariants ---
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="shell mode is posix-only")
+@settings(max_examples=300)
+@given(value=text_values)
+def test_shell_interpolation_stays_single_token(value: str):
+    """INV-shell: under a pipe template, shlex.split yields value as one token."""
+    p = plan(Template("cat ", Interpolation(value, "v", None, ""), " | wc -l"))
+    assert p.mode == "shell"
+    assert p.shell_line is not None
+    tokens = shlex.split(p.shell_line)
+    # "cat", VALUE, "|", "wc", "-l" = 5 tokens
+    assert len(tokens) == 5
+    assert tokens[1] == value
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="shell mode is posix-only")
+@settings(max_examples=200)
+@given(a=text_values, b=text_values)
+def test_shell_two_interpolations_stay_separate(a: str, b: str):
+    """Two shell-mode interpolations must each occupy one token."""
+    p = plan(
+        Template(
+            "grep ", Interpolation(a, "x", None, ""), " ", Interpolation(b, "y", None, ""),
+            " | sort",
+        )
+    )
+    assert p.mode == "shell"
+    assert p.shell_line is not None
+    tokens = shlex.split(p.shell_line)
+    # "grep", A, B, "|", "sort" = 5 tokens
+    assert len(tokens) == 5
+    assert tokens[1] == a
+    assert tokens[2] == b

shellsafe-0.2.0/tests/unit/test_payload_corpus.py

@@ -0,0 +1,74 @@
+"""Payload corpus gate: every injection case renders inert.
+
+Argv mode: each .txt file in cases/ holds exactly one interpolated value. The
+command is argv mode "echo <value>"; the invariant under test: the value occupies
+exactly one argv element equal to the original payload. If any payload can escape
+into a second command, this suite fails and the release is blocked.
+
+Shell mode: the same payloads are tested under a pipe template. The invariant:
+shlex.split(rendered_line) yields the interpolated value as exactly one token
+equal to the original payload.
+"""
+
+import shlex
+import sys
+from pathlib import Path
+from string.templatelib import Interpolation, Template
+
+import pytest
+
+from shellsafe.render import plan
+
+CASES_DIR = Path(__file__).parent.parent / "payloads" / "cases"
+CASE_FILES = sorted(CASES_DIR.glob("case_*.txt"))
+
+
+def payloads() -> list[tuple[str, str]]:
+    out = []
+    for path in CASE_FILES:
+        raw = path.read_text()
+        # strip one trailing newline added by file storage; keep all else verbatim
+        value = raw[:-1] if raw.endswith("\n") else raw
+        out.append((path.stem, value))
+    return out
+
+
+# --- argv mode ---
+
+
+@pytest.mark.parametrize(
+    ("name", "payload"),
+    payloads(),
+    ids=[n for n, _ in payloads()],
+)
+def test_payload_stays_single_argument(name: str, payload: str):
+    p = plan(Template("echo ", Interpolation(payload, "value", None, "")))
+    assert p.mode == "argv"
+    assert p.argv == ("echo", payload)
+
+
+# --- shell mode ---
+
+
+@pytest.mark.parametrize(
+    ("name", "payload"),
+    payloads(),
+    ids=[n for n, _ in payloads()],
+)
+@pytest.mark.skipif(sys.platform == "win32", reason="shell mode is posix-only")
+def test_shell_payload_stays_single_token(name: str, payload: str):
+    """Pipe template: value must be shell-quoted, never splitting into tokens."""
+    p = plan(
+        Template("cat ", Interpolation(payload, "value", None, ""), " | wc -l")
+    )
+    assert p.mode == "shell"
+    assert p.shell_line is not None
+    tokens = shlex.split(p.shell_line)
+    # static tokens: "cat", "|", "wc", "-l"  (4); value must be exactly one
+    assert len(tokens) == 5
+    assert tokens[1] == payload
+
+
+def test_corpus_is_present():
+    # guard against silent corpus deletion
+    assert len(CASE_FILES) >= 10

shellsafe-0.1.1/CHANGELOG.md

@@ -1,22 +0,0 @@
-# Changelog
-
-All notable changes to this project are documented here. Format follows
-Keep a Changelog; versioning follows SemVer.
-
-## [0.1.1] - 2026-08-24
-
-### Changed
-
-- Project description rewritten
-- README restructured for PyPI: package page now leads with the why, usage and
-  limits; contributing details stay in the repository only
-
-## [0.1.0] - 2026-08-24
-
-### Added
-
-- Argv-mode rendering and execution via template strings
-- RAW trust marker with argv splicing
-- capture() helper with utf-8 stdout/stderr
-- plan() helper for inspecting commands before execution
-- Injection payload corpus as a release gate; all cases render inert

shellsafe-0.1.1/src/shellsafe/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.1"

shellsafe-0.1.1/tests/integration/test_exec_posix.py

@@ -1,44 +0,0 @@
-"""Real-execution integration tests (posix). Proves the end-to-end path."""
-
-import sys
-
-import pytest
-
-from shellsafe import capture, shx
-from shellsafe.errors import ShellSafeError, UnsupportedPlatformError
-
-
-@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
-def test_capture_round_trip():
-    res = capture(t"echo hello")
-    assert res.returncode == 0
-    assert res.stdout == "hello\n"
-
-
-@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
-def test_injection_payload_arrives_as_text():
-    payload = "hello; echo PWNED"
-    res = capture(t"echo {payload}")
-    # argv mode: echo receives the whole payload as ONE argument; no second
-    # command can exist. The output is the payload text itself.
-    assert res.stdout.strip() == payload
-
-
-@pytest.mark.skipif(sys.platform == "win32", reason="posix-only execution test")
-def test_interpolation_with_spaces_stays_one_argument():
-    value = "two words"
-    res = capture(t"echo {value}")
-    assert res.stdout.strip() == "two words"
-
-
-def test_shell_mode_execution_not_yet_available():
-    # posix: rendering works, execution gate is explicit until v0.2
-    # windows: the route itself is refused before any process spawns
-    p = t"cat /etc/hostname | wc -l"
-
-    if sys.platform == "win32":
-        with pytest.raises(UnsupportedPlatformError):
-            shx(p)
-    else:
-        with pytest.raises(ShellSafeError, match=r"0\.2"):
-            shx(p)

shellsafe-0.1.1/tests/property/test_invariants.py

@@ -1,35 +0,0 @@
-"""Property tests: invariants that must hold for arbitrary inputs."""
-
-from string.templatelib import Interpolation, Template
-
-from hypothesis import given, settings
-from hypothesis import strategies as st
-
-from shellsafe.render import plan
-
-# NUL bytes are refused at resolution; everything else must render safely.
-text_values = st.text(st.characters(blacklist_characters="\x00"), max_size=200)
-
-
-@settings(max_examples=300)
-@given(value=text_values)
-def test_one_interpolation_is_exactly_one_argument(value: str):
-    p = plan(Template("run ", Interpolation(value, "v", None, "")))
-    assert p.argv == ("run", value)
-
-
-@settings(max_examples=200)
-@given(a=text_values, b=text_values)
-def test_two_interpolations_stay_separate(a: str, b: str):
-    p = plan(
-        Template("copy ", Interpolation(a, "x", None, ""), " ", Interpolation(b, "y", None, ""))
-    )
-    assert p.argv == ("copy", a, b)
-
-
-@settings(max_examples=200)
-@given(value=text_values)
-def test_repr_round_trip_is_byte_stable(value: str):
-    p1 = plan(Template("run ", Interpolation(value, "v", None, "")))
-    p2 = plan(Template("run ", Interpolation(value, "v", None, "")))
-    assert repr(p1) == repr(p2)

shellsafe-0.1.1/tests/unit/test_payload_corpus.py

@@ -1,43 +0,0 @@
-"""Payload corpus gate: every injection case renders inert.
-
-Each .txt file in cases/ holds exactly one interpolated value. The command is
-argv mode "echo <value>"; the invariant under test: the value occupies exactly
-one argv element equal to the original payload. If any payload can escape into a
-second command, this suite fails and the release is blocked.
-"""
-
-from pathlib import Path
-from string.templatelib import Interpolation, Template
-
-import pytest
-
-from shellsafe.render import plan
-
-CASES_DIR = Path(__file__).parent.parent / "payloads" / "cases"
-CASE_FILES = sorted(CASES_DIR.glob("case_*.txt"))
-
-
-def payloads() -> list[tuple[str, str]]:
-    out = []
-    for path in CASE_FILES:
-        raw = path.read_text()
-        # strip one trailing newline added by file storage; keep all else verbatim
-        value = raw[:-1] if raw.endswith("\n") else raw
-        out.append((path.stem, value))
-    return out
-
-
-@pytest.mark.parametrize(
-    ("name", "payload"),
-    payloads(),
-    ids=[n for n, _ in payloads()],
-)
-def test_payload_stays_single_argument(name: str, payload: str):
-    p = plan(Template("echo ", Interpolation(payload, "value", None, "")))
-    assert p.mode == "argv"
-    assert p.argv == ("echo", payload)
-
-
-def test_corpus_is_present():
-    # guard against silent corpus deletion
-    assert len(CASE_FILES) >= 10