tova 0.7.0 → 0.9.4

package/src/codegen/codegen.js

@@ -36,6 +36,18 @@ function getEdgeCodegen() {
   return _EdgeCodegen;
 }
 
+let _DeployCodegen;
+function getDeployCodegen() {
+  if (!_DeployCodegen) _DeployCodegen = _require('./deploy-codegen.js').DeployCodegen;
+  return _DeployCodegen;
+}
+
+let _ThemeCodegen;
+function getThemeCodegen() {
+  if (!_ThemeCodegen) _ThemeCodegen = _require('./theme-codegen.js').ThemeCodegen;
+  return _ThemeCodegen;
+}
+
 export class CodeGenerator {
   constructor(ast, filename = '<stdin>', options = {}) {
     this.ast = ast;
@@ -60,6 +72,11 @@ export class CodeGenerator {
     const topLevel = [];
 
     for (const node of this.ast.body) {
+      // pub component declarations at top level are module-level exports, not browser block children
+      if (node.type === 'ComponentDeclaration' && node.isPublic) {
+        topLevel.push(node);
+        continue;
+      }
       const plugin = BlockRegistry.getByAstType(node.type);
       if (plugin) {
         if (!blocksByType.has(plugin.name)) blocksByType.set(plugin.name, []);
@@ -87,20 +104,67 @@ export class CodeGenerator {
     const dataBlocks = getBlocks('data');
     const securityBlocks = getBlocks('security');
     const edgeBlocks = getBlocks('edge');
+    const deployBlocks = getBlocks('deploy');
+    const themeBlocks = getBlocks('theme');
 
     // Detect module mode: no blocks, only top-level statements
     const hasAnyBlocks = BlockRegistry.all().some(p => getBlocks(p.name).length > 0);
     const isModule = !hasAnyBlocks && topLevel.length > 0;
 
     if (isModule) {
+      // Separate pub component declarations from other top-level nodes
+      const componentNodes = topLevel.filter(n => n.type === 'ComponentDeclaration');
+      const otherNodes = topLevel.filter(n => n.type !== 'ComponentDeclaration');
+
       const moduleGen = new SharedCodegen();
       moduleGen._sourceMapsEnabled = this._sourceMaps;
       moduleGen.setSourceFile(this.filename);
-      // Use genBlockStatements for pattern optimization (array fill detection, etc.)
-      const fakeBlock = { type: 'BlockStatement', body: topLevel };
-      const moduleCode = moduleGen.genBlockStatements(fakeBlock);
+
+      // Generate non-component top-level code
+      let moduleCode = '';
+      if (otherNodes.length > 0) {
+        const fakeBlock = { type: 'BlockStatement', body: otherNodes };
+        moduleCode = moduleGen.genBlockStatements(fakeBlock);
+      }
+
+      // Generate pub component code using BrowserCodegen
+      let componentCode = '';
+      if (componentNodes.length > 0) {
+        const BrowserCodegen = getBrowserCodegen();
+        const compGen = new BrowserCodegen();
+        compGen._sourceMapsEnabled = this._sourceMaps;
+        compGen.setSourceFile(this.filename);
+
+        // Sort: parent components first, then compound (child) components
+        const sortedComponents = [...componentNodes].sort((a, b) => {
+          const aIsChild = a.parent ? 1 : 0;
+          const bIsChild = b.parent ? 1 : 0;
+          return aIsChild - bIsChild;
+        });
+
+        const compParts = [];
+        for (const comp of sortedComponents) {
+          if (comp.parent) {
+            // Compound component — assign as property on parent
+            compParts.push(`${comp.parent}.${comp.child} = ${compGen.generateComponent(comp)};`);
+          } else {
+            const exportPrefix = comp.isPublic ? 'export ' : '';
+            compParts.push(exportPrefix + compGen.generateComponent(comp));
+          }
+        }
+        componentCode = compParts.join('\n\n');
+      }
+
       const helpers = moduleGen.generateHelpers();
-      const combined = [helpers, moduleCode].filter(s => s.trim()).join('\n').trim();
+      const parts = [helpers];
+
+      // Add runtime imports for component DOM/reactivity functions
+      if (componentNodes.length > 0) {
+        parts.unshift(`import { createSignal, createEffect, createComputed, batch, onMount, onUnmount, onCleanup, tova_el, tova_fragment, tova_keyed, tova_inject_css, createRef, createContext, provide, inject } from './runtime/reactivity.js';`);
+      }
+
+      parts.push(moduleCode, componentCode);
+      const combined = parts.filter(s => s.trim()).join('\n').trim();
       return {
         shared: combined,
         server: '',
@@ -164,6 +228,11 @@ export class CodeGenerator {
       ? getSecurityCodegen().mergeSecurityBlocks(securityBlocks)
       : null;
 
+    // Merge theme blocks into a single config
+    const themeConfig = themeBlocks.length > 0
+      ? getThemeCodegen().mergeThemeBlocks(themeBlocks)
+      : null;
+
     // Generate server outputs (one per named group)
     const servers = {};
     for (const [name, blocks] of serverGroups) {
@@ -215,7 +284,7 @@ export class CodeGenerator {
       const gen = new (getBrowserCodegen())();
       gen._sourceMapsEnabled = this._sourceMaps;
       const key = name || 'default';
-      browsers[key] = gen.generate(blocks, combinedShared, sharedGen._usedBuiltins, securityConfig, typeValidatorsMap);
+      browsers[key] = gen.generate(blocks, combinedShared, sharedGen._usedBuiltins, securityConfig, typeValidatorsMap, themeConfig);
     }
 
     // Generate edge outputs (one per named group)
@@ -232,6 +301,17 @@ export class CodeGenerator {
       }
     }
 
+    // Generate deploy configs (one per named block)
+    const deploys = {};
+    if (deployBlocks.length > 0) {
+      const Deploy = getDeployCodegen();
+      const deployGroups = this._groupByName(deployBlocks);
+      for (const [name, blocks] of deployGroups) {
+        const key = name || 'default';
+        deploys[key] = Deploy.mergeDeployBlocks(blocks);
+      }
+    }
+
     // Generate tests if test blocks exist
     let testCode = '';
     if (testBlocks.length > 0) {
@@ -267,6 +347,7 @@ export class CodeGenerator {
         browser: browserCode,
         client: browserCode,  // deprecated alias for backward compat
         edge: edges['default'] || '',
+        deploy: Object.keys(deploys).length > 0 ? deploys : undefined,
         sourceMappings,
         _sourceFile: this.filename,
       };
@@ -287,6 +368,7 @@ export class CodeGenerator {
       browsers,  // { "admin": code, "dashboard": code, ... }
       clients: browsers,   // deprecated alias for backward compat
       edges,     // { "api": code, "assets": code, ... }
+      deploy: Object.keys(deploys).length > 0 ? deploys : undefined,
       multiBlock: true,
       sourceMappings,
       _sourceFile: this.filename,

package/src/codegen/deploy-codegen.js

@@ -0,0 +1,49 @@
+// Deploy-specific codegen for the Tova language
+// Produces a configuration manifest (plain JS object) from deploy block AST nodes.
+
+const DEFAULTS = {
+  instances: 1,
+  memory: '512mb',
+  branch: 'main',
+  health: '/healthz',
+  health_interval: 30,
+  health_timeout: 5,
+  restart_on_failure: true,
+  keep_releases: 5,
+};
+
+export class DeployCodegen {
+  static mergeDeployBlocks(blocks) {
+    const config = { ...DEFAULTS, env: {}, databases: [] };
+    for (const block of blocks) {
+      config.name = block.name;
+      for (const stmt of block.body) {
+        switch (stmt.type) {
+          case 'DeployConfigField': {
+            // Extract literal value from AST expression
+            const val = stmt.value;
+            config[stmt.key] = val.value !== undefined ? val.value : val;
+            break;
+          }
+          case 'DeployEnvBlock': {
+            for (const entry of stmt.entries) {
+              config.env[entry.key] = entry.value.value !== undefined ? entry.value.value : entry.value;
+            }
+            break;
+          }
+          case 'DeployDbBlock': {
+            const dbConfig = {};
+            if (stmt.config && typeof stmt.config === 'object') {
+              for (const [k, v] of Object.entries(stmt.config)) {
+                dbConfig[k] = v.value !== undefined ? v.value : v;
+              }
+            }
+            config.databases.push({ engine: stmt.engine, config: dbConfig });
+            break;
+          }
+        }
+      }
+    }
+    return config;
+  }
+}

package/src/codegen/server-codegen.js

@@ -1052,6 +1052,22 @@ export class ServerCodegen extends BaseCodegen {
     // ════════════════════════════════════════════════════════════
     // 8b. Security Headers — OWASP recommended
     // ════════════════════════════════════════════════════════════
+    // Always emit base security headers (even in fast mode)
+    lines.push('// ── Base Security Headers (always) ──');
+    lines.push('const __baseSecurityHeaders = Object.freeze({');
+    lines.push('  "X-Content-Type-Options": "nosniff",');
+    lines.push('  "X-Frame-Options": "DENY",');
+    lines.push('  "X-XSS-Protection": "0",');
+    lines.push('  "Referrer-Policy": "strict-origin-when-cross-origin",');
+    lines.push('});');
+    lines.push('function __applyBaseHeaders(res) {');
+    lines.push('  if (!res) return res;');
+    lines.push('  const h = new Headers(res.headers);');
+    lines.push('  for (const [k, v] of Object.entries(__baseSecurityHeaders)) h.set(k, v);');
+    lines.push('  return new Response(res.body, { status: res.status, statusText: res.statusText, headers: h });');
+    lines.push('}');
+    lines.push('');
+
     if (!isFastMode) {
       lines.push('// ── Security Headers ──');
       lines.push('const __securityHeaders = Object.freeze({');
@@ -2365,7 +2381,12 @@ export class ServerCodegen extends BaseCodegen {
           const rlWindow = rateLimitDec.args[1] ? this.genExpression(rateLimitDec.args[1]) : '60';
           lines.push(`  const __rlIp = __getClientIp(req);`);
           lines.push(`  const __rlRoute = __checkRateLimit(\`route:${path}:\${__rlIp}\`, ${rlMax}, ${rlWindow});`);
-          lines.push(`  if (__rlRoute.limited) return __errorResponse(429, "RATE_LIMITED", "Too Many Requests", null, { "Retry-After": String(__rlRoute.retryAfter) });`);
+          lines.push(`  if (__rlRoute.limited) {`);
+          if (securityFragments && securityFragments.auditCode) {
+            lines.push(`    __auditLog("rate_limit:exceeded", { method: req.method, path: __pathname }, { id: null });`);
+          }
+          lines.push(`    return __errorResponse(429, "RATE_LIMITED", "Too Many Requests", null, { "Retry-After": String(__rlRoute.retryAfter) });`);
+          lines.push(`  }`);
         }
 
         // Upload decorator — parse multipart body, validate file field
@@ -3133,8 +3154,8 @@ export class ServerCodegen extends BaseCodegen {
         }
       }
 
-      // Client HTML fallback
-      lines.push('  if (__pathname === "/" && typeof __clientHTML !== "undefined") {');
+      // Client HTML fallback — serve SPA shell for any non-API route so client router handles 404s
+      lines.push('  if (typeof __clientHTML !== "undefined") {');
       lines.push('    return new Response(__clientHTML, { status: 200, headers: { "Content-Type": "text/html" } });');
       lines.push('  }');
       lines.push('  return new Response("Not Found", { status: 404 });');
@@ -3217,6 +3238,9 @@ export class ServerCodegen extends BaseCodegen {
       lines.push('  const __clientIp = __getClientIp(req);');
       lines.push('  const __rl = __checkRateLimit(__clientIp, __rateLimitMax, __rateLimitWindow);');
       lines.push('  if (__rl.limited) {');
+      if (securityFragments && securityFragments.auditCode) {
+        lines.push('    __auditLog("rate_limit:exceeded", { method: req.method, path: __pathname, ip: __clientIp }, { id: null });');
+      }
       lines.push('    return __errorResponse(429, "RATE_LIMITED", "Too Many Requests", null, { ...__cors, "Retry-After": String(__rl.retryAfter) });');
       lines.push('  }');
     }
@@ -3266,6 +3290,10 @@ export class ServerCodegen extends BaseCodegen {
       lines.push('  // Security block: route protection');
       if (authConfig) {
         lines.push('  const __secUser = await __authenticate(req);');
+        if (securityFragments && securityFragments.auditCode) {
+          lines.push('  if (__secUser) __auditLog("auth:success", { method: req.method, path: __pathname }, __secUser);');
+          lines.push('  else if (req.headers.get("Authorization")) __auditLog("auth:failure", { method: req.method, path: __pathname, reason: "invalid_token" }, { id: null });');
+        }
       } else {
         lines.push('  const __secUser = null;');
       }
@@ -3273,17 +3301,31 @@ export class ServerCodegen extends BaseCodegen {
       lines.push('  if (!__protection.allowed) {');
       lines.push('    const __statusCode = __secUser ? 403 : 401;');
       lines.push('    const __errorCode = __secUser ? "FORBIDDEN" : "AUTH_REQUIRED";');
+      if (securityFragments && securityFragments.auditCode) {
+        lines.push('    __auditLog("auth:denied", { method: req.method, path: __pathname }, __secUser || { id: null });');
+      }
       lines.push('    return __errorResponse(__statusCode, __errorCode, __protection.reason, null, __cors);');
       lines.push('  }');
       lines.push('  if (__protection.rateLimit && __protection.rateLimit.max) {');
       lines.push('    const __protectIp = __getClientIp(req);');
       lines.push('    const __protectRl = __checkRateLimit("protect:" + __pathname + ":" + __protectIp, __protection.rateLimit.max, __protection.rateLimit.window || 60);');
       lines.push('    if (__protectRl.limited) {');
+      if (securityFragments && securityFragments.auditCode) {
+        lines.push('      __auditLog("rate_limit:exceeded", { method: req.method, path: __pathname, ip: __protectIp }, { id: null });');
+      }
       lines.push('      return __errorResponse(429, "RATE_LIMITED", "Too Many Requests", null, { ...__cors, "Retry-After": String(__protectRl.retryAfter) });');
       lines.push('    }');
       lines.push('  }');
     }
 
+    // Audit logging for auth (when no protection block but auth+audit configured)
+    if (!(securityFragments && securityFragments.protectCode) && authConfig && securityFragments && securityFragments.auditCode) {
+      lines.push('  // Audit: auth logging');
+      lines.push('  const __secUser = await __authenticate(req);');
+      lines.push('  if (__secUser) __auditLog("auth:success", { method: req.method, path: __pathname }, __secUser);');
+      lines.push('  else if (req.headers.get("Authorization")) __auditLog("auth:failure", { method: req.method, path: __pathname, reason: "invalid_token" }, { id: null });');
+    }
+
     // Idempotency key check
     lines.push('  const __idempotencyKey = req.headers.get("Idempotency-Key");');
     lines.push('  if (__idempotencyKey && req.method !== "GET" && req.method !== "HEAD" && req.method !== "OPTIONS") {');
@@ -3422,8 +3464,8 @@ export class ServerCodegen extends BaseCodegen {
     lines.push('    }');
     lines.push('  }');
 
-    // Serve client HTML at root
-    lines.push('  if (__pathname === "/" && typeof __clientHTML !== "undefined") {');
+    // Serve client HTML — SPA fallback for any non-API route so client router handles 404s
+    lines.push('  if (typeof __clientHTML !== "undefined") {');
     lines.push('    return new Response(__clientHTML, { status: 200, headers: { "Content-Type": "text/html", ...(__cors) } });');
     lines.push('  }');
     lines.push('  const __notFound = __errorResponse(404, "NOT_FOUND", "Not Found", null, __cors);');
@@ -3490,8 +3532,14 @@ export class ServerCodegen extends BaseCodegen {
       lines.push('  if (!res) return res;');
       lines.push('  return __compressResponse(req, res);');
       lines.push('};');
+    } else if (isFastMode) {
+      // Fast mode: wrap with base security headers
+      lines.push('const __secureFetch = async (req) => {');
+      lines.push('  const res = await __handleRequest(req);');
+      lines.push('  return __applyBaseHeaders(res);');
+      lines.push('};');
     }
-    const fetchHandler = (!isFastMode || compressionConfig) ? '__idempotentFetch' : '__handleRequest';
+    const fetchHandler = !isFastMode ? '__idempotentFetch' : (compressionConfig ? '__idempotentFetch' : '__secureFetch');
     lines.push(`const __server = Bun.serve({`);
     lines.push(`  port: __port,`);
     lines.push(`  maxRequestBodySize: __maxBodySize,`);

package/src/codegen/shared-codegen.js

@@ -10,6 +10,11 @@ export class SharedCodegen extends BaseCodegen {
   // Generate any needed helpers (called after all code is generated)
   generateHelpers() {
     const helpers = [];
+    // Runtime bridge for WASM-Tokio concurrent execution
+    if (this._needsRuntimeBridge) {
+      // Try multiple paths: relative to script, package require, absolute from process.cwd()
+      helpers.push(`let __tova_rt = null; try { const __p = require('path'); const __d = __p.dirname(typeof __filename !== 'undefined' ? __filename : process.argv[1] || ''); const __candidates = [__p.join(__d, '..', 'src', 'stdlib', 'runtime-bridge.js'), __p.join(process.cwd(), 'src', 'stdlib', 'runtime-bridge.js')]; for (const __c of __candidates) { try { __tova_rt = require(__c); break; } catch(_) {} } } catch(_) {}`);
+    }
     helpers.push(this.getStringProtoHelper());
     // Only include Result/Option if Ok/Err/Some/None are used
     if (this._needsResultOption) {

package/src/codegen/theme-codegen.js

@@ -0,0 +1,69 @@
+// Theme codegen: converts ThemeBlock AST to CSS custom properties
+
+const PX_SECTIONS = new Set(['spacing', 'radius']);
+const PX_FONT_PREFIXES = ['size.'];
+
+const CATEGORY_MAP = {
+  colors: 'color',
+  spacing: 'spacing',
+  radius: 'radius',
+  shadow: 'shadow',
+  font: 'font',
+  breakpoints: 'breakpoint',
+  transition: 'transition',
+};
+
+export class ThemeCodegen {
+  static mergeThemeBlocks(themeBlocks) {
+    const sections = new Map();
+    const darkOverrides = [];
+    for (const block of themeBlocks) {
+      for (const section of block.sections) {
+        if (!sections.has(section.name)) sections.set(section.name, []);
+        sections.get(section.name).push(...section.tokens);
+      }
+      darkOverrides.push(...block.darkOverrides);
+    }
+    return { sections, darkOverrides };
+  }
+
+  static generateCSS(themeConfig) {
+    const { sections, darkOverrides } = themeConfig;
+    const rootProps = [];
+    const darkProps = [];
+
+    for (const [sectionName, tokens] of sections) {
+      const prefix = CATEGORY_MAP[sectionName] || sectionName;
+      for (const token of tokens) {
+        const cssName = `--tova-${prefix}-${token.name.replace(/\./g, '-')}`;
+        const cssValue = ThemeCodegen._formatValue(sectionName, token.name, token.value);
+        rootProps.push(`  ${cssName}: ${cssValue};`);
+      }
+    }
+
+    for (const override of darkOverrides) {
+      const dotIdx = override.name.indexOf('.');
+      const sectionName = override.name.slice(0, dotIdx);
+      const tokenName = override.name.slice(dotIdx + 1);
+      const prefix = CATEGORY_MAP[sectionName] || sectionName;
+      const cssName = `--tova-${prefix}-${tokenName.replace(/\./g, '-')}`;
+      const cssValue = ThemeCodegen._formatValue(sectionName, tokenName, override.value);
+      darkProps.push(`    ${cssName}: ${cssValue};`);
+    }
+
+    let css = `:root {\n${rootProps.join('\n')}\n}`;
+    if (darkProps.length > 0) {
+      css += `\n@media (prefers-color-scheme: dark) {\n  :root {\n${darkProps.join('\n')}\n  }\n}`;
+    }
+    return css;
+  }
+
+  static _formatValue(sectionName, tokenName, value) {
+    if (typeof value === 'number') {
+      if (PX_SECTIONS.has(sectionName)) return value + 'px';
+      if (sectionName === 'font' && PX_FONT_PREFIXES.some(p => tokenName.startsWith(p))) return value + 'px';
+      return String(value);
+    }
+    return value;
+  }
+}

package/src/codegen/wasm-codegen.js

@@ -602,6 +602,12 @@ export function generateWasmGlue(funcNode, wasmBytes) {
   return `const ${name} = new WebAssembly.Instance(new WebAssembly.Module(new Uint8Array([${bytesStr}]))).exports.${name};`;
 }
 
+// Generate a module-level constant holding the raw WASM bytes for runtime use
+export function generateWasmBytesExport(funcName, wasmBytes) {
+  const bytesStr = Array.from(wasmBytes).join(',');
+  return `const __wasm_bytes_${funcName} = new Uint8Array([${bytesStr}]);`;
+}
+
 // Generate JS glue code for a multi-function WASM module
 export function generateMultiWasmGlue(funcNodes, wasmBytes) {
   const bytesStr = Array.from(wasmBytes).join(',');

package/src/config/edit-toml.js

@@ -28,13 +28,15 @@ export function addToSection(filePath, section, key, value) {
   const endIdx = findSectionEnd(lines, sectionIdx);
 
   // Check if key already exists in this section — update it
+  const bareKey = key.replace(/^"|"$/g, '');
   for (let i = sectionIdx + 1; i < endIdx; i++) {
     const line = lines[i].trim();
     if (line === '' || line.startsWith('#')) continue;
     const eqIdx = line.indexOf('=');
     if (eqIdx !== -1) {
       const existingKey = line.slice(0, eqIdx).trim();
-      if (existingKey === key) {
+      const existingBare = existingKey.replace(/^"|"$/g, '');
+      if (existingKey === key || existingBare === bareKey) {
         lines[i] = entry;
         writeFileSync(filePath, lines.join('\n'));
         return;
@@ -57,6 +59,7 @@ export function addToSection(filePath, section, key, value) {
 export function removeFromSection(filePath, section, key) {
   const content = readFileSync(filePath, 'utf-8');
   const lines = content.split('\n');
+  const bareKey = key.replace(/^"|"$/g, '');
 
   const sectionIdx = findSectionIndex(lines, section);
   if (sectionIdx === -1) return false;
@@ -69,7 +72,8 @@ export function removeFromSection(filePath, section, key) {
     const eqIdx = line.indexOf('=');
     if (eqIdx !== -1) {
       const existingKey = line.slice(0, eqIdx).trim();
-      if (existingKey === key) {
+      const existingBare = existingKey.replace(/^"|"$/g, '');
+      if (existingKey === key || existingBare === bareKey) {
         lines.splice(i, 1);
         writeFileSync(filePath, lines.join('\n'));
         return true;

package/src/config/git-resolver.js

@@ -0,0 +1,128 @@
+// Git resolver for the Tova package manager.
+// Handles git operations: parsing tag lists, sorting by semver,
+// picking the latest tag, and fetching modules from remote repositories.
+
+import { spawn } from 'child_process';
+import { join } from 'path';
+import { mkdirSync, renameSync, rmSync, existsSync } from 'fs';
+import { parseSemver, compareSemver } from './semver.js';
+import { moduleToGitUrl, parseModulePath } from './module-path.js';
+import { getModuleCachePath, getCacheDir } from './module-cache.js';
+
+/**
+ * Parse `git ls-remote --tags` output into an array of { version, sha } objects.
+ * Filters out non-semver tags and prefers dereferenced (^{}) SHAs for annotated tags.
+ */
+export function parseTagList(output) {
+  if (!output.trim()) return [];
+  const lines = output.trim().split('\n');
+  const tagMap = new Map();
+  for (const line of lines) {
+    const [sha, ref] = line.split('\t');
+    if (!ref || !ref.startsWith('refs/tags/')) continue;
+    const tagName = ref.replace('refs/tags/', '');
+    const isDeref = tagName.endsWith('^{}');
+    const cleanName = isDeref ? tagName.slice(0, -3) : tagName;
+    const versionStr = cleanName.startsWith('v') ? cleanName.slice(1) : cleanName;
+    try { parseSemver(versionStr); } catch { continue; }
+    if (isDeref || !tagMap.has(versionStr)) {
+      tagMap.set(versionStr, sha);
+    }
+  }
+  return Array.from(tagMap.entries()).map(([version, sha]) => ({ version, sha }));
+}
+
+/**
+ * Sort an array of { version, sha } tags by semver in ascending order.
+ * Returns a new array (does not mutate the input).
+ */
+export function sortTags(tags) {
+  return [...tags].sort((a, b) => compareSemver(a.version, b.version));
+}
+
+/**
+ * Pick the tag with the highest semver version.
+ * Returns null if the tags array is empty.
+ */
+export function pickLatestTag(tags) {
+  if (tags.length === 0) return null;
+  const sorted = sortTags(tags);
+  return sorted[sorted.length - 1];
+}
+
+/**
+ * List all semver tags from a remote git repository.
+ * Returns a promise resolving to an array of { version, sha } objects.
+ */
+export function listRemoteTags(modulePath) {
+  const gitUrl = moduleToGitUrl(modulePath);
+  return new Promise((resolve, reject) => {
+    const proc = spawn('git', ['ls-remote', '--tags', gitUrl], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', d => stdout += d);
+    proc.stderr.on('data', d => stderr += d);
+    proc.on('close', code => {
+      if (code !== 0) {
+        reject(new Error(`Failed to list tags for ${modulePath}: ${stderr.trim()}`));
+        return;
+      }
+      resolve(parseTagList(stdout));
+    });
+  });
+}
+
+/**
+ * Clone a specific version of a module into the local cache.
+ * Performs a shallow clone, removes .git directory, and moves to the cache path.
+ * Returns the destination path on success.
+ */
+export function fetchModule(modulePath, version, cacheDir) {
+  const gitUrl = moduleToGitUrl(modulePath);
+  const destPath = getModuleCachePath(modulePath, version, cacheDir);
+  const dir = getCacheDir(cacheDir);
+  const tmpPath = join(dir, '.tmp-' + Date.now());
+  return new Promise((resolve, reject) => {
+    const proc = spawn('git', [
+      'clone', '--depth', '1', '--branch', `v${version}`, gitUrl, tmpPath,
+    ], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stderr = '';
+    proc.stderr.on('data', d => stderr += d);
+    proc.on('close', code => {
+      if (code !== 0) {
+        if (existsSync(tmpPath)) rmSync(tmpPath, { recursive: true, force: true });
+        reject(new Error(`Failed to fetch ${modulePath}@v${version}: ${stderr.trim()}`));
+        return;
+      }
+      const dotGit = join(tmpPath, '.git');
+      if (existsSync(dotGit)) rmSync(dotGit, { recursive: true, force: true });
+      mkdirSync(join(destPath, '..'), { recursive: true });
+      renameSync(tmpPath, destPath);
+      resolve(destPath);
+    });
+  });
+}
+
+/**
+ * Get the commit SHA for a specific version tag from a remote repository.
+ * Prefers the dereferenced SHA for annotated tags.
+ * Returns null if the version tag is not found.
+ */
+export function getCommitSha(modulePath, version, cacheDir) {
+  const gitUrl = moduleToGitUrl(modulePath);
+  return new Promise((resolve, reject) => {
+    const proc = spawn('git', ['ls-remote', gitUrl, `refs/tags/v${version}^{}`, `refs/tags/v${version}`], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    proc.stdout.on('data', d => stdout += d);
+    proc.on('close', code => {
+      if (code !== 0) { reject(new Error('Failed to get SHA')); return; }
+      const tags = parseTagList(stdout);
+      const tag = tags.find(t => t.version === version);
+      resolve(tag ? tag.sha : null);
+    });
+  });
+}

package/src/config/lock-file.js

@@ -0,0 +1,57 @@
+// src/config/lock-file.js
+import { join } from 'path';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { parseTOML } from './toml.js';
+
+export function writeLockFile(cwd, resolvedModules, npmDeps) {
+  const lines = [];
+  lines.push('[lock]');
+  lines.push(`generated = "${new Date().toISOString()}"`);
+  lines.push('');
+
+  for (const [mod, info] of Object.entries(resolvedModules)) {
+    lines.push(`["${mod}"]`);
+    lines.push(`version = "${info.version}"`);
+    lines.push(`sha = "${info.sha}"`);
+    lines.push(`source = "${info.source}"`);
+    lines.push('');
+  }
+
+  if (npmDeps && Object.keys(npmDeps).length > 0) {
+    lines.push('[npm]');
+    for (const [name, version] of Object.entries(npmDeps)) {
+      lines.push(`${name} = "${version}"`);
+    }
+    lines.push('');
+  }
+
+  writeFileSync(join(cwd, 'tova.lock'), lines.join('\n'));
+}
+
+export function readLockFile(cwd) {
+  const lockPath = join(cwd, 'tova.lock');
+  if (!existsSync(lockPath)) return null;
+  const content = readFileSync(lockPath, 'utf-8');
+  const parsed = parseTOML(content);
+
+  const modules = {};
+  const npm = {};
+
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === 'lock') continue;
+    if (key === 'npm') {
+      Object.assign(npm, value);
+      continue;
+    }
+    // Module entries are quoted keys like "github.com/alice/http"
+    if (typeof value === 'object' && value.version) {
+      modules[key] = {
+        version: value.version,
+        sha: value.sha,
+        source: value.source,
+      };
+    }
+  }
+
+  return { modules, npm, generated: parsed.lock?.generated };
+}