Tect.js v0.2.5

A lightweight JavaScript runtime and CLI execution tool. Tect.js provides a minimal, production-structured runtime for executing JavaScript scripts with a strictly isolated execution environment, safe file access, timing utilities, and controlled environment access.

Features

• Strict VM Isolation: All user code executes in isolated VM contexts with controlled API exposure
• Global Leak Mitigation: Runtime Guard Layer provides detection of global scope modification attempts
• CLI Interface: Clean command-line interface for script execution
• Argument Passing: Pass arguments to scripts via CLI
• Runtime Context: Access to Tect.js API within executed scripts
• Structured Error System: Consistent error types and exit codes
• Internal Logging: Timestamped logging for runtime events
• Configuration: Optional configuration for runtime behavior

Installation

# Clone the repository
git clone https://github.com/your-org/tect.js.git
cd tect.js

# Install dependencies
npm install

# Link globally (optional)
npm link

Quick Start

# Run the hello example
tect run examples/hello.js

# Run with arguments
tect run examples/args-demo.js --name World --count 3

# Execute a file
tect exec examples/math.js

# Initialize a new project
tect init

# Check version
tect version

Commands

tect run <file>

Execute a JavaScript file with validation.

tect run examples/hello.js
tect run examples/args-demo.js --name User

tect exec <file>

Execute a JavaScript file without validation (for dynamic execution).

tect exec examples/math.js

tect init

Initialize a new Tect.js project in the current directory.

tect init

Creates tect.config.js with default configuration.

tect version

Display version and environment information.

tect version

tect help

Show help information.

tect help

Exit Codes

Tect.js uses standardized exit codes:

• 0 - Success
• 1 - Runtime error
• 2 - File not found / validation error
• 3 - Isolation boundary violation / global scope modification attempt

v0.2.5 Safety Features

Strict VM Isolation

All user code executes in isolated VM contexts with:

• Controlled access to Node.js globals via explicit API
• Fresh runtime context for each execution
• Memory separation between execution contexts

Global Leak Mitigation

Runtime Guard Layer provides:

• Detection of global scope modification attempts
• Configurable enforcement mode (enabled by default)
• Automatic logging of modification attempts

Execution Isolation Characteristics

• Variables declared in one run do not exist in next run
• Context resets after each execution
• Runtime state separation between executions

Runtime Context API

Scripts executed by Tect.js have access to the tect global object:

{
    version: string,    // Tect.js version
    args: object,       // Parsed CLI arguments
    env: object,        // Environment variables
    exit: (code) => void // Explicit runtime exit
}

Examples

Basic Execution

// examples/hello.js
console.log('Hello from Tect.js runtime');

if (typeof tect !== 'undefined') {
    console.log('Tect version:', tect.version);
    console.log('Runtime args:', tect.args);
}

Using Arguments

// examples/args-demo.js
console.log('Arguments received:', JSON.stringify(tect.args));

Run with: tect run examples/args-demo.js --name World --count 3

Mathematical Operations

// examples/math.js
function add(a, b) {
    return a + b;
}

console.log('5 + 3 =', add(5, 3));

Configuration

Optional tect.config.js for project-level configuration:

module.exports = {
    runtime: {
        timeout: 30000,           // Execution timeout in ms
        memoryLimit: 512,         // Memory limit in MB
        strictMode: true,         // Enable strict mode by default
        blockGlobalAccess: true,   // Block access to global properties
        warnOnGlobalLeak: true     // Log warnings for global leak attempts
    },
    paths: {
        modules: './node_modules',
        include: ['./src']
    }
};

Project Structure

tect.js/
├── src/
│   ├── core/         # Runtime engine
│   ├── cli/          # CLI command handlers
│   ├── loader/       # Script loading logic
│   └── utils/        # Helper functions
├── bin/
│   └── tect.js       # CLI entry point
├── examples/         # Example scripts
├── tests/            # Execution tests
└── tect.config.js    # Configuration

Development

Running Tests

# Basic execution tests
npm test

# v0.2.5 safety tests (global leak prevention, isolation, etc.)
npm run test:safety

Development Workflow

1. Modify source files in src/
2. Test using example scripts in examples/
3. Run the test suite to verify execution
4. Update documentation as needed

Roadmap

• [ ] Module system implementation
• [ ] Async/await support
• [ ] Package manager integration
• [ ] Security sandbox improvements
• [ ] Performance optimizations

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Status

v0.2.5 - Execution safety and stability upgrade

• Strict VM isolation for all executions
• Global variable leak mitigation
• Runtime Guard Layer for isolation boundary detection
• Structured error system with consistent exit codes
• Internal logging layer
• Comprehensive isolation test suite
• Enhanced CLI stability

v0.1.0 - Initial prototype release

• Basic runtime execution
• CLI commands: run, exec, init, version
• Argument passing
• Configuration support
• Example scripts