@freestyle-sh/with-nodejs 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,98 @@
+# @freestyle-sh/with-nodejs
+
+Node.js runtime via [NVM](https://github.com/nvm-sh/nvm) for [Freestyle](https://freestyle.sh) VMs.
+
+## Installation
+
+```bash
+npm install @freestyle-sh/with-nodejs freestyle-sandboxes
+```
+
+## Usage
+
+```typescript
+import { freestyle } from "freestyle-sandboxes";
+import { VmNodeJs } from "@freestyle-sh/with-nodejs";
+
+const { vm } = await freestyle.vms.create({
+  with: {
+    node: new VmNodeJs(),
+  },
+});
+
+const res = await vm.node.runCode({
+  code: "console.log(JSON.stringify({ hello: 'world' }));"
+});
+
+console.log(res);
+// { result: { hello: 'world' }, stdout: '{"hello":"world"}\n', statusCode: 0 }
+```
+
+## Options
+
+```typescript
+new VmNodeJs({
+  version: "22", // Optional: Node.js version (default: "24")
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `version` | `string` | `"24"` | Node.js version to install via NVM. |
+
+## API
+
+### `vm.node.runCode({ code: string })`
+
+Executes JavaScript code in the Node.js runtime.
+
+**Returns:** `Promise<RunCodeResponse>`
+
+```typescript
+type RunCodeResponse<Result> = {
+  result: Result;      // Parsed JSON from stdout (if valid JSON)
+  stdout?: string;     // Raw stdout output
+  stderr?: string;     // Raw stderr output
+  statusCode?: number; // Exit code
+};
+```
+
+### `vm.node.install(options?)`
+
+Installs npm packages.
+
+```typescript
+// Install from package.json in current directory
+await vm.node.install();
+
+// Install from package.json in specific directory
+await vm.node.install({ directory: "/app" });
+
+// Install specific packages
+await vm.node.install({ deps: ["lodash", "express"] });
+
+// Install with specific versions
+await vm.node.install({ deps: { "lodash": "^4.0.0", "express": "~5.0.0" } });
+
+// Install as dev dependencies
+await vm.node.install({ deps: ["typescript"], dev: true });
+
+// Install globally
+await vm.node.install({ global: true, deps: ["typescript"] });
+```
+
+**Returns:** `Promise<InstallResult>`
+
+```typescript
+type InstallResult = {
+  success: boolean;
+  stdout?: string;
+  stderr?: string;
+};
+```
+
+## Documentation
+
+- [Freestyle Documentation](https://docs.freestyle.sh)
+- [Node.js Documentation](https://nodejs.org/docs)
+- [NVM Documentation](https://github.com/nvm-sh/nvm)

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { VmWith, VmWithInstance, CreateVmOptions } from 'freestyle-sandboxes';
-import { VmJavaScriptRuntimeInstance, JSONValue, RunCodeResponse, VmJavaScriptRuntime } from '@freestyle-sh/with-type-js';
+import { VmWith, VmWithInstance, VmSpec } from 'freestyle-sandboxes';
+import { VmJavaScriptRuntimeInstance, JSONValue, RunCodeResponse, InstallOptions, InstallResult, VmJavaScriptRuntime } from '@freestyle-sh/with-type-js';
 
 type NodeJsOptions = {
     version?: string;
@@ -12,16 +12,17 @@ type NodeJsResolvedOptions = {
 declare class VmNodeJs extends VmWith<NodeJsRuntimeInstance> implements VmJavaScriptRuntime<VmJavaScriptRuntimeInstance> {
     options: NodeJsResolvedOptions;
     constructor(options?: NodeJsOptions);
-    configure(existingConfig: CreateVmOptions): CreateVmOptions | Promise<CreateVmOptions>;
+    configureSnapshotSpec(spec: VmSpec): VmSpec;
     createInstance(): NodeJsRuntimeInstance;
     installServiceName(): string;
 }
 declare class NodeJsRuntimeInstance extends VmWithInstance implements VmJavaScriptRuntimeInstance {
     builder: VmNodeJs;
     constructor(builder: VmNodeJs);
-    runCode<Result extends JSONValue = any>({ code, }: {
+    runCode<Result extends JSONValue = any>(args: string | {
         code: string;
     }): Promise<RunCodeResponse<Result>>;
+    install(options?: InstallOptions): Promise<InstallResult>;
 }
 
 export { VmNodeJs };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { VmWith, VmTemplate, VmWithInstance } from 'freestyle-sandboxes';
+import { VmWith, VmSpec, VmWithInstance } from 'freestyle-sandboxes';
 
 class VmNodeJs extends VmWith {
   options;
@@ -9,7 +9,7 @@ class VmNodeJs extends VmWith {
       workdir: options?.workdir
     };
   }
-  configure(existingConfig) {
+  configureSnapshotSpec(spec) {
     const installScript = `#!/bin/bash
 set -e
 export NVM_DIR="/opt/nvm"
@@ -25,8 +25,9 @@ npm -v
 [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
 [ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
 `;
-    const nodeJsConfig = {
-      template: new VmTemplate({
+    return this.composeSpecs(
+      spec,
+      new VmSpec({
         additionalFiles: {
           "/opt/install-nodejs.sh": {
             content: installScript
@@ -47,8 +48,7 @@ npm -v
           ]
         }
       })
-    };
-    return this.compose(existingConfig, nodeJsConfig);
+    );
   }
   createInstance() {
     return new NodeJsRuntimeInstance(this);
@@ -63,9 +63,8 @@ class NodeJsRuntimeInstance extends VmWithInstance {
     super();
     this.builder = builder;
   }
-  async runCode({
-    code
-  }) {
+  async runCode(args) {
+    const code = typeof args === "string" ? args : args.code;
     const result = await this.vm.exec({
       command: `node -e "${code.replace(/"/g, '\\"')}"`
     });
@@ -86,6 +85,27 @@ class NodeJsRuntimeInstance extends VmWithInstance {
       statusCode: result.statusCode ?? -1
     };
   }
+  async install(options) {
+    let command;
+    if (options?.global) {
+      command = `npm install -g ${options.deps.join(" ")}`;
+    } else {
+      const cdPrefix = options?.directory ? `cd ${options.directory} && ` : "";
+      if (!options?.deps) {
+        command = `${cdPrefix}npm install`;
+      } else {
+        const deps = Array.isArray(options.deps) ? options.deps : Object.entries(options.deps).map(([pkg, ver]) => `${pkg}@${ver}`);
+        const devFlag = options.dev ? " --save-dev" : "";
+        command = `${cdPrefix}npm install${devFlag} ${deps.join(" ")}`;
+      }
+    }
+    const result = await this.vm.exec({ command });
+    return {
+      success: result.statusCode === 0,
+      stdout: result.stdout ?? void 0,
+      stderr: result.stderr ?? void 0
+    };
+  }
 }
 
 export { VmNodeJs };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@freestyle-sh/with-nodejs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "dependencies": {
-    "freestyle-sandboxes": "^0.1.2",
-    "@freestyle-sh/with-type-js": "^0.2.0"
+    "freestyle-sandboxes": "^0.1.8",
+    "@freestyle-sh/with-type-js": "^0.2.1"
   },
   "type": "module",
   "main": "./dist/index.js",