vmlive 1.0.2 → 1.0.4

package/README.md

@@ -29,9 +29,16 @@ Interactively scaffolds additional serverless endpoints natively into your `src/
 ### `npx vmlive dev`
 Starts the local emulation environment.
 - Iteratively hosts your entire multi-function footprint locally via predictable slugs: `http://<workspace_id>-<project_id>-<function_name>.localhost:8787`.
+- **Local Dashboard:** Automatically spawns a web dashboard at `http://dashboard.localhost:8787` for visualizing offline databases, global KV, and Object Storage.
 - Provides local proxy bindings for your SQL Database (`env.DB`), Global KV (`env.KV`), and Object Storage (`env.BUCKET`) using the `.vmlive/` directory for persistent storage.
 - Supports hot-reloading for `.js` and `.ts` files.
 
+### `npx vmlive test`
+Executes your Vitest suites against a strictly ephemeral **in-memory** engine.
+- Spins up `VirtualMachine` in memory-only mode without touching `.vmlive/` disk databases.
+- Runs `npx vitest run` and gracefully destroys the engine upon exit.
+- Allows test suites to deeply mutate state predictably without sandbox bleeding.
+
 ### `npx vmlive deploy`
 Uploads the local code to the vm.live edge platform.
 - Bundles the code using `esbuild`.
@@ -42,6 +49,5 @@ Uploads the local code to the vm.live edge platform.
 If you are using an AI assistant (such as Cursor, Copilot, or Aider) to write code, provide it with the platform context to ensure it adheres to the V8 Isolate execution model and uses the correct infrastructure bindings.
 
 **Instructions:**
-1. Download the `vmlive-ai-rules.md` file (or relevant rules document) provided by the platform.
-2. Place it in the root directory of your project.
-3. If using Cursor, rename the file to `.cursorrules` to force the AI to apply the constraints automatically.
+1. Download the rules seamlessly via the API directly into your local root footprint: `curl -O https://api.vm.live/vmlive-ai-rules.md`
+2. Configure your AI Assistant (e.g. Cursor, Copilot) to ingest this manifest so it dynamically enforces the strict PaaS architectural primitives across your local logic scope!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vmlive",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Local development VM for custom Serverless PaaS",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -28,31 +28,51 @@ const buildResourcesConfig = () => {
   };
 };
 
-const buildProxyDispatcher = (functions, workspaceId, projectId) => ({
+const buildProxyDispatcher = (functions, workspaceId, projectId, includeDashboard = true) => ({
   name: "vm-gateway-proxy",
   modules: true,
   script: `
     export default {
       async fetch(request, env) {
         const url = new URL(request.url);
+        
+        if (url.pathname === '/favicon.ico') {
+            return new Response(null, { status: 204 });
+        }
+        
         const hostHeader = request.headers.get("Host") || url.hostname;
         let targetName = hostHeader.split('.')[0]; 
         
-        if (targetName && env[targetName]) {
-          return env[targetName].fetch(request);
+        let res;
+
+        if (targetName === 'dashboard' && env.DASHBOARD) {
+            res = await env.DASHBOARD.fetch(request);
+        } else if (targetName && env[targetName]) {
+            res = await env[targetName].fetch(request);
+        } else {
+            res = new Response(
+              \`Function Not Found: \${targetName}.\\n\\nExpected format: http://${workspaceId}-${projectId}-<function_name>.localhost\`, 
+              { status: 404 }
+            );
         }
+
+        const method = request.method;
+        const path = url.pathname;
+        const status = res.status;
+        const color = status >= 500 ? "\\x1b[31m" : status >= 400 ? "\\x1b[33m" : "\\x1b[32m";
         
-        return new Response(
-          \`Function Not Found: \${targetName}.\\n\\nExpected format: http://${workspaceId}-${projectId}-<function_name>.localhost\`, 
-          { status: 404 }
-        );
+        console.log(\`\\x1b[90m[\${targetName}]\\x1b[0m \${method} \${path} \${color}\${status}\\x1b[0m\`);
+        return res;
       }
     }
   `,
-  serviceBindings: functions.reduce((acc, fn) => {
-    acc[`${workspaceId}-${projectId}-${fn.name}`] = fn.name;
-    return acc;
-  }, {})
+  serviceBindings: {
+    ...functions.reduce((acc, fn) => {
+      acc[`${workspaceId}-${projectId}-${fn.name}`] = fn.name;
+      return acc;
+    }, {}),
+    ...(includeDashboard ? { DASHBOARD: "vm-dashboard-worker" } : {})
+  }
 });
 
 const runInit = async () => {
@@ -138,7 +158,7 @@ const runInit = async () => {
          
          if (stripeRes.ok) {
              const stripeData = await stripeRes.json();
-             console.log(`\n\x1b[34m${stripeData.url}\x1b[0m\n`);
+             console.log(`\n\x1b]8;;${stripeData.url}\x1b\\\x1b[34m${stripeData.url}\x1b[0m\x1b]8;;\x1b\\\n`);
              const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
              exec(`${openCmd} "${stripeData.url}"`);
              await input({ message: 'Press Enter once verified to continue:' });
@@ -401,10 +421,21 @@ const runDev = async () => {
   const shadowSource = fs.readFileSync(path.join(__dirname, 'shadow-dos.js'), 'utf-8');
   fs.writeFileSync(path.join(WORK_DIR, 'shadow-dos.mjs'), shadowSource);
 
+  const dashSource = fs.readFileSync(path.join(__dirname, 'dashboard-worker.js'), 'utf-8');
+  fs.writeFileSync(path.join(WORK_DIR, 'dashboard-worker.mjs'), dashSource);
+
   const mfPort = process.env.PORT ? parseInt(process.env.PORT) : (config.port || 8787);
 
   const miniflareWorkers = [
     buildProxyDispatcher(config.functions, workspaceId, projectId),
+    {
+      name: "vm-dashboard-worker",
+      modules: true,
+      scriptPath: path.join(WORK_DIR, 'dashboard-worker.mjs'),
+      d1Databases: resourcesConfig.d1Databases,
+      kvNamespaces: resourcesConfig.kvNamespaces,
+      r2Buckets: resourcesConfig.r2Buckets
+    },
     {
       name: "vm-shadow-worker",
       modules: true,
@@ -436,9 +467,14 @@ const runDev = async () => {
     r2Persist: path.join(DATA_DIR, 'bucket')
   });
   await mf.ready;
-  console.log('\\nLocal endpoints available:');
+  console.log('\nLocal endpoints available:');
+  
+  const dashboardUrl = `http://dashboard.localhost:${mfPort}`;
+  console.log(`  \x1b]8;;${dashboardUrl}\x1b\\${dashboardUrl}\x1b]8;;\x1b\\  \x1b[32m[Dashboard]\x1b[0m`);
+  
   config.functions.forEach(fn => {
-    console.log(`  http://${workspaceId}-${projectId}-${fn.name}.localhost:${mfPort}`);
+    const endpointUrl = `http://${workspaceId}-${projectId}-${fn.name}.localhost:${mfPort}`;
+    console.log(`  \x1b]8;;${endpointUrl}\x1b\\${endpointUrl}\x1b]8;;\x1b\\`);
   });
 
   setInterval(() => {
@@ -489,6 +525,100 @@ const runDev = async () => {
   });
 };
 
+const runTest = async () => {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    throw new Error("Missing vm.json in project root. Run 'vm init' to scaffold a new project workspace.");
+  }
+  
+  const testArgs = process.argv.slice(3);
+  console.log('\x1b[36mInitializing Ephemeral Target Engine for Integration Tests...\x1b[0m');
+
+  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  if (!fs.existsSync(WORK_DIR)) fs.mkdirSync(WORK_DIR, { recursive: true });
+  
+  const sharedBindings = fs.existsSync(path.resolve('.env')) 
+    ? dotenv.parse(fs.readFileSync(path.resolve('.env'))) 
+    : {};
+
+  const resourcesConfig = buildResourcesConfig();
+
+  const entryPoints = config.functions.reduce((acc, fn) => {
+    acc[`${fn.name}-out`] = path.resolve(fn.entry);
+    return acc;
+  }, {});
+
+  const workspaceId = config.workspaceId || "ws_local";
+  const projectId = config.projectId || "prj_local";
+
+  config.functions.forEach(fn => {
+    const relativeTarget = `./${fn.name}-out.mjs`;
+    fs.writeFileSync(path.join(WORK_DIR, `${fn.name}-shim.mjs`), generateShim(relativeTarget, workspaceId, projectId, fn.name));
+  });
+
+  const builder = await esbuild.context({
+    entryPoints,
+    bundle: true,
+    format: 'esm',
+    outdir: WORK_DIR,
+    outExtension: { '.js': '.mjs' },
+    external: ['cloudflare:*'], 
+    logLevel: 'silent'
+  });
+
+  await builder.rebuild();
+
+  const shadowSource = fs.readFileSync(path.join(__dirname, 'shadow-dos.js'), 'utf-8');
+  fs.writeFileSync(path.join(WORK_DIR, 'shadow-dos.mjs'), shadowSource);
+
+  const mfPort = process.env.PORT ? parseInt(process.env.PORT) : 8787;
+
+  // Exact parity workers but omitting the Dashboard intentionally
+  const miniflareWorkers = [
+    buildProxyDispatcher(config.functions, workspaceId, projectId, false),
+    {
+      name: "vm-shadow-worker",
+      modules: true,
+      scriptPath: path.join(WORK_DIR, 'shadow-dos.mjs'),
+      bindings: { PORT: mfPort },
+      durableObjects: { LocalTaskManagerDO: "LocalTaskManagerDO", LocalChannelRoomDO: "LocalChannelRoomDO" }
+    },
+    ...config.functions.map(fn => ({
+      name: fn.name,
+      modules: true,
+      scriptPath: path.join(WORK_DIR, `${fn.name}-shim.mjs`),
+      bindings: sharedBindings,
+      ...resourcesConfig,
+      durableObjects: {
+        TASK_DO: { className: "LocalTaskManagerDO", scriptName: "vm-shadow-worker" },
+        CHANNEL_DO: { className: "LocalChannelRoomDO", scriptName: "vm-shadow-worker" }
+      }
+    }))
+  ];
+  
+  // IN-MEMORY EMULATOR (NO PERSIST PATHS)
+  const mf = new Emulator({ 
+    workers: miniflareWorkers, 
+    port: mfPort 
+  });
+  
+  await mf.ready;
+  console.log('\x1b[32m✔ Ephemeral environment completely provisioned and bound.\x1b[0m\\n');
+
+  const { spawn } = await import('child_process');
+  
+  const testProcess = spawn('npx', ['vitest', 'run', ...testArgs], {
+      stdio: 'inherit',
+      env: { ...process.env, VMLIVE_TESTING: "true" }
+  });
+
+  testProcess.on('exit', async (code) => {
+      console.log('\\n\x1b[36mTerminating ephemeral engine execution context...\x1b[0m');
+      await builder.dispose();
+      await mf.dispose();
+      process.exit(code || 0);
+  });
+};
+
 const runDeploy = async () => {
   console.log('\x1b[36mDeploying...\x1b[0m');
   
@@ -633,7 +763,7 @@ const runLogin = async () => {
     const PORT = server.address().port;
     const EDITOR_URL = process.env.EDITOR_URL || 'http://localhost:5174';
     const authUrl = `${EDITOR_URL}/?challenge=${codeChallenge}&port=${PORT}`;
-    console.log(`\x1b[34mOpening browser to: ${authUrl}\x1b[0m`);
+    console.log(`\x1b[34mOpening browser to: \x1b]8;;${authUrl}\x1b\\${authUrl}\x1b]8;;\x1b\\\x1b[0m`);
     const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
     exec(`${openCmd} "${authUrl}"`);
   });
@@ -645,15 +775,17 @@ const main = async () => {
     runInit();
   } else if (command === 'add') {
     await runAdd();
-  } else if (command === 'dev' || !command) {
+  } else if (command === 'dev') {
     await runDev();
+  } else if (command === 'test') {
+    await runTest();
   } else if (command === 'login') {
     await runLogin();
   } else if (command === 'deploy') {
     await runDeploy();
   } else {
-    console.error(`\x1b[31m❌ Unknown command: ${command}\x1b[0m`);
-    console.log('Usage: vm init | vm add | vm dev | vm login | vm deploy');
+    console.error(`\x1b[31m❌ Unknown command: ${command || 'missing'}\x1b[0m`);
+    console.log('Usage: vm init | vm add | vm dev | vm test | vm login | vm deploy');
     process.exit(1);
   }
 };

package/src/dashboard-worker.js

@@ -0,0 +1,149 @@
+const UI_HTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>vm.live — Local Dashboard</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
+  <style>
+    body { font-family: 'Inter', sans-serif; background-color: #09090b; color: #f4f4f5; }
+    .tab-active { border-bottom: 2px solid #10b981; color: #10b981; }
+    .tab-inactive { color: #a1a1aa; }
+    .tab-inactive:hover { color: #f4f4f5; }
+    pre { background: #18181b; padding: 1rem; border-radius: 0.5rem; border: 1px solid #27272a; overflow-x: auto; font-size: 0.875rem; color: #a1a1aa; }
+  </style>
+</head>
+<body class="h-screen flex flex-col">
+  <header class="border-b border-zinc-800 bg-zinc-950 p-4 shrink-0 flex items-center justify-between">
+    <div class="flex items-center gap-3">
+      <div class="w-8 h-8 rounded-full bg-emerald-500/10 text-emerald-500 flex items-center justify-center font-bold">V</div>
+      <h1 class="font-semibold tracking-tight">Local Sandbox</h1>
+    </div>
+    <div class="flex gap-6 text-sm font-medium">
+      <button onclick="switchTab('db')" id="tab-db" class="tab-active pb-4 -mb-4">Database (D1)</button>
+      <button onclick="switchTab('kv')" id="tab-kv" class="tab-inactive pb-4 -mb-4">Global KV</button>
+      <button onclick="switchTab('r2')" id="tab-r2" class="tab-inactive pb-4 -mb-4">Storage (R2)</button>
+    </div>
+  </header>
+
+  <main class="flex-1 overflow-hidden relative">
+    <!-- D1 View -->
+    <div id="view-db" class="absolute inset-0 flex flex-col p-6 gap-4">
+      <h2 class="text-lg font-semibold">Execute SQL Query</h2>
+      <div class="flex gap-2">
+        <input type="text" id="sql-input" placeholder="SELECT * FROM users;" class="flex-1 bg-zinc-900 border border-zinc-800 rounded-md px-4 py-2 font-mono text-sm focus:outline-none focus:border-emerald-500 focus:ring-1 focus:ring-emerald-500">
+        <button onclick="runQuery()" class="bg-emerald-600 hover:bg-emerald-500 text-white px-6 py-2 rounded-md font-medium transition-colors">Run</button>
+      </div>
+      <div class="flex-1 overflow-auto rounded-md border border-zinc-800 bg-zinc-900/50">
+        <pre id="db-results" class="h-full m-0 rounded-none border-0 text-sm">Awaiting query...</pre>
+      </div>
+    </div>
+
+    <!-- KV View -->
+    <div id="view-kv" class="absolute inset-0 flex flex-col p-6 gap-4 hidden">
+      <div class="flex items-center justify-between">
+        <h2 class="text-lg font-semibold">Key-Value Pairs</h2>
+        <button onclick="loadKV()" class="text-xs bg-zinc-800 hover:bg-zinc-700 px-3 py-1.5 rounded-md transition-colors">Refresh</button>
+      </div>
+      <div class="flex-1 overflow-auto rounded-md border border-zinc-800 bg-zinc-900/50">
+        <pre id="kv-results" class="h-full m-0 rounded-none border-0 text-sm">Loading keys...</pre>
+      </div>
+    </div>
+
+    <!-- R2 View -->
+    <div id="view-r2" class="absolute inset-0 flex flex-col p-6 gap-4 hidden">
+      <div class="flex items-center justify-between">
+        <h2 class="text-lg font-semibold">Object Storage</h2>
+        <button onclick="loadR2()" class="text-xs bg-zinc-800 hover:bg-zinc-700 px-3 py-1.5 rounded-md transition-colors">Refresh</button>
+      </div>
+      <div class="flex-1 overflow-auto rounded-md border border-zinc-800 bg-zinc-900/50">
+        <pre id="r2-results" class="h-full m-0 rounded-none border-0 text-sm">Loading objects...</pre>
+      </div>
+    </div>
+  </main>
+
+  <script>
+    const views = ['db', 'kv', 'r2'];
+    function switchTab(target) {
+      views.forEach(v => {
+        document.getElementById('view-' + v).classList.add('hidden');
+        document.getElementById('tab-' + v).className = 'tab-inactive pb-4 -mb-4';
+      });
+      document.getElementById('view-' + target).classList.remove('hidden');
+      document.getElementById('tab-' + target).className = 'tab-active pb-4 -mb-4';
+      
+      if (target === 'kv') loadKV();
+      if (target === 'r2') loadR2();
+    }
+
+    async function runQuery() {
+      const q = document.getElementById('sql-input').value;
+      if (!q) return;
+      document.getElementById('db-results').innerText = 'Executing...';
+      try {
+        const res = await fetch('/api/db', { method: 'POST', body: JSON.stringify({ query: q }) });
+        const json = await res.json();
+        document.getElementById('db-results').innerText = JSON.stringify(json, null, 2);
+      } catch (e) {
+        document.getElementById('db-results').innerText = 'Network Error: ' + e.message;
+      }
+    }
+
+    async function loadKV() {
+      document.getElementById('kv-results').innerText = 'Fetching keys...';
+      const res = await fetch('/api/kv');
+      const json = await res.json();
+      document.getElementById('kv-results').innerText = JSON.stringify(json, null, 2);
+    }
+
+    async function loadR2() {
+      document.getElementById('r2-results').innerText = 'Fetching objects...';
+      const res = await fetch('/api/bucket');
+      const json = await res.json();
+      document.getElementById('r2-results').innerText = JSON.stringify(json, null, 2);
+    }
+  </script>
+</body>
+</html>
+\`;
+
+export default {
+  async fetch(req, env) {
+    const url = new URL(req.url);
+
+    if (req.method === 'POST' && url.pathname === '/api/db') {
+       if (!env.DB) return Response.json({ error: "DB binding not configured in emulator" }, { status: 400 });
+       const body = await req.json();
+       try {
+           const res = await env.DB.prepare(body.query).all();
+           return Response.json(res);
+       } catch(e) {
+           return Response.json({ error: e.message }, { status: 400 });
+       }
+    }
+    
+    if (req.method === 'GET' && url.pathname === '/api/kv') {
+       if (!env.__RAW_KV) return Response.json({ error: "KV binding not configured in emulator" }, { status: 400 });
+       try {
+           const res = await env.__RAW_KV.list();
+           return Response.json(res);
+       } catch(e) {
+           return Response.json({ error: e.message }, { status: 400 });
+       }
+    }
+
+    if (req.method === 'GET' && url.pathname === '/api/bucket') {
+       if (!env.R2) return Response.json({ error: "BUCKET binding not configured in emulator" }, { status: 400 });
+       try {
+           const res = await env.R2.list();
+           return Response.json(res);
+       } catch(e) {
+           return Response.json({ error: e.message }, { status: 400 });
+       }
+    }
+
+    // Default to the Editor UI Payload
+    return new Response(UI_HTML, { headers: { 'Content-Type': 'text/html; charset=utf-8' }});
+  }
+};

package/src/string-shim.js

@@ -3,8 +3,8 @@ import * as UserCode from '${outFileUrl}';
 
 export default {
   async fetch(req, env, ctx) {
-    // Isolate the global KV 
-    const { __RAW_KV, ...safeEnv } = env;
+    // Isolate the global KV and Storage
+    const { __RAW_KV, R2, ...safeEnv } = env;
     const KV_PREFIX = \`${workspaceId}:${projectId}:\`;
 
     // 1. Air-Gapped Virtual KV Multiplexer
@@ -80,9 +80,12 @@ export default {
     const Channels = {
       accept: async (roomName, metadata) => {
         console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 🔌 Channels.accept: [\${roomName}]\`, metadata);
-        const req = new Request("http://platform/.internal", { headers: { Upgrade: "websocket" }});
+        if (req.headers.get("Upgrade") !== "websocket") {
+            return new Response("Upgrade Required: Endpoint expects a WebSocket connection.", { status: 426 });
+        }
+        const doReq = new Request("http://platform/.internal", { headers: req.headers });
         const stub = env.CHANNEL_DO.idFromName(roomName);
-        return await env.CHANNEL_DO.get(stub).fetch(req);
+        return await env.CHANNEL_DO.get(stub).fetch(doReq);
       },
       broadcast: async (roomName, payload) => {
         console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 📡 Channels.broadcast: [\${roomName}]\`, payload);
@@ -110,6 +113,7 @@ export default {
     const customEnv = { 
       ...safeEnv, 
       KV: virtualKV, 
+      BUCKET: R2,
       Tasks, 
       Channels, 
       Discord,