smartdeno/readme.md

# @push.rocks/smartdeno

Run Deno scripts from Node.js with automatic Deno management, permission control, and ephemeral script execution. 🦕➡️📦

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
npm install @push.rocks/smartdeno
# or
pnpm add @push.rocks/smartdeno
```

## Usage

### 🚀 Basic Example

```typescript
import { SmartDeno } from '@push.rocks/smartdeno';

const smartDeno = new SmartDeno();

// Start SmartDeno (downloads Deno if needed)
await smartDeno.start();

// Execute a Deno script
const result = await smartDeno.executeScript(`console.log("Hello from Deno!")`);
console.log(result.stdout); // "Hello from Deno!"
console.log(result.exitCode); // 0

// Clean up when done
await smartDeno.stop();
```

### ⚙️ Configuration Options

#### Start Options

```typescript
await smartDeno.start({
  // Force download a local copy of Deno even if it's in PATH
  forceLocalDeno: true,

  // Custom port for the internal script server (default: 3210)
  port: 4000,
});
```

### 🔐 Deno Permissions

Control what your Deno scripts can access using the permissions option:

```typescript
// Allow network access
const result = await smartDeno.executeScript(
  `const response = await fetch("https://api.example.com/data");
   console.log(await response.text());`,
  { permissions: ['net'] }
);

// Allow environment variable access
const envResult = await smartDeno.executeScript(
  `console.log(Deno.env.get("HOME"))`,
  { permissions: ['env'] }
);

// Allow all permissions (use with caution! ⚠️)
const fullResult = await smartDeno.executeScript(
  `// Script with full access`,
  { permissions: ['all'] }
);
```

#### Available Permissions

| Permission | Description |
|------------|-------------|
| `all` | Grant all permissions (`-A` flag) |
| `env` | Environment variable access |
| `ffi` | Foreign function interface |
| `hrtime` | High-resolution time measurement |
| `net` | Network access |
| `read` | File system read access |
| `run` | Subprocess execution |
| `sys` | System information access |
| `write` | File system write access |

### 📤 Execution Results

The `executeScript` method returns detailed execution information:

```typescript
const result = await smartDeno.executeScript(`console.log("test")`);

console.log(result.exitCode); // 0 for success, non-zero for errors
console.log(result.stdout);   // Standard output
console.log(result.stderr);   // Standard error output
```

### 🛡️ Error Handling

```typescript
// Scripts that throw errors return non-zero exit codes
const result = await smartDeno.executeScript(`throw new Error("Something went wrong")`);

if (result.exitCode !== 0) {
  console.error('Script failed:', result.stderr);
}

// Attempting to execute before starting throws an error
try {
  const unstarted = new SmartDeno();
  await unstarted.executeScript(`console.log("test")`);
} catch (error) {
  console.error(error.message); // "SmartDeno is not started. Call start() first."
}
```

### 🔄 Lifecycle Management

```typescript
const smartDeno = new SmartDeno();

// Check if running
console.log(smartDeno.isRunning()); // false

await smartDeno.start();
console.log(smartDeno.isRunning()); // true

// Execute scripts...

await smartDeno.stop();
console.log(smartDeno.isRunning()); // false

// Safe to call stop() multiple times
await smartDeno.stop(); // No error
```

### 🌐 Integration Example

Using SmartDeno in an Express server:

```typescript
import express from 'express';
import { SmartDeno } from '@push.rocks/smartdeno';

const app = express();
const smartDeno = new SmartDeno();

app.use(express.json());

// Initialize on startup
await smartDeno.start({ port: 3211 });

app.post('/execute', async (req, res) => {
  const { script, permissions } = req.body;

  try {
    const result = await smartDeno.executeScript(script, { permissions });
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Cleanup on shutdown
process.on('SIGTERM', async () => {
  await smartDeno.stop();
  process.exit(0);
});

app.listen(3000);
```

## 🔧 How It Works

SmartDeno works by:

1. **🦕 Deno Management** — Automatically downloads the latest Deno binary for your platform if not available or if `forceLocalDeno` is set
2. **🖥️ Script Server** — Runs an internal HTTP server that serves scripts to Deno
3. **⚡ Ephemeral Execution** — Each script execution is isolated and cleaned up after completion
4. **🔒 Permission Control** — Translates permission options to Deno's security flags

## 📚 API Reference

### `SmartDeno`

#### Constructor

```typescript
const smartDeno = new SmartDeno();
```

#### Methods

| Method | Description |
|--------|-------------|
| `start(options?)` | Initialize and start SmartDeno |
| `stop()` | Stop SmartDeno and clean up resources |
| `isRunning()` | Check if SmartDeno is currently running |
| `executeScript(script, options?)` | Execute a Deno script |

### Types

```typescript
interface ISmartDenoOptions {
  forceLocalDeno?: boolean;
  port?: number;
}

interface IExecuteScriptOptions {
  permissions?: TDenoPermission[];
}

type TDenoPermission =
  | 'all'
  | 'env'
  | 'ffi'
  | 'hrtime'
  | 'net'
  | 'read'
  | 'run'
  | 'sys'
  | 'write';
```

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.