shellsim 0.1.0__tar.gz → 0.1.2__tar.gz

{shellsim-0.1.0 → shellsim-0.1.2}/Cargo.lock

@@ -330,7 +330,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "base64",
  "crc32fast",

{shellsim-0.1.0 → shellsim-0.1.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "shellsim"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 description = "Deterministic, resource-constrained BusyBox-like environment for evaluating agents"
 license = "Apache-2.0"
@@ -58,4 +58,5 @@ python = []
 opt-level = 1
 
 [profile.release]
-opt-level = 2
+opt-level = "s"
+lto = false

{shellsim-0.1.0 → shellsim-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellsim
-Version: 0.1.0
+Version: 0.1.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: MacOS :: MacOS X
@@ -119,6 +119,15 @@ environment.write_file("/work/main.py", "print(6 * 7)\n")
 result = environment.run("python3.14 /work/main.py")
 assert result.stdout == b"42\n"
 PY
+
+# Run the PyPI package as an ephemeral tool
+uvx shellsim -c 'printf "b\na\n" | sort'
+
+# Copy a trusted host project into /work, then modify only the disposable VFS snapshot
+uvx shellsim --root ./project -c 'pwd; find . -type f; make test'
+
+# Open a persistent interactive simulator rooted at a host-project snapshot
+uvx shellsim --root ./project
 ```
 
 Limit values accept `k`, `m`, and `g` binary suffixes. Arguments after `--` in `eval` mode become
@@ -153,6 +162,11 @@ process-wide seccomp filter, so importing or using it does not restrict the embe
 process. Simulated programs still execute through the capability-free Rust library and cannot
 reach ambient host resources.
 
+The installed `shellsim` console command uses the same facade. With a terminal it opens a
+persistent simulated shell; with piped input it executes that input as shell source, and `-c`
+executes one action. `--root DIR` performs a bounded, symlink-rejecting snapshot copy into `/work`.
+Changes made by simulated commands are never written back to the host directory.
+
 ## Virtual time
 
 An environment owns deterministic monotonic, wall, and process-CPU clocks. Sleeps and deadlines

{shellsim-0.1.0 → shellsim-0.1.2}/README.md

@@ -96,6 +96,15 @@ environment.write_file("/work/main.py", "print(6 * 7)\n")
 result = environment.run("python3.14 /work/main.py")
 assert result.stdout == b"42\n"
 PY
+
+# Run the PyPI package as an ephemeral tool
+uvx shellsim -c 'printf "b\na\n" | sort'
+
+# Copy a trusted host project into /work, then modify only the disposable VFS snapshot
+uvx shellsim --root ./project -c 'pwd; find . -type f; make test'
+
+# Open a persistent interactive simulator rooted at a host-project snapshot
+uvx shellsim --root ./project
 ```
 
 Limit values accept `k`, `m`, and `g` binary suffixes. Arguments after `--` in `eval` mode become
@@ -130,6 +139,11 @@ process-wide seccomp filter, so importing or using it does not restrict the embe
 process. Simulated programs still execute through the capability-free Rust library and cannot
 reach ambient host resources.
 
+The installed `shellsim` console command uses the same facade. With a terminal it opens a
+persistent simulated shell; with piped input it executes that input as shell source, and `-c`
+executes one action. `--root DIR` performs a bounded, symlink-rejecting snapshot copy into `/work`.
+Changes made by simulated commands are never written back to the host directory.
+
 ## Virtual time
 
 An environment owns deterministic monotonic, wall, and process-CPU clocks. Sleeps and deadlines

{shellsim-0.1.0 → shellsim-0.1.2}/pyproject.toml

@@ -29,6 +29,9 @@ Homepage = "https://github.com/rjpower/shellsim"
 Issues = "https://github.com/rjpower/shellsim/issues"
 Repository = "https://github.com/rjpower/shellsim"
 
+[project.scripts]
+shellsim = "shellsim._cli:main"
+
 [dependency-groups]
 test = ["pytest>=8"]
 

{shellsim-0.1.0 → shellsim-0.1.2}/python/native/Cargo.lock

@@ -406,7 +406,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "base64",
  "crc32fast",
@@ -427,7 +427,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim-python-bindings"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "pyo3",
  "serde",

{shellsim-0.1.0 → shellsim-0.1.2}/python/native/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "shellsim-python-bindings"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 description = "Python bindings for shellsim"
 license = "Apache-2.0"
@@ -18,3 +18,7 @@ pyo3 = { version = "0.28", features = ["abi3-py39", "extension-module"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 shellsim = { path = "../.." }
+
+[profile.release]
+opt-level = "s"
+lto = false

shellsim-0.1.2/python/shellsim/__main__.py

@@ -0,0 +1,6 @@
+"""Run the shellsim package as a module."""
+
+from ._cli import main
+
+
+raise SystemExit(main())

shellsim-0.1.2/python/shellsim/_cli.py

@@ -0,0 +1,182 @@
+"""Command-line interface for the installed shellsim Python package."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+import sys
+from typing import Any, Optional
+
+from ._api import Environment, RunResult, SimulationError
+
+
+_MAX_U64 = (1 << 64) - 1
+
+
+def _quantity(value: str) -> int:
+    """Parse a non-negative count with an optional binary k, m, or g suffix."""
+
+    suffixes = {"k": 1024, "m": 1024**2, "g": 1024**3}
+    suffix = value[-1:].lower()
+    multiplier = suffixes.get(suffix, 1)
+    digits = value[:-1] if suffix in suffixes else value
+    try:
+        number = int(digits)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(
+            "expected a count, optionally suffixed with k, m, or g"
+        ) from error
+    result = number * multiplier
+    if number < 0 or result > _MAX_U64:
+        raise argparse.ArgumentTypeError(f"expected a count between 0 and {_MAX_U64}")
+    return result
+
+
+def _parser() -> argparse.ArgumentParser:
+    """Build the command-line parser shared by the console and module entry points."""
+
+    parser = argparse.ArgumentParser(
+        prog="shellsim",
+        description="Run shell commands in a deterministic in-memory simulation.",
+    )
+    parser.add_argument("-c", "--command", metavar="SOURCE", help="execute one shell action")
+    parser.add_argument(
+        "--root",
+        metavar="DIR",
+        help="copy this trusted host directory into the simulated /work tree",
+    )
+    parser.add_argument("--cpu", type=_quantity, help="cumulative CPU fuel limit")
+    parser.add_argument("--memory", type=_quantity, help="modeled memory limit")
+    parser.add_argument("--disk", type=_quantity, help="simulated filesystem limit")
+    parser.add_argument("--output", type=_quantity, help="cumulative output limit")
+    return parser
+
+
+def _binary_stream(stream: Any) -> Any:
+    """Return a stream that accepts bytes, including under in-process test doubles."""
+
+    return getattr(stream, "buffer", stream)
+
+
+def _write_bytes(stream: Any, data: bytes) -> None:
+    """Write exact simulator bytes to a host console stream."""
+
+    binary = _binary_stream(stream)
+    try:
+        binary.write(data)
+    except TypeError:
+        binary.write(data.decode("utf-8", errors="replace"))
+    binary.flush()
+
+
+def _emit_result(result: RunResult, stdout: Any, stderr: Any) -> None:
+    """Forward one simulated action's byte-preserving output."""
+
+    _write_bytes(stdout, result.stdout)
+    _write_bytes(stderr, result.stderr)
+
+
+def _execute_action(
+    environment: Environment,
+    source: str,
+    stdin: bytes,
+    stdout: Any,
+    stderr: Any,
+) -> Optional[RunResult]:
+    """Execute and forward one action, reporting adapter failures without a traceback."""
+
+    try:
+        result = environment.run(source, stdin)
+    except SimulationError as error:
+        print(f"shellsim: {error}", file=stderr)
+        return None
+    _emit_result(result, stdout, stderr)
+    return result
+
+
+def _read_bytes(stream: Any) -> bytes:
+    """Read all remaining input without depending on a text-stream encoding."""
+
+    data = _binary_stream(stream).read()
+    return data.encode() if isinstance(data, str) else data
+
+
+def _prepare_environment(
+    options: argparse.Namespace, stdout: Any, stderr: Any
+) -> tuple[Optional[Environment], int]:
+    """Create a simulated machine, import an optional host snapshot, and enter `/work`."""
+
+    environment = Environment(
+        cpu=options.cpu,
+        memory=options.memory,
+        disk=options.disk,
+        output=options.output,
+    )
+    try:
+        if options.root is not None:
+            environment.mount(options.root)
+        prepared = environment.run("cd /work")
+    except SimulationError as error:
+        print(f"shellsim: {error}", file=stderr)
+        return None, 2
+
+    if prepared.returncode != 0:
+        _emit_result(prepared, stdout, stderr)
+        return None, prepared.returncode
+    return environment, 0
+
+
+def _interactive(environment: Environment, stdin: Any, stdout: Any, stderr: Any) -> int:
+    """Run one action per input line while retaining simulated state."""
+
+    status = 0
+    while not environment.terminated:
+        stdout.write("shellsim$ ")
+        stdout.flush()
+        try:
+            line = stdin.readline()
+        except KeyboardInterrupt:
+            stdout.write("\n")
+            stdout.flush()
+            continue
+        if not line:
+            stdout.write("\n")
+            stdout.flush()
+            break
+        result = _execute_action(environment, line, b"", stdout, stderr)
+        if result is None:
+            return 1
+        status = result.returncode
+    return status
+
+
+def main(arguments: Optional[Sequence[str]] = None) -> int:
+    """Run the package CLI and return the simulated or usage exit status."""
+
+    options = _parser().parse_args(sys.argv[1:] if arguments is None else arguments)
+    environment, preparation_status = _prepare_environment(options, sys.stdout, sys.stderr)
+    if environment is None:
+        return preparation_status
+
+    if options.command is not None:
+        stdin = b"" if sys.stdin.isatty() else _read_bytes(sys.stdin)
+        result = _execute_action(
+            environment, options.command, stdin, sys.stdout, sys.stderr
+        )
+        if result is None:
+            return 1
+        return result.returncode
+
+    if sys.stdin.isatty():
+        return _interactive(environment, sys.stdin, sys.stdout, sys.stderr)
+
+    source_bytes = _read_bytes(sys.stdin)
+    try:
+        source = source_bytes.decode("utf-8")
+    except UnicodeDecodeError as error:
+        print(f"shellsim: stdin is not valid UTF-8 shell source: {error}", file=sys.stderr)
+        return 2
+    result = _execute_action(environment, source, b"", sys.stdout, sys.stderr)
+    if result is None:
+        return 1
+    return result.returncode