tova 0.1.1 → 0.2.2

package/bin/tova.js

@@ -1,19 +1,24 @@
 #!/usr/bin/env bun
 
 import { resolve, basename, dirname, join, relative } from 'path';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, copyFileSync, watch as fsWatch } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, copyFileSync, rmSync, watch as fsWatch } from 'fs';
 import { spawn } from 'child_process';
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
 import { Lexer } from '../src/lexer/lexer.js';
 import { Parser } from '../src/parser/parser.js';
 import { Analyzer } from '../src/analyzer/analyzer.js';
+import { Program } from '../src/parser/ast.js';
 import { CodeGenerator } from '../src/codegen/codegen.js';
 import { richError, formatDiagnostics, DiagnosticFormatter } from '../src/diagnostics/formatter.js';
-import { getFullStdlib, BUILTINS, PROPAGATE } from '../src/stdlib/inline.js';
+import { getFullStdlib, buildSelectiveStdlib, BUILTIN_NAMES, PROPAGATE } from '../src/stdlib/inline.js';
 import { Formatter } from '../src/formatter/formatter.js';
 import { REACTIVITY_SOURCE, RPC_SOURCE, ROUTER_SOURCE } from '../src/runtime/embedded.js';
 import '../src/runtime/string-proto.js';
+import { resolveConfig } from '../src/config/resolve.js';
+import { writePackageJson } from '../src/config/package-json.js';
+import { addToSection, removeFromSection } from '../src/config/edit-toml.js';
+import { stringifyTOML } from '../src/config/toml.js';
 
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../package.json');
@@ -23,6 +28,7 @@ const HELP = `
   ║  ║ ║ ║ ╠╣
   ╩═╝╚═╝╩═╝╩  v${VERSION}
 
+  Created by Enoch Kujem Abassey
   A modern full-stack language that transpiles to JavaScript
 
 Usage:
@@ -31,10 +37,13 @@ Usage:
 Commands:
   run <file>       Compile and execute a .tova file
   build [dir]      Compile .tova files to JavaScript (default: current dir)
-  dev              Start development server with file watching
+  dev              Start development server with live reload
+  new <name>       Create a new Tova project
+  install          Install npm dependencies from tova.toml
+  add <pkg>        Add an npm dependency (--dev for dev dependency)
+  remove <pkg>     Remove an npm dependency
   repl             Start interactive Tova REPL
   lsp              Start Language Server Protocol server
-  new <name>       Create a new Tova project
   fmt <file>      Format a .tova file (--check to verify only)
   test [dir]      Run test blocks in .tova files (--filter, --watch)
   migrate:create <name>   Create a new migration file
@@ -48,6 +57,7 @@ Options:
   --production     Production build (minify, bundle, hash)
   --watch          Watch for file changes
   --debug          Show verbose error output
+  --strict         Enable strict type checking
 `;
 
 async function main() {
@@ -65,9 +75,10 @@ async function main() {
 
   const command = args[0];
 
+  const isStrict = args.includes('--strict');
   switch (command) {
     case 'run':
-      await runFile(args[1]);
+      await runFile(args.filter(a => a !== '--strict')[1], { strict: isStrict });
       break;
     case 'build':
       buildProject(args.slice(1));
@@ -84,6 +95,15 @@ async function main() {
     case 'new':
       newProject(args[1]);
       break;
+    case 'install':
+      await installDeps();
+      break;
+    case 'add':
+      await addDep(args.slice(1));
+      break;
+    case 'remove':
+      await removeDep(args[1]);
+      break;
     case 'fmt':
       formatFile(args.slice(1));
       break;
@@ -101,7 +121,7 @@ async function main() {
       break;
     default:
       if (command.endsWith('.tova')) {
-        await runFile(command);
+        await runFile(command, { strict: isStrict });
       } else {
         console.error(`Unknown command: ${command}`);
         console.log(HELP);
@@ -112,14 +132,14 @@ async function main() {
 
 // ─── Compile a .tova source string ───────────────────────────
 
-function compileTova(source, filename) {
+function compileTova(source, filename, options = {}) {
   const lexer = new Lexer(source, filename);
   const tokens = lexer.tokenize();
 
   const parser = new Parser(tokens, filename);
   const ast = parser.parse();
 
-  const analyzer = new Analyzer(ast, filename);
+  const analyzer = new Analyzer(ast, filename, { strict: options.strict || false });
   const { warnings } = analyzer.analyze();
 
   if (warnings.length > 0) {
@@ -299,11 +319,25 @@ function findTovaFiles(dir) {
 
 // ─── Run ────────────────────────────────────────────────────
 
-async function runFile(filePath) {
+async function runFile(filePath, options = {}) {
   if (!filePath) {
-    console.error('Error: No file specified');
-    console.error('Usage: tova run <file.tova>');
-    process.exit(1);
+    // If tova.toml exists, try to find a main file in the entry directory
+    const config = resolveConfig(process.cwd());
+    if (config._source === 'tova.toml') {
+      const entryDir = resolve(config.project.entry || '.');
+      for (const name of ['main.tova', 'app.tova']) {
+        const candidate = join(entryDir, name);
+        if (existsSync(candidate)) {
+          filePath = candidate;
+          break;
+        }
+      }
+    }
+    if (!filePath) {
+      console.error('Error: No file specified');
+      console.error('Usage: tova run <file.tova>');
+      process.exit(1);
+    }
   }
 
   const resolved = resolve(filePath);
@@ -315,7 +349,7 @@ async function runFile(filePath) {
   const source = readFileSync(resolved, 'utf-8');
 
   try {
-    const output = compileTova(source, filePath);
+    const output = compileTova(source, filePath, { strict: options.strict });
 
     // Execute the generated JavaScript (with stdlib)
     const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
@@ -335,10 +369,13 @@ async function runFile(filePath) {
 // ─── Build ──────────────────────────────────────────────────
 
 async function buildProject(args) {
+  const config = resolveConfig(process.cwd());
   const isProduction = args.includes('--production');
-  const srcDir = resolve(args.filter(a => !a.startsWith('--'))[0] || '.');
+  const buildStrict = args.includes('--strict');
+  const explicitSrc = args.filter(a => !a.startsWith('--'))[0];
+  const srcDir = resolve(explicitSrc || config.project.entry || '.');
   const outIdx = args.indexOf('--output');
-  const outDir = resolve(outIdx >= 0 ? args[outIdx + 1] : '.tova-out');
+  const outDir = resolve(outIdx >= 0 ? args[outIdx + 1] : (config.build.output || '.tova-out'));
 
   // Production build uses a separate optimized pipeline
   if (isProduction) {
@@ -364,22 +401,33 @@ async function buildProject(args) {
 
   let errorCount = 0;
   compilationCache.clear();
-  for (const file of tovaFiles) {
-    const rel = relative(srcDir, file);
+
+  // Group files by directory for multi-file merging
+  const dirGroups = groupFilesByDirectory(tovaFiles);
+
+  for (const [dir, files] of dirGroups) {
+    const dirName = basename(dir) === '.' ? 'app' : basename(dir);
+    const relDir = relative(srcDir, dir) || '.';
     try {
-      const source = readFileSync(file, 'utf-8');
-      const output = compileWithImports(source, file, srcDir);
-      const baseName = basename(file, '.tova');
+      const result = mergeDirectory(dir, srcDir, { strict: buildStrict });
+      if (!result) continue;
+
+      const { output, single } = result;
+      // Use single-file basename for single-file dirs, directory name for multi-file
+      const outBaseName = single ? basename(files[0], '.tova') : dirName;
+      const relLabel = single ? relative(srcDir, files[0]) : `${relDir}/ (${files.length} files merged)`;
 
-      // Generate source map if mappings available
+      // Helper to generate source maps
       const generateSourceMap = (code, jsFile) => {
         if (output.sourceMappings && output.sourceMappings.length > 0) {
-          const smb = new SourceMapBuilder(rel);
+          const sourceFile = single ? relative(srcDir, files[0]) : relDir;
+          const smb = new SourceMapBuilder(sourceFile, output._sourceFiles);
           for (const m of output.sourceMappings) {
-            smb.addMapping(m.sourceLine, m.sourceCol, m.outputLine, m.outputCol);
+            smb.addMapping(m.sourceLine, m.sourceCol, m.outputLine, m.outputCol, m.sourceFile);
           }
+          const sourceContent = single ? readFileSync(files[0], 'utf-8') : null;
           const mapFile = jsFile + '.map';
-          writeFileSync(mapFile, smb.generate(source));
+          writeFileSync(mapFile, smb.generate(sourceContent, output._sourceContents));
           return code + `\n//# sourceMappingURL=${basename(mapFile)}`;
         }
         return code;
@@ -387,32 +435,32 @@ async function buildProject(args) {
 
       // Write shared
       if (output.shared && output.shared.trim()) {
-        const sharedPath = join(outDir, `${baseName}.shared.js`);
+        const sharedPath = join(outDir, `${outBaseName}.shared.js`);
         writeFileSync(sharedPath, generateSourceMap(output.shared, sharedPath));
-        console.log(`  ✓ ${rel} → ${relative('.', sharedPath)}`);
+        console.log(`  ✓ ${relLabel} → ${relative('.', sharedPath)}`);
       }
 
       // Write default server
       if (output.server) {
-        const serverPath = join(outDir, `${baseName}.server.js`);
+        const serverPath = join(outDir, `${outBaseName}.server.js`);
         writeFileSync(serverPath, generateSourceMap(output.server, serverPath));
-        console.log(`  ✓ ${rel} → ${relative('.', serverPath)}`);
+        console.log(`  ✓ ${relLabel} → ${relative('.', serverPath)}`);
       }
 
       // Write default client
       if (output.client) {
-        const clientPath = join(outDir, `${baseName}.client.js`);
+        const clientPath = join(outDir, `${outBaseName}.client.js`);
         writeFileSync(clientPath, generateSourceMap(output.client, clientPath));
-        console.log(`  ✓ ${rel} → ${relative('.', clientPath)}`);
+        console.log(`  ✓ ${relLabel} → ${relative('.', clientPath)}`);
       }
 
       // Write named server blocks (multi-block)
       if (output.multiBlock && output.servers) {
         for (const [name, code] of Object.entries(output.servers)) {
-          if (name === 'default') continue; // already written above
-          const path = join(outDir, `${baseName}.server.${name}.js`);
+          if (name === 'default') continue;
+          const path = join(outDir, `${outBaseName}.server.${name}.js`);
           writeFileSync(path, code);
-          console.log(`  ✓ ${rel} → ${relative('.', path)} [server:${name}]`);
+          console.log(`  ✓ ${relLabel} → ${relative('.', path)} [server:${name}]`);
         }
       }
 
@@ -420,26 +468,31 @@ async function buildProject(args) {
       if (output.multiBlock && output.clients) {
         for (const [name, code] of Object.entries(output.clients)) {
           if (name === 'default') continue;
-          const path = join(outDir, `${baseName}.client.${name}.js`);
+          const path = join(outDir, `${outBaseName}.client.${name}.js`);
           writeFileSync(path, code);
-          console.log(`  ✓ ${rel} → ${relative('.', path)} [client:${name}]`);
+          console.log(`  ✓ ${relLabel} → ${relative('.', path)} [client:${name}]`);
         }
       }
     } catch (err) {
-      console.error(`  ✗ ${rel}: ${err.message}`);
+      console.error(`  ✗ ${relDir}: ${err.message}`);
       errorCount++;
     }
   }
 
-  console.log(`\n  Build complete. ${tovaFiles.length - errorCount}/${tovaFiles.length} succeeded.\n`);
+  const dirCount = dirGroups.size;
+  console.log(`\n  Build complete. ${dirCount - errorCount}/${dirCount} directory group(s) succeeded.\n`);
   if (errorCount > 0) process.exit(1);
 }
 
 // ─── Dev Server ─────────────────────────────────────────────
 
 async function devServer(args) {
-  const srcDir = resolve(args[0] || '.');
-  const basePort = parseInt(args.find((_, i, a) => a[i - 1] === '--port') || '3000');
+  const config = resolveConfig(process.cwd());
+  const explicitSrc = args.filter(a => !a.startsWith('--'))[0];
+  const srcDir = resolve(explicitSrc || config.project.entry || '.');
+  const explicitPort = args.find((_, i, a) => a[i - 1] === '--port');
+  const basePort = parseInt(explicitPort || config.dev.port || '3000');
+  const buildStrict = args.includes('--strict');
 
   const tovaFiles = findFiles(srcDir, '.tova');
   if (tovaFiles.length === 0) {
@@ -447,6 +500,8 @@ async function devServer(args) {
     process.exit(1);
   }
 
+  const reloadPort = basePort + 100;
+
   console.log(`\n  Tova dev server starting...\n`);
 
   // Compile all files
@@ -463,63 +518,75 @@ async function devServer(args) {
   const serverFiles = [];
   let hasClient = false;
 
-  for (const file of tovaFiles) {
+  // Clear import caches for fresh compilation
+  compilationCache.clear();
+  compilationInProgress.clear();
+  moduleExports.clear();
+
+  // Compile via directory merging
+  const dirGroups = groupFilesByDirectory(tovaFiles);
+  let clientHTML = '';
+
+  // Pass 1: Merge each directory, write shared/client outputs, collect clientHTML
+  const dirResults = [];
+  for (const [dir, files] of dirGroups) {
+    const dirName = basename(dir) === '.' ? 'app' : basename(dir);
     try {
-      const source = readFileSync(file, 'utf-8');
-      const output = compileTova(source, file);
-      const baseName = basename(file, '.tova');
+      const result = mergeDirectory(dir, srcDir, { strict: buildStrict });
+      if (!result) continue;
+
+      const { output, single } = result;
+      const outBaseName = single ? basename(files[0], '.tova') : dirName;
+      dirResults.push({ dir, output, outBaseName, single, files });
 
       if (output.shared && output.shared.trim()) {
-        writeFileSync(join(outDir, `${baseName}.shared.js`), output.shared);
+        writeFileSync(join(outDir, `${outBaseName}.shared.js`), output.shared);
       }
 
-      // Default client (generate HTML first so server can embed it)
-      let clientHTML = '';
       if (output.client) {
-        const p = join(outDir, `${baseName}.client.js`);
+        const p = join(outDir, `${outBaseName}.client.js`);
         writeFileSync(p, output.client);
-        clientHTML = generateDevHTML(output.client);
+        clientHTML = await generateDevHTML(output.client, srcDir, reloadPort);
         writeFileSync(join(outDir, 'index.html'), clientHTML);
         hasClient = true;
       }
+    } catch (err) {
+      console.error(`  ✗ ${relative(srcDir, dir)}: ${err.message}`);
+    }
+  }
 
-      // Default server (inject client HTML for serving at /)
-      if (output.server) {
-        let serverCode = output.server;
-        if (clientHTML) {
-          // Inject __clientHTML constant before the request handler
-          const htmlConst = `const __clientHTML = ${JSON.stringify(clientHTML)};\n`;
-          serverCode = htmlConst + serverCode;
-        }
-        const p = join(outDir, `${baseName}.server.js`);
-        writeFileSync(p, serverCode);
-        serverFiles.push({ path: p, name: 'default', baseName });
+  // Pass 2: Write server files with clientHTML injected
+  for (const { output, outBaseName } of dirResults) {
+    if (output.server) {
+      let serverCode = output.server;
+      if (clientHTML) {
+        const htmlConst = `const __clientHTML = ${JSON.stringify(clientHTML)};\n`;
+        serverCode = htmlConst + serverCode;
       }
+      const p = join(outDir, `${outBaseName}.server.js`);
+      writeFileSync(p, serverCode);
+      serverFiles.push({ path: p, name: 'default', baseName: outBaseName });
+    }
 
-      // Named server blocks
-      if (output.multiBlock && output.servers) {
-        for (const [name, code] of Object.entries(output.servers)) {
-          if (name === 'default') continue;
-          const p = join(outDir, `${baseName}.server.${name}.js`);
-          writeFileSync(p, code);
-          serverFiles.push({ path: p, name, baseName });
-        }
+    if (output.multiBlock && output.servers) {
+      for (const [name, code] of Object.entries(output.servers)) {
+        if (name === 'default') continue;
+        const p = join(outDir, `${outBaseName}.server.${name}.js`);
+        writeFileSync(p, code);
+        serverFiles.push({ path: p, name, baseName: outBaseName });
       }
+    }
 
-      // Named client blocks
-      if (output.multiBlock && output.clients) {
-        for (const [name, code] of Object.entries(output.clients)) {
-          if (name === 'default') continue;
-          const p = join(outDir, `${baseName}.client.${name}.js`);
-          writeFileSync(p, code);
-        }
+    if (output.multiBlock && output.clients) {
+      for (const [name, code] of Object.entries(output.clients)) {
+        if (name === 'default') continue;
+        const p = join(outDir, `${outBaseName}.client.${name}.js`);
+        writeFileSync(p, code);
       }
-    } catch (err) {
-      console.error(`  ✗ ${relative(srcDir, file)}: ${err.message}`);
     }
   }
 
-  console.log(`  ✓ Compiled ${tovaFiles.length} file(s)`);
+  console.log(`  ✓ Compiled ${tovaFiles.length} file(s) from ${dirGroups.size} directory group(s)`);
   console.log(`  ✓ Output: ${relative('.', outDir)}/`);
 
   // Orchestrate: spawn each server block as a separate Bun process
@@ -559,6 +626,49 @@ async function devServer(args) {
     console.log(`  ✓ Client: ${relative('.', outDir)}/index.html`);
   }
 
+  // Start live-reload SSE server
+  const reloadClients = new Set();
+  const reloadServer = Bun.serve({
+    port: reloadPort,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === '/__tova_reload') {
+        const stream = new ReadableStream({
+          start(controller) {
+            const client = { controller };
+            reloadClients.add(client);
+            // Send heartbeat to keep connection alive
+            const heartbeat = setInterval(() => {
+              try { controller.enqueue(new TextEncoder().encode(': heartbeat\n\n')); } catch { clearInterval(heartbeat); }
+            }, 15000);
+            req.signal.addEventListener('abort', () => {
+              clearInterval(heartbeat);
+              reloadClients.delete(client);
+            });
+          },
+        });
+        return new Response(stream, {
+          headers: {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'Access-Control-Allow-Origin': '*',
+          },
+        });
+      }
+      return new Response('Not Found', { status: 404 });
+    },
+  });
+
+  function notifyReload() {
+    const msg = new TextEncoder().encode('data: reload\n\n');
+    for (const client of reloadClients) {
+      try { client.controller.enqueue(msg); } catch { reloadClients.delete(client); }
+    }
+  }
+
+  console.log(`  ✓ Live reload on port ${reloadPort}`);
+
   // Start file watcher for auto-rebuild
   const watcher = startWatcher(srcDir, async () => {
     console.log('  Rebuilding...');
@@ -566,30 +676,50 @@ async function devServer(args) {
     // Recompile first — keep old processes alive until success
     const currentFiles = findFiles(srcDir, '.tova');
     const newServerFiles = [];
+
+    // Clear import caches for fresh compilation
+    compilationCache.clear();
+    compilationInProgress.clear();
+    moduleExports.clear();
+
     try {
-      for (const file of currentFiles) {
-        const source = readFileSync(file, 'utf-8');
-        const output = compileTova(source, file);
-        const baseName = basename(file, '.tova');
+      // Merge each directory group, collect client HTML
+      const rebuildDirGroups = groupFilesByDirectory(currentFiles);
+      let rebuildClientHTML = '';
+
+      for (const [dir, files] of rebuildDirGroups) {
+        const dirName = basename(dir) === '.' ? 'app' : basename(dir);
+        const result = mergeDirectory(dir, srcDir, { strict: buildStrict });
+        if (!result) continue;
+
+        const { output, single } = result;
+        const outBaseName = single ? basename(files[0], '.tova') : dirName;
 
         if (output.shared && output.shared.trim()) {
-          writeFileSync(join(outDir, `${baseName}.shared.js`), output.shared);
+          writeFileSync(join(outDir, `${outBaseName}.shared.js`), output.shared);
         }
         if (output.client) {
-          writeFileSync(join(outDir, `${baseName}.client.js`), output.client);
-          const html = generateDevHTML(output.client);
-          writeFileSync(join(outDir, 'index.html'), html);
+          writeFileSync(join(outDir, `${outBaseName}.client.js`), output.client);
+          rebuildClientHTML = await generateDevHTML(output.client, srcDir, reloadPort);
+          writeFileSync(join(outDir, 'index.html'), rebuildClientHTML);
         }
         if (output.server) {
           let serverCode = output.server;
-          if (output.client) {
-            const html = generateDevHTML(output.client);
-            serverCode = `const __clientHTML = ${JSON.stringify(html)};\n` + serverCode;
+          if (rebuildClientHTML) {
+            serverCode = `const __clientHTML = ${JSON.stringify(rebuildClientHTML)};\n` + serverCode;
           }
-          const p = join(outDir, `${baseName}.server.js`);
+          const p = join(outDir, `${outBaseName}.server.js`);
           writeFileSync(p, serverCode);
           newServerFiles.push(p);
         }
+        if (output.multiBlock && output.servers) {
+          for (const [name, code] of Object.entries(output.servers)) {
+            if (name === 'default') continue;
+            const p = join(outDir, `${outBaseName}.server.${name}.js`);
+            writeFileSync(p, code);
+            newServerFiles.push(p);
+          }
+        }
       }
     } catch (err) {
       console.error(`  ✗ Rebuild failed: ${err.message}`);
@@ -620,6 +750,7 @@ async function devServer(args) {
       rebuildPortOffset++;
     }
     console.log('  ✓ Rebuild complete');
+    notifyReload();
   });
 
   console.log(`\n  Watching for changes. Press Ctrl+C to stop\n`);
@@ -628,6 +759,7 @@ async function devServer(args) {
   process.on('SIGINT', () => {
     console.log('\n  Shutting down...');
     watcher.close();
+    reloadServer.stop();
     for (const p of processes) {
       p.child.kill('SIGTERM');
     }
@@ -638,14 +770,50 @@ async function devServer(args) {
   await new Promise(() => {});
 }
 
-function generateDevHTML(clientCode) {
+async function generateDevHTML(clientCode, srcDir, reloadPort = 0) {
+  const liveReloadScript = reloadPort ? `
+  <script>
+    (function() {
+      var es = new EventSource("http://localhost:${reloadPort}/__tova_reload");
+      es.onmessage = function(e) { if (e.data === "reload") window.location.reload(); };
+      es.onerror = function() { setTimeout(function() { window.location.reload(); }, 1000); };
+    })();
+  </script>` : '';
+
+  // Check if client code uses npm packages — if so, bundle with Bun.build
+  if (srcDir && hasNpmImports(clientCode)) {
+    const bundled = await bundleClientCode(clientCode, srcDir);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Tova App</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; color: #1a1a1a; }
+    ul { list-style: none; }
+    .done { text-decoration: line-through; opacity: 0.5; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module">
+${bundled}
+  </script>${liveReloadScript}
+</body>
+</html>`;
+  }
+
+  // Original path: no npm imports — inline runtime, no bundling overhead
   // Use embedded runtime sources (no disk reads needed)
   const inlineReactivity = REACTIVITY_SOURCE.replace(/^export /gm, '');
   const inlineRpc = RPC_SOURCE.replace(/^export /gm, '');
 
-  // Strip import lines from client code (we inline the runtime instead)
+  // Strip all import lines from client code (we inline the runtime instead)
   const inlineClient = clientCode
-    .replace(/^import\s+\{[^}]+\}\s+from\s+'[^']+';?\s*$/gm, '')
+    .replace(/^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gm, '')
     .trim();
 
   return `<!DOCTYPE html>
@@ -654,20 +822,10 @@ function generateDevHTML(clientCode) {
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Tova App</title>
+  <script src="https://cdn.tailwindcss.com"></script>
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-    body { font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; color: #1a1a1a; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); min-height: 100vh; }
-    #app { max-width: 520px; margin: 0 auto; padding: 2rem 1rem; }
-    .app { background: white; border-radius: 16px; padding: 2rem; box-shadow: 0 20px 60px rgba(0,0,0,0.15); }
-    header { text-align: center; margin-bottom: 1.5rem; }
-    h1 { font-size: 2rem; margin-bottom: 0.25rem; color: #333; }
-    h2 { font-size: 1.2rem; margin-bottom: 0.75rem; color: #555; }
-    .subtitle { font-size: 0.9rem; color: #888; letter-spacing: 0.1em; text-transform: uppercase; }
-    button { cursor: pointer; padding: 0.5rem 1rem; border: 1px solid #ddd; border-radius: 8px; background: white; font-size: 0.9rem; transition: all 0.15s; }
-    button:hover { background: #f0f0f0; transform: translateY(-1px); }
-    button:active { transform: translateY(0); }
-    input[type="text"] { padding: 0.6rem 0.75rem; border: 2px solid #e0e0e0; border-radius: 8px; font-size: 0.9rem; width: 100%; outline: none; transition: border-color 0.2s; }
-    input[type="text"]:focus { border-color: #667eea; }
+    body { font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; color: #1a1a1a; }
     ul { list-style: none; }
     .done { text-decoration: line-through; opacity: 0.5; }
     .timer-section { text-align: center; padding: 1.5rem; margin-bottom: 1.5rem; background: #f8f9ff; border-radius: 12px; }
@@ -705,7 +863,7 @@ ${inlineRpc}
 
 // ── App ──
 ${inlineClient}
-  </script>
+  </script>${liveReloadScript}
 </body>
 </html>`;
 }
@@ -730,19 +888,34 @@ function newProject(name) {
   mkdirSync(projectDir, { recursive: true });
   mkdirSync(join(projectDir, 'src'));
 
-  // package.json
-  writeFileSync(join(projectDir, 'package.json'), JSON.stringify({
-    name,
-    version: '0.1.0',
-    type: 'module',
-    scripts: {
-      dev: 'tova dev src',
-      build: 'tova build src',
+  // tova.toml
+  const tomlContent = stringifyTOML({
+    project: {
+      name,
+      version: '0.1.0',
+      description: 'A full-stack Tova application',
+      entry: 'src',
     },
-    dependencies: {
-      'tova': '^0.1.0',
+    build: {
+      output: '.tova-out',
     },
-  }, null, 2) + '\n');
+    dev: {
+      port: 3000,
+    },
+    dependencies: {},
+    npm: {},
+  });
+  writeFileSync(join(projectDir, 'tova.toml'), tomlContent);
+
+  // .gitignore
+  writeFileSync(join(projectDir, '.gitignore'), `node_modules/
+.tova-out/
+package.json
+bun.lock
+*.db
+*.db-shm
+*.db-wal
+`);
 
   // Main app file
   writeFileSync(join(projectDir, 'src', 'app.tova'), `// ${name} — Built with Tova
@@ -786,24 +959,146 @@ Built with [Tova](https://github.com/tova-lang/tova-lang) — a modern full-stac
 ## Development
 
 \`\`\`bash
-bun install
-bun run dev
+tova install
+tova dev
 \`\`\`
 
 ## Build
 
 \`\`\`bash
-bun run build
+tova build
+\`\`\`
+
+## Add npm packages
+
+\`\`\`bash
+tova add htmx
+tova add prettier --dev
 \`\`\`
 `);
 
-  console.log(`  ✓ Created ${name}/package.json`);
+  console.log(`  ✓ Created ${name}/tova.toml`);
+  console.log(`  ✓ Created ${name}/.gitignore`);
   console.log(`  ✓ Created ${name}/src/app.tova`);
   console.log(`  ✓ Created ${name}/README.md`);
   console.log(`\n  Get started:\n`);
   console.log(`    cd ${name}`);
-  console.log(`    bun install`);
-  console.log(`    bun run dev\n`);
+  console.log(`    tova install`);
+  console.log(`    tova dev\n`);
+}
+
+// ─── Package Management ─────────────────────────────────────
+
+async function installDeps() {
+  const cwd = process.cwd();
+  const config = resolveConfig(cwd);
+
+  if (config._source !== 'tova.toml') {
+    // No tova.toml — just run bun install as normal
+    console.log('  No tova.toml found, running bun install...\n');
+    const proc = spawn('bun', ['install'], { stdio: 'inherit', cwd });
+    const code = await new Promise(res => proc.on('close', res));
+    process.exit(code);
+    return;
+  }
+
+  // Generate shadow package.json from tova.toml
+  const wrote = writePackageJson(config, cwd);
+  if (wrote) {
+    console.log('  Generated package.json from tova.toml');
+    const proc = spawn('bun', ['install'], { stdio: 'inherit', cwd });
+    const code = await new Promise(res => proc.on('close', res));
+    process.exit(code);
+  } else {
+    console.log('  No npm dependencies in tova.toml. Nothing to install.\n');
+  }
+}
+
+async function addDep(args) {
+  const isDev = args.includes('--dev');
+  const pkg = args.find(a => !a.startsWith('--'));
+
+  if (!pkg) {
+    console.error('Error: No package specified');
+    console.error('Usage: tova add <package> [--dev]');
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const tomlPath = join(cwd, 'tova.toml');
+
+  if (!existsSync(tomlPath)) {
+    console.error('Error: No tova.toml found in current directory');
+    console.error('Run `tova new <name>` to create a new project, or create tova.toml manually.');
+    process.exit(1);
+  }
+
+  // Parse package name and version
+  let name = pkg;
+  let version = 'latest';
+  if (pkg.includes('@') && !pkg.startsWith('@')) {
+    const atIdx = pkg.lastIndexOf('@');
+    name = pkg.slice(0, atIdx);
+    version = pkg.slice(atIdx + 1);
+  } else if (pkg.startsWith('@') && pkg.includes('@', 1)) {
+    // Scoped package with version: @scope/name@version
+    const atIdx = pkg.lastIndexOf('@');
+    name = pkg.slice(0, atIdx);
+    version = pkg.slice(atIdx + 1);
+  }
+
+  // If version is 'latest', resolve it via npm registry
+  if (version === 'latest') {
+    try {
+      const proc = spawn('npm', ['view', name, 'version'], { stdio: ['pipe', 'pipe', 'pipe'] });
+      let out = '';
+      proc.stdout.on('data', d => out += d);
+      const code = await new Promise(res => proc.on('close', res));
+      if (code === 0 && out.trim()) {
+        version = `^${out.trim()}`;
+      } else {
+        version = '*';
+      }
+    } catch {
+      version = '*';
+    }
+  }
+
+  const section = isDev ? 'npm.dev' : 'npm';
+  addToSection(tomlPath, section, name, version);
+
+  console.log(`  Added ${name}@${version} to [${section}] in tova.toml`);
+
+  // Run install
+  await installDeps();
+}
+
+async function removeDep(pkg) {
+  if (!pkg) {
+    console.error('Error: No package specified');
+    console.error('Usage: tova remove <package>');
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const tomlPath = join(cwd, 'tova.toml');
+
+  if (!existsSync(tomlPath)) {
+    console.error('Error: No tova.toml found in current directory');
+    process.exit(1);
+  }
+
+  // Try removing from [npm] first, then [npm.dev]
+  const removed = removeFromSection(tomlPath, 'npm', pkg) ||
+                  removeFromSection(tomlPath, 'npm.dev', pkg);
+
+  if (removed) {
+    console.log(`  Removed ${pkg} from tova.toml`);
+    await installDeps();
+  } else {
+    console.error(`  Package '${pkg}' not found in tova.toml`);
+    process.exit(1);
+  }
 }
 
 // ─── Migrations ─────────────────────────────────────────────
@@ -1026,10 +1321,74 @@ async function migrateStatus(args) {
 
 function getStdlibForRuntime() {
   return getFullStdlib();  // Full stdlib for REPL
-}  
-function getRunStdlib() { // Excludes RESULT_OPTION (emitted by codegen)
-  return `${BUILTINS}
-${PROPAGATE}`;
+}
+function getRunStdlib() { // Only PROPAGATE — codegen tree-shakes stdlib into output.shared
+  return PROPAGATE;
+}
+
+// ─── npm Interop Utilities ───────────────────────────────────
+
+function hasNpmImports(code) {
+  // Match import statements with bare specifiers (not relative paths or runtime imports)
+  const importRegex = /^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"]([^'"]+)['"];?\s*$/gm;
+  let match;
+  while ((match = importRegex.exec(code)) !== null) {
+    const source = match[1];
+    // Skip relative imports and runtime imports
+    if (source.startsWith('./') || source.startsWith('../') || source.startsWith('/') || source.startsWith('./runtime/')) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+async function bundleClientCode(clientCode, srcDir) {
+  const tmpDir = join(srcDir, '.tova-out', '.tmp-bundle');
+  try {
+    mkdirSync(tmpDir, { recursive: true });
+    mkdirSync(join(tmpDir, 'runtime'), { recursive: true });
+
+    // Write runtime files so Bun.build can resolve ./runtime/ imports
+    writeFileSync(join(tmpDir, 'runtime', 'reactivity.js'), REACTIVITY_SOURCE);
+    writeFileSync(join(tmpDir, 'runtime', 'rpc.js'), RPC_SOURCE);
+    writeFileSync(join(tmpDir, 'runtime', 'router.js'), ROUTER_SOURCE);
+
+    // Write client code as entrypoint
+    const entryPath = join(tmpDir, '__entry.js');
+    writeFileSync(entryPath, clientCode);
+
+    const result = await Bun.build({
+      entrypoints: [entryPath],
+      bundle: true,
+      format: 'esm',
+      target: 'browser',
+    });
+
+    if (!result.success) {
+      const errors = result.logs.filter(l => l.level === 'error').map(l => l.message);
+      // Check for missing package errors and provide actionable message
+      const missingPkgs = errors
+        .map(e => {
+          const m = e.match(/Could not resolve ["']([^"']+)["']/);
+          return m ? m[1] : null;
+        })
+        .filter(Boolean);
+      if (missingPkgs.length > 0) {
+        throw new Error(`Missing npm packages in client block. Run: bun install ${missingPkgs.join(' ')}`);
+      }
+      throw new Error(`Client bundling failed:\n${errors.join('\n')}`);
+    }
+
+    // Read the bundled output
+    const bundled = await result.outputs[0].text();
+    return bundled;
+  } finally {
+    // Clean up temp files
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {}
+  }
 }
 
 // ─── LSP Server ──────────────────────────────────────────────
@@ -1054,14 +1413,8 @@ async function startRepl() {
 
   const context = {};
   const stdlib = getStdlibForRuntime();
-  // Initialize stdlib in context — dynamically extract all function names
-  const fnNameRegex = /\bfunction\s+([a-zA-Z_]\w*)/g;
-  const stdlibNames = [];
-  let fnMatch;
-  while ((fnMatch = fnNameRegex.exec(stdlib)) !== null) stdlibNames.push(fnMatch[1]);
-  // Also include const bindings (Ok, Err, Some, None, __propagate)
-  const constRegex = /\bconst\s+([a-zA-Z_]\w*)/g;
-  while ((fnMatch = constRegex.exec(stdlib)) !== null) stdlibNames.push(fnMatch[1]);
+  // Use authoritative BUILTIN_NAMES + runtime names (Ok, Err, Some, None, __propagate)
+  const stdlibNames = [...BUILTIN_NAMES, 'Ok', 'Err', 'Some', 'None', '__propagate'];
   const initFn = new Function(stdlib + '\nObject.assign(this, {' + stdlibNames.join(',') + '});');
   initFn.call(context);
 
@@ -1136,8 +1489,12 @@ async function startRepl() {
           evalCode = allButLast + (allButLast ? '\n' : '') + `return (${returnExpr});`;
         }
         try {
-          const keys = Object.keys(context);
-          const destructure = keys.length > 0 ? `const {${keys.join(',')}} = __ctx;` : '';
+          // Extract function/const names from compiled code to avoid shadowing conflicts
+          const declaredInCode = new Set();
+          for (const m of evalCode.matchAll(/\bfunction\s+([a-zA-Z_]\w*)/g)) declaredInCode.add(m[1]);
+          for (const m of evalCode.matchAll(/\bconst\s+([a-zA-Z_]\w*)/g)) declaredInCode.add(m[1]);
+          const ctxKeys = Object.keys(context).filter(k => !declaredInCode.has(k));
+          const destructure = ctxKeys.length > 0 ? `const {${ctxKeys.join(',')}} = __ctx;` : '';
           const fn = new Function('__ctx', `${destructure}\n${evalCode}`);
           const result = fn(context);
           if (result !== undefined) {
@@ -1145,8 +1502,11 @@ async function startRepl() {
           }
         } catch (e) {
           // If return-wrapping fails, fall back to plain execution
-          const keys = Object.keys(context);
-          const destructure = keys.length > 0 ? `const {${keys.join(',')}} = __ctx;` : '';
+          const declaredInCode = new Set();
+          for (const m of code.matchAll(/\bfunction\s+([a-zA-Z_]\w*)/g)) declaredInCode.add(m[1]);
+          for (const m of code.matchAll(/\bconst\s+([a-zA-Z_]\w*)/g)) declaredInCode.add(m[1]);
+          const ctxKeys = Object.keys(context).filter(k => !declaredInCode.has(k));
+          const destructure = ctxKeys.length > 0 ? `const {${ctxKeys.join(',')}} = __ctx;` : '';
           const fn = new Function('__ctx', `${destructure}\n${code}`);
           fn(context);
         }
@@ -1191,27 +1551,43 @@ function startWatcher(srcDir, callback) {
 // ─── Source Map Support ──────────────────────────────────────
 
 class SourceMapBuilder {
-  constructor(sourceFile) {
+  constructor(sourceFile, sourceFiles = null) {
     this.sourceFile = sourceFile;
+    // Multi-source support: array of all source files for merged output
+    this.sourceFiles = sourceFiles || [sourceFile];
+    this._sourceIndex = new Map();
+    for (let i = 0; i < this.sourceFiles.length; i++) {
+      this._sourceIndex.set(this.sourceFiles[i], i);
+    }
     this.mappings = [];
     this.outputLine = 0;
     this.outputCol = 0;
   }
 
-  addMapping(sourceLine, sourceCol, outputLine, outputCol) {
-    this.mappings.push({ sourceLine, sourceCol, outputLine, outputCol });
+  addMapping(sourceLine, sourceCol, outputLine, outputCol, sourceFile = null) {
+    const srcIdx = sourceFile ? (this._sourceIndex.get(sourceFile) || 0) : 0;
+    this.mappings.push({ sourceLine, sourceCol, outputLine, outputCol, sourceIdx: srcIdx });
   }
 
   // Generate a VLQ-encoded source map
-  generate(sourceContent) {
-    const sources = [this.sourceFile];
+  generate(sourceContent, sourceContentsMap = null) {
+    const sources = this.sourceFiles;
     const names = [];
 
+    // Build sourcesContent array for multi-source
+    let sourcesContent;
+    if (sourceContentsMap && sourceContentsMap instanceof Map) {
+      sourcesContent = sources.map(s => sourceContentsMap.get(s) || null);
+    } else if (sourceContent) {
+      sourcesContent = [sourceContent];
+    }
+
     // Sort mappings by output position
     this.mappings.sort((a, b) => a.outputLine - b.outputLine || a.outputCol - b.outputCol);
 
     // Encode mappings using VLQ
     let prevOutputCol = 0;
+    let prevSourceIdx = 0;
     let prevSourceLine = 0;
     let prevSourceCol = 0;
     let currentOutputLine = 0;
@@ -1229,22 +1605,24 @@ class SourceMapBuilder {
 
       const segment = [];
       segment.push(this._vlqEncode(m.outputCol - prevOutputCol));
-      segment.push(this._vlqEncode(0)); // source index (always 0)
+      segment.push(this._vlqEncode(m.sourceIdx - prevSourceIdx));
       segment.push(this._vlqEncode(m.sourceLine - prevSourceLine));
       segment.push(this._vlqEncode(m.sourceCol - prevSourceCol));
 
       currentLine.push(segment.join(''));
       prevOutputCol = m.outputCol;
+      prevSourceIdx = m.sourceIdx;
       prevSourceLine = m.sourceLine;
       prevSourceCol = m.sourceCol;
     }
     lines.push(currentLine.join(','));
 
+    const outFile = typeof this.sourceFile === 'string' ? this.sourceFile.replace('.tova', '.js') : 'merged.js';
     return JSON.stringify({
       version: 3,
-      file: this.sourceFile.replace('.tova', '.js'),
+      file: outFile,
       sources,
-      sourcesContent: sourceContent ? [sourceContent] : undefined,
+      sourcesContent: sourcesContent || undefined,
       names,
       mappings: lines.join(';'),
     });
@@ -1263,8 +1641,8 @@ class SourceMapBuilder {
     return encoded;
   }
 
-  toDataURL(sourceContent) {
-    const mapJson = this.generate(sourceContent);
+  toDataURL(sourceContent, sourceContentsMap = null) {
+    const mapJson = this.generate(sourceContent, sourceContentsMap);
     const base64 = Buffer.from(mapJson).toString('base64');
     return `//# sourceMappingURL=data:application/json;base64,${base64}`;
   }
@@ -1317,11 +1695,22 @@ async function productionBuild(srcDir, outDir) {
 
   // Write client bundle
   if (allClientCode.trim()) {
-    const reactivityCode = REACTIVITY_SOURCE.replace(/^export /gm, '');
-    const rpcCode = RPC_SOURCE.replace(/^export /gm, '');
+    const fullClientModule = allSharedCode + '\n' + allClientCode;
 
-    const clientBundle = reactivityCode + '\n' + rpcCode + '\n' + allSharedCode + '\n' +
-      allClientCode.replace(/^import\s+\{[^}]+\}\s+from\s+'[^']+';?\s*$/gm, '').trim();
+    let clientBundle;
+    let useModule = false;
+
+    if (hasNpmImports(fullClientModule)) {
+      // npm imports detected — bundle with Bun.build to resolve bare specifiers
+      clientBundle = await bundleClientCode(fullClientModule, srcDir);
+      useModule = true;
+    } else {
+      // No npm imports — inline runtime, strip all imports
+      const reactivityCode = REACTIVITY_SOURCE.replace(/^export /gm, '');
+      const rpcCode = RPC_SOURCE.replace(/^export /gm, '');
+      clientBundle = reactivityCode + '\n' + rpcCode + '\n' + allSharedCode + '\n' +
+        allClientCode.replace(/^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gm, '').trim();
+    }
 
     const hash = hashCode(clientBundle);
     const clientPath = join(outDir, `client.${hash}.js`);
@@ -1329,6 +1718,9 @@ async function productionBuild(srcDir, outDir) {
     console.log(`  client.${hash}.js`);
 
     // Generate production HTML
+    const scriptTag = useModule
+      ? `<script type="module" src="client.${hash}.js"></script>`
+      : `<script src="client.${hash}.js"></script>`;
     const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -1338,7 +1730,7 @@ async function productionBuild(srcDir, outDir) {
 </head>
 <body>
   <div id="app"></div>
-  <script src="client.${hash}.js"></script>
+  ${scriptTag}
 </body>
 </html>`;
     writeFileSync(join(outDir, 'index.html'), html);
@@ -1378,7 +1770,8 @@ const moduleExports = new Map();
 function collectExports(ast, filename) {
   const publicExports = new Set();
   const allNames = new Set();
-  for (const node of ast.body) {
+
+  function collectFromNode(node) {
     if (node.type === 'FunctionDeclaration') {
       allNames.add(node.name);
       if (node.isPublic) publicExports.add(node.name);
@@ -1421,6 +1814,19 @@ function collectExports(ast, filename) {
     }
     if (node.type === 'ImplDeclaration') { /* impl doesn't export a name */ }
   }
+
+  for (const node of ast.body) {
+    // Also collect exports from inside shared/server/client blocks
+    if (node.type === 'SharedBlock' || node.type === 'ServerBlock' || node.type === 'ClientBlock') {
+      if (node.body) {
+        for (const inner of node.body) {
+          collectFromNode(inner);
+        }
+      }
+      continue;
+    }
+    collectFromNode(node);
+  }
   moduleExports.set(filename, { publicExports, allNames });
   return { publicExports, allNames };
 }
@@ -1509,6 +1915,257 @@ function compileWithImports(source, filename, srcDir) {
   }
 }
 
+// ─── Multi-file Directory Merging ────────────────────────────
+
+function validateMergedAST(mergedBlocks, sourceFiles) {
+  const errors = [];
+
+  function addDup(kind, name, loc1, loc2) {
+    const f1 = loc1.source || 'unknown';
+    const f2 = loc2.source || 'unknown';
+    errors.push(
+      `Duplicate ${kind} '${name}'\n` +
+      `  → first defined in ${basename(f1)}:${loc1.line}\n` +
+      `  → also defined in ${basename(f2)}:${loc2.line}`
+    );
+  }
+
+  // Check client blocks — top-level declarations only
+  const clientDecls = { component: new Map(), state: new Map(), computed: new Map(), store: new Map(), fn: new Map() };
+  for (const block of mergedBlocks.clientBlocks) {
+    for (const stmt of block.body) {
+      const loc = stmt.loc || block.loc;
+      if (stmt.type === 'ComponentDeclaration') {
+        if (clientDecls.component.has(stmt.name)) addDup('component', stmt.name, clientDecls.component.get(stmt.name), loc);
+        else clientDecls.component.set(stmt.name, loc);
+      } else if (stmt.type === 'StateDeclaration') {
+        const name = stmt.name || (stmt.targets && stmt.targets[0]);
+        if (name) {
+          if (clientDecls.state.has(name)) addDup('state', name, clientDecls.state.get(name), loc);
+          else clientDecls.state.set(name, loc);
+        }
+      } else if (stmt.type === 'ComputedDeclaration') {
+        const name = stmt.name;
+        if (name) {
+          if (clientDecls.computed.has(name)) addDup('computed', name, clientDecls.computed.get(name), loc);
+          else clientDecls.computed.set(name, loc);
+        }
+      } else if (stmt.type === 'StoreDeclaration') {
+        if (clientDecls.store.has(stmt.name)) addDup('store', stmt.name, clientDecls.store.get(stmt.name), loc);
+        else clientDecls.store.set(stmt.name, loc);
+      } else if (stmt.type === 'FunctionDeclaration') {
+        if (clientDecls.fn.has(stmt.name)) addDup('function', stmt.name, clientDecls.fn.get(stmt.name), loc);
+        else clientDecls.fn.set(stmt.name, loc);
+      }
+    }
+  }
+
+  // Check server blocks — group by block name, check within same-name groups
+  const serverGrouped = new Map();
+  for (const block of mergedBlocks.serverBlocks) {
+    const key = block.name || null;
+    if (!serverGrouped.has(key)) serverGrouped.set(key, []);
+    serverGrouped.get(key).push(block);
+  }
+
+  for (const [, blocks] of serverGrouped) {
+    const serverDecls = { fn: new Map(), model: new Map(), route: new Map() };
+    const singletons = new Map(); // db, cors, auth, session, etc.
+    const SINGLETON_TYPES = {
+      'DbDeclaration': 'db', 'CorsDeclaration': 'cors', 'AuthDeclaration': 'auth',
+      'SessionDeclaration': 'session', 'CompressionDeclaration': 'compression',
+      'TlsDeclaration': 'tls', 'UploadDeclaration': 'upload', 'RateLimitDeclaration': 'rate_limit',
+    };
+
+    for (const block of blocks) {
+      const walkBody = (stmts) => {
+        for (const stmt of stmts) {
+          const loc = stmt.loc || block.loc;
+          if (stmt.type === 'FunctionDeclaration') {
+            if (serverDecls.fn.has(stmt.name)) addDup('server function', stmt.name, serverDecls.fn.get(stmt.name), loc);
+            else serverDecls.fn.set(stmt.name, loc);
+          } else if (stmt.type === 'ModelDeclaration') {
+            if (serverDecls.model.has(stmt.name)) addDup('model', stmt.name, serverDecls.model.get(stmt.name), loc);
+            else serverDecls.model.set(stmt.name, loc);
+          } else if (stmt.type === 'RouteDeclaration') {
+            const routeKey = `${stmt.method} ${stmt.path}`;
+            if (serverDecls.route.has(routeKey)) addDup('route', routeKey, serverDecls.route.get(routeKey), loc);
+            else serverDecls.route.set(routeKey, loc);
+          } else if (SINGLETON_TYPES[stmt.type]) {
+            const sName = SINGLETON_TYPES[stmt.type];
+            if (singletons.has(sName)) addDup('server config', sName, singletons.get(sName), loc);
+            else singletons.set(sName, loc);
+          } else if (stmt.type === 'RouteGroupDeclaration') {
+            walkBody(stmt.body);
+          }
+        }
+      };
+      walkBody(block.body);
+    }
+  }
+
+  // Check shared blocks
+  const sharedDecls = { type: new Map(), fn: new Map(), interface: new Map() };
+  for (const block of mergedBlocks.sharedBlocks) {
+    for (const stmt of block.body) {
+      const loc = stmt.loc || block.loc;
+      if (stmt.type === 'TypeDeclaration') {
+        if (sharedDecls.type.has(stmt.name)) addDup('type', stmt.name, sharedDecls.type.get(stmt.name), loc);
+        else sharedDecls.type.set(stmt.name, loc);
+      } else if (stmt.type === 'FunctionDeclaration') {
+        if (sharedDecls.fn.has(stmt.name)) addDup('shared function', stmt.name, sharedDecls.fn.get(stmt.name), loc);
+        else sharedDecls.fn.set(stmt.name, loc);
+      } else if (stmt.type === 'InterfaceDeclaration' || stmt.type === 'TraitDeclaration') {
+        if (sharedDecls.interface.has(stmt.name)) addDup('interface/trait', stmt.name, sharedDecls.interface.get(stmt.name), loc);
+        else sharedDecls.interface.set(stmt.name, loc);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error('Merge validation failed:\n\n' + errors.join('\n\n'));
+  }
+}
+
+function mergeDirectory(dir, srcDir, options = {}) {
+  // Find all .tova files in this directory only (non-recursive)
+  const entries = readdirSync(dir);
+  const tovaFiles = entries
+    .filter(e => e.endsWith('.tova') && !e.startsWith('.'))
+    .map(e => join(dir, e))
+    .filter(f => statSync(f).isFile())
+    .sort();
+
+  if (tovaFiles.length === 0) return null;
+  if (tovaFiles.length === 1) {
+    // Single file — use existing per-file compilation
+    const file = tovaFiles[0];
+    const source = readFileSync(file, 'utf-8');
+    return { output: compileWithImports(source, file, srcDir), files: [file], single: true };
+  }
+
+  // Parse all files in the directory
+  const parsedFiles = [];
+  for (const file of tovaFiles) {
+    const source = readFileSync(file, 'utf-8');
+    const lexer = new Lexer(source, file);
+    const tokens = lexer.tokenize();
+    const parser = new Parser(tokens, file);
+    const ast = parser.parse();
+
+    // Collect exports for cross-file import validation
+    collectExports(ast, file);
+
+    // Resolve cross-directory .tova imports (same logic as compileWithImports)
+    for (const node of ast.body) {
+      if ((node.type === 'ImportDeclaration' || node.type === 'ImportDefault' || node.type === 'ImportWildcard') && node.source.endsWith('.tova')) {
+        const importPath = resolve(dirname(file), node.source);
+        // Only process imports from OTHER directories (same-dir files are merged)
+        if (dirname(importPath) !== dir) {
+          if (compilationInProgress.has(importPath)) {
+            throw new Error(`Circular import detected: ${file} → ${importPath}`);
+          } else if (existsSync(importPath) && !compilationCache.has(importPath)) {
+            const importSource = readFileSync(importPath, 'utf-8');
+            compileWithImports(importSource, importPath, srcDir);
+          }
+          // Validate imported names
+          if (node.type === 'ImportDeclaration' && moduleExports.has(importPath)) {
+            const { publicExports, allNames } = moduleExports.get(importPath);
+            for (const spec of node.specifiers) {
+              if (!publicExports.has(spec.imported)) {
+                if (allNames.has(spec.imported)) {
+                  throw new Error(`'${spec.imported}' is private in module '${node.source}'. Add 'pub' to export it.`);
+                } else {
+                  throw new Error(`Module '${node.source}' does not export '${spec.imported}'`);
+                }
+              }
+            }
+          }
+          // Rewrite to .js
+          node.source = node.source.replace('.tova', '.shared.js');
+        } else {
+          // Same-directory import — remove it since files are merged
+          node._removed = true;
+        }
+      }
+    }
+
+    parsedFiles.push({ file, source, ast });
+  }
+
+  // Merge ASTs: collect blocks from all files, tagged with source file
+  const mergedBody = [];
+  const sharedBlocks = [];
+  const serverBlocks = [];
+  const clientBlocks = [];
+
+  for (const { file, ast } of parsedFiles) {
+    for (const node of ast.body) {
+      // Skip removed same-directory imports
+      if (node._removed) continue;
+
+      // Tag node with source file for source maps and error reporting
+      if (node.loc) node.loc.source = file;
+      else node.loc = { line: 1, column: 0, source: file };
+
+      // Tag children too
+      if (node.body && Array.isArray(node.body)) {
+        for (const child of node.body) {
+          if (child.loc) child.loc.source = file;
+          else child.loc = { line: 1, column: 0, source: file };
+        }
+      }
+
+      if (node.type === 'SharedBlock') sharedBlocks.push(node);
+      else if (node.type === 'ServerBlock') serverBlocks.push(node);
+      else if (node.type === 'ClientBlock') clientBlocks.push(node);
+
+      mergedBody.push(node);
+    }
+  }
+
+  // Validate for duplicate declarations across files
+  validateMergedAST({ sharedBlocks, serverBlocks, clientBlocks }, tovaFiles);
+
+  // Build merged Program AST
+  const mergedAST = new Program(mergedBody);
+
+  // Run analyzer on merged AST
+  const analyzer = new Analyzer(mergedAST, dir);
+  const { warnings } = analyzer.analyze();
+
+  if (warnings.length > 0) {
+    for (const w of warnings) {
+      console.warn(`  Warning: ${w.message} (line ${w.line})`);
+    }
+  }
+
+  // Run codegen on merged AST
+  const codegen = new CodeGenerator(mergedAST, dir);
+  const output = codegen.generate();
+
+  // Collect source content from all files for source maps
+  const sourceContents = new Map();
+  for (const { file, source } of parsedFiles) {
+    sourceContents.set(file, source);
+  }
+  output._sourceContents = sourceContents;
+  output._sourceFiles = tovaFiles;
+
+  return { output, files: tovaFiles, single: false };
+}
+
+// Group .tova files by their parent directory
+function groupFilesByDirectory(files) {
+  const groups = new Map();
+  for (const file of files) {
+    const dir = dirname(file);
+    if (!groups.has(dir)) groups.set(dir, []);
+    groups.get(dir).push(file);
+  }
+  return groups;
+}
+
 function findFiles(dir, ext) {
   const results = [];
   if (!existsSync(dir)) return results;