push.rocks/smartdeno
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(core): Add permission-controlled Deno execution, configurable script server port, improved downloader, dependency bumps and test updates

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-02 11:27:35 +00:00
parent 01dd40e599
commit fb0bfed4ab
20 changed files with 7919 additions and 3613 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
readme.md
View File

@@ -1,114 +1,249 @@
# @push.rocks/smartdeno
a module to run deno from node
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
To install `@push.rocks/smartdeno`, run the following command in your project directory:
```bash
npm install @push.rocks/smartdeno --save
npm install @push.rocks/smartdeno
# or
pnpm add @push.rocks/smartdeno
```
## Usage
This guide will provide an overview of how to use `@push.rocks/smartdeno` in your Node.js project to run Deno scripts. Given the nature of the project, which allows running Deno from Node.js environments, we'll explore various scenarios including setup, executing a simple Deno script, integrating with existing Node.js workflows, and managing Deno downloads.
### Setting Up
First, ensure you import `SmartDeno` in your TypeScript file using the ESM syntax:
### 🚀 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();
```
#### Initializing SmartDeno
### ⚙️ Configuration Options
To start working with Deno in your Node.js project, you first need to create an instance of `SmartDeno` and start it. This process prepares the environment, including downloading Deno if necessary:
#### 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();
async function setup() {
await smartDeno.start({
forceLocalDeno: true // Use this to force a local download of Deno even if it's globally available
});
}
// Check if running
console.log(smartDeno.isRunning()); // false
setup();
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
```
### Executing a Deno Script
### 🌐 Integration Example
With `SmartDeno` set and started, you can now execute Deno scripts. Let's run a simple script that prints a message:
```typescript
async function runDenoScript() {
const script = `console.log("Hello from Deno!");`;
await smartDeno.executeScript(script);
}
runDenoScript();
```
This method sends the script to Deno for execution. The flexibility of `SmartDeno` allows for more complex scripts to be executed similarly.
### Integrating with Node.js Workflows
`SmartDeno` can be seamlessly integrated into existing Node.js applications or workflows. Here's an example of integrating a Deno script execution within a Node.js Express server:
Using SmartDeno in an Express server:
```typescript
import express from 'express';
import { SmartDeno } from '@push.rocks/smartdeno';
const app = express();
const port = 3000;
const smartDeno = new SmartDeno();
app.get('/run-deno-script', async (req, res) => {
const script = `console.log("Deno script executed!");`;
await smartDeno.executeScript(script);
res.send('Deno script executed. Check console for output.');
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 });
}
});
app.listen(port, () => {
console.log(`Example app listening at http://localhost:${port}`);
// Cleanup on shutdown
process.on('SIGTERM', async () => {
await smartDeno.stop();
process.exit(0);
});
app.listen(3000);
```
### Managing Deno Version
## 🔧 How It Works
To manage which Deno version `SmartDeno` uses, the setup step allows for specifying `forceLocalDeno`. If you need to use a specific version of Deno, you can customize the download process by extending or modifying the download logic in `classes.denodownloader.ts`.
SmartDeno works by:
### Stopping SmartDeno
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
When your application is done using Deno, or if you need to clean up resources, you can stop the `SmartDeno` instance:
## 📚 API Reference
### `SmartDeno`
#### Constructor
```typescript
async function teardown() {
await smartDeno.stop();
}
teardown();
const smartDeno = new SmartDeno();
```
### Conclusion
#### Methods
`@push.rocks/smartdeno` provides a powerful and simple pathway for Node.js applications to run Deno scripts, combine the strengths of both environments, and leverage Deno's features within Node.js projects. Whether it's for executing isolated scripts, taking advantage of Deno's security model, or using Deno modules, `SmartDeno` offers the tools necessary for seamless integration.
| 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 |
For further information and advanced use cases, refer to the official GitHub repository and the typed documentation linked at the top of this guide.
### 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 that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
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
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
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.