sandbox-engine 1.0.0__py3-none-any.whl

sandbox_engine-1.0.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: sandbox-engine
+Version: 1.0.0
+Summary: Automatic Repository Sandbox Runner — detects any repo's runtime and launches it in a sandbox
+Home-page: https://github.com/VivanRajath/sandbox-engine
+Author: Vivan Rajath
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# Sandbox Engine Architecture & Documentation
+
+## Overview
+
+**Sandbox Engine** is an Automatic Repository Sandbox Runner built in Go. It provides a CLI interface designed to seamlessly scan any repository, automatically detect the programming language and framework for all contained projects, install required dependencies in isolated environments, and launch the application.
+
+This document details the end-to-end architecture, the internal flow, and the robust support system that makes it highly versatile.
+
+---
+
+## High-Level Architecture Flow
+
+The execution lifecycle of the Sandbox Engine consists of three main phases, orchestrated by `main.go`.
+
+1.  **Scan Phase:** Recursively traverses the file system to find all application roots.
+2.  **Detect Phase:** Analyzes each discovered project to identify its language, framework, dependencies, entry point, and default port.
+3.  **Run Phase:** Prepares the environment (e.g., instantiating virtual environments, downloading packages) and executes the project.
+
+### 1. Scanner (`internal/scanner`)
+
+The Scanner is responsible for identifying where projects live within a potentially large monolithic repository structure.
+
+-   **Concurrency:** It uses a fixed worker pool of 8 goroutines to perform a depth-first traversal of the filesystem concurrently. This ensures high performance without overwhelming the OS file descriptor limits.
+-   **Indicator Files:** It identifies a "project root" by the presence of specific files like `package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `dockerfile`, etc.
+-   **Skip Directories:** To optimize scanning, it inherently ignores dependency paths and compiled outputs such as `node_modules`, `.git`, `vendor`, `__pycache__`, `target`, `build`, etc.
+-   **Output:** Generates a `types.ScanResult` containing distinct `Project` blocks with the files mapped for each root.
+
+### 2. Detector (`internal/detector`)
+
+The Detector consumes the output of the Scanner. For each project, it analyzes its filesystem structure and file contents to populate rich runtime metadata (defined in `internal/types/types.go`).
+
+-   **Language Inference:** Determines the primary language (`LangNode`, `LangPython`, `LangGo`, `LangJava`, `LangRust`, `LangDotNet`, `LangStatic`, `LangDocker`) based on the matching indicator files.
+-   **Framework Detection:** Deep-inspects configuration files or dependency lists to detect frameworks:
+    -   *Node / JS:* Angular, Astro, Gatsby, Vite, Nuxt, Next.js, Svelte, NestJS, Express, Vue, React.
+    -   *Python:* Django, FastAPI, Flask (reads `requirements.txt` and entry `.py` files).
+    -   *Java:* Spring Boot (reads `pom.xml` / `build.gradle`).
+    -   *.NET:* ASP.NET (reads `.csproj`).
+-   **EntryPoint & Port Allocation:** Deduces the main file to execute (e.g., `main.go`, `src/index.ts`, `manage.py`, `index.html`) and assigns the conventional port representing that framework (e.g., 3000 for Node/Static, 8000 for FastAPI/Django, 8080 for Spring Boot/Go).
+-   **Environment Configuration:** For environments like Python, it checks for existing virtual environments (`venv`, `.venv`, `env`). If missing, it notes where one needs to be created. It also detects package managers like `pnpm`, `yarn`, or `npm` based on lock files.
+
+### 3. Runtime & Exec (`internal/runtime` & `internal/exec`)
+
+The Runtime module bridges detection with actual execution via two main steps:
+
+#### Dependency Installation (`InstallDependencies`)
+Depending on the resolved language type, it delegates to specialized installers:
+-   **Node:** Uses `npm install`, `yarn install`, or `pnpm install` based on detected lock files.
+-   **Python:** Sets up an isolated virtual environment (`python -m venv`) and installs requirements via `pip`.
+-   **Java / Go / Rust:** Uses their native package resolution (Maven/Gradle, Go modules, Cargo).
+-   *Note: If Docker/Docker Compose is detected, host-level dependency installation is skipped in favor of containerized isolation.*
+
+#### Application Launch (`RunProject`)
+Executes the project using the corresponding language runner:
+-   **Docker Priority:** If a `docker-compose.yml` or `Dockerfile` is present, those take absolute precedence. `RunProject` launches Docker Compose or builds and runs the container, maintaining sandboxed isolation.
+-   **Language Runtimes:** Executes specific launch commands (e.g., `node src/index.js`, `python manage.py runserver`, `go run main.go`, or using `serve` for static HTML roots).
+-   **Subprocess Management (`internal/exec`):** All processes are hooked to standard inputs and outputs via OS execution wrappers. `RunCmdAttached` and `RunCmdAttachedEnv` ensure that interactive processes (like dev servers) bind directly to the TTY, proxying stdout and stderr visually back to the user seamlessly.
+
+---
+
+## Supported Ecosystems
+
+| Language | Support / Runtime | Detected Frameworks | Package Management |
+| :------- | :--- | :--- | :--- |
+| **Node.js** | Supported | React, Next.js, Vue, Nuxt, Angular, Vite, Svelte, Astro, Gatsby, Express, NestJS | `npm`, `yarn`, `pnpm` |
+| **Python** | Supported | Django, FastAPI, Flask | Isolated `venv`, `pip` |
+| **Java** | Supported | Spring Boot | Maven (`pom.xml`), Gradle (`build.gradle`) |
+| **Go** | Supported | Standard Library | Go Modules (`go.mod`) |
+| **Rust** | Supported | Standard Library | Cargo (`Cargo.toml`) |
+| **C# (.NET)** | Detected | ASP.NET | Standard `.csproj` |
+| **PHP** | Detected | None specifically | N/A |
+| **Static HTML** | Supported | Static File Server (`index.html`) | N/A (Launched via static file hosting) |
+| **Docker** | Supported | Any Containerized App | Dockerfile, Docker Compose |
+
+---
+
+## Command Line Interface (CLI) Use-Cases
+
+-   **`sandbox-engine scan`**: Performs the file system traversal and outputs a formatted list of all root sub-projects discovered.
+-   **`sandbox-engine detect`**: Extends the scan operation to analyze and output the language, framework, port, entrypoint, and Docker usage for every project.
+-   **`sandbox-engine run`**: The primary command. It installs dependencies and safely sandboxes the *first* detected project in the repository.
+-   **`sandbox-engine run <project>`**: Allows sandboxing of a specific project within a monorepo by string matching the project directory or name.
+-   **`--path <dir>`**: An overarching flag that allows the CLI tool to process an external repository without having to change the current working directory.
+
+## Summary
+
+The **Sandbox Engine** is built strictly emphasizing modularity:
+`Scanner` maps the territory ➔ `Detector` interprets the context ➔ `Runtime` handles the execution. 
+
+This strict separation of concerns allows adding support for new languages and frameworks just by appending the indicator file constants in `scanner.go`, defining the metadata enums in `types.go`, assigning the logic in `detector.go`, and creating the relevant runner script under `internal/runtime/`.

sandbox_engine-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sandbox_engine_pkg/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sandbox_engine_pkg/sandbox-engine,sha256=4bMEg8IJuqfxwhOWvA3KSrjUuNfGSKaIlWD8dCCT58Q,1926816
+sandbox_engine_pkg/wrapper.py,sha256=9_qWoWf6YPrwrqgNOVG7Ar9e-0h0Jw22G8J60keswnY,946
+sandbox_engine-1.0.0.dist-info/METADATA,sha256=tV7uwF1p0KMk_4n4QRdGeuDK0dGC7Bptix9e_6sPhBE,7636
+sandbox_engine-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sandbox_engine-1.0.0.dist-info/entry_points.txt,sha256=sdsrqcZQsGcBeHXBu7-rnAACj3V8wSKb6OXHWd7iMEw,67
+sandbox_engine-1.0.0.dist-info/top_level.txt,sha256=TaAjjY-qwzbUygBsrIODAreZIJfghAReBis_Cijz62k,19
+sandbox_engine-1.0.0.dist-info/RECORD,,

sandbox_engine-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sandbox_engine-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sandbox-engine = sandbox_engine_pkg.wrapper:main

sandbox_engine-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sandbox_engine_pkg

sandbox_engine_pkg/wrapper.py

@@ -0,0 +1,26 @@
+import os
+import sys
+import subprocess
+
+def main():
+    # Find the binary in the same directory as this script
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    
+    # Determine the binary name based on the platform
+    binary_name = "sandbox-engine.exe" if sys.platform == "win32" else "sandbox-engine"
+    binary_path = os.path.join(pkg_dir, binary_name)
+    
+    if not os.path.exists(binary_path):
+        print(f"Error: The compiled Go binary was not found at {binary_path}", file=sys.stderr)
+        print("Please ensure the package was installed correctly and Go is available.", file=sys.stderr)
+        sys.exit(1)
+        
+    # Execute the binary, passing all arguments provided to this script
+    # sys.argv[0] is the Python script name, so we slice from [1:]
+    try:
+        sys.exit(subprocess.call([binary_path] + sys.argv[1:]))
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+if __name__ == "__main__":
+    main()