@magpiecloud/mags 1.0.0

package/README.md

@@ -0,0 +1,111 @@
+# @magpiecloud/mags
+
+Execute scripts instantly on Magpie's microVM infrastructure. VMs boot in <100ms from a warm pool.
+
+## Installation
+
+```bash
+npm install -g @magpiecloud/mags
+```
+
+## Quick Start
+
+### 1. Set your API token
+
+```bash
+export MAGS_API_TOKEN="your-token-here"
+```
+
+### 2. Run a script
+
+```bash
+mags run 'echo Hello World'
+```
+
+## CLI Commands
+
+```bash
+# Simple command
+mags run 'echo Hello'
+
+# With persistent workspace (S3 sync)
+mags run -w my-project 'apk add nodejs && node --version'
+
+# Persistent VM with public URL
+mags run -w webapp -p --url 'python3 -m http.server 8080'
+
+# With startup command (for auto-wake)
+mags run -w webapp -p --url --startup-command 'npm start' 'npm install && npm start'
+
+# Custom port
+mags run -w webapp -p --url --port 3000 'npm start'
+
+# Enable URL for existing job
+mags url <job-id>
+mags url <job-id> 8080
+
+# Other commands
+mags status <job-id>
+mags logs <job-id>
+mags list
+mags stop <job-id>
+```
+
+## CLI Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-w, --workspace` | Workspace ID for persistent storage | auto |
+| `-p, --persistent` | Keep VM alive for URL/SSH access | false |
+| `--url` | Enable public URL access (requires -p) | false |
+| `--port` | Port to expose for URL access | 8080 |
+| `--startup-command` | Command when VM wakes from sleep | none |
+
+## Node.js SDK
+
+```javascript
+const Mags = require('@magpiecloud/mags');
+
+const mags = new Mags({
+  apiToken: process.env.MAGS_API_TOKEN
+});
+
+// Run and wait for completion
+const result = await mags.runAndWait('echo Hello World');
+console.log(result.logs);
+
+// Run with workspace
+const { requestId } = await mags.run('python script.py', {
+  workspaceId: 'myproject',
+  persistent: true
+});
+
+// Get status
+const status = await mags.status(requestId);
+
+// Enable URL access
+await mags.enableUrl(requestId, 8080);
+
+// List jobs
+const jobs = await mags.list({ page: 1, pageSize: 10 });
+
+// Stop a job
+await mags.stop(requestId);
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MAGS_API_TOKEN` | Your API token (required) | - |
+| `MAGS_API_URL` | API endpoint | https://api.magpiecloud.com |
+
+## Performance
+
+- **Warm start**: <100ms (VM from pool)
+- **Cold start**: ~4 seconds (new VM boot)
+- **Script overhead**: ~50ms
+
+## License
+
+MIT

package/bin/mags.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+// Configuration
+const API_URL = process.env.MAGS_API_URL || 'https://api.magpiecloud.com';
+const API_TOKEN = process.env.MAGS_API_TOKEN || '';
+
+// Colors
+const colors = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+  reset: '\x1b[0m'
+};
+
+function log(color, msg) {
+  console.log(`${colors[color]}${msg}${colors.reset}`);
+}
+
+function request(method, path, body = null) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, API_URL);
+    const isHttps = url.protocol === 'https:';
+    const lib = isHttps ? https : http;
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      method,
+      headers: {
+        'Authorization': `Bearer ${API_TOKEN}`,
+        'Content-Type': 'application/json'
+      }
+    };
+
+    const req = lib.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve(data);
+        }
+      });
+    });
+
+    req.on('error', reject);
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function usage() {
+  console.log(`
+${colors.cyan}Mags CLI - Instant VM Execution${colors.reset}
+
+Usage: mags <command> [options] [script]
+
+Commands:
+  run [options] <script>          Execute a script on a microVM
+  status <job-id>                 Get job status
+  logs <job-id>                   Get job logs
+  list                            List recent jobs
+  url <job-id> [port]             Enable URL access for a job
+  stop <job-id>                   Stop a running job
+
+Run Options:
+  -w, --workspace <id>            Use persistent workspace (S3 sync)
+  -p, --persistent                Keep VM alive after script completes
+  --url                           Enable public URL access (requires -p)
+  --port <port>                   Port to expose for URL (default: 8080)
+  --startup-command <cmd>         Command to run when VM wakes from sleep
+
+Environment:
+  MAGS_API_TOKEN                  Your API token (required)
+  MAGS_API_URL                    API endpoint (default: https://api.magpiecloud.com)
+
+Examples:
+  mags run 'echo Hello World'
+  mags run -w myproject 'python3 script.py'
+  mags run -p --url 'python3 -m http.server 8080'
+  mags run -w webapp -p --url --port 3000 'npm start'
+  mags status abc123
+  mags logs abc123
+  mags url abc123 8080
+`);
+  process.exit(1);
+}
+
+async function runJob(args) {
+  let script = '';
+  let workspace = '';
+  let persistent = false;
+  let enableUrl = false;
+  let port = 8080;
+  let startupCommand = '';
+
+  // Parse flags
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '-w':
+      case '--workspace':
+        workspace = args[++i];
+        break;
+      case '-p':
+      case '--persistent':
+        persistent = true;
+        break;
+      case '--url':
+        enableUrl = true;
+        break;
+      case '--port':
+        port = parseInt(args[++i]) || 8080;
+        break;
+      case '--startup-command':
+        startupCommand = args[++i];
+        break;
+      default:
+        script = args.slice(i).join(' ');
+        i = args.length;
+    }
+  }
+
+  if (!script) {
+    log('red', 'Error: No script provided');
+    usage();
+  }
+
+  log('blue', 'Submitting job...');
+
+  const payload = {
+    script,
+    type: 'inline',
+    persistent
+  };
+  if (workspace) payload.workspace_id = workspace;
+  if (startupCommand) payload.startup_command = startupCommand;
+
+  const response = await request('POST', '/api/v1/mags-jobs', payload);
+
+  if (!response.request_id) {
+    log('red', 'Failed to submit job:');
+    console.log(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  const requestId = response.request_id;
+  log('green', `Job submitted: ${requestId}`);
+  if (workspace) log('blue', `Workspace: ${workspace}`);
+  if (persistent) log('yellow', 'Persistent: VM will stay alive');
+
+  // Poll for completion
+  const maxAttempts = 120;
+  let attempt = 0;
+
+  while (attempt < maxAttempts) {
+    const status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+
+    if (status.status === 'completed') {
+      log('green', `Completed in ${status.script_duration_ms}ms`);
+      break;
+    } else if (status.status === 'running' && persistent) {
+      log('green', 'VM running');
+
+      if (enableUrl && status.subdomain) {
+        log('blue', `Enabling URL access on port ${port}...`);
+        const accessResp = await request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+        if (accessResp.success) {
+          log('green', `URL: https://${status.subdomain}.apps.magpiecloud.com`);
+        } else {
+          log('yellow', 'Warning: Could not enable URL access');
+        }
+      } else if (status.subdomain) {
+        log('cyan', `Subdomain: ${status.subdomain}`);
+        log('cyan', `To enable URL: mags url ${requestId} ${port}`);
+      }
+      return;
+    } else if (status.status === 'error') {
+      log('red', 'Job failed');
+      console.log(JSON.stringify(status, null, 2));
+      process.exit(1);
+    }
+
+    process.stdout.write('.');
+    await sleep(1000);
+    attempt++;
+  }
+
+  console.log('');
+
+  // Get logs
+  log('cyan', 'Output:');
+  const logsResp = await request('GET', `/api/v1/mags-jobs/${requestId}/logs`);
+  if (logsResp.logs) {
+    logsResp.logs
+      .filter(l => l.source === 'stdout' || l.source === 'stderr')
+      .forEach(l => console.log(l.message));
+  }
+}
+
+async function enableUrlAccess(requestId, port = 8080) {
+  if (!requestId) {
+    log('red', 'Error: Job ID required');
+    usage();
+  }
+
+  log('blue', `Enabling URL access on port ${port}...`);
+
+  const accessResp = await request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+
+  if (accessResp.success) {
+    const status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+    if (status.subdomain) {
+      log('green', `URL enabled: https://${status.subdomain}.apps.magpiecloud.com`);
+    } else {
+      log('green', 'URL access enabled');
+    }
+  } else {
+    log('red', 'Failed to enable URL access');
+    console.log(JSON.stringify(accessResp, null, 2));
+    process.exit(1);
+  }
+}
+
+async function getStatus(requestId) {
+  if (!requestId) {
+    log('red', 'Error: Job ID required');
+    usage();
+  }
+  const status = await request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+  console.log(JSON.stringify(status, null, 2));
+}
+
+async function getLogs(requestId) {
+  if (!requestId) {
+    log('red', 'Error: Job ID required');
+    usage();
+  }
+  const logsResp = await request('GET', `/api/v1/mags-jobs/${requestId}/logs`);
+  if (logsResp.logs) {
+    logsResp.logs.forEach(l => {
+      const levelColor = l.level === 'error' ? 'red' : l.level === 'warn' ? 'yellow' : 'gray';
+      console.log(`${colors[levelColor]}[${l.level}]${colors.reset} ${l.message}`);
+    });
+  }
+}
+
+async function listJobs() {
+  const resp = await request('GET', '/api/v1/mags-jobs?page=1&page_size=10');
+  if (resp.jobs && resp.jobs.length > 0) {
+    log('cyan', 'Recent Jobs:\n');
+    resp.jobs.forEach(job => {
+      const statusColor = job.status === 'completed' ? 'green'
+        : job.status === 'running' ? 'blue'
+        : job.status === 'error' ? 'red'
+        : 'yellow';
+      console.log(`${colors.gray}${job.request_id}${colors.reset}`);
+      console.log(`  Name: ${job.name || '-'}`);
+      console.log(`  Status: ${colors[statusColor]}${job.status}${colors.reset}`);
+      console.log(`  Workspace: ${job.workspace_id || '-'}`);
+      console.log(`  Duration: ${job.script_duration_ms ? job.script_duration_ms + 'ms' : '-'}`);
+      console.log(`  Created: ${job.created_at || '-'}`);
+      console.log('');
+    });
+  } else {
+    log('yellow', 'No jobs found');
+  }
+}
+
+async function stopJob(requestId) {
+  if (!requestId) {
+    log('red', 'Error: Job ID required');
+    usage();
+  }
+  log('blue', `Stopping job ${requestId}...`);
+  const resp = await request('POST', `/api/v1/mags-jobs/${requestId}/stop`);
+  if (resp.success) {
+    log('green', 'Job stopped');
+  } else {
+    log('red', 'Failed to stop job');
+    console.log(JSON.stringify(resp, null, 2));
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (!API_TOKEN) {
+    log('red', 'Error: MAGS_API_TOKEN not set');
+    console.log('Set it via: export MAGS_API_TOKEN=your-token');
+    process.exit(1);
+  }
+
+  const command = args[0];
+
+  try {
+    switch (command) {
+      case 'run':
+        await runJob(args.slice(1));
+        break;
+      case 'url':
+        await enableUrlAccess(args[1], parseInt(args[2]) || 8080);
+        break;
+      case 'status':
+        await getStatus(args[1]);
+        break;
+      case 'logs':
+        await getLogs(args[1]);
+        break;
+      case 'list':
+        await listJobs();
+        break;
+      case 'stop':
+        await stopJob(args[1]);
+        break;
+      case '--help':
+      case '-h':
+      case '--version':
+      case '-v':
+        if (command === '--version' || command === '-v') {
+          console.log('mags v1.0.0');
+          process.exit(0);
+        }
+        usage();
+        break;
+      default:
+        if (!command) {
+          usage();
+        }
+        log('red', `Unknown command: ${command}`);
+        usage();
+    }
+  } catch (err) {
+    log('red', `Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/index.js

@@ -0,0 +1,180 @@
+/**
+ * Mags SDK - Execute scripts on Magpie's instant VM infrastructure
+ * @module @magpiecloud/mags
+ */
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+class Mags {
+  /**
+   * Create a Mags client
+   * @param {object} options - Configuration options
+   * @param {string} options.apiUrl - API endpoint (default: https://api.magpiecloud.com)
+   * @param {string} options.apiToken - API token (required, or set MAGS_API_TOKEN env var)
+   */
+  constructor(options = {}) {
+    this.apiUrl = options.apiUrl || process.env.MAGS_API_URL || 'https://api.magpiecloud.com';
+    this.apiToken = options.apiToken || process.env.MAGS_API_TOKEN;
+
+    if (!this.apiToken) {
+      throw new Error('API token required. Set MAGS_API_TOKEN or pass apiToken option.');
+    }
+  }
+
+  _request(method, path, body = null) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.apiUrl);
+      const isHttps = url.protocol === 'https:';
+      const lib = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method,
+        headers: {
+          'Authorization': `Bearer ${this.apiToken}`,
+          'Content-Type': 'application/json'
+        }
+      };
+
+      const req = lib.request(options, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            if (res.statusCode >= 400) {
+              reject(new Error(parsed.error || parsed.message || `HTTP ${res.statusCode}`));
+            } else {
+              resolve(parsed);
+            }
+          } catch {
+            resolve(data);
+          }
+        });
+      });
+
+      req.on('error', reject);
+      if (body) req.write(JSON.stringify(body));
+      req.end();
+    });
+  }
+
+  /**
+   * Submit a job for execution
+   * @param {string} script - Script to execute
+   * @param {object} options - Job options
+   * @param {string} options.name - Job name
+   * @param {string} options.workspaceId - Persistent workspace ID
+   * @param {boolean} options.persistent - Keep VM alive after script
+   * @param {string} options.startupCommand - Command to run when waking from sleep
+   * @param {object} options.environment - Environment variables
+   * @returns {Promise<{requestId: string, status: string}>}
+   */
+  async run(script, options = {}) {
+    const payload = {
+      script,
+      type: 'inline',
+      name: options.name,
+      workspace_id: options.workspaceId,
+      persistent: options.persistent || false,
+      startup_command: options.startupCommand,
+      environment: options.environment
+    };
+
+    const response = await this._request('POST', '/api/v1/mags-jobs', payload);
+    return {
+      requestId: response.request_id,
+      status: response.status
+    };
+  }
+
+  /**
+   * Get job status
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<object>}
+   */
+  async status(requestId) {
+    return this._request('GET', `/api/v1/mags-jobs/${requestId}/status`);
+  }
+
+  /**
+   * Get job logs
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<{logs: Array}>}
+   */
+  async logs(requestId) {
+    return this._request('GET', `/api/v1/mags-jobs/${requestId}/logs`);
+  }
+
+  /**
+   * List recent jobs
+   * @param {object} options - Pagination options
+   * @param {number} options.page - Page number (default: 1)
+   * @param {number} options.pageSize - Page size (default: 20)
+   * @returns {Promise<{jobs: Array, total: number}>}
+   */
+  async list(options = {}) {
+    const page = options.page || 1;
+    const pageSize = options.pageSize || 20;
+    return this._request('GET', `/api/v1/mags-jobs?page=${page}&page_size=${pageSize}`);
+  }
+
+  /**
+   * Enable URL access for a job
+   * @param {string} requestId - Job request ID
+   * @param {number} port - Port to expose (default: 8080)
+   * @returns {Promise<object>}
+   */
+  async enableUrl(requestId, port = 8080) {
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/access`, { port });
+  }
+
+  /**
+   * Stop a running job
+   * @param {string} requestId - Job request ID
+   * @returns {Promise<object>}
+   */
+  async stop(requestId) {
+    return this._request('POST', `/api/v1/mags-jobs/${requestId}/stop`);
+  }
+
+  /**
+   * Run a job and wait for completion
+   * @param {string} script - Script to execute
+   * @param {object} options - Job options
+   * @param {number} options.timeout - Timeout in ms (default: 60000)
+   * @returns {Promise<{status: string, exitCode: number, logs: Array}>}
+   */
+  async runAndWait(script, options = {}) {
+    const timeout = options.timeout || 60000;
+    const { requestId } = await this.run(script, options);
+
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      const status = await this.status(requestId);
+
+      if (status.status === 'completed' || status.status === 'error') {
+        const logsResp = await this.logs(requestId);
+        return {
+          requestId,
+          status: status.status,
+          exitCode: status.exit_code,
+          durationMs: status.script_duration_ms,
+          logs: logsResp.logs || []
+        };
+      }
+
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+
+    throw new Error(`Job ${requestId} timed out after ${timeout}ms`);
+  }
+}
+
+module.exports = Mags;
+module.exports.Mags = Mags;
+module.exports.default = Mags;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@magpiecloud/mags",
+  "version": "1.0.0",
+  "description": "Mags CLI - Execute scripts on Magpie's instant VM infrastructure",
+  "main": "index.js",
+  "bin": {
+    "mags": "./bin/mags.js"
+  },
+  "scripts": {
+    "test": "node bin/mags.js --help"
+  },
+  "keywords": [
+    "magpie",
+    "mags",
+    "vm",
+    "microvm",
+    "cloud",
+    "serverless",
+    "execution",
+    "cli"
+  ],
+  "author": "Magpie Cloud",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/magpiecloud/mags"
+  },
+  "homepage": "https://magpiecloud.com/docs/mags",
+  "bugs": {
+    "url": "https://github.com/magpiecloud/mags/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "index.js",
+    "bin/mags.js",
+    "README.md"
+  ]
+}