just-py-bash 2.14.1__tar.gz

just_py_bash-2.14.1/.gitignore

@@ -0,0 +1,22 @@
+site
+.venv
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+dist/
+dist-node/
+just_py_bash/src/just_bash/_vendor/just-bash/
+build/
+*.egg-info/
+.env
+.dev.vars
+.coverage
+.coverage*
+htmlcov/
+.cache/
+.vscode/
+.DS_Store
+node_modules/
+.hypothesis/

just_py_bash-2.14.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: just-py-bash
+Version: 2.14.1
+Summary: A Python wrapper around the just-bash virtual shell
+Author-email: Nathan Gage <nathan@sweetspot.so>
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.13.0
+Provides-Extra: node
+Requires-Dist: just-bash-bundled-runtime<23,>=22; extra == 'node'
+Description-Content-Type: text/markdown
+
+# just-py-bash
+
+This directory contains the distributable Python package for `just-py-bash`.
+
+Install with `just-py-bash`, import with `just_bash`.
+
+For full project documentation, examples, workflows, and development notes, see the repository root:
+
+- `../README.md`
+- `../examples/`
+- `../docs/`

just_py_bash-2.14.1/README.md

@@ -0,0 +1,11 @@
+# just-py-bash
+
+This directory contains the distributable Python package for `just-py-bash`.
+
+Install with `just-py-bash`, import with `just_bash`.
+
+For full project documentation, examples, workflows, and development notes, see the repository root:
+
+- `../README.md`
+- `../examples/`
+- `../docs/`

just_py_bash-2.14.1/hatch_build.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+_PACKAGE_ROOT = Path("src") / "just_bash"
+_RUNTIME_ROOT = _PACKAGE_ROOT / "_vendor" / "just-bash"
+_BUILD_SCRIPT = Path("tools") / "build_packaged_runtime.sh"
+_MISSING_RUNTIME_MESSAGE = (
+    "Could not assemble the packaged just-bash runtime. "
+    "Build vendor/just-bash first with `make bootstrap-just-bash`, or build from an sdist "
+    "that already contains the packaged runtime payload."
+)
+
+
+class JustBashBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, object]) -> None:
+        del version, build_data
+
+        project_root = Path(self.root)
+        runtime_root = project_root / _RUNTIME_ROOT
+        if source_vendor_checkout_build_ready(project_root):
+            build_script = project_root / _BUILD_SCRIPT
+            if not build_script.exists():
+                raise RuntimeError(f"Missing packaged runtime build script: {build_script}")
+
+            completed = subprocess.run(
+                ["bash", str(build_script)],
+                cwd=project_root,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+            if completed.returncode != 0:
+                raise RuntimeError(
+                    f"{_MISSING_RUNTIME_MESSAGE}\n\nstdout:\n{completed.stdout}\nstderr:\n{completed.stderr}",
+                )
+
+            if not packaged_runtime_ready(runtime_root):
+                raise RuntimeError(
+                    f"Packaged runtime build finished without producing the expected runtime payload at {runtime_root}",
+                )
+
+            return
+
+        if packaged_runtime_ready(runtime_root):
+            return
+
+        raise RuntimeError(_MISSING_RUNTIME_MESSAGE)
+
+
+def source_vendor_checkout_build_ready(project_root: Path) -> bool:
+    vendor_root = project_root.parent / "vendor" / "just-bash"
+    required_files = (
+        "package.json",
+        "dist/index.js",
+        "dist/bin/just-bash.js",
+        "dist/bin/shell/shell.js",
+        "src/commands/python3/worker.js",
+    )
+    return (
+        all(vendor_root.joinpath(relative_path).is_file() for relative_path in required_files)
+        and vendor_root.joinpath("node_modules").is_dir()
+    )
+
+
+def packaged_runtime_ready(runtime_root: Path) -> bool:
+    if not runtime_root.joinpath("package.json").is_file():
+        return False
+
+    entry_candidates = (
+        runtime_root / "dist" / "index.js",
+        runtime_root / "dist" / "bundle" / "index.js",
+    )
+    if not any(path.is_file() for path in entry_candidates):
+        return False
+
+    cli_candidates = (
+        runtime_root / "dist" / "bin" / "just-bash.js",
+        runtime_root / "dist" / "bin" / "shell" / "shell.js",
+    )
+    if not all(path.is_file() for path in cli_candidates):
+        return False
+
+    return runtime_root.joinpath("vendor", "cpython-emscripten").is_dir()

just_py_bash-2.14.1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "just-py-bash"
+dynamic = ["version"]
+description = "A Python wrapper around the just-bash virtual shell"
+readme = "README.md"
+authors = [{ name = "Nathan Gage", email = "nathan@sweetspot.so" }]
+requires-python = ">=3.11"
+dependencies = ["pydantic>=2.13.0"]
+
+[project.optional-dependencies]
+node = ["just-bash-bundled-runtime>=22,<23"]
+
+[project.scripts]
+just-py-bash = "just_bash:main"
+just-py-bash-shell = "just_bash:shell_main"
+
+[tool.uv.sources]
+just-bash-bundled-runtime = { path = "../just_bash_bundled_runtime" }
+
+[tool.hatch.build]
+artifacts = [
+  "src/just_bash/_vendor/just-bash/package.json",
+  "src/just_bash/_vendor/just-bash/dist/**",
+  "src/just_bash/_vendor/just-bash/vendor/**",
+]
+exclude = ["src/just_bash/__pycache__/**"]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "2.14.1"
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/just_bash"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "README.md",
+  "pyproject.toml",
+  "hatch_build.py",
+  "tools/build_packaged_runtime.sh",
+  "src/just_bash/**",
+]
+
+[build-system]
+requires = ["hatchling>=1.29.0", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"

just_py_bash-2.14.1/src/just_bash/__init__.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError, version
+
+from ._api import Bash
+from ._async_api import AsyncBash
+from ._cli import run_upstream_cli, run_upstream_shell
+from ._command_registry import (
+    get_command_names,
+    get_javascript_command_names,
+    get_network_command_names,
+    get_python_command_names,
+)
+from ._custom_commands import (
+    AsyncCustomCommandCallback,
+    AsyncCustomCommandContext,
+    AsyncCustomCommands,
+    CustomCommandCallback,
+    CustomCommandContext,
+    CustomCommands,
+)
+from ._exceptions import (
+    BackendError,
+    BackendUnavailableError,
+    BridgeError,
+    BridgeTimeoutError,
+    CommandFailedError,
+    JustBashError,
+)
+from ._fs import FileInit, FsStat, InMemoryFs, LazyFile, MountableFs, MountConfig, OverlayFs, ReadWriteFs
+from ._models import ExecResult, ExecutionLimits, JavaScriptConfig
+from ._option_hooks import (
+    BashLogger,
+    DefenseInDepthConfig,
+    DefenseViolationCallback,
+    FeatureCoverageWriter,
+    FetchCallback,
+    FetchRequest,
+    FetchResult,
+    SecurityViolation,
+    TraceCallback,
+    TraceEvent,
+)
+from ._options import BashOptions, ExecOptions
+from ._parser import parse, serialize
+from ._sandbox import (
+    AsyncSandbox,
+    AsyncSandboxCommand,
+    Sandbox,
+    SandboxCommand,
+    SandboxOptions,
+    SandboxOutputMessage,
+    SandboxWriteFile,
+)
+from ._security import (
+    SecurityViolationError,
+    SecurityViolationLogger,
+    ViolationSummary,
+    create_console_violation_callback,
+)
+from ._transform import (
+    BashTransformPipeline,
+    BashTransformResult,
+    CommandCollectorPlugin,
+    TeePlugin,
+    TransformPlugin,
+)
+from ._types import AllowedUrl, AllowedUrlEntry, NetworkConfig, ProcessInfo, RequestTransform
+
+try:
+    __version__ = version("just-py-bash")
+except PackageNotFoundError:  # pragma: no cover - editable installs during development
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AsyncBash",
+    "Bash",
+    "AsyncCustomCommandCallback",
+    "AsyncCustomCommandContext",
+    "AsyncCustomCommands",
+    "AllowedUrl",
+    "AllowedUrlEntry",
+    "AsyncSandbox",
+    "AsyncSandboxCommand",
+    "BackendError",
+    "BackendUnavailableError",
+    "BashOptions",
+    "BashTransformPipeline",
+    "BashTransformResult",
+    "CustomCommandCallback",
+    "CustomCommandContext",
+    "CustomCommands",
+    "BridgeError",
+    "BridgeTimeoutError",
+    "CommandCollectorPlugin",
+    "CommandFailedError",
+    "DefenseInDepthConfig",
+    "DefenseViolationCallback",
+    "ExecOptions",
+    "ExecResult",
+    "ExecutionLimits",
+    "FileInit",
+    "FsStat",
+    "FeatureCoverageWriter",
+    "FetchCallback",
+    "FetchRequest",
+    "FetchResult",
+    "InMemoryFs",
+    "MountConfig",
+    "MountableFs",
+    "NetworkConfig",
+    "OverlayFs",
+    "ProcessInfo",
+    "JavaScriptConfig",
+    "LazyFile",
+    "BashLogger",
+    "ReadWriteFs",
+    "Sandbox",
+    "SandboxCommand",
+    "SandboxOptions",
+    "SandboxOutputMessage",
+    "SandboxWriteFile",
+    "SecurityViolation",
+    "SecurityViolationError",
+    "SecurityViolationLogger",
+    "JustBashError",
+    "RequestTransform",
+    "TeePlugin",
+    "TraceCallback",
+    "TraceEvent",
+    "TransformPlugin",
+    "ViolationSummary",
+    "__version__",
+    "create_console_violation_callback",
+    "get_command_names",
+    "get_javascript_command_names",
+    "get_network_command_names",
+    "get_python_command_names",
+    "main",
+    "parse",
+    "serialize",
+    "shell_main",
+]
+
+
+def _run_cli_with_error_handling(
+    runner: Callable[[list[str] | None], int],
+    argv: list[str] | None = None,
+) -> int:
+    try:
+        return runner(argv)
+    except BackendUnavailableError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    return _run_cli_with_error_handling(run_upstream_cli, argv)
+
+
+def shell_main(argv: list[str] | None = None) -> int:
+    return _run_cli_with_error_handling(run_upstream_shell, argv)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

just_py_bash-2.14.1/src/just_bash/_api.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from typing import Self, cast
+
+from ._bridge import NodeBridge
+from ._custom_commands import CustomCommands
+from ._fs import FileSystemConfig, InitialFileValue
+from ._models import ExecResult, ExecutionLimits, JavaScriptConfig
+from ._option_hooks import BashLogger, DefenseInDepthConfig, FeatureCoverageWriter, FetchCallback, TraceCallback
+from ._options import BashOptions, ExecOptions
+from ._session_fs import SessionFs
+from ._transform import BashTransformResult, TransformPlugin
+from ._types import NetworkConfig, ProcessInfo
+
+
+class Bash:
+    """Python wrapper around a long-lived just-bash session.
+
+    Each instance owns a dedicated Node.js worker process and a single just-bash
+    ``Bash`` instance inside that worker.
+
+    just-bash semantics are preserved:
+    - filesystem state is shared across ``exec`` calls
+    - shell state is isolated per ``exec`` call
+    """
+
+    def __init__(
+        self,
+        *,
+        files: Mapping[str, InitialFileValue] | None = None,
+        env: Mapping[str, str] | None = None,
+        cwd: str | None = None,
+        fs: FileSystemConfig | None = None,
+        execution_limits: ExecutionLimits | None = None,
+        python: bool = False,
+        javascript: bool | JavaScriptConfig = False,
+        commands: Sequence[str] | None = None,
+        custom_commands: CustomCommands | None = None,
+        fetch: FetchCallback | None = None,
+        logger: BashLogger | None = None,
+        trace: TraceCallback | None = None,
+        defense_in_depth: bool | DefenseInDepthConfig | None = None,
+        coverage: FeatureCoverageWriter | None = None,
+        network: NetworkConfig | None = None,
+        process_info: ProcessInfo | None = None,
+        node_command: Sequence[str] | None = None,
+        js_entry: str | os.PathLike[str] | None = None,
+        package_json: str | os.PathLike[str] | None = None,
+    ) -> None:
+        self._open_bridge(
+            BashOptions(
+                files=files,
+                env=env,
+                cwd=cwd,
+                fs=fs,
+                execution_limits=execution_limits,
+                python=python,
+                javascript=javascript,
+                commands=commands,
+                custom_commands=custom_commands,
+                fetch=fetch,
+                logger=logger,
+                trace=trace,
+                defense_in_depth=defense_in_depth,
+                coverage=coverage,
+                network=network,
+                process_info=process_info,
+            ),
+            node_command=node_command,
+            js_entry=js_entry,
+            package_json=package_json,
+        )
+
+    @classmethod
+    def from_options(
+        cls,
+        options: BashOptions,
+        *,
+        node_command: Sequence[str] | None = None,
+        js_entry: str | os.PathLike[str] | None = None,
+        package_json: str | os.PathLike[str] | None = None,
+    ) -> Self:
+        self = cls.__new__(cls)
+        self._open_bridge(
+            options,
+            node_command=node_command,
+            js_entry=js_entry,
+            package_json=package_json,
+        )
+        return self
+
+    def _open_bridge(
+        self,
+        options: BashOptions,
+        *,
+        node_command: Sequence[str] | None,
+        js_entry: str | os.PathLike[str] | None,
+        package_json: str | os.PathLike[str] | None,
+    ) -> None:
+        init_options, hooks = options.to_bridge_init()
+        self._bridge = NodeBridge(
+            init_options=init_options,
+            custom_commands=options.custom_commands,
+            lazy_file_providers=hooks.lazy_file_providers,
+            fetch_callback=hooks.fetch_callback,
+            logger=hooks.logger,
+            trace_callback=hooks.trace_callback,
+            coverage_writer=hooks.coverage_writer,
+            defense_violation_callback=hooks.defense_violation_callback,
+            node_command=node_command,
+            js_entry=js_entry,
+            package_json=package_json,
+        )
+        self.fs = SessionFs(self._bridge)
+
+    @property
+    def backend_version(self) -> str | None:
+        return self._bridge.backend_version
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Bash(backend_version={self.backend_version!r}, closed={self.closed!r})"
+
+    def close(self) -> None:
+        self._bridge.close()
+
+    def exec(
+        self,
+        command_line: str,
+        *,
+        env: Mapping[str, str] | None = None,
+        replace_env: bool = False,
+        cwd: str | None = None,
+        raw_script: bool = False,
+        stdin: str | None = None,
+        args: Sequence[str] | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        return self.exec_with_options(
+            command_line,
+            ExecOptions(
+                env=env,
+                replace_env=replace_env,
+                cwd=cwd,
+                raw_script=raw_script,
+                stdin=stdin,
+                args=args,
+                timeout=timeout,
+            ),
+        )
+
+    def exec_with_options(self, command_line: str, options: ExecOptions) -> ExecResult:
+        payload = self._bridge.request(
+            "exec",
+            {
+                "script": command_line,
+                "options": options.to_wire(),
+            },
+            timeout=None if options.timeout is None else options.timeout + 5.0,
+        )
+        return ExecResult.from_wire(payload)
+
+    def register_transform_plugin(self, plugin: TransformPlugin) -> None:
+        self._bridge.request_raw("register_transform_plugin", {"plugin": plugin.to_wire()})
+
+    def transform(self, command_line: str) -> BashTransformResult:
+        raw_payload = self._bridge.request_raw("transform", {"script": command_line})
+        if not isinstance(raw_payload, Mapping):
+            raise TypeError(f"Expected a transform result mapping, got {type(raw_payload).__name__}")
+        payload = cast(Mapping[str, object], raw_payload)
+        return BashTransformResult.from_wire(payload)
+
+    def read_text(self, path: str) -> str:
+        return self.fs.read_text(path)
+
+    def read_bytes(self, path: str) -> bytes:
+        return self.fs.read_bytes(path)
+
+    def write_text(self, path: str, content: str) -> None:
+        self.fs.write_text(path, content)
+
+    def write_bytes(self, path: str, content: bytes) -> None:
+        self.fs.write_bytes(path, content)
+
+    def get_env(self) -> dict[str, str]:
+        return dict(self._bridge.request("get_env"))
+
+    def get_cwd(self) -> str:
+        return self._bridge.request("get_cwd")
+
+    @property
+    def closed(self) -> bool:
+        return self._bridge.closed