sandbox-engine 1.0.0__tar.gz

sandbox_engine-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include readme.md
+include go.mod
+include go.sum
+include main.go
+recursive-include internal *
+include sandbox_engine_pkg/*.py

sandbox_engine-1.0.0/PKG-INFO

@@ -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/go.mod

@@ -0,0 +1,3 @@
+module sandbox-engine
+
+go 1.25.0

sandbox_engine-1.0.0/internal/color/color.go

@@ -0,0 +1,61 @@
+// Package color provides zero-dependency ANSI colour helpers and structured
+// log functions for the sandbox-engine CLI.
+package color
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+// ANSI escape codes.
+const (
+	Reset   = "\033[0m"
+	Bold    = "\033[1m"
+	Cyan    = "\033[36m"
+	Green   = "\033[32m"
+	Yellow  = "\033[33m"
+	Red     = "\033[31m"
+	Magenta = "\033[35m"
+	White   = "\033[97m"
+)
+
+// Sprintf wraps text with an ANSI colour code and resets afterwards.
+func Sprintf(code, format string, args ...interface{}) string {
+	return code + fmt.Sprintf(format, args...) + Reset
+}
+
+// Info prints an informational message to stdout.
+func Info(format string, args ...interface{}) {
+	fmt.Printf("%s  %s\n", Sprintf(Cyan, "[INFO]"), fmt.Sprintf(format, args...))
+}
+
+// Success prints a success message to stdout.
+func Success(format string, args ...interface{}) {
+	fmt.Printf("%s  %s\n", Sprintf(Green, "[OK]"), fmt.Sprintf(format, args...))
+}
+
+// Warn prints a warning message to stdout.
+func Warn(format string, args ...interface{}) {
+	fmt.Printf("%s  %s\n", Sprintf(Yellow, "[WARN]"), fmt.Sprintf(format, args...))
+}
+
+// Error prints an error message to stderr.
+func Error(format string, args ...interface{}) {
+	fmt.Fprintf(os.Stderr, "%s  %s\n", Sprintf(Red, "[ERR]"), fmt.Sprintf(format, args...))
+}
+
+// Step prints a step/action message to stdout.
+func Step(format string, args ...interface{}) {
+	fmt.Printf("%s  %s\n", Sprintf(Magenta, "[-->]"), fmt.Sprintf(format, args...))
+}
+
+// Header prints a bold section header with a horizontal rule.
+func Header(title string) {
+	line := strings.Repeat("-", 60)
+	fmt.Printf("\n%s%s%s\n  %s\n%s%s%s\n",
+		Bold, line, Reset,
+		Sprintf(Bold, title),
+		Bold, line, Reset,
+	)
+}

sandbox_engine-1.0.0/internal/detector/detector.go

@@ -0,0 +1,253 @@
+// Package detector analyses Project metadata to determine language, framework,
+// entry point, and default port.
+package detector
+
+import (
+	"path/filepath"
+	"strings"
+
+	"sandbox-engine/internal/color"
+	"sandbox-engine/internal/fsutil"
+	"sandbox-engine/internal/pkgjson"
+	"sandbox-engine/internal/types"
+)
+
+// Detector analyses Projects and fills Language, Framework, EntryPoint, Port.
+type Detector struct{}
+
+// New returns a ready-to-use Detector.
+func New() *Detector { return &Detector{} }
+
+// DetectAll runs detection across every project in the scan result.
+func (d *Detector) DetectAll(result *types.ScanResult) {
+	color.Header("Runtime & Framework Detector")
+	for _, p := range result.Projects {
+		d.Detect(p)
+	}
+}
+
+// Detect fills all detection fields for a single project.
+func (d *Detector) Detect(p *types.Project) {
+	fs := fsutil.FileSet(p.Files)
+
+	// Docker presence
+	p.UseDCom = fs["docker-compose.yml"] || fs["docker-compose.yaml"]
+	p.UseDocker = fs["dockerfile"]
+
+	// Language — priority order
+	switch {
+	case fs["package.json"]:
+		p.Language = types.LangNode
+	case fs["requirements.txt"] || fs["pyproject.toml"] || fs["pipfile"] || fs["manage.py"]:
+		p.Language = types.LangPython
+	case fs["go.mod"]:
+		p.Language = types.LangGo
+	case fs["pom.xml"] || fs["build.gradle"]:
+		p.Language = types.LangJava
+	case fs["cargo.toml"]:
+		p.Language = types.LangRust
+	case fsutil.HasCsproj(p.Files):
+		p.Language = types.LangDotNet
+		p.Framework = types.FWAspNet
+	case fs["index.html"] || fs["index.htm"]:
+		p.Language = types.LangStatic
+	case p.UseDCom || p.UseDocker:
+		p.Language = types.LangDocker
+	default:
+		p.Language = types.LangUnknown
+	}
+
+	// Framework
+	switch p.Language {
+	case types.LangNode:
+		p.Framework = d.detectNodeFramework(p, fs)
+		p.LockFile = detectLockFile(fs)
+	case types.LangPython:
+		p.Framework = d.detectPythonFramework(p, fs)
+	case types.LangJava:
+		p.Framework = d.detectJavaFramework(p)
+	}
+
+	// Python virtual environment
+	if p.Language == types.LangPython {
+		for _, name := range []string{"venv", ".venv", "env"} {
+			if fsutil.DirExists(filepath.Join(p.Root, name)) {
+				p.HasVenv = true
+				p.VenvPath = filepath.Join(p.Root, name)
+				break
+			}
+		}
+		if !p.HasVenv {
+			p.VenvPath = filepath.Join(p.Root, "venv")
+		}
+	}
+
+	// Entry point and port
+	p.EntryPoint = d.detectEntryPoint(p, fs)
+	p.Port = defaultPort(p)
+
+	color.Success("%-20s  lang=%-12s  fw=%-12s  port=%d  entry=%s",
+		p.Name,
+		color.Sprintf(color.Cyan, string(p.Language)),
+		color.Sprintf(color.Yellow, string(p.Framework)),
+		p.Port,
+		p.EntryPoint,
+	)
+}
+
+// detectNodeFramework returns the JS/Node framework for the project.
+func (d *Detector) detectNodeFramework(p *types.Project, fs map[string]bool) types.Framework {
+	// Config-file signals carry the highest confidence.
+	switch {
+	case fs["angular.json"]:
+		return types.FWAngular
+	case fs["astro.config.mjs"] || fs["astro.config.ts"]:
+		return types.FWAstro
+	case fs["gatsby-config.js"] || fs["gatsby-config.ts"]:
+		return types.FWGatsby
+	case fs["vite.config.js"] || fs["vite.config.ts"]:
+		return types.FWVite
+	}
+
+	// Fall back to scanning package.json dependencies.
+	deps := pkgjson.ReadDeps(filepath.Join(p.Root, "package.json"))
+	switch {
+	case deps["nuxt"]:
+		return types.FWNuxt
+	case deps["next"]:
+		return types.FWNextJS
+	case deps["gatsby"]:
+		return types.FWGatsby
+	case deps["@sveltejs/kit"] || deps["svelte"]:
+		return types.FWSvelte
+	case deps["@angular/core"]:
+		return types.FWAngular
+	case deps["@nestjs/core"]:
+		return types.FWNestJS
+	case deps["express"]:
+		return types.FWExpress
+	case deps["vue"]:
+		return types.FWVue
+	case deps["react"]:
+		return types.FWReact
+	}
+	return types.FWNone
+}
+
+// detectLockFile returns "pnpm", "yarn", or "npm" based on lock-file presence.
+func detectLockFile(fs map[string]bool) string {
+	switch {
+	case fs["pnpm-lock.yaml"]:
+		return "pnpm"
+	case fs["yarn.lock"]:
+		return "yarn"
+	default:
+		return "npm"
+	}
+}
+
+// detectPythonFramework infers the Python web framework.
+func (d *Detector) detectPythonFramework(p *types.Project, fs map[string]bool) types.Framework {
+	if fs["manage.py"] {
+		return types.FWDjango
+	}
+
+	// Scan requirements.txt for known package names.
+	for _, line := range fsutil.ReadLines(filepath.Join(p.Root, "requirements.txt")) {
+		lower := strings.ToLower(strings.TrimSpace(line))
+		switch {
+		case strings.HasPrefix(lower, "fastapi"):
+			return types.FWFastAPI
+		case strings.HasPrefix(lower, "flask"):
+			return types.FWFlask
+		case strings.HasPrefix(lower, "django"):
+			return types.FWDjango
+		}
+	}
+
+	// Scan common Python entry files for import statements.
+	for _, candidate := range []string{"app.py", "main.py", "server.py"} {
+		content := fsutil.ReadFileLower(filepath.Join(p.Root, candidate))
+		switch {
+		case strings.Contains(content, "fastapi"):
+			return types.FWFastAPI
+		case strings.Contains(content, "flask"):
+			return types.FWFlask
+		case strings.Contains(content, "django"):
+			return types.FWDjango
+		}
+	}
+	return types.FWNone
+}
+
+// detectJavaFramework checks pom.xml / build.gradle for Spring Boot markers.
+func (d *Detector) detectJavaFramework(p *types.Project) types.Framework {
+	combined := fsutil.ReadFileLower(filepath.Join(p.Root, "pom.xml")) +
+		fsutil.ReadFileLower(filepath.Join(p.Root, "build.gradle"))
+	if strings.Contains(combined, "spring-boot") || strings.Contains(combined, "spring.boot") {
+		return types.FWSpringBoot
+	}
+	return types.FWNone
+}
+
+// detectEntryPoint returns the primary launch file for the project.
+func (d *Detector) detectEntryPoint(p *types.Project, fs map[string]bool) string {
+	switch p.Language {
+	case types.LangPython:
+		for _, ep := range []string{"manage.py", "app.py", "main.py", "server.py"} {
+			if fs[strings.ToLower(ep)] {
+				return ep
+			}
+		}
+	case types.LangNode:
+		if main := pkgjson.ReadMain(filepath.Join(p.Root, "package.json")); main != "" {
+			return main
+		}
+		for _, ep := range []string{"index.js", "server.js", "app.js", "index.ts", "src/index.js", "src/index.ts"} {
+			if fsutil.FileExists(filepath.Join(p.Root, ep)) {
+				return ep
+			}
+		}
+	case types.LangGo:
+		if fs["main.go"] {
+			return "main.go"
+		}
+	case types.LangJava:
+		if fs["pom.xml"] {
+			return "pom.xml"
+		}
+		return "build.gradle"
+	case types.LangRust:
+		return "Cargo.toml"
+	case types.LangDotNet:
+		for _, f := range p.Files {
+			if strings.HasSuffix(strings.ToLower(f), ".csproj") {
+				return f
+			}
+		}
+	case types.LangStatic:
+		return "index.html"
+	}
+	return ""
+}
+
+// defaultPort returns the conventional port for a project.
+func defaultPort(p *types.Project) int {
+	switch p.Framework {
+	case types.FWFlask:
+		return 5000
+	case types.FWFastAPI, types.FWDjango:
+		return 8000
+	case types.FWSpringBoot, types.FWAspNet:
+		return 8080
+	}
+	switch p.Language {
+	case types.LangGo, types.LangJava:
+		return 8080
+	case types.LangPython:
+		return 5000
+	case types.LangNode, types.LangStatic:
+		return 3000
+	}
+	return 3000
+}

sandbox_engine-1.0.0/internal/exec/exec.go

@@ -0,0 +1,45 @@
+// Package exec provides thin wrappers around os/exec for running subprocesses.
+package exec
+
+import (
+	"os"
+	osexec "os/exec"
+)
+
+// RunCmd runs name+args in dir, streaming stdout/stderr. Returns any error.
+func RunCmd(dir, name string, args ...string) error {
+	cmd := osexec.Command(name, args...)
+	cmd.Dir = dir
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}
+
+// RunCmdAttached attaches stdin/stdout/stderr for interactive or long-lived
+// processes (dev servers, docker compose, etc.).
+func RunCmdAttached(dir, name string, args ...string) error {
+	cmd := osexec.Command(name, args...)
+	cmd.Dir = dir
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}
+
+// RunCmdAttachedEnv is like RunCmdAttached but prepends extra environment
+// variables before the inherited process environment.
+func RunCmdAttachedEnv(dir string, extraEnv []string, name string, args ...string) error {
+	cmd := osexec.Command(name, args...)
+	cmd.Dir = dir
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.Env = append(os.Environ(), extraEnv...)
+	return cmd.Run()
+}
+
+// CommandExists reports whether the named binary is accessible via PATH.
+func CommandExists(name string) bool {
+	_, err := osexec.LookPath(name)
+	return err == nil
+}

sandbox_engine-1.0.0/internal/fsutil/fsutil.go

@@ -0,0 +1,74 @@
+// Package fsutil provides file-system utility helpers used across sandbox-engine.
+package fsutil
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// FileSet converts a filename slice into a lowercase presence map for fast
+// membership checks.
+func FileSet(files []string) map[string]bool {
+	fs := make(map[string]bool, len(files))
+	for _, f := range files {
+		fs[strings.ToLower(f)] = true
+	}
+	return fs
+}
+
+// HasCsproj returns true if any element of files ends with ".csproj".
+func HasCsproj(files []string) bool {
+	for _, f := range files {
+		if strings.HasSuffix(strings.ToLower(f), ".csproj") {
+			return true
+		}
+	}
+	return false
+}
+
+// FileExists reports whether path is a regular file.
+func FileExists(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && !info.IsDir()
+}
+
+// DirExists reports whether path is a directory.
+func DirExists(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && info.IsDir()
+}
+
+// ReadFileLower reads a file and returns its contents lower-cased.
+// Returns an empty string on any error.
+func ReadFileLower(path string) string {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.ToLower(string(data))
+}
+
+// ReadLines returns the lines of a file split on newline.
+// Returns nil on any error.
+func ReadLines(path string) []string {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	return strings.Split(string(data), "\n")
+}
+
+// PythonBin resolves the path to a binary inside a virtual-env.
+// Falls back to the bare binary name (PATH lookup) when not found in the venv.
+func PythonBin(venvPath, bin string) string {
+	// Unix layout
+	if p := filepath.Join(venvPath, "bin", bin); FileExists(p) {
+		return p
+	}
+	// Windows layout
+	if p := filepath.Join(venvPath, "Scripts", bin+".exe"); FileExists(p) {
+		return p
+	}
+	return bin
+}

sandbox_engine-1.0.0/internal/pkgjson/pkgjson.go

@@ -0,0 +1,110 @@
+// Package pkgjson provides lightweight, zero-allocation helpers for extracting
+// data from package.json files without importing encoding/json.
+package pkgjson
+
+import (
+	"os"
+	"strings"
+)
+
+// ReadDeps returns a presence map of all dependency names declared in the
+// dependencies, devDependencies, and peerDependencies sections.
+func ReadDeps(path string) map[string]bool {
+	result := map[string]bool{}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return result
+	}
+	content := string(data)
+	for _, section := range []string{`"dependencies"`, `"devDependencies"`, `"peerDependencies"`} {
+		idx := strings.Index(content, section)
+		if idx < 0 {
+			continue
+		}
+		rest := content[idx:]
+		start := strings.Index(rest, "{")
+		end := strings.Index(rest, "}")
+		if start < 0 || end < 0 || end <= start {
+			continue
+		}
+		block := rest[start+1 : end]
+		for _, line := range strings.Split(block, "\n") {
+			line = strings.TrimSpace(line)
+			if len(line) == 0 || line[0] != '"' {
+				continue
+			}
+			closeQ := strings.Index(line[1:], `"`)
+			if closeQ < 0 {
+				continue
+			}
+			pkg := line[1 : closeQ+1]
+			if pkg != "" {
+				result[pkg] = true
+			}
+		}
+	}
+	return result
+}
+
+// ReadMain extracts the value of the "main" field from package.json.
+// Returns an empty string when not found.
+func ReadMain(path string) string {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	content := string(data)
+	idx := strings.Index(content, `"main"`)
+	if idx < 0 {
+		return ""
+	}
+	rest := strings.TrimSpace(content[idx+6:])
+	colon := strings.Index(rest, ":")
+	if colon < 0 {
+		return ""
+	}
+	rest = strings.TrimSpace(rest[colon+1:])
+	if len(rest) == 0 || rest[0] != '"' {
+		return ""
+	}
+	end := strings.Index(rest[1:], `"`)
+	if end < 0 {
+		return ""
+	}
+	return rest[1 : end+1]
+}
+
+// ReadScripts returns a map of script-name to command string from package.json.
+func ReadScripts(path string) map[string]string {
+	result := map[string]string{}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return result
+	}
+	content := string(data)
+	idx := strings.Index(content, `"scripts"`)
+	if idx < 0 {
+		return result
+	}
+	rest := content[idx:]
+	start := strings.Index(rest, "{")
+	end := strings.Index(rest, "}")
+	if start < 0 || end < 0 || end <= start {
+		return result
+	}
+	block := rest[start+1 : end]
+	for _, line := range strings.Split(block, "\n") {
+		line = strings.TrimSpace(strings.TrimRight(line, ","))
+		if len(line) == 0 || line[0] != '"' {
+			continue
+		}
+		parts := strings.SplitN(line, ":", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		key := strings.Trim(strings.TrimSpace(parts[0]), `"`)
+		val := strings.Trim(strings.TrimSpace(parts[1]), `"`)
+		result[key] = val
+	}
+	return result
+}

sandbox_engine-1.0.0/internal/runtime/docker.go

@@ -0,0 +1,29 @@
+// Package runtime — Docker and docker-compose launch logic.
+package runtime
+
+import (
+	"fmt"
+	"strings"
+
+	"sandbox-engine/internal/color"
+	"sandbox-engine/internal/exec"
+	"sandbox-engine/internal/types"
+)
+
+// LaunchDockerCompose starts the stack defined by docker-compose.yml.
+func LaunchDockerCompose(p *types.Project) error {
+	color.Step("docker compose up")
+	return exec.RunCmdAttached(p.Root, "docker", "compose", "up")
+}
+
+// LaunchDockerfile builds a Docker image then runs a container from it.
+func LaunchDockerfile(p *types.Project) error {
+	image := strings.ToLower(strings.ReplaceAll(p.Name, " ", "-")) + "-sandbox"
+	color.Step("docker build -t %s .", image)
+	if err := exec.RunCmd(p.Root, "docker", "build", "-t", image, "."); err != nil {
+		return err
+	}
+	portMap := fmt.Sprintf("%d:%d", p.Port, p.Port)
+	color.Step("docker run --rm -p %s %s", portMap, image)
+	return exec.RunCmdAttached(p.Root, "docker", "run", "--rm", "-p", portMap, image)
+}