vmlive 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# @vmlive/cli
+
+Local emulation sandbox and deployment CLI for vm.live.
+
+This CLI provides a local development environment for serverless edge functions running on vm.live, including local emulation for DB, KV, and Bucket storage.
+
+## Installation
+
+You do not need to install the CLI globally. It can be run directly via `npx`:
+
+```bash
+npx vmlive [command]
+```
+
+## Commands
+
+### `npx vmlive login`
+Authenticates the CLI with your vm.live account via PKCE OAuth. Saves the access token to `~/.vm-config.json`.
+
+### `npx vmlive init`
+Scaffolds a new project in the current directory.
+- Prompts for Workspace and Project selection.
+- Generates `vm.json` (configuration manifest) and `index.ts`.
+- Installs `@vmlive/types` and configures TypeScript.
+
+### `npx vmlive dev`
+Starts the local emulation environment.
+- Runs functions locally via `http://<function-name>.localhost:8787`.
+- 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 deploy`
+Uploads the local code to the vm.live edge platform.
+- Bundles the code using `esbuild`.
+- Evaluates and injects environment variables from `.env` and `.env.production`.
+
+## AI / LLM Tooling Setup
+
+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.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "vmlive",
+  "version": "1.0.0",
+  "description": "Local development VM for custom Serverless PaaS",
+  "type": "module",
+  "bin": {
+    "vmlive": "./src/cli.js"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "dotenv": "^16.4.5",
+    "esbuild": "^0.20.2",
+    "miniflare": "^3.20231218.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
+}

package/src/cli.js

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL, fileURLToPath } from 'url';
+import esbuild from 'esbuild';
+import dotenv from 'dotenv';
+import http from 'http';
+import os from 'os';
+import crypto from 'crypto';
+import { exec } from 'child_process';
+import { Miniflare } from 'miniflare';
+import { select, input } from '@inquirer/prompts';
+import { generateShim } from './string-shim.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Securely project the Miniflare abstraction globally entirely out of sight into the nested Node cache.
+const WORK_DIR = path.resolve('node_modules', '.cache', 'vmlive');
+const DATA_DIR = path.resolve('.vmlive');
+const CONFIG_PATH = path.resolve('vm.json');
+const API_FILE = path.resolve('index.ts');
+
+const buildResourcesConfig = () => {
+  return {
+    d1Databases: ["DB"], 
+    kvNamespaces: { "__RAW_KV": "local_store" },
+    r2Buckets: ["R2"]
+  };
+};
+
+const buildProxyDispatcher = (functions) => ({
+  name: "vm-gateway-proxy",
+  modules: true,
+  script: `
+    export default {
+      async fetch(request, env) {
+        const url = new URL(request.url);
+        const hostHeader = request.headers.get("Host") || url.hostname;
+        let targetName = hostHeader.split('.')[0]; 
+        
+        if (targetName === '127' || targetName === 'localhost') {
+            targetName = 'api';
+        }
+        
+        if (targetName && env[targetName]) {
+          return env[targetName].fetch(request);
+        }
+        
+        return new Response(
+          \`Function Not Found: \${targetName}.\\n\\nUse format: http://<function-name>.localhost:8787\`, 
+          { status: 404 }
+        );
+      }
+    }
+  `,
+  serviceBindings: functions.reduce((acc, fn) => {
+    acc[fn.name] = fn.name;
+    return acc;
+  }, {})
+});
+
+const runInit = async () => {
+  if (fs.existsSync(CONFIG_PATH)) {
+    console.error('\x1b[31m❌ Initialization Aborted:\x1b[0m vm.json already exists in this directory.');
+    process.exit(1);
+  }
+
+  // 1. Enforce Authentication Guard
+  const configPath = path.join(os.homedir(), '.vm-config.json');
+  let jwtToken = process.env.VM_API_TOKEN;
+  if (!jwtToken && fs.existsSync(configPath)) {
+     jwtToken = JSON.parse(fs.readFileSync(configPath, 'utf-8')).token;
+  }
+
+  if (!jwtToken) {
+     console.error('\x1b[31m❌ Unauthorized.\x1b[0m Please run \x1b[36mnpx vmlive login\x1b[0m first to securely pair this CLI.');
+     process.exit(1);
+  }
+
+  const GATEKEEPER_URL = process.env.GATEKEEPER_URL || 'http://localhost:8787';
+
+  // 2. Extract Workspace Architecture
+  console.log('\x1b[36m⏳ Orchestrating live Platform boundaries...\x1b[0m');
+  const wsRes = await fetch(`${GATEKEEPER_URL}/api/workspaces`, {
+      headers: { 'Authorization': `Bearer ${jwtToken}` }
+  });
+
+  if (!wsRes.ok) {
+     if (wsRes.status === 401) {
+         console.error('\x1b[31m❌ Session Expired:\x1b[0m Your authentication token has expired. Please run \x1b[36mnpx vmlive login\x1b[0m to securely re-authenticate.');
+     } else {
+         console.error('\x1b[31m❌ Sandbox Error:\x1b[0m Failed to securely retrieve workspace architecture from Production. HTTP ' + wsRes.status);
+     }
+     process.exit(1);
+  }
+
+  const workspaces = await wsRes.json();
+  if (!Array.isArray(workspaces) || workspaces.length === 0) {
+     console.error('\x1b[31m❌ Sandbox Error:\x1b[0m You do not possess any authorized Workspaces. Please map one on the dashboard first!');
+     process.exit(1);
+  }
+
+  // 3. Interactive Target Lock
+  const workspaceSlug = await select({
+     message: 'Select exactly which Platform Workspace you want this Sandbox to dynamically bind to:',
+     choices: workspaces.map(w => ({ name: w.name, value: w.slug }))
+  });
+
+  // 4. Extract Project Containers
+  const projRes = await fetch(`${GATEKEEPER_URL}/api/${workspaceSlug}/projects`, {
+     headers: { 'Authorization': `Bearer ${jwtToken}` }
+  });
+
+  if (!projRes.ok) {
+     console.error('\x1b[31m❌ Sandbox Error:\x1b[0m Failed to logically retrieve project constraints from Production.');
+     process.exit(1);
+  }
+
+  const projects = await projRes.json();
+  if (!Array.isArray(projects) || projects.length === 0) {
+     console.error('\x1b[31m❌ Sandbox Error:\x1b[0m No projects mathematically exist in this Workspace constraint.');
+     process.exit(1);
+  }
+
+  const projectSlug = await select({
+     message: 'Select exactly which Edge Project you want to natively emulate offline:',
+     choices: projects.map(p => ({ name: p.name, value: p.slug }))
+  });
+
+  const functionNameRaw = await input({
+     message: 'What do you want to conceptually name this initial serverless function?',
+     default: 'api'
+  });
+  const functionName = functionNameRaw.trim().toLowerCase().replace(/[^a-z0-9-]/g, '') || 'api';
+
+  // 5. Instantiation
+  if (!fs.existsSync(API_FILE)) {
+    const defaultApiTs = `import type { Env, Context } from '@vmlive/types';
+export default {
+  async fetch(request: Request, env: Env, ctx: Context) {
+    return new Response("Hello from your Local PaaS Edge!", { status: 200 });
+  }
+};
+`;
+    fs.writeFileSync(API_FILE, defaultApiTs);
+  }
+
+  if (!fs.existsSync(CONFIG_PATH)) {
+    const defaultVmJson = `{
+  "workspaceId": "${workspaceSlug}",
+  "projectId": "${projectSlug}",
+  "functions": [
+    { "name": "${functionName}", "entry": "index.ts" }
+  ]
+}
+`;
+    fs.writeFileSync(CONFIG_PATH, defaultVmJson);
+  }
+
+  const gitignorePath = path.resolve('.gitignore');
+  const ignoreEntries = ['node_modules', '.vmlive', '.env'];
+  if (fs.existsSync(gitignorePath)) {
+    let currentIgnore = fs.readFileSync(gitignorePath, 'utf8');
+    let appended = false;
+    ignoreEntries.forEach(entry => {
+      if (!currentIgnore.includes(entry)) {
+        currentIgnore += `\n${entry}`;
+        appended = true;
+      }
+    });
+    if (appended) fs.writeFileSync(gitignorePath, currentIgnore.trim() + '\n');
+  } else {
+    fs.writeFileSync(gitignorePath, ignoreEntries.join('\n') + '\n');
+  }
+
+  const pkgPath = path.resolve('package.json');
+  if (!fs.existsSync(pkgPath)) {
+    const defaultPackageJson = `{
+  "name": "vmlive-project",
+  "version": "1.0.0",
+  "type": "module",
+  "devDependencies": {
+    "@vmlive/types": "*",
+    "typescript": "^5.0.0"
+  }
+}
+`;
+    fs.writeFileSync(pkgPath, defaultPackageJson);
+  } else {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        pkg.devDependencies = pkg.devDependencies || {};
+        if (!pkg.devDependencies['@vmlive/types']) {
+            pkg.devDependencies['@vmlive/types'] = '*';
+            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+        }
+    } catch(e) {
+        // gracefully ignore malformed package.json
+    }
+  }
+
+  const tsConfigPath = path.resolve('tsconfig.json');
+  if (!fs.existsSync(tsConfigPath)) {
+    const defaultTsConfig = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["@vmlive/types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["**/*.ts"]
+}
+`;
+    fs.writeFileSync(tsConfigPath, defaultTsConfig);
+  } else {
+    try {
+        const tsconfig = JSON.parse(fs.readFileSync(tsConfigPath, 'utf8'));
+        tsconfig.compilerOptions = tsconfig.compilerOptions || {};
+        tsconfig.compilerOptions.types = tsconfig.compilerOptions.types || [];
+        if (!tsconfig.compilerOptions.types.includes('@vmlive/types')) {
+             tsconfig.compilerOptions.types.push('@vmlive/types');
+             fs.writeFileSync(tsConfigPath, JSON.stringify(tsconfig, null, 2));
+        }
+    } catch(e) {}
+  }
+
+  console.log('\x1b[36m📦 Installing platform types and dependencies...\x1b[0m');
+  await new Promise((resolve) => {
+     exec('npm install', (err) => {
+        if (err) console.error('\x1b[33m⚠️ Warning: npm install failed. You may need to run it manually to resolve TS errors.\x1b[0m');
+        resolve();
+     });
+  });
+
+  console.log('\x1b[32m✨ Extensible Project Scaffolded Successfully!\x1b[0m');
+  console.log('You can now natively run \x1b[36mnpx vmlive dev\x1b[0m to initiate the offline sandbox proxy.');
+};
+
+const runDev = 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 config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  
+  if (!fs.existsSync(WORK_DIR)) fs.mkdirSync(WORK_DIR, { recursive: true });
+  if (!fs.existsSync(DATA_DIR)) {
+    fs.mkdirSync(DATA_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: 'warning'
+  });
+
+  await builder.rebuild();
+  console.log('\x1b[32m✨ Platform Engine Initialized.\x1b[0m');
+
+  // Copy Shadow Worker to ephemeral .vm directory for Miniflare Sandbox Bounds
+  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) : (config.port || 8787);
+
+  const miniflareWorkers = [
+    buildProxyDispatcher(config.functions),
+    {
+      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" }
+      }
+    }))
+  ];
+  const mf = new Miniflare({ 
+    workers: miniflareWorkers, 
+    port: mfPort, 
+    cachePersist: path.join(WORK_DIR, 'cache'),
+    d1Persist: path.join(DATA_DIR, 'db'),
+    kvPersist: path.join(DATA_DIR, 'kv'),
+    r2Persist: path.join(DATA_DIR, 'bucket')
+  });
+  await mf.ready;
+  console.log(`🚀 Extensible Serverless VM running natively on http://*.localhost:${mfPort}`);
+
+  setInterval(() => {
+     const memoryData = process.memoryUsage();
+     const heapMb = Math.round(memoryData.heapUsed / 1024 / 1024);
+     if (heapMb > 110) {
+        console.warn(`\n\x1b[33m⚠️ [VM-CLI] CAUTION: HIGH MEMORY USAGE (${heapMb}MB)\x1b[0m`);
+        console.warn(`\x1b[33mYour worker environment is approaching the 128MB production limit. Local memory profiling is bloated due to dev-tooling overhead, but ensure your production build avoids massive synchronous allocations.\x1b[0m`);
+     }
+  }, 10000);
+
+  let debounceTimeout = null;
+  fs.watch(process.cwd(), { recursive: true }, (eventType, filename) => {
+    if (filename && (filename.endsWith('.ts') || filename.endsWith('.js'))) {
+      if (debounceTimeout) clearTimeout(debounceTimeout);
+      debounceTimeout = setTimeout(async () => {
+        try {
+          console.log(`\n🔄 ${filename} mutated. Syncing Engine...`);
+          await builder.rebuild();
+          
+          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));
+          });
+
+          await mf.setOptions({ 
+            workers: miniflareWorkers, 
+            port: mfPort, 
+            cachePersist: path.join(WORK_DIR, 'cache'),
+            d1Persist: path.join(DATA_DIR, 'db'),
+            kvPersist: path.join(DATA_DIR, 'kv'),
+            r2Persist: path.join(DATA_DIR, 'bucket')
+          });
+          await mf.ready;
+          console.log('\x1b[32m✨ Engine Hot-Reloaded.\x1b[0m');
+        } catch (err) {
+          console.error('\x1b[31m❌ Engine Sync Crash:\x1b[0m', err.message);
+        }
+      }, 150);
+    }
+  });
+
+  process.on('SIGINT', async () => {
+    console.log('\n🛑 Suspending Platform VM...');
+    await builder.dispose();
+    await mf.dispose();
+    process.exit(0);
+  });
+};
+
+const runDeploy = async () => {
+  console.log('\x1b[36m🚀 Initiating Deployment pipeline...\x1b[0m');
+  
+  const configPath = path.join(os.homedir(), '.vm-config.json');
+  let token = process.env.VM_API_TOKEN;
+  if (!token && fs.existsSync(configPath)) {
+     token = JSON.parse(fs.readFileSync(configPath, 'utf-8')).token;
+  }
+  
+  if (!token) {
+     console.error('\x1b[31m❌ Unauthorized. Please run `vm login` first.\x1b[0m');
+     process.exit(1);
+  }
+
+  if (!fs.existsSync(CONFIG_PATH)) {
+    console.error('\x1b[31m❌ Config vm.json missing. Run `vm init` first.\x1b[0m');
+    process.exit(1);
+  }
+
+  const vmConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  const { workspaceId, projectId, functions } = vmConfig;
+
+  // Dotenv Cascading: Extract explicitly configured variables mapping them tightly
+  let userEnv = {};
+  if (fs.existsSync('.env')) {
+      const baseEnv = dotenv.parse(fs.readFileSync('.env'));
+      userEnv = { ...userEnv, ...baseEnv };
+  }
+  if (fs.existsSync('.env.production')) {
+      const prodEnv = dotenv.parse(fs.readFileSync('.env.production'));
+      userEnv = { ...userEnv, ...prodEnv }; // Strict Override True
+  }
+  
+  console.log(`\x1b[35m[Config]\x1b[0m Successfully extracted ${Object.keys(userEnv).length} Environment Variables.`);
+
+  for (const fn of functions) {
+     console.log(`\x1b[36m[esbuild]\x1b[0m Bundling ${fn.name}...`);
+     const outPath = path.join(WORK_DIR, `${fn.name}-out.mjs`);
+     
+     await esbuild.build({
+        entryPoints: [path.resolve(fn.entry)],
+        bundle: true,
+        format: 'esm',
+        outfile: outPath,
+        external: ['cloudflare:*', 'node:*'],
+     });
+
+     const code = fs.readFileSync(outPath, 'utf8');
+     
+     const GATEKEEPER_URL = process.env.GATEKEEPER_URL || 'http://localhost:8787';
+     const target = `${GATEKEEPER_URL}/api/${workspaceId}/projects/${projectId}/functions/${fn.name}/deploy`;
+     
+     console.log(`\x1b[36m[POST]\x1b[0m Uploading to Gatekeeper Dispatch Edge...`);
+     
+     const res = await fetch(target, {
+         method: 'POST',
+         headers: {
+             'Authorization': `Bearer ${token}`,
+             'Content-Type': 'application/json'
+         },
+         body: JSON.stringify({ code, envVars: userEnv })
+     });
+
+     if (!res.ok) {
+         console.error(`\x1b[31m❌ Deployment failed: ${res.status}\x1b[0m`);
+         console.error(await res.text());
+         process.exit(1);
+     }
+
+     const jsonRes = await res.json();
+     console.log(`\x1b[32m✨ Extracted Function Deployed to: ${jsonRes.public_url || 'Success!'}\x1b[0m`);
+  }
+};
+
+const runLogin = async () => {
+  console.log('\x1b[36m✨ Initiating vm.live PKCE Authentication...\x1b[0m');
+
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+
+  const GATEKEEPER_URL = process.env.GATEKEEPER_URL || 'http://localhost:8787';
+  
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://127.0.0.1:${server.address().port}`);
+    const authCode = url.searchParams.get('code');
+
+    if (!authCode) {
+      res.writeHead(400);
+      res.end('Bad Request: Missing OAuth Code');
+      return;
+    }
+
+    try {
+      // Exchange
+      console.log('⏳ Exchanging PKCE Authorization Code...');
+      const tokenRes = await fetch(`${GATEKEEPER_URL}/api/auth/cli/exchange`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ auth_code: authCode, code_verifier: codeVerifier })
+      });
+
+      if (!tokenRes.ok) throw new Error(await tokenRes.text());
+      const { access_token } = await tokenRes.json();
+
+      const configPath = path.join(os.homedir(), '.vm-config.json');
+      fs.writeFileSync(configPath, JSON.stringify({ token: access_token }, null, 2));
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <html><body style="background:#09090b;color:#fff;font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;">
+          <div style="text-align:center;">
+             <div style="width:64px;height:64px;background:rgba(16,185,129,0.1);color:#10b981;border-radius:50%;display:flex;align-items:center;justify-content:center;margin:0 auto 24px auto;">
+               <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M20 6L9 17l-5-5"></path></svg>
+             </div>
+             <h1 style="color:#f4f4f5;font-size:24px;margin-bottom:8px;">Authentication Successful</h1>
+             <p style="color:#a1a1aa;margin-bottom:24px;">Your vm.live CLI is securely authorized.</p>
+             <p style="color:#52525b;font-size:14px;">You may now safely close this browser window and return to your terminal.</p>
+          </div>
+        </body></html>
+      `);
+      console.log('\x1b[32m✅ Successfully authenticated! Saved strictly to ~/.vm-config.json\x1b[0m');
+      
+      setTimeout(() => {
+        server.close();
+        process.exit(0);
+      }, 1500); // 1.5s flush buffer TCP protection
+      
+      
+    } catch (e) {
+      console.error('\x1b[31m❌ Failed to exchange code:\x1b[0m', e.message);
+      res.writeHead(500, { 'Content-Type': 'text/html' });
+      res.end('<html><body><h1>Authentication Failed</h1></body></html>');
+      
+      setTimeout(() => {
+        server.close();
+        process.exit(1);
+      }, 1500);
+    }
+  });
+
+  server.listen(0, '127.0.0.1', () => {
+    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`);
+    const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    exec(`${openCmd} "${authUrl}"`);
+  });
+};
+
+const main = async () => {
+  const command = process.argv[2];
+  if (command === 'init') {
+    runInit();
+  } else if (command === 'dev' || !command) {
+    await runDev();
+  } 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 dev | vm login | vm deploy');
+    process.exit(1);
+  }
+};
+
+main().catch(err => {
+  console.error("Fatal Kernel Exception:", err);
+  process.exit(1);
+});

package/src/shadow-dos.js

@@ -0,0 +1,137 @@
+import { DurableObject } from "cloudflare:workers";
+
+export class LocalTaskManagerDO extends DurableObject {
+    constructor(ctx, env) {
+        super(ctx, env);
+    }
+
+    async fetch(request) {
+        const url = new URL(request.url);
+        
+        if (request.method === "POST" && url.pathname === "/.internal/tasks/schedule") {
+            const body = await request.json();
+            const { functionSlug, executeAt, name, payload, workspaceId, projectId, interval } = body;
+            
+            const taskId = interval ? `cron:${functionSlug}:${name}` : crypto.randomUUID();
+            
+            const taskRecord = {
+                id: taskId,
+                function_slug: functionSlug,
+                type: "schedule",
+                execute_at: executeAt,
+                name: name,
+                payload: JSON.stringify(payload || {}),
+                workspace_id: workspaceId,
+                project_id: projectId,
+                interval: interval || null,
+                status: "pending"
+            };
+
+            await this.ctx.storage.put(taskId, taskRecord);
+            // We set the native Miniflare alarm
+            await this.ctx.storage.setAlarm(executeAt);
+            
+            return Response.json({ success: true, id: taskId });
+        }
+        return new Response("Not Found", { status: 404 });
+    }
+
+    async alarm() {
+        const now = Date.now();
+        const MapTasks = await this.ctx.storage.list();
+        
+        for (const [id, task] of MapTasks) {
+            if (task.execute_at <= now && task.status !== 'completed') {
+                try {
+                    // Structurally bypass network by resolving back through Miniflare host headers natively 
+                    const invokeUrl = `http://127.0.0.1:${this.env.PORT || 8787}/.internal/tasks/dispatch`;
+                    
+                    const res = await fetch(invokeUrl, {
+                        method: 'POST',
+                        headers: {
+                            'Host': `${task.function_slug}.localhost`,
+                            'Content-Type': 'application/json',
+                            'x-vm-system-signature': 'local-bypass'
+                        },
+                        body: JSON.stringify({
+                            taskId: task.id,
+                            name: task.name,
+                            payload: JSON.parse(task.payload),
+                            executeAt: task.execute_at,
+                            dispatchedAt: now
+                        })
+                    });
+
+                    if (res.ok) {
+                        if (task.interval) {
+                            const match = task.interval.match(/^(\d+)([smh])$/);
+                            if (match) {
+                                const val = parseInt(match[1]);
+                                const unit = match[2];
+                                let addMs = 0;
+                                if (unit === 's') addMs = val * 1000;
+                                else if (unit === 'm') addMs = val * 60000;
+                                else if (unit === 'h') addMs = val * 3600000;
+                                
+                                task.execute_at = now + addMs;
+                                await this.ctx.storage.put(id, task);
+                                await this.ctx.storage.setAlarm(task.execute_at);
+                            }
+                        } else {
+                            task.status = 'completed';
+                            await this.ctx.storage.put(id, task);
+                        }
+                    }
+                } catch (e) {
+                    console.error("[Shadow DO] Task execution failed locally:", e);
+                }
+            }
+        }
+    }
+}
+
+export class LocalChannelRoomDO extends DurableObject {
+    constructor(ctx, env) {
+        super(ctx, env);
+    }
+    
+    async fetch(request) {
+        const url = new URL(request.url);
+        
+        if (request.method === "POST" && url.pathname === "/broadcast") {
+            const body = await request.json();
+            const websockets = this.ctx.getWebSockets();
+            for (const ws of websockets) {
+                ws.send(JSON.stringify(body));
+            }
+            return new Response("OK");
+        }
+        
+        if (request.headers.get("Upgrade") === "websocket") {
+            const pair = new WebSocketPair();
+            const [client, server] = Object.values(pair);
+            this.ctx.acceptWebSocket(server);
+            return new Response(null, { status: 101, webSocket: client });
+        }
+        
+        return new Response("Not Found", { status: 404 });
+    }
+    
+    webSocketMessage(ws, message) {
+        this.ctx.getWebSockets().forEach((sock) => {
+             if (sock !== ws) {
+                 sock.send(message);
+             }
+        });
+    }
+    
+    webSocketClose(ws, code, reason, wasClean) {
+        ws.close(code, reason);
+    }
+}
+
+export default {
+    async fetch() {
+        return new Response("Shadow DO Platform Engine Internal Worker", { status: 200 });
+    }
+};

package/src/string-shim.js

@@ -0,0 +1,151 @@
+export const generateShim = (outFileUrl, workspaceId, projectId, functionSlug) => `
+import * as UserCode from '${outFileUrl}';
+
+export default {
+  async fetch(req, env, ctx) {
+    // Isolate the global KV 
+    const { __RAW_KV, ...safeEnv } = env;
+    const KV_PREFIX = \`${workspaceId}:${projectId}:\`;
+
+    // 1. Air-Gapped Virtual KV Multiplexer
+    const virtualKV = __RAW_KV ? {
+      get: (key, options) => __RAW_KV.get(KV_PREFIX + key, options),
+      getWithMetadata: (key, options) => __RAW_KV.getWithMetadata(KV_PREFIX + key, options),
+      put: (key, value, options) => __RAW_KV.put(KV_PREFIX + key, value, options),
+      delete: (key) => __RAW_KV.delete(KV_PREFIX + key),
+      list: async (options = {}) => {
+        const mergedOptions = { ...options, prefix: KV_PREFIX + (options.prefix || "") };
+        const result = await __RAW_KV.list(mergedOptions);
+        return {
+          ...result,
+          keys: result.keys.map(k => ({ ...k, name: k.name.substring(KV_PREFIX.length) }))
+        };
+      }
+    } : undefined;
+
+    // 2. Custom Platform Bindings internally mapped to Shadow DO instances
+    const Tasks = {
+      schedule: async (time, name, payload) => {
+        let addMs = 0;
+        const match = time.toString().match(/^(\\d+)([smhd])$/);
+        if (match) {
+            const val = parseInt(match[1]);
+            const unit = match[2];
+            if (unit === 's') addMs = val * 1000;
+            else if (unit === 'm') addMs = val * 60000;
+            else if (unit === 'h') addMs = val * 3600000;
+            else if (unit === 'd') addMs = val * 86400000;
+        } else {
+            addMs = parseInt(time) || 0; 
+        }
+        
+        console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 🕒 Tasks.schedule: [\${name}] at \${time}\`);
+        
+        const req = new Request("http://platform/.internal/tasks/schedule", {
+           method: "POST", body: JSON.stringify({
+              functionSlug: "${functionSlug}",
+              executeAt: Date.now() + addMs,
+              name,
+              payload,
+              workspaceId: "${workspaceId}",
+              projectId: "${projectId}"
+           })
+        });
+        const stub = env.TASK_DO.idFromName("${workspaceId}:${projectId}");
+        await env.TASK_DO.get(stub).fetch(req);
+        
+        return { success: true };
+      },
+      every: async (interval, name, payload) => {
+        console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 🔄 Tasks.every: [\${name}] every \${interval}\`);
+        
+        const req = new Request("http://platform/.internal/tasks/schedule", {
+           method: "POST", body: JSON.stringify({
+              functionSlug: "${functionSlug}",
+              executeAt: Date.now(), 
+              name,
+              payload,
+              workspaceId: "${workspaceId}",
+              projectId: "${projectId}",
+              interval
+           })
+        });
+        const stub = env.TASK_DO.idFromName("${workspaceId}:${projectId}");
+        await env.TASK_DO.get(stub).fetch(req);
+        
+        return { success: true };
+      }
+    };
+
+    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" }});
+        const stub = env.CHANNEL_DO.idFromName(roomName);
+        return await env.CHANNEL_DO.get(stub).fetch(req);
+      },
+      broadcast: async (roomName, payload) => {
+        console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 📡 Channels.broadcast: [\${roomName}]\`, payload);
+        const req = new Request("http://platform/broadcast", { method: "POST", body: JSON.stringify(payload) });
+        const stub = env.CHANNEL_DO.idFromName(roomName);
+        await env.CHANNEL_DO.get(stub).fetch(req);
+      }
+    };
+
+    const Discord = {
+      verify: async (request, publicKeyHex) => {
+        console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 👾 Discord.verify: Payload spoofed locally as True\`);
+        return {}; // Truthy mock return
+      }
+    };
+
+    const Slack = {
+      verify: async (request, signingSecret) => {
+        console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m 💬 Slack.verify: Payload spoofed locally as True\`);
+        return {}; // Truthy mock return
+      }
+    };
+
+    // 3. Hydrate exact customEnv definition expected by the tenant code
+    const customEnv = { 
+      ...safeEnv, 
+      KV: virtualKV, 
+      Tasks, 
+      Channels, 
+      Discord, 
+      Slack 
+    };
+
+    // 4. Secure boundary execution
+    try {
+      const url = new URL(req.url);
+      
+      // Native Mock Webhook Interception for Shadow DO
+      if (req.method === "POST" && url.pathname === "/.internal/tasks/dispatch" && req.headers.get("x-vm-system-signature") === "local-bypass") {
+         const payloadBody = await req.json();
+         const taskHandler = UserCode.default?.tasks || UserCode.tasks;
+         if (taskHandler) {
+             console.log(\`\\x1b[36m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m ⚡ Executing Scheduled Task: [\${payloadBody.name}]\`);
+             await taskHandler(payloadBody.payload, customEnv, ctx);
+             return new Response("OK");
+         } else {
+             console.warn(\`\\x1b[33m[\${env.PROJECT_ID || '${projectId}'}]\\x1b[0m ⚠️ Warning: Task '[\${payloadBody.name}]' dispatched, but no exported 'tasks()' handler was found.\`);
+             return new Response("No tasks handler", { status: 404 });
+         }
+      }
+
+      const handler = UserCode.default?.fetch || UserCode.fetch;
+      if (!handler) {
+        throw new Error("Application does not export a 'fetch' handler.");
+      }
+      return await handler(req, customEnv, ctx);
+    } catch (err) {
+      console.error("\\x1b[31m[Runtime Crash]\\x1b[0m", err);
+      return new Response(
+        JSON.stringify({ error: "Runtime Error", message: err.message, stack: err.stack }), 
+        { status: 500, headers: { "Content-Type": "application/json" } }
+      );
+    }
+  }
+};
+`;

package/tests/cli.integration.test.js

@@ -0,0 +1,198 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn, execSync } from 'child_process';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const CLI_PATH = path.resolve(__dirname, '../src/cli.js');
+const FIXTURE_DIR = path.resolve(__dirname, 'fixtures/tmp-app');
+
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+describe('VM CLI Workspace Scaffold', () => {
+  beforeAll(() => {
+    if (fs.existsSync(FIXTURE_DIR)) {
+      fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+    }
+  });
+
+  afterAll(() => {
+    if (fs.existsSync(FIXTURE_DIR)) {
+      fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+    }
+  });
+
+  it('1. should run "vm init" and dynamically scaffold the workspace', () => {
+    fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+    
+    // Execute init
+    execSync(`node ${CLI_PATH} init`, { cwd: FIXTURE_DIR });
+
+    // Assert files are created
+    expect(fs.existsSync(path.join(FIXTURE_DIR, 'vm.json'))).toBe(true);
+    expect(fs.existsSync(path.join(FIXTURE_DIR, 'index.ts'))).toBe(true);
+
+    const vmJson = JSON.parse(fs.readFileSync(path.join(FIXTURE_DIR, 'vm.json'), 'utf8'));
+    expect(vmJson.workspaceId).toBe('ws_123');
+  });
+});
+
+describe('VM CLI Emulator Bindings', () => {
+  let devProcess;
+  let logBuffer = "";
+
+  beforeAll(async () => {
+    // 1. Prepare Workspace by calling the native scaffold directly
+    if (!fs.existsSync(FIXTURE_DIR)) fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+    execSync(`node ${CLI_PATH} init`, { cwd: FIXTURE_DIR });
+    
+    // Ensure we specifically override the workspaceId for test predictability
+    const vmJson = JSON.parse(fs.readFileSync(path.join(FIXTURE_DIR, 'vm.json'), 'utf8'));
+    vmJson.workspaceId = 'ws_123';
+    vmJson.projectId = 'demo-project';
+    fs.writeFileSync(path.join(FIXTURE_DIR, 'vm.json'), JSON.stringify(vmJson, null, 2));
+
+    // 2. Overwrite the boilerplate index.ts with a massive dynamic router
+    const customApiTs = `export default {
+      async fetch(req, env) {
+          const url = new URL(req.url);
+          if (url.pathname === '/tasks/schedule') {
+              await env.Tasks.schedule("5m", "test_sync", { data: 1 });
+              return new Response("OK");
+          }
+          if (url.pathname === '/tasks/every') {
+              await env.Tasks.every("1h", "test_cron", { data: 2 });
+              return new Response("OK");
+          }
+          if (url.pathname === '/channels/accept') {
+              return await env.Channels.accept("lobby", { pub: true });
+          }
+          if (url.pathname === '/channels/broadcast') {
+              await env.Channels.broadcast("lobby", { msg: "hello" });
+              return new Response("OK");
+          }
+          if (url.pathname === '/discord') {
+              const res = await env.Discord.verify(req, "hex_key");
+              return new Response(JSON.stringify({ verified: !!res }));
+          }
+          if (url.pathname === '/slack') {
+              const res = await env.Slack.verify(req, "secret_key");
+              return new Response(JSON.stringify({ verified: !!res }));
+          }
+          if (url.pathname === '/kv') {
+              await env.KV.put("test_key", "test_val");
+              const keys = await env.KV.list({});
+              return new Response(JSON.stringify(keys), { headers: { "Content-Type": "application/json" } });
+          }
+          return new Response("Not Found", { status: 404 });
+      }
+    };`;
+    
+    fs.writeFileSync(path.join(FIXTURE_DIR, 'index.ts'), customApiTs);
+
+    // 3. Boot dev process natively and intercept STDOUT stream
+    devProcess = spawn('node', [CLI_PATH, 'dev'], { 
+        cwd: FIXTURE_DIR,
+        env: { ...process.env, PORT: "8799" }
+    });
+
+    await new Promise((resolve, reject) => {
+      let isReady = false;
+      const timeout = setTimeout(() => {
+        if (!isReady) {
+            devProcess.kill();
+            reject(new Error('CLI Dev server boot timeout.'));
+        }
+      }, 25000);
+
+      devProcess.stdout.on('data', (data) => {
+        const out = data.toString();
+        logBuffer += out;
+        if (out.includes('Extensible Serverless VM running')) {
+           isReady = true;
+           clearTimeout(timeout);
+           resolve(true);
+        }
+      });
+      devProcess.stderr.on('data', (data) => {
+        console.error("CLI STDERR:", data.toString());
+      });
+    });
+
+    // We must wait just a bit for Miniflare HTTP sockets to actually map
+    await sleep(500);
+  }, 30000); // Extended timeout to compile the shim
+
+  afterAll(() => {
+    if (devProcess) {
+      devProcess.kill('SIGINT');
+    }
+    if (fs.existsSync(FIXTURE_DIR)) {
+      fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+    }
+  });
+
+
+  // =========================================================================
+  // SEPARATED BINDING TESTS
+  // =========================================================================
+
+  it('should completely mock Tasks.schedule and trigger the STDOUT array', async () => {
+    await fetch('http://127.0.0.1:8799/tasks/schedule', { headers: { "Host": "api.localhost" } });
+    await sleep(100);
+    expect(logBuffer).toContain("Tasks.schedule: [test_sync] at 5m");
+  });
+
+  it('should beautifully mock Tasks.every recursively with STDOUT matching', async () => {
+    await fetch('http://127.0.0.1:8799/tasks/every', { headers: { "Host": "api.localhost" } });
+    await sleep(100);
+    expect(logBuffer).toContain("Tasks.every: [test_cron] every 1h");
+  });
+
+  it('should intercept Channels.accept and return an HTTP 101 WebSocket Upgrade packet', async () => {
+    try {
+        await fetch('http://127.0.0.1:8799/channels/accept', { 
+            headers: { "Host": "api.localhost" } 
+        });
+    } catch (e) {
+        // Node's native fetch (undici) explicitly throws when receiving HTTP 101
+    }
+    await sleep(100);
+    expect(logBuffer).toContain("Channels.accept: [lobby]");
+  });
+
+  it('should fire Channels.broadcast silently mapping via STDOUT', async () => {
+    await fetch('http://127.0.0.1:8799/channels/broadcast', { headers: { "Host": "api.localhost" } });
+    await sleep(100);
+    expect(logBuffer).toContain("Channels.broadcast: [lobby]");
+  });
+
+  it('should safely spoof Discord.verify logic via simple WebCrypto circumvention', async () => {
+    const discordRes = await fetch('http://127.0.0.1:8799/discord', { headers: { "Host": "api.localhost" } });
+    const json = JSON.parse(await discordRes.text());
+    expect(json.verified).toBe(true);
+    await sleep(100);
+    expect(logBuffer).toContain("Discord.verify: Payload spoofed locally as True");
+  });
+
+  it('should strictly bypass Slack HMAC logic locally', async () => {
+    const slackRes = await fetch('http://127.0.0.1:8799/slack', { headers: { "Host": "api.localhost" } });
+    const json = JSON.parse(await slackRes.text());
+    expect(json.verified).toBe(true);
+    await sleep(100);
+    expect(logBuffer).toContain("Slack.verify: Payload spoofed locally as True");
+  });
+
+  it('should strip boundary prefixes mathematically from Virtual KV arrays', async () => {
+    const kvResponse = await fetch('http://127.0.0.1:8799/kv', { headers: { "Host": "api.localhost" } });
+    const kvJson = JSON.parse(await kvResponse.text());
+    
+    expect(kvJson.keys).toBeDefined();
+    expect(kvJson.keys.length).toBeGreaterThan(0);
+    // Crucially asserts we natively stripped workspaceId:projectId:
+    expect(kvJson.keys[0].name).toBe('test_key');
+  });
+});