Metadata-Version: 2.4
Name: sandbox-engine
Version: 1.0.1
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/`.
