almostnode 0.1.0

package/src/cors-proxy.ts

@@ -0,0 +1,81 @@
+/**
+ * CORS Proxy Utility
+ *
+ * Provides optional CORS proxy support for fetching external APIs
+ * that don't allow browser origins.
+ *
+ * No default proxy is configured for security reasons.
+ * Users must explicitly set a proxy URL if needed.
+ *
+ * Example usage:
+ *   setCorsProxy('https://corsproxy.io/?');
+ *   const response = await proxyFetch('https://api.example.com/data');
+ */
+
+// No default proxy - must be explicitly set
+let proxyUrl: string | null = null;
+
+/**
+ * Set the CORS proxy URL
+ * @param url - Proxy URL (e.g., 'https://corsproxy.io/?')
+ *              The target URL will be appended as an encoded parameter.
+ *              Set to null to disable proxy and use direct fetch.
+ */
+export function setCorsProxy(url: string | null): void {
+  proxyUrl = url;
+  if (url) {
+    console.log(`[cors-proxy] Proxy configured: ${url}`);
+  } else {
+    console.log('[cors-proxy] Proxy disabled, using direct fetch');
+  }
+}
+
+/**
+ * Get the current CORS proxy URL
+ * @returns The configured proxy URL, or null if not set
+ */
+export function getCorsProxy(): string | null {
+  return proxyUrl;
+}
+
+/**
+ * Check if a proxy is configured
+ */
+export function hasProxy(): boolean {
+  return proxyUrl !== null;
+}
+
+/**
+ * Fetch with optional CORS proxy
+ *
+ * If a proxy is configured, the request goes through the proxy.
+ * Otherwise, a direct fetch is performed (may hit CORS issues).
+ *
+ * @param url - The target URL to fetch
+ * @param options - Standard fetch options
+ * @returns Promise<Response>
+ */
+export async function proxyFetch(
+  url: string,
+  options?: RequestInit
+): Promise<Response> {
+  if (proxyUrl) {
+    // Route through proxy
+    const proxiedUrl = proxyUrl + encodeURIComponent(url);
+    return fetch(proxiedUrl, options);
+  }
+
+  // No proxy configured - direct fetch
+  return fetch(url, options);
+}
+
+/**
+ * Build a proxied URL without fetching
+ * Useful for displaying the URL or using with other fetch mechanisms
+ */
+export function buildProxyUrl(url: string): string {
+  if (proxyUrl) {
+    return proxyUrl + encodeURIComponent(url);
+  }
+  return url;
+}

package/src/create-runtime.ts

@@ -0,0 +1,147 @@
+/**
+ * Runtime Factory - Create sandboxed, worker, or main-thread runtime
+ *
+ * SECURITY: By default, createRuntime requires either:
+ *   1. A sandbox URL for cross-origin isolation (recommended)
+ *   2. Explicit opt-in via dangerouslyAllowSameOrigin for trusted code
+ *
+ * Usage:
+ *   // Secure: Cross-origin sandbox (recommended for untrusted code)
+ *   const runtime = await createRuntime(vfs, {
+ *     sandbox: 'https://myapp-sandbox.vercel.app'
+ *   });
+ *
+ *   // Same-origin with Worker (for demos/trusted code)
+ *   const runtime = await createRuntime(vfs, {
+ *     dangerouslyAllowSameOrigin: true,
+ *     useWorker: true
+ *   });
+ *
+ *   // Same-origin main thread (least secure, trusted code only)
+ *   const runtime = await createRuntime(vfs, {
+ *     dangerouslyAllowSameOrigin: true
+ *   });
+ */
+
+import { Runtime } from './runtime';
+import { WorkerRuntime } from './worker-runtime';
+import { SandboxRuntime } from './sandbox-runtime';
+import type { VirtualFS } from './virtual-fs';
+import type { IRuntime, IExecuteResult, CreateRuntimeOptions, IRuntimeOptions } from './runtime-interface';
+
+/**
+ * Check if Web Workers are available in the current environment
+ */
+function isWorkerAvailable(): boolean {
+  return typeof Worker !== 'undefined';
+}
+
+/**
+ * Wrapper that makes the synchronous Runtime conform to the async IRuntime interface
+ */
+class AsyncRuntimeWrapper implements IRuntime {
+  private runtime: Runtime;
+
+  constructor(vfs: VirtualFS, options: IRuntimeOptions = {}) {
+    this.runtime = new Runtime(vfs, options);
+  }
+
+  async execute(code: string, filename?: string): Promise<IExecuteResult> {
+    return Promise.resolve(this.runtime.execute(code, filename));
+  }
+
+  async runFile(filename: string): Promise<IExecuteResult> {
+    return Promise.resolve(this.runtime.runFile(filename));
+  }
+
+  clearCache(): void {
+    this.runtime.clearCache();
+  }
+
+  getVFS(): VirtualFS {
+    return this.runtime.getVFS();
+  }
+
+  /**
+   * Get the underlying sync Runtime for direct access to sync methods
+   */
+  getSyncRuntime(): Runtime {
+    return this.runtime;
+  }
+}
+
+/**
+ * Create a runtime instance based on configuration
+ *
+ * SECURITY: Requires either sandbox URL or explicit dangerouslyAllowSameOrigin.
+ *
+ * @param vfs - Virtual file system instance
+ * @param options - Runtime options including sandbox/security settings
+ * @returns Promise resolving to IRuntime instance
+ * @throws Error if neither sandbox nor dangerouslyAllowSameOrigin is specified
+ */
+export async function createRuntime(
+  vfs: VirtualFS,
+  options: CreateRuntimeOptions = {}
+): Promise<IRuntime> {
+  const { sandbox, dangerouslyAllowSameOrigin, useWorker = false, ...runtimeOptions } = options;
+
+  // SECURE: Cross-origin sandbox mode
+  if (sandbox) {
+    console.log('[createRuntime] Creating SandboxRuntime (cross-origin isolated)');
+    const sandboxRuntime = new SandboxRuntime(sandbox, vfs, runtimeOptions);
+    // Wait for sandbox to be ready by executing a simple command
+    await sandboxRuntime.execute('/* sandbox ready check */', '/__sandbox_init__.js');
+    return sandboxRuntime;
+  }
+
+  // SECURITY CHECK: Same-origin execution requires explicit opt-in
+  if (!dangerouslyAllowSameOrigin) {
+    throw new Error(
+      'almostnode: For security, you must either:\n' +
+      '  1. Use sandbox mode: { sandbox: "https://your-sandbox.vercel.app" }\n' +
+      '  2. Explicitly opt-in to same-origin: { dangerouslyAllowSameOrigin: true }\n' +
+      '\n' +
+      'Same-origin execution allows code to access cookies, localStorage, and IndexedDB.\n' +
+      'Only use dangerouslyAllowSameOrigin for trusted code or demos.\n' +
+      '\n' +
+      'For sandbox setup instructions, see: https://github.com/anthropics/almostnode#sandbox-setup'
+    );
+  }
+
+  // Same-origin modes (requires explicit opt-in)
+  let shouldUseWorker = false;
+
+  if (useWorker === true) {
+    shouldUseWorker = isWorkerAvailable();
+    if (!shouldUseWorker) {
+      console.warn('[createRuntime] Worker requested but not available, falling back to main thread');
+    }
+  } else if (useWorker === 'auto') {
+    shouldUseWorker = isWorkerAvailable();
+    console.log(`[createRuntime] Auto mode: using ${shouldUseWorker ? 'worker' : 'main thread'}`);
+  }
+
+  if (shouldUseWorker) {
+    console.log('[createRuntime] Creating WorkerRuntime (same-origin, thread-isolated)');
+    const workerRuntime = new WorkerRuntime(vfs, runtimeOptions);
+    // Wait for worker to be ready by executing a simple command
+    await workerRuntime.execute('/* worker ready check */', '/__worker_init__.js');
+    return workerRuntime;
+  }
+
+  console.log('[createRuntime] Creating main-thread Runtime (same-origin, least secure)');
+  return new AsyncRuntimeWrapper(vfs, runtimeOptions);
+}
+
+// Re-export types and classes for convenience
+export { Runtime } from './runtime';
+export { WorkerRuntime } from './worker-runtime';
+export { SandboxRuntime } from './sandbox-runtime';
+export type {
+  IRuntime,
+  IExecuteResult,
+  IRuntimeOptions,
+  CreateRuntimeOptions,
+  VFSSnapshot,
+} from './runtime-interface';

package/src/demo.ts

@@ -0,0 +1,304 @@
+/**
+ * Mini WebContainer Demo
+ * Demonstrates running an HTTP server in the browser
+ */
+
+import { VirtualFS } from './virtual-fs';
+import { Runtime } from './runtime';
+import { ServerBridge, getServerBridge, resetServerBridge } from './server-bridge';
+import { PackageManager } from './npm';
+
+// DOM elements
+const editorEl = document.getElementById('editor') as HTMLTextAreaElement;
+const previewEl = document.getElementById('preview') as HTMLIFrameElement;
+const terminalEl = document.getElementById('terminal') as HTMLDivElement;
+const statusEl = document.getElementById('status') as HTMLSpanElement;
+const runBtn = document.getElementById('runBtn') as HTMLButtonElement;
+
+// State
+let vfs: VirtualFS;
+let runtime: Runtime;
+let serverBridge: ServerBridge;
+let npm: PackageManager;
+let currentServerPort: number | null = null;
+
+// Log to terminal
+function log(message: string, type: 'info' | 'error' | 'success' = 'info') {
+  const colors = {
+    info: '#888',
+    error: '#e74c3c',
+    success: '#27ae60',
+  };
+  const time = new Date().toLocaleTimeString();
+  terminalEl.innerHTML += `<span style="color: ${colors[type]}">[${time}] ${escapeHtml(message)}</span>\n`;
+  terminalEl.scrollTop = terminalEl.scrollHeight;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// Update status indicator
+function setStatus(text: string, className: 'loading' | 'ready' | 'error') {
+  statusEl.textContent = text;
+  statusEl.className = 'status ' + className;
+}
+
+// Initialize the container
+function initContainer() {
+  vfs = new VirtualFS();
+  runtime = new Runtime(vfs, {
+    onConsole: (method, args) => {
+      const message = args.map(arg =>
+        typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+      ).join(' ');
+      log(message, method === 'error' ? 'error' : 'info');
+    },
+  });
+
+  npm = new PackageManager(vfs);
+
+  // Reset the server bridge to get fresh callbacks
+  resetServerBridge();
+
+  serverBridge = getServerBridge({
+    baseUrl: window.location.origin,
+    onServerReady: (port, url) => {
+      currentServerPort = port;
+      log(`Server ready on port ${port}`, 'success');
+      setStatus('Running', 'ready');
+
+      // Load the preview
+      loadPreview('/');
+    },
+  });
+
+  log('Container initialized', 'success');
+}
+
+// Load content from virtual server into preview
+async function loadPreview(path: string) {
+  if (!currentServerPort) {
+    log('No server running', 'error');
+    return;
+  }
+
+  try {
+    const response = await serverBridge.handleRequest(
+      currentServerPort,
+      'GET',
+      path,
+      {
+        host: 'localhost',
+        'user-agent': 'MiniWebContainer/1.0',
+      }
+    );
+
+    const contentType = response.headers['content-type'] || 'text/plain';
+    const body = response.body.toString();
+
+    if (contentType.includes('text/html')) {
+      // Inject script to intercept link clicks
+      const htmlWithInterceptor = injectLinkInterceptor(body);
+      const blob = new Blob([htmlWithInterceptor], { type: 'text/html' });
+      previewEl.src = URL.createObjectURL(blob);
+    } else if (contentType.includes('application/json')) {
+      // Display JSON nicely
+      const html = `
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <style>
+              body { font-family: monospace; padding: 1rem; background: #1a1a2e; color: #0f0; }
+              pre { white-space: pre-wrap; word-wrap: break-word; }
+            </style>
+          </head>
+          <body>
+            <pre>${escapeHtml(JSON.stringify(JSON.parse(body), null, 2))}</pre>
+          </body>
+        </html>
+      `;
+      const blob = new Blob([html], { type: 'text/html' });
+      previewEl.src = URL.createObjectURL(blob);
+    } else {
+      // Display as plain text
+      const html = `
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <style>
+              body { font-family: monospace; padding: 1rem; background: #1a1a2e; color: #eee; }
+              pre { white-space: pre-wrap; word-wrap: break-word; }
+            </style>
+          </head>
+          <body>
+            <pre>${escapeHtml(body)}</pre>
+          </body>
+        </html>
+      `;
+      const blob = new Blob([html], { type: 'text/html' });
+      previewEl.src = URL.createObjectURL(blob);
+    }
+  } catch (error) {
+    log(`Error loading preview: ${error}`, 'error');
+  }
+}
+
+// Inject script to intercept link clicks in the preview
+function injectLinkInterceptor(html: string): string {
+  const script = `
+    <script>
+      document.addEventListener('click', function(e) {
+        const link = e.target.closest('a');
+        if (link) {
+          e.preventDefault();
+          // Get the href attribute directly (not the resolved href property)
+          const href = link.getAttribute('href');
+          if (href) {
+            // Handle relative URLs directly
+            if (href.startsWith('/')) {
+              window.parent.postMessage({ type: 'navigate', path: href }, '*');
+            } else if (href.startsWith('http')) {
+              // Absolute URL - extract pathname
+              try {
+                const url = new URL(href);
+                window.parent.postMessage({ type: 'navigate', path: url.pathname + url.search }, '*');
+              } catch (e) {
+                console.error('Invalid URL:', href);
+              }
+            } else {
+              // Relative path without leading slash
+              window.parent.postMessage({ type: 'navigate', path: '/' + href }, '*');
+            }
+          }
+        }
+      });
+    </script>
+  `;
+
+  // Insert before </body> or at the end
+  if (html.includes('</body>')) {
+    return html.replace('</body>', script + '</body>');
+  }
+  return html + script;
+}
+
+// Check if code uses Express
+function usesExpress(code: string): boolean {
+  return code.includes("require('express')") || code.includes('require("express")');
+}
+
+// Check if express is installed in VFS
+function isExpressInstalled(): boolean {
+  return vfs.existsSync('/node_modules/express/package.json');
+}
+
+// Install dependencies
+async function installDependencies() {
+  setStatus('Installing...', 'loading');
+  runBtn.disabled = true;
+
+  try {
+    log('Installing express (this may take a moment)...', 'info');
+
+    await npm.install('express', {
+      onProgress: (msg) => log(msg, 'info'),
+    });
+
+    log('Express installed successfully!', 'success');
+  } catch (error) {
+    log(`Install failed: ${error}`, 'error');
+    setStatus('Install Failed', 'error');
+    throw error;
+  } finally {
+    runBtn.disabled = false;
+  }
+}
+
+// Reset runtime for a fresh execution (but keep VFS with installed packages)
+function resetRuntime() {
+  runtime = new Runtime(vfs, {
+    onConsole: (method, args) => {
+      const message = args.map(arg =>
+        typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+      ).join(' ');
+      log(message, method === 'error' ? 'error' : 'info');
+    },
+  });
+
+  // Reset the server bridge to get fresh callbacks
+  resetServerBridge();
+
+  serverBridge = getServerBridge({
+    baseUrl: window.location.origin,
+    onServerReady: (port, url) => {
+      currentServerPort = port;
+      log(`Server ready on port ${port}`, 'success');
+      setStatus('Running', 'ready');
+
+      // Load the preview
+      loadPreview('/');
+    },
+  });
+}
+
+// Run the server code
+async function runServer() {
+  const code = editorEl.value;
+
+  // Reset state
+  currentServerPort = null;
+  setStatus('Starting...', 'loading');
+  runBtn.disabled = true;
+
+  // Clear terminal
+  terminalEl.innerHTML = '';
+  log('Running script...');
+
+  // Reset runtime (keeps VFS with installed packages)
+  resetRuntime();
+
+  try {
+    // Check if Express is needed and not installed
+    if (usesExpress(code) && !isExpressInstalled()) {
+      await installDependencies();
+    }
+
+    // Execute the code
+    log('Executing code...', 'info');
+    runtime.execute(code, '/server.js');
+    log('Code executed successfully', 'success');
+
+    // If no server started after a short delay, mark as completed
+    setTimeout(() => {
+      if (!currentServerPort) {
+        setStatus('Completed', 'ready');
+      }
+    }, 500);
+  } catch (error) {
+    log(`Error: ${error}`, 'error');
+    setStatus('Error', 'error');
+  } finally {
+    runBtn.disabled = false;
+  }
+}
+
+// Handle messages from preview iframe
+window.addEventListener('message', (event) => {
+  if (event.data?.type === 'navigate') {
+    log(`Navigating to ${event.data.path}`);
+    loadPreview(event.data.path);
+  }
+});
+
+// Initialize on load
+runBtn.addEventListener('click', runServer);
+
+// Initialize container
+initContainer();
+setStatus('Ready', 'ready');
+log('Click "Run Server" to start the HTTP server');
+log('Express will be auto-installed if you use require("express")');