shellsafe 0.1.0__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.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: shellsafe
+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
+Project-URL: Changelog, https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md
+Author-email: Rahul Sharma <rahulxsh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,command-injection,injection,pep750,security,shell,subprocess,t-strings,template-strings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# shellsafe
+
+> Run shell commands safely using Python 3.14 template strings. Values can never
+> turn into commands.
+
+```python
+from shellsafe import run
+
+message = get_user_input()          # "fix; rm -rf ~"
+run(t"git commit -m {message}")
+# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
+# one command; the scary text is just an argument
+```
+
+## Why this package exists
+
+Python 3.14 added template strings (PEP 750). Now Python keeps your fixed text
+and your values separate at the language level.
+
+Shell commands are the first place people want to use this. That is because
+f-strings inside shell commands have caused real security bugs for ten years:
+
+```python
+subprocess.run(f"git commit -m {message}", shell=True)
+# if message = "fix; rm -rf ~"  ->  two commands run. The second one is bad.
+```
+
+Python planned to solve this officially (PEP 787), but that plan was postponed.
+So today there is no standard way to run shell commands safely with templates.
+This package fills that gap.
+
+## Install
+
+```bash
+pip install shellsafe
+```
+
+Needs Python 3.14 or newer.
+
+## How to use
+
+Run a command. Your values always stay one argument each:
+
+```python
+from shellsafe import run
+
+run(t"mkdir {path}")
+run(t"docker build -t {tag} .", check=True, timeout=300)
+```
+
+Get the output as text:
+
+```python
+from shellsafe import capture
+
+res = capture(t"grep {pattern} {file}")
+print(res.stdout, res.returncode)
+```
+
+Need pipes? Works on Linux and macOS. Your values are quoted safely first:
+
+```python
+from shellsafe import shx
+
+shx(t"cat {file} | wc -l")
+```
+
+Want to see exactly what will run?
+
+```python
+from shellsafe import plan
+
+print(plan(t"git commit -m {message}"))
+# argv: ["git","commit","-m","fix; rm -rf ~"]
+```
+
+## Safety rules
+
+| Case | What happens |
+|---|---|
+| Any value you pass | becomes one argument, exactly as given |
+| Value used as the program name | error: program names must be written as fixed text |
+| Shell features on Windows | error: we cannot make Windows safe this way, so we say no |
+| RAW() misuse | error: one value only, used as-is, no nesting |
+
+`RAW(...)` marks content you have already made safe by hand. It is loud and easy
+to find in code review, so trust is never hidden.
+
+## Limits
+
+- 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.
+
+## Needs
+
+- Python 3.14 or newer
+- Linux, macOS, Windows (pipes work on Linux and macOS only)
+
+## More
+
+- Source and issues: [github.com/rahulXs/shellsafe](https://github.com/rahulXs/shellsafe)
+- Want to help? See CONTRIBUTING.md in the repository.
+
+License: MIT

shellsafe-0.2.0/README.md

@@ -0,0 +1,109 @@
+# shellsafe
+
+> Run shell commands safely using Python 3.14 template strings. Values can never
+> turn into commands.
+
+```python
+from shellsafe import run
+
+message = get_user_input()          # "fix; rm -rf ~"
+run(t"git commit -m {message}")
+# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
+# one command; the scary text is just an argument
+```
+
+## Why this package exists
+
+Python 3.14 added template strings (PEP 750). Now Python keeps your fixed text
+and your values separate at the language level.
+
+Shell commands are the first place people want to use this. That is because
+f-strings inside shell commands have caused real security bugs for ten years:
+
+```python
+subprocess.run(f"git commit -m {message}", shell=True)
+# if message = "fix; rm -rf ~"  ->  two commands run. The second one is bad.
+```
+
+Python planned to solve this officially (PEP 787), but that plan was postponed.
+So today there is no standard way to run shell commands safely with templates.
+This package fills that gap.
+
+## Install
+
+```bash
+pip install shellsafe
+```
+
+Needs Python 3.14 or newer.
+
+## How to use
+
+Run a command. Your values always stay one argument each:
+
+```python
+from shellsafe import run
+
+run(t"mkdir {path}")
+run(t"docker build -t {tag} .", check=True, timeout=300)
+```
+
+Get the output as text:
+
+```python
+from shellsafe import capture
+
+res = capture(t"grep {pattern} {file}")
+print(res.stdout, res.returncode)
+```
+
+Need pipes? Works on Linux and macOS. Your values are quoted safely first:
+
+```python
+from shellsafe import shx
+
+shx(t"cat {file} | wc -l")
+```
+
+Want to see exactly what will run?
+
+```python
+from shellsafe import plan
+
+print(plan(t"git commit -m {message}"))
+# argv: ["git","commit","-m","fix; rm -rf ~"]
+```
+
+## Safety rules
+
+| Case | What happens |
+|---|---|
+| Any value you pass | becomes one argument, exactly as given |
+| Value used as the program name | error: program names must be written as fixed text |
+| Shell features on Windows | error: we cannot make Windows safe this way, so we say no |
+| RAW() misuse | error: one value only, used as-is, no nesting |
+
+`RAW(...)` marks content you have already made safe by hand. It is loud and easy
+to find in code review, so trust is never hidden.
+
+## Limits
+
+- 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.
+
+## Needs
+
+- Python 3.14 or newer
+- Linux, macOS, Windows (pipes work on Linux and macOS only)
+
+## More
+
+- Source and issues: [github.com/rahulXs/shellsafe](https://github.com/rahulXs/shellsafe)
+- Want to help? See CONTRIBUTING.md in the repository.
+
+License: MIT

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

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "shellsafe"
 dynamic = ["version"]
-description = "Safe shell commands via Python 3.14 template strings. Injection-proof by construction."
+description = "Run shell commands safely using Python 3.14 template strings. Values can never turn into commands."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.14"
@@ -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.0 → 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.0 → 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.0 → 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.2.0/tests/unit/test_raw.py

@@ -0,0 +1,15 @@
+"""RAW marker invariants: nesting refused, verbatim display, single argument."""
+
+import pytest
+
+from shellsafe import RAW
+from shellsafe.errors import RawUsageError
+
+
+def test_raw_repr_shows_trust_boundary():
+    assert "<RAW" in repr(RAW("pre-quoted"))
+
+
+def test_nested_raw_refused():
+    with pytest.raises(RawUsageError):
+        RAW(RAW(["x"]))

shellsafe-0.1.0/CHANGELOG.md

@@ -1,14 +0,0 @@
-# Changelog
-
-All notable changes to this project are documented here. Format follows
-Keep a Changelog; versioning follows SemVer.
-
-## [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.0/PKG-INFO

@@ -1,126 +0,0 @@
-Metadata-Version: 2.5
-Name: shellsafe
-Version: 0.1.0
-Summary: Safe shell commands via Python 3.14 template strings. Injection-proof by construction.
-Project-URL: Repository, https://github.com/rahulXs/shellsafe
-Project-URL: Issues, https://github.com/rahulXs/shellsafe/issues
-Project-URL: Changelog, https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md
-Author-email: Rahul Sharma <rahulxsh@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: automation,command-injection,injection,pep750,security,shell,subprocess,t-strings,template-strings
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Typing :: Typed
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-
-# shellsafe
-
-> Safe shell commands via Python 3.14 template strings. Injection-proof by
-> construction.
-
-```python
-from shellsafe import run
-
-message = get_user_input()          # "fix; rm -rf ~"
-run(t"git commit -m {message}")
-# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
-# one command; the scary text is just an argument
-```
-
-## Why
-
-The dominant pattern in scripts and automation is still this:
-
-```python
-subprocess.run(f"git commit -m {message}", shell=True)   # injection waiting to happen
-```
-
-Python 3.14 template strings (`t"..."`) separate static text from interpolated
-values. shellsafe turns that structure into argv lists where interpolated values
-are always data, never commands. When you genuinely need pipes, shell mode quotes
-every value with POSIX rules first.
-
-## Install
-
-```bash
-pip install shellsafe
-```
-
-Requires Python 3.14+ (template strings).
-
-## Usage
-
-Run a command. Interpolated values are always single arguments:
-
-```python
-from shellsafe import run
-
-run(t"mkdir {path}")
-run(t"docker build -t {tag} .", check=True, timeout=300)
-```
-
-Capture output as text:
-
-```python
-from shellsafe import capture
-
-res = capture(t"grep {pattern} {file}")
-print(res.stdout, res.returncode)
-```
-
-Pipes and redirections on POSIX (values are quoted with `shlex.quote` first):
-
-```python
-from shellsafe import shx
-
-shx(t"cat {file} | wc -l")
-```
-
-Inspect exactly what will execute:
-
-```python
-from shellsafe import plan  # lower-level: render without running
-
-print(plan(t"git commit -m {message}"))
-# argv: ["git","commit","-m","fix; rm -rf ~"]
-```
-
-## What it refuses
-
-| Case | Behavior |
-|---|---|
-| Interpolation as the executable | error: the command comes from static text only |
-| Shell route on Windows | error: cmd.exe quoting cannot be made injection-safe; use argv mode |
-| RAW misuse | error: one argument, verbatim, nesting refused |
-
-`RAW("...")` / `RAW(["a", "b"])` is the single explicit trust boundary for
-pre-quoted content. Every use site is greppable.
-
-## Limits
-
-- Windows: interpolated shell routes are refused rather than approximated;
-  argv-mode commands work fully.
-- Bytes interpolations are rejected: decode explicitly first.
-- Runtime behavior after import is your test suite's job, same trust model as
-  calling subprocess yourself.
-
-## Contributing
-
-Issues and PRs welcome. Security reports go privately to the maintainer, never
-through public issues.
-
-## Requirements
-
-- CPython >= 3.14 (uses template strings from PEP 750)
-- Linux, macOS, Windows (Windows supports argv mode; POSIX-only shell mode)
-
-## License
-
-MIT

shellsafe-0.1.0/README.md

@@ -1,104 +0,0 @@
-# shellsafe
-
-> Safe shell commands via Python 3.14 template strings. Injection-proof by
-> construction.
-
-```python
-from shellsafe import run
-
-message = get_user_input()          # "fix; rm -rf ~"
-run(t"git commit -m {message}")
-# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
-# one command; the scary text is just an argument
-```
-
-## Why
-
-The dominant pattern in scripts and automation is still this:
-
-```python
-subprocess.run(f"git commit -m {message}", shell=True)   # injection waiting to happen
-```
-
-Python 3.14 template strings (`t"..."`) separate static text from interpolated
-values. shellsafe turns that structure into argv lists where interpolated values
-are always data, never commands. When you genuinely need pipes, shell mode quotes
-every value with POSIX rules first.
-
-## Install
-
-```bash
-pip install shellsafe
-```
-
-Requires Python 3.14+ (template strings).
-
-## Usage
-
-Run a command. Interpolated values are always single arguments:
-
-```python
-from shellsafe import run
-
-run(t"mkdir {path}")
-run(t"docker build -t {tag} .", check=True, timeout=300)
-```
-
-Capture output as text:
-
-```python
-from shellsafe import capture
-
-res = capture(t"grep {pattern} {file}")
-print(res.stdout, res.returncode)
-```
-
-Pipes and redirections on POSIX (values are quoted with `shlex.quote` first):
-
-```python
-from shellsafe import shx
-
-shx(t"cat {file} | wc -l")
-```
-
-Inspect exactly what will execute:
-
-```python
-from shellsafe import plan  # lower-level: render without running
-
-print(plan(t"git commit -m {message}"))
-# argv: ["git","commit","-m","fix; rm -rf ~"]
-```
-
-## What it refuses
-
-| Case | Behavior |
-|---|---|
-| Interpolation as the executable | error: the command comes from static text only |
-| Shell route on Windows | error: cmd.exe quoting cannot be made injection-safe; use argv mode |
-| RAW misuse | error: one argument, verbatim, nesting refused |
-
-`RAW("...")` / `RAW(["a", "b"])` is the single explicit trust boundary for
-pre-quoted content. Every use site is greppable.
-
-## Limits
-
-- Windows: interpolated shell routes are refused rather than approximated;
-  argv-mode commands work fully.
-- Bytes interpolations are rejected: decode explicitly first.
-- Runtime behavior after import is your test suite's job, same trust model as
-  calling subprocess yourself.
-
-## Contributing
-
-Issues and PRs welcome. Security reports go privately to the maintainer, never
-through public issues.
-
-## Requirements
-
-- CPython >= 3.14 (uses template strings from PEP 750)
-- Linux, macOS, Windows (Windows supports argv mode; POSIX-only shell mode)
-
-## License
-
-MIT

shellsafe-0.1.0/src/shellsafe/_version.py

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

shellsafe-0.1.0/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.0/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.0/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

shellsafe-0.1.0/tests/unit/test_raw.py

@@ -1,28 +0,0 @@
-"""RAW marker invariants: nesting refused, verbatim display, single argument."""
-
-import pytest
-
-from shellsafe import RAW
-from shellsafe.errors import RawUsageError
-from shellsafe.raw import Raw
-
-
-def test_raw_wraps_list_verbatim():
-    r = RAW(["git", "log", "--oneline"])
-    assert isinstance(r, Raw)
-    assert r.value == ["git", "log", "--oneline"]
-
-
-def test_raw_repr_shows_trust_boundary():
-    assert "<RAW" in repr(RAW("pre-quoted"))
-
-
-def test_nested_raw_refused():
-    with pytest.raises(RawUsageError):
-        RAW(RAW(["x"]))
-
-
-def test_raw_is_greppable():
-    # house rule: trust boundaries are greppable; this documents the pattern
-    source = 'RAW("trusted")'
-    assert "RAW(" in source