tova 0.5.1 → 0.8.2

package/src/codegen/server-codegen.js

@@ -136,6 +136,69 @@ export class ServerCodegen extends BaseCodegen {
     return checks;
   }
 
+  // Generate validation checks from type-level validators (Phase 3)
+  // Returns an array of JS code lines for inline validation
+  _genTypeValidatorCode(paramName, typeInfo, indent = '  ') {
+    const checks = [];
+    for (const field of typeInfo.fields) {
+      if (!field.validators || field.validators.length === 0) continue;
+      const accessor = `${paramName}.${field.name}`;
+      for (const v of field.validators) {
+        // The last argument is typically the error message
+        const msgArg = v.args.length > 0 ? this.genExpression(v.args[v.args.length - 1]) : null;
+        switch (v.name) {
+          case 'required': {
+            const msg = msgArg || `"${field.name} is required"`;
+            checks.push(`${indent}if (${accessor} === undefined || ${accessor} === null || ${accessor} === "") __validationErrors.push({ field: "${field.name}", message: ${msg} });`);
+            break;
+          }
+          case 'email': {
+            const msg = msgArg || `"${field.name} must be a valid email"`;
+            checks.push(`${indent}if (${accessor} && !/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(${accessor})) __validationErrors.push({ field: "${field.name}", message: ${msg} });`);
+            break;
+          }
+          case 'min': {
+            const minVal = this.genExpression(v.args[0]);
+            const minMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} must be at least ${v.args[0].value || v.args[0].name}"`;
+            checks.push(`${indent}if (typeof ${accessor} === "number" && ${accessor} < ${minVal}) __validationErrors.push({ field: "${field.name}", message: ${minMsg} });`);
+            break;
+          }
+          case 'max': {
+            const maxVal = this.genExpression(v.args[0]);
+            const maxMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} must be at most ${v.args[0].value || v.args[0].name}"`;
+            checks.push(`${indent}if (typeof ${accessor} === "number" && ${accessor} > ${maxVal}) __validationErrors.push({ field: "${field.name}", message: ${maxMsg} });`);
+            break;
+          }
+          case 'minLength': {
+            const minLen = this.genExpression(v.args[0]);
+            const minLenMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} is too short"`;
+            checks.push(`${indent}if (typeof ${accessor} === "string" && ${accessor}.length < ${minLen}) __validationErrors.push({ field: "${field.name}", message: ${minLenMsg} });`);
+            break;
+          }
+          case 'maxLength': {
+            const maxLen = this.genExpression(v.args[0]);
+            const maxLenMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} is too long"`;
+            checks.push(`${indent}if (typeof ${accessor} === "string" && ${accessor}.length > ${maxLen}) __validationErrors.push({ field: "${field.name}", message: ${maxLenMsg} });`);
+            break;
+          }
+          case 'pattern': {
+            const regex = this.genExpression(v.args[0]);
+            const patMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} has invalid format"`;
+            checks.push(`${indent}if (typeof ${accessor} === "string" && !${regex}.test(${accessor})) __validationErrors.push({ field: "${field.name}", message: ${patMsg} });`);
+            break;
+          }
+          case 'oneOf': {
+            const vals = this.genExpression(v.args[0]);
+            const oneOfMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} has invalid value"`;
+            checks.push(`${indent}if (!${vals}.includes(${accessor})) __validationErrors.push({ field: "${field.name}", message: ${oneOfMsg} });`);
+            break;
+          }
+        }
+      }
+    }
+    return checks;
+  }
+
   // Emit handler call, optionally wrapped in Promise.race for timeout
   _emitHandlerCall(lines, callExpr, timeoutMs) {
     if (timeoutMs) {
@@ -304,14 +367,19 @@ export class ServerCodegen extends BaseCodegen {
     }
 
     // Collect type declarations from shared blocks for model/ORM generation
-    const sharedTypes = new Map(); // typeName -> { fields: [{ name, type }] }
+    const sharedTypes = new Map(); // typeName -> { fields: [{ name, type, validators? }] }
     const _collectTypes = (stmts) => {
       for (const stmt of stmts) {
         if (stmt.type === 'TypeDeclaration' && stmt.variants) {
           const fields = [];
           for (const v of stmt.variants) {
             if (v.type === 'TypeField' && v.typeAnnotation) {
-              fields.push({ name: v.name, type: v.typeAnnotation.name || (v.typeAnnotation.type === 'ArrayTypeAnnotation' ? 'Array' : 'Any') });
+              const fieldInfo = { name: v.name, type: v.typeAnnotation.name || (v.typeAnnotation.type === 'ArrayTypeAnnotation' ? 'Array' : 'Any') };
+              // Capture type-level validators (Phase 3) if present
+              if (v.validators && v.validators.length > 0) {
+                fieldInfo.validators = v.validators;
+              }
+              fields.push(fieldInfo);
             }
           }
           if (fields.length > 0) {
@@ -2166,9 +2234,19 @@ export class ServerCodegen extends BaseCodegen {
             lines.push(`  const ${paramNames[pi]} = body.__args ? body.__args[${pi}] : body.${paramNames[pi]};`);
           }
           const validationChecks = this._genValidationCode(fn.params);
-          if (validationChecks.length > 0) {
+          // Phase 3: Also generate type-level validator checks for typed parameters
+          const typeValidatorChecks = [];
+          for (const p of fn.params) {
+            if (p.typeAnnotation && p.typeAnnotation.type === 'TypeAnnotation' && sharedTypes.has(p.typeAnnotation.name)) {
+              const typeInfo = sharedTypes.get(p.typeAnnotation.name);
+              const tvChecks = this._genTypeValidatorCode(p.name, typeInfo);
+              typeValidatorChecks.push(...tvChecks);
+            }
+          }
+          const allChecks = [...validationChecks, ...typeValidatorChecks];
+          if (allChecks.length > 0) {
             lines.push(`  const __validationErrors = [];`);
-            for (const check of validationChecks) {
+            for (const check of allChecks) {
               lines.push(check);
             }
             lines.push(`  if (__validationErrors.length > 0) return __errorResponse(400, "VALIDATION_FAILED", "Validation failed", __validationErrors);`);
@@ -2702,6 +2780,9 @@ export class ServerCodegen extends BaseCodegen {
           lines.push('  responses: { "200": { description: "Success" } },');
         }
 
+        // Close the OpenAPI path entry object
+        lines.push('};');
+
         // Auto-generate error responses based on route context
         const routeHasAuth = (route.decorators || []).some(d => d.name === 'auth');
         const routeHasRateLimit = (route.decorators || []).some(d => d.name === 'rate_limit');
@@ -2709,7 +2790,8 @@ export class ServerCodegen extends BaseCodegen {
         const routeHasTimeout = (route.decorators || []).some(d => d.name === 'timeout');
         const errRef = '{ "$ref": "#/components/schemas/ErrorResponse" }';
 
-        // Merge error responses into existing 200 response
+        // Merge error responses into existing 200 response (wrapped in block scope to avoid __r redeclaration)
+        lines.push('{');
         lines.push(`const __r = __openApiSpec.paths[${JSON.stringify(path)}][${JSON.stringify(method)}].responses;`);
         if (routeHasValidation || ['post', 'put', 'patch'].includes(method)) {
           lines.push(`__r["400"] = { description: "Validation Failed", content: { "application/json": { schema: ${errRef} } } };`);
@@ -2733,8 +2815,7 @@ export class ServerCodegen extends BaseCodegen {
           lines.push(`__r["504"] = { description: "Gateway Timeout", content: { "application/json": { schema: ${errRef} } } };`);
         }
         lines.push(`__r["500"] = { description: "Internal Server Error", content: { "application/json": { schema: ${errRef} } } };`);
-
-        lines.push('};');
+        lines.push('}');
       }
 
       // Add the /docs endpoint

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/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 };
+}

package/src/config/module-cache.js

@@ -0,0 +1,58 @@
+// Global cache manager for the Tova package manager.
+// Manages the ~/.tova/pkg/ directory where downloaded packages are stored.
+// Provides path resolution, version lookup, and cleanup utilities.
+
+import { join } from 'path';
+import { existsSync, readdirSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { compareSemver } from './semver.js';
+import { parseModulePath } from './module-path.js';
+
+const DEFAULT_CACHE = join(homedir(), '.tova', 'pkg');
+
+export function getCacheDir(override) {
+  return override || process.env.TOVA_CACHE_DIR || DEFAULT_CACHE;
+}
+
+export function getModuleCachePath(modulePath, version, cacheDir) {
+  const dir = getCacheDir(cacheDir);
+  const parsed = typeof modulePath === 'string' ? parseModulePath(modulePath) : modulePath;
+  return join(dir, parsed.host, parsed.owner, parsed.repo, `v${version}`);
+}
+
+export function isVersionCached(modulePath, version, cacheDir) {
+  const p = getModuleCachePath(modulePath, version, cacheDir);
+  return existsSync(p) && existsSync(join(p, 'tova.toml'));
+}
+
+export function listCachedVersions(modulePath, cacheDir) {
+  const dir = getCacheDir(cacheDir);
+  const parsed = typeof modulePath === 'string' ? parseModulePath(modulePath) : modulePath;
+  const moduleDir = join(dir, parsed.host, parsed.owner, parsed.repo);
+  if (!existsSync(moduleDir)) return [];
+  const entries = readdirSync(moduleDir).filter(e => e.startsWith('v'));
+  const versions = entries.map(e => e.slice(1));
+  return versions.sort((a, b) => compareSemver(a, b));
+}
+
+export function getCompileCachePath(modulePath, version, cacheDir) {
+  const dir = getCacheDir(cacheDir);
+  return join(dir, '.cache', modulePath, `v${version}`);
+}
+
+export function cleanUnusedVersions(modulePath, keepVersions, cacheDir) {
+  const dir = getCacheDir(cacheDir);
+  const parsed = typeof modulePath === 'string' ? parseModulePath(modulePath) : modulePath;
+  const moduleDir = join(dir, parsed.host, parsed.owner, parsed.repo);
+  if (!existsSync(moduleDir)) return [];
+  const entries = readdirSync(moduleDir).filter(e => e.startsWith('v'));
+  const keepSet = new Set(keepVersions.map(v => `v${v}`));
+  const removed = [];
+  for (const entry of entries) {
+    if (!keepSet.has(entry)) {
+      rmSync(join(moduleDir, entry), { recursive: true, force: true });
+      removed.push(entry.slice(1));
+    }
+  }
+  return removed.sort((a, b) => compareSemver(a, b));
+}

package/src/config/module-entry.js

@@ -0,0 +1,37 @@
+// src/config/module-entry.js
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+const ENTRY_CANDIDATES = [
+  'src/lib.tova',
+  'lib.tova',
+  'index.tova',
+  'src/index.tova',
+  'src/main.tova',
+  'main.tova',
+];
+
+/**
+ * Finds the entry point .tova file for a module.
+ * Checks: explicit entry → src/lib.tova → lib.tova → index.tova
+ */
+export function findEntryPoint(moduleDir, explicitEntry, subpath) {
+  const base = subpath ? join(moduleDir, subpath) : moduleDir;
+
+  if (explicitEntry) {
+    const p = join(base, explicitEntry);
+    if (existsSync(p)) return p;
+    throw new Error(`Explicit entry point not found: ${explicitEntry} in ${base}`);
+  }
+
+  for (const candidate of ENTRY_CANDIDATES) {
+    const p = join(base, candidate);
+    if (existsSync(p)) return p;
+  }
+
+  throw new Error(
+    `No entry point found in ${base}\n` +
+    `  Looked for: ${ENTRY_CANDIDATES.join(', ')}\n` +
+    `  Tip: Add an \`entry\` field to the package's tova.toml.`
+  );
+}

package/src/config/module-path.js

@@ -0,0 +1,31 @@
+// Module path utilities for Tova package management.
+// Determines whether an import is a Tova module (vs npm/relative),
+// parses module paths into components, and converts them to git URLs.
+
+export function isTovModule(source) {
+  if (!source || source.startsWith('.') || source.startsWith('/') || source.startsWith('@') || source.includes(':')) {
+    return false;
+  }
+  const firstSegment = source.split('/')[0];
+  return firstSegment.includes('.');
+}
+
+export function parseModulePath(source) {
+  if (!isTovModule(source)) {
+    throw new Error(`Invalid Tova module path: "${source}"`);
+  }
+  const parts = source.split('/');
+  if (parts.length < 3) {
+    throw new Error(`Invalid Tova module path: "${source}" — expected at least host/owner/repo`);
+  }
+  const host = parts[0];
+  const owner = parts[1];
+  const repo = parts[2];
+  const subpath = parts.length > 3 ? parts.slice(3).join('/') : null;
+  return { host, owner, repo, subpath, full: `${host}/${owner}/${repo}` };
+}
+
+export function moduleToGitUrl(modulePath) {
+  const parsed = typeof modulePath === 'string' ? parseModulePath(modulePath) : modulePath;
+  return `https://${parsed.full}.git`;
+}

package/src/config/pkg-errors.js

@@ -0,0 +1,62 @@
+// src/config/pkg-errors.js
+
+export function formatVersionConflict(modulePath, sources) {
+  const lines = [`error: version conflict for ${modulePath}`, ''];
+  for (const s of sources) {
+    lines.push(`  ${s.source} requires ${s.constraint}`);
+  }
+  lines.push('');
+  lines.push('  These constraints cannot be satisfied simultaneously.');
+  lines.push('  Tip: Check if either dependency has a newer version that resolves this.');
+  return lines.join('\n');
+}
+
+export function formatFetchError(modulePath, detail, cachedVersions = []) {
+  const lines = [`error: failed to fetch ${modulePath}`, '', `  ${detail}`];
+  if (cachedVersions.length > 0) {
+    lines.push('');
+    lines.push(`  Cached versions available: ${cachedVersions.join(', ')}`);
+    lines.push('  Tip: Run with --offline to use cached versions only.');
+  }
+  return lines.join('\n');
+}
+
+export function formatMissingEntry(modulePath, version) {
+  return [
+    `error: no entry point found for ${modulePath}@v${version}`,
+    '',
+    '  Looked for: src/lib.tova, lib.tova, index.tova',
+    "  Tip: The package may need an `entry` field in its tova.toml.",
+  ].join('\n');
+}
+
+export function formatAuthError(modulePath) {
+  return [
+    `error: authentication failed for ${modulePath}`,
+    '',
+    '  git clone returned: Permission denied (publickey)',
+    '  Tip: Ensure your SSH key or git credentials have access to this repo.',
+  ].join('\n');
+}
+
+export function formatCircularDep(chain) {
+  return [
+    'error: circular dependency detected',
+    '',
+    `  ${chain.join(' \u2192 ')}`,
+    '',
+    '  Tova does not allow circular module dependencies.',
+  ].join('\n');
+}
+
+export function formatIntegrityError(modulePath, version, expectedSha, actualSha) {
+  return [
+    `error: integrity check failed for ${modulePath}@v${version}`,
+    '',
+    `  Expected SHA: ${expectedSha}`,
+    `  Got SHA:      ${actualSha}`,
+    '',
+    '  The git tag may have been force-pushed. This could indicate tampering.',
+    `  Run \`tova update ${modulePath}\` to re-resolve.`,
+  ].join('\n');
+}

package/src/config/resolve.js

@@ -73,6 +73,23 @@ function normalizeConfig(parsed, source) {
     }
   }
 
+  // [package] section: marks this as a publishable package
+  if (parsed.package) {
+    config.package = {
+      name: parsed.package.name || '',
+      version: parsed.package.version || '0.1.0',
+      description: parsed.package.description || '',
+      license: parsed.package.license || '',
+      keywords: parsed.package.keywords || [],
+      homepage: parsed.package.homepage || '',
+      exports: parsed.package.exports || null,
+      entry: parsed.package.entry || null,
+    };
+    config.isPackage = true;
+  } else {
+    config.isPackage = false;
+  }
+
   return config;
 }