@marsengine/mars-client 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# @yakreentechnologies/mars-client
+
+The official client for the **MARS Engine** - The Enterprise-Grade WebContainer Replacement.
+
+This lightweight library allows you to connect to a hosted MARS Engine runtime and control a full Node.js environment directly from the browser.
+
+## Features
+
+*   🚀 **Zero-Copy I/O**: Blazing fast communication with the engine.
+*   🔒 **Secure Sandbox**: Runs code in a hidden, isolated iframe.
+*   📦 **Drop-in Replacement**: API compatible with WebContainer.
+*   ⚡ **Vibe Coding Ready**: Optimized for AI-driven development.
+
+## Installation
+
+```bash
+npm install @marsengine/mars-client
+```
+
+## Usage
+
+### 1. Boot the Engine
+
+```typescript
+import { MarsEngineMessenger } from '@marsengine/mars-client';
+
+// Initialize the engine (pointing to your hosted runtime)
+const engine = new MarsEngineMessenger('https://engine.yourdomain.com');
+
+await engine.boot();
+console.log('MARS Engine is ready! 🚀');
+```
+
+### 2. Run a Command
+
+```typescript
+// Run 'npm install' inside the browser
+const process = await engine.spawn('npm', ['install']);
+
+// Stream the output to your terminal
+process.output.pipeTo(new WritableStream({
+  write(chunk) {
+    console.log(chunk);
+  }
+}));
+
+await process.exit;
+```
+
+### 3. Write a File
+
+```typescript
+await engine.fs.writeFile('/src/App.tsx', `
+  import React from 'react';
+  export default () => <h1>Hello from MARS! 🪐</h1>;
+`);
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MARS Messenger (Public API)
+ * This is the lightweight "Messenger" library that customers install.
+ * It contains NO engine logic, only a bridge to the hosted runtime.
+ */
+export declare class MarsEngineMessenger {
+    private runtimeUrl;
+    private iframe;
+    private channel;
+    private port;
+    constructor(runtimeUrl?: string);
+    /**
+     * Boot the engine by creating a hidden iframe to the hosted runtime.
+     */
+    boot(): Promise<void>;
+    /**
+     * Proxy call to the hosted engine.
+     */
+    call(method: string, args: any[]): Promise<any>;
+    spawn(command: string, args: string[]): Promise<any>;
+    get fs(): {
+        writeFile: (path: string, content: any) => Promise<any>;
+        readFile: (path: string) => Promise<any>;
+    };
+}

package/dist/index.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * MARS Messenger (Public API)
+ * This is the lightweight "Messenger" library that customers install.
+ * It contains NO engine logic, only a bridge to the hosted runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarsEngineMessenger = void 0;
+class MarsEngineMessenger {
+    constructor(runtimeUrl = 'https://runtime.mars.ai') {
+        this.runtimeUrl = runtimeUrl;
+        this.iframe = null;
+        this.port = null;
+        this.channel = new MessageChannel();
+    }
+    /**
+     * Boot the engine by creating a hidden iframe to the hosted runtime.
+     */
+    async boot() {
+        return new Promise((resolve, reject) => {
+            this.iframe = document.createElement('iframe');
+            this.iframe.src = this.runtimeUrl;
+            this.iframe.style.display = 'none';
+            this.iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+            this.iframe.onload = () => {
+                // Handshake: Send our MessagePort to the hosted runtime
+                this.iframe.contentWindow.postMessage({ type: 'MARS_HANDSHAKE' }, this.runtimeUrl, [this.channel.port2]);
+                this.port = this.channel.port1;
+                this.port.onmessage = (event) => {
+                    if (event.data.type === 'MARS_READY')
+                        resolve();
+                };
+            };
+            this.iframe.onerror = reject;
+            document.body.appendChild(this.iframe);
+        });
+    }
+    /**
+     * Proxy call to the hosted engine.
+     */
+    async call(method, args) {
+        if (!this.port)
+            throw new Error('Engine not booted');
+        const requestId = Math.random().toString(36).substring(7);
+        this.port.postMessage({ type: 'MARS_CALL', requestId, method, args });
+        return new Promise((resolve) => {
+            const handler = (event) => {
+                if (event.data.requestId === requestId) {
+                    this.port.removeEventListener('message', handler);
+                    resolve(event.data.result);
+                }
+            };
+            this.port.addEventListener('message', handler);
+            this.port.start();
+        });
+    }
+    // Public API Proxies
+    async spawn(command, args) {
+        return this.call('spawn', [command, args]);
+    }
+    get fs() {
+        return {
+            writeFile: (path, content) => this.call('fs.writeFile', [path, content]),
+            readFile: (path) => this.call('fs.readFile', [path]),
+        };
+    }
+}
+exports.MarsEngineMessenger = MarsEngineMessenger;

package/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "@marsengine/mars-client",
+    "version": "1.0.0",
+    "description": "Public Client for MARS Engine (WebContainer Replacement)",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc"
+    },
+    "keywords": [
+        "mars",
+        "webcontainer",
+        "client"
+    ],
+    "author": "MARS Team",
+    "license": "MIT",
+    "devDependencies": {
+        "typescript": "^5.3.3"
+    }
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * MARS Messenger (Public API)
+ * This is the lightweight "Messenger" library that customers install.
+ * It contains NO engine logic, only a bridge to the hosted runtime.
+ */
+
+export class MarsEngineMessenger {
+    private iframe: HTMLIFrameElement | null = null;
+    private channel: MessageChannel;
+    private port: MessagePort | null = null;
+
+    constructor(private runtimeUrl: string = 'https://runtime.mars.ai') {
+        this.channel = new MessageChannel();
+    }
+
+    /**
+     * Boot the engine by creating a hidden iframe to the hosted runtime.
+     */
+    async boot(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            this.iframe = document.createElement('iframe');
+            this.iframe.src = this.runtimeUrl;
+            this.iframe.style.display = 'none';
+            this.iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+
+            this.iframe.onload = () => {
+                // Handshake: Send our MessagePort to the hosted runtime
+                this.iframe!.contentWindow!.postMessage(
+                    { type: 'MARS_HANDSHAKE' },
+                    this.runtimeUrl,
+                    [this.channel.port2]
+                );
+
+                this.port = this.channel.port1;
+                this.port.onmessage = (event) => {
+                    if (event.data.type === 'MARS_READY') resolve();
+                };
+            };
+
+            this.iframe.onerror = reject;
+            document.body.appendChild(this.iframe);
+        });
+    }
+
+    /**
+     * Proxy call to the hosted engine.
+     */
+    async call(method: string, args: any[]): Promise<any> {
+        if (!this.port) throw new Error('Engine not booted');
+
+        const requestId = Math.random().toString(36).substring(7);
+        this.port.postMessage({ type: 'MARS_CALL', requestId, method, args });
+
+        return new Promise((resolve) => {
+            const handler = (event: MessageEvent) => {
+                if (event.data.requestId === requestId) {
+                    this.port!.removeEventListener('message', handler);
+                    resolve(event.data.result);
+                }
+            };
+            this.port!.addEventListener('message', handler);
+            this.port!.start();
+        });
+    }
+
+    // Public API Proxies
+    async spawn(command: string, args: string[]) {
+        return this.call('spawn', [command, args]);
+    }
+
+    get fs() {
+        return {
+            writeFile: (path: string, content: any) => this.call('fs.writeFile', [path, content]),
+            readFile: (path: string) => this.call('fs.readFile', [path]),
+        };
+    }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "CommonJS",
+        "declaration": true,
+        "outDir": "./dist",
+        "strict": true
+    },
+    "include": [
+        "src"
+    ]
+}