uniweb 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -31,9 +31,9 @@
     "node": ">=20.19"
   },
   "dependencies": {
+    "handlebars": "^4.7.8",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/templates": "0.1.6",
-    "@uniweb/build": "0.1.0"
+    "@uniweb/build": "0.1.5"
   }
 }

package/src/commands/docs.js

@@ -0,0 +1,143 @@
+/**
+ * Docs Command
+ *
+ * Generates markdown documentation from foundation schema.
+ *
+ * Usage:
+ *   uniweb docs                    # Generate docs for current directory
+ *   uniweb docs --output README.md # Custom output filename
+ *   uniweb docs --from-source      # Build schema from source (no build required)
+ */
+
+import { existsSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { generateDocs } from '@uniweb/build'
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+}
+
+function log(message) {
+  console.log(message)
+}
+
+function success(message) {
+  console.log(`${colors.green}✓${colors.reset} ${message}`)
+}
+
+function error(message) {
+  console.error(`${colors.red}✗${colors.reset} ${message}`)
+}
+
+function info(message) {
+  console.log(`${colors.cyan}→${colors.reset} ${message}`)
+}
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(args) {
+  const options = {
+    output: 'COMPONENTS.md',
+    fromSource: false,
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--output' || arg === '-o') {
+      options.output = args[++i]
+    } else if (arg === '--from-source' || arg === '-s') {
+      options.fromSource = true
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true
+    }
+  }
+
+  return options
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  log(`
+${colors.bright}uniweb docs${colors.reset} - Generate component documentation
+
+${colors.dim}Usage:${colors.reset}
+  uniweb docs                         Generate COMPONENTS.md from schema.json
+  uniweb docs --output DOCS.md        Custom output filename
+  uniweb docs --from-source           Build schema from source (no build required)
+
+${colors.dim}Options:${colors.reset}
+  -o, --output <file>    Output filename (default: COMPONENTS.md)
+  -s, --from-source      Read meta.js files directly instead of schema.json
+  -h, --help             Show this help message
+
+${colors.dim}Notes:${colors.reset}
+  By default, docs are generated from dist/schema.json (requires build).
+  Use --from-source to generate without building first.
+`)
+}
+
+/**
+ * Detect if current directory is a foundation
+ */
+function isFoundation(dir) {
+  const srcDir = join(dir, 'src')
+  const componentsDir = join(srcDir, 'components')
+  return existsSync(componentsDir)
+}
+
+/**
+ * Main docs command
+ */
+export async function docs(args) {
+  const options = parseArgs(args)
+
+  if (options.help) {
+    showHelp()
+    return
+  }
+
+  const projectDir = resolve(process.cwd())
+
+  // Verify this is a foundation
+  if (!isFoundation(projectDir)) {
+    error('This directory does not appear to be a foundation.')
+    log(`${colors.dim}Foundations have a src/components/ directory with component folders.${colors.reset}`)
+    process.exit(1)
+  }
+
+  // Check if schema.json exists (if not using --from-source)
+  const schemaPath = join(projectDir, 'dist', 'schema.json')
+  if (!options.fromSource && !existsSync(schemaPath)) {
+    log(`${colors.yellow}⚠${colors.reset} No dist/schema.json found.`)
+    log(`${colors.dim}Run 'uniweb build' first, or use '--from-source' to read meta.js files directly.${colors.reset}`)
+    log('')
+    info('Falling back to --from-source mode')
+    options.fromSource = true
+  }
+
+  try {
+    info('Generating documentation...')
+
+    const result = await generateDocs(projectDir, {
+      output: options.output,
+      fromSource: options.fromSource,
+    })
+
+    success(`Generated ${result.outputPath}`)
+    log(`${colors.dim}Documented ${result.componentCount} components${colors.reset}`)
+  } catch (err) {
+    error(`Failed to generate docs: ${err.message}`)
+    process.exit(1)
+  }
+}

package/src/index.js

@@ -3,14 +3,13 @@
 /**
  * Uniweb CLI
  *
- * Scaffolds new Uniweb sites and foundations, and builds projects.
+ * Scaffolds new Uniweb sites and foundations, builds projects, and generates docs.
  *
  * Usage:
  *   npx uniweb create [project-name]
- *   npx uniweb create --template single      # site/ + foundation/ (default)
- *   npx uniweb create --template multi       # sites/* + foundations/*
+ *   npx uniweb create --template marketing
  *   npx uniweb build
- *   npx uniweb build --target foundation
+ *   npx uniweb docs                          # Generate COMPONENTS.md from schema
  */
 
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'
@@ -18,6 +17,8 @@ import { resolve, join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import prompts from 'prompts'
 import { build } from './commands/build.js'
+import { docs } from './commands/docs.js'
+import { getVersionsForTemplates, getVersion } from './versions.js'
 import {
   resolveTemplate,
   applyExternalTemplate,
@@ -83,6 +84,12 @@ async function main() {
     return
   }
 
+  // Handle docs command
+  if (command === 'docs') {
+    await docs(args.slice(1))
+    return
+  }
+
   // Handle create command
   if (command !== 'create') {
     error(`Unknown command: ${command}`)
@@ -109,6 +116,20 @@ async function main() {
     }
   }
 
+  // Check for --variant flag
+  let variant = null
+  const variantIndex = args.indexOf('--variant')
+  if (variantIndex !== -1 && args[variantIndex + 1]) {
+    variant = args[variantIndex + 1]
+  }
+
+  // Check for --name flag (used for project display name)
+  let displayName = null
+  const nameIndex = args.indexOf('--name')
+  if (nameIndex !== -1 && args[nameIndex + 1]) {
+    displayName = args[nameIndex + 1]
+  }
+
   // Interactive prompts
   const response = await prompts([
     {
@@ -190,7 +211,11 @@ async function main() {
 
       log(`\nCreating project from ${resolved.name || resolved.package || `${resolved.owner}/${resolved.repo}`}...`)
 
-      await applyExternalTemplate(resolved, projectDir, { projectName }, {
+      await applyExternalTemplate(resolved, projectDir, {
+        projectName: displayName || projectName,
+        versions: getVersionsForTemplates(),
+      }, {
+        variant,
         onProgress: (msg) => log(`  ${colors.dim}${msg}${colors.reset}`),
         onWarning: (msg) => log(`  ${colors.yellow}Warning: ${msg}${colors.reset}`),
       })
@@ -220,9 +245,12 @@ ${colors.bright}Usage:${colors.reset}
 ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
   build              Build the current project
+  docs               Generate component documentation
 
 ${colors.bright}Create Options:${colors.reset}
   --template <type>  Project template
+  --variant <name>   Template variant (e.g., tailwind3 for legacy)
+  --name <name>      Project display name
 
 ${colors.bright}Build Options:${colors.reset}
   --target <type>    Build target (foundation, site) - auto-detected if not specified
@@ -230,6 +258,10 @@ ${colors.bright}Build Options:${colors.reset}
   --foundation-dir   Path to foundation directory (for prerendering)
   --platform <name>  Deployment platform (e.g., vercel) for platform-specific output
 
+${colors.bright}Docs Options:${colors.reset}
+  --output <file>    Output filename (default: COMPONENTS.md)
+  --from-source      Read meta.js files directly instead of schema.json
+
 ${colors.bright}Template Types:${colors.reset}
   single                        One site + one foundation (default)
   multi                         Multiple sites and foundations
@@ -242,10 +274,12 @@ ${colors.bright}Examples:${colors.reset}
   npx uniweb create my-project
   npx uniweb create my-project --template single
   npx uniweb create my-project --template marketing
+  npx uniweb create my-project --template marketing --variant tailwind3
   npx uniweb create my-project --template github:myorg/template
   npx uniweb build
   npx uniweb build --target foundation
   npx uniweb build --prerender                         # Build site + pre-render to static HTML
+  cd foundation && npx uniweb docs                     # Generate COMPONENTS.md
 `)
 }
 
@@ -600,11 +634,11 @@ async function createSite(projectDir, projectName, isWorkspace = false) {
       preview: 'vite preview',
     },
     dependencies: {
-      '@uniweb/runtime': '^0.1.0',
+      '@uniweb/runtime': getVersion('@uniweb/runtime'),
       ...(isWorkspace ? {} : { 'foundation-example': '^0.1.0' }),
     },
     devDependencies: {
-      '@uniweb/build': '^0.1.3',
+      '@uniweb/build': getVersion('@uniweb/build'),
       '@vitejs/plugin-react': '^5.0.0',
       autoprefixer: '^10.4.18',
       'js-yaml': '^4.1.0',
@@ -904,7 +938,7 @@ async function createFoundation(projectDir, projectName, isWorkspace = false) {
       react: '^18.2.0',
       'react-dom': '^18.2.0',
       tailwindcss: '^3.4.1',
-      uniweb: '^0.2.0',
+      uniweb: getVersion('uniweb'),
       vite: '^7.0.0',
       'vite-plugin-svgr': '^4.2.0',
     },

package/src/templates/fetchers/release.js

@@ -0,0 +1,240 @@
+/**
+ * GitHub Release fetcher - downloads official templates from GitHub releases
+ */
+
+import { pipeline } from 'node:stream/promises'
+import { createGunzip } from 'node:zlib'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import * as tar from 'tar'
+
+// GitHub repository for official templates
+const TEMPLATES_REPO = 'uniweb/templates'
+const GITHUB_API = 'https://api.github.com'
+
+// Cache for manifest (avoid re-fetching in same session)
+let manifestCache = null
+
+/**
+ * Fetch the manifest.json from the latest release
+ *
+ * @param {Object} options - Fetch options
+ * @param {string} options.version - Specific version tag (default: latest)
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} { version, templates, downloadUrl }
+ */
+export async function fetchManifest(options = {}) {
+  const { version, onProgress } = options
+
+  // Return cached manifest if available and no specific version requested
+  if (manifestCache && !version) {
+    return manifestCache
+  }
+
+  onProgress?.('Fetching template manifest...')
+
+  // Get release info
+  const releaseUrl = version
+    ? `${GITHUB_API}/repos/${TEMPLATES_REPO}/releases/tags/${version}`
+    : `${GITHUB_API}/repos/${TEMPLATES_REPO}/releases/latest`
+
+  const releaseResponse = await fetchWithRetry(releaseUrl, {
+    headers: getGitHubHeaders(),
+  })
+
+  if (!releaseResponse.ok) {
+    if (releaseResponse.status === 404) {
+      throw new Error(
+        version
+          ? `Release ${version} not found for ${TEMPLATES_REPO}`
+          : `No releases found for ${TEMPLATES_REPO}`
+      )
+    }
+    await handleGitHubError(releaseResponse)
+  }
+
+  const release = await releaseResponse.json()
+
+  // Find manifest.json asset
+  const manifestAsset = release.assets?.find(a => a.name === 'manifest.json')
+  if (!manifestAsset) {
+    throw new Error(
+      `Release ${release.tag_name} does not contain manifest.json. ` +
+      `This may be an older release format.`
+    )
+  }
+
+  // Download manifest
+  const manifestResponse = await fetchWithRetry(manifestAsset.browser_download_url, {
+    headers: getGitHubHeaders(),
+  })
+
+  if (!manifestResponse.ok) {
+    throw new Error(`Failed to download manifest: ${manifestResponse.status}`)
+  }
+
+  const manifest = await manifestResponse.json()
+
+  // Build result with download URL base
+  const result = {
+    version: release.tag_name,
+    templates: manifest.templates || {},
+    // Base URL for downloading template tarballs
+    downloadUrlBase: `https://github.com/${TEMPLATES_REPO}/releases/download/${release.tag_name}`,
+  }
+
+  // Cache if this was a "latest" fetch
+  if (!version) {
+    manifestCache = result
+  }
+
+  return result
+}
+
+/**
+ * Fetch a specific template from GitHub releases
+ *
+ * @param {string} name - Template name (e.g., 'marketing')
+ * @param {Object} options - Fetch options
+ * @param {string} options.version - Specific version tag (default: latest)
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} { tempDir, version, metadata }
+ */
+export async function fetchOfficialTemplate(name, options = {}) {
+  const { version, onProgress } = options
+
+  // Get manifest first
+  const manifest = await fetchManifest({ version, onProgress })
+
+  // Check if template exists
+  const templateInfo = manifest.templates[name]
+  if (!templateInfo) {
+    const available = Object.keys(manifest.templates).join(', ')
+    throw new Error(
+      `Template "${name}" not found in release ${manifest.version}.\n` +
+      `Available templates: ${available || 'none'}`
+    )
+  }
+
+  onProgress?.(`Downloading ${name} template (${manifest.version})...`)
+
+  // Download template tarball
+  const tarballUrl = `${manifest.downloadUrlBase}/${name}.tar.gz`
+  const tarballResponse = await fetchWithRetry(tarballUrl, {
+    headers: getGitHubHeaders(),
+  })
+
+  if (!tarballResponse.ok) {
+    if (tarballResponse.status === 404) {
+      throw new Error(
+        `Template tarball not found: ${name}.tar.gz\n` +
+        `The release may be incomplete or corrupted.`
+      )
+    }
+    throw new Error(`Failed to download template: ${tarballResponse.status}`)
+  }
+
+  // Extract to temp directory
+  const tempDir = await mkdtemp(join(tmpdir(), 'uniweb-template-'))
+
+  try {
+    onProgress?.('Extracting template...')
+
+    await pipeline(
+      tarballResponse.body,
+      createGunzip(),
+      tar.extract({ cwd: tempDir, strip: 0 })
+    )
+
+    // Tarball contains template in a subdirectory named after the template
+    // e.g., marketing.tar.gz extracts to marketing/template.json
+    return {
+      tempDir: join(tempDir, name),
+      baseTempDir: tempDir, // For cleanup
+      version: manifest.version,
+      metadata: templateInfo,
+    }
+  } catch (err) {
+    // Clean up on error
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    throw err
+  }
+}
+
+/**
+ * List available templates from the latest release
+ *
+ * @param {Object} options - Fetch options
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Array>} List of template metadata
+ */
+export async function listOfficialTemplates(options = {}) {
+  try {
+    const manifest = await fetchManifest(options)
+    return Object.entries(manifest.templates).map(([id, info]) => ({
+      id,
+      ...info,
+    }))
+  } catch {
+    // Return empty list if can't fetch
+    return []
+  }
+}
+
+/**
+ * Clear the manifest cache
+ */
+export function clearManifestCache() {
+  manifestCache = null
+}
+
+/**
+ * Get GitHub API headers
+ */
+function getGitHubHeaders() {
+  return {
+    'Accept': 'application/vnd.github+json',
+    'User-Agent': 'uniweb-cli',
+    // Support private repos or higher rate limits if GITHUB_TOKEN is set
+    ...(process.env.GITHUB_TOKEN && {
+      'Authorization': `Bearer ${process.env.GITHUB_TOKEN}`
+    }),
+  }
+}
+
+/**
+ * Handle GitHub API errors
+ */
+async function handleGitHubError(response) {
+  if (response.status === 403) {
+    const remaining = response.headers.get('x-ratelimit-remaining')
+    if (remaining === '0') {
+      throw new Error(
+        'GitHub API rate limit exceeded.\n' +
+        'Set GITHUB_TOKEN environment variable for higher limits.'
+      )
+    }
+  }
+  throw new Error(`GitHub API error: ${response.status}`)
+}
+
+/**
+ * Fetch with retry and timeout
+ */
+async function fetchWithRetry(url, options = {}, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, {
+        ...options,
+        redirect: 'follow',
+        signal: AbortSignal.timeout(60000), // 60s timeout
+      })
+      return response
+    } catch (err) {
+      if (attempt === maxRetries) throw err
+      const delay = Math.min(1000 * Math.pow(2, attempt), 10000)
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+}

package/src/templates/index.js

@@ -3,21 +3,19 @@
  */
 
 import { rm } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
 
 import { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES } from './resolver.js'
 import { fetchNpmTemplate } from './fetchers/npm.js'
 import { fetchGitHubTemplate } from './fetchers/github.js'
-
-// Try to import from @uniweb/templates if available
-let templatesPackage = null
-try {
-  templatesPackage = await import('@uniweb/templates')
-} catch {
-  // @uniweb/templates not installed - official templates won't be available locally
-}
+import { fetchOfficialTemplate, listOfficialTemplates } from './fetchers/release.js'
+import { validateTemplate } from './validator.js'
+import {
+  copyTemplateDirectory,
+  registerVersions,
+  getMissingVersions,
+  clearMissingVersions
+} from './processor.js'
 
 /**
  * Resolve a template identifier and return the template path
@@ -55,36 +53,24 @@ export async function resolveTemplate(identifier, options = {}) {
 }
 
 /**
- * Resolve an official template from @uniweb/templates
+ * Resolve an official template from GitHub releases
  */
 async function resolveOfficialTemplate(name, options = {}) {
   const { onProgress } = options
 
-  if (!templatesPackage) {
-    throw new Error(
-      `Official template "${name}" requires @uniweb/templates package.\n` +
-      `Install it with: npm install @uniweb/templates`
-    )
-  }
+  const { tempDir, baseTempDir, version } = await fetchOfficialTemplate(name, { onProgress })
 
-  if (!templatesPackage.hasTemplate(name)) {
-    const available = await templatesPackage.listBuiltinTemplates()
-    const names = available.map(t => t.id).join(', ')
-    throw new Error(
-      `Official template "${name}" not found.\n` +
-      `Available templates: ${names || 'none'}`
-    )
-  }
-
-  const templatePath = templatesPackage.getTemplatePath(name)
-
-  onProgress?.(`Using official template: ${name}`)
+  onProgress?.(`Using official template: ${name} (${version})`)
 
   return {
     type: 'official',
     name,
-    path: templatePath,
-    cleanup: async () => {}, // Nothing to clean up
+    version,
+    path: tempDir,
+    cleanup: async () => {
+      // Clean up the base temp directory (parent of the template)
+      await rm(baseTempDir, { recursive: true, force: true }).catch(() => {})
+    },
   }
 }
 
@@ -132,6 +118,54 @@ async function resolveGitHubTemplate(parsed, options = {}) {
   }
 }
 
+/**
+ * Apply a template to a target directory
+ *
+ * @param {string} templatePath - Path to the template root (contains template.json)
+ * @param {string} targetPath - Destination directory for the scaffolded project
+ * @param {Object} data - Template variables
+ * @param {Object} options - Apply options
+ * @param {string} options.variant - Template variant to use
+ * @param {string} options.uniwebVersion - Current Uniweb version for compatibility check
+ * @param {Function} options.onWarning - Warning callback
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} Template metadata
+ */
+export async function applyTemplate(templatePath, targetPath, data = {}, options = {}) {
+  const { uniwebVersion, variant, onWarning, onProgress } = options
+
+  // Validate the template
+  const metadata = await validateTemplate(templatePath, { uniwebVersion })
+
+  // Register versions for the {{version}} helper
+  if (data.versions) {
+    registerVersions(data.versions)
+  }
+
+  // Apply default variables
+  const templateData = {
+    year: new Date().getFullYear(),
+    ...data
+  }
+
+  // Copy template files
+  await copyTemplateDirectory(
+    metadata.templateDir,
+    targetPath,
+    templateData,
+    { variant, onWarning, onProgress }
+  )
+
+  // Check for missing versions and warn
+  const missingVersions = getMissingVersions()
+  if (missingVersions.length > 0 && onWarning) {
+    onWarning(`Missing version data for packages: ${missingVersions.join(', ')}. Using fallback version.`)
+  }
+  clearMissingVersions()
+
+  return metadata
+}
+
 /**
  * Apply an external template to a target directory
  *
@@ -141,21 +175,14 @@ async function resolveGitHubTemplate(parsed, options = {}) {
  * @param {Object} options - Apply options
  */
 export async function applyExternalTemplate(resolved, targetPath, data, options = {}) {
-  const { onProgress, onWarning } = options
-
-  if (!templatesPackage) {
-    throw new Error(
-      'External template application requires @uniweb/templates package.\n' +
-      'Install it with: npm install @uniweb/templates'
-    )
-  }
+  const { variant, onProgress, onWarning } = options
 
   try {
-    const metadata = await templatesPackage.applyTemplate(
+    const metadata = await applyTemplate(
       resolved.path,
       targetPath,
       data,
-      { onProgress, onWarning }
+      { variant, onProgress, onWarning }
     )
 
     return metadata
@@ -185,21 +212,19 @@ export async function listAvailableTemplates() {
     })
   }
 
-  // Official templates from @uniweb/templates
-  if (templatesPackage) {
-    try {
-      const official = await templatesPackage.listBuiltinTemplates()
-      for (const t of official) {
-        templates.push({
-          type: 'official',
-          id: t.id,
-          name: t.name,
-          description: t.description,
-        })
-      }
-    } catch {
-      // Ignore errors listing official templates
+  // Official templates from GitHub releases
+  try {
+    const official = await listOfficialTemplates()
+    for (const t of official) {
+      templates.push({
+        type: 'official',
+        id: t.id,
+        name: t.name || t.id,
+        description: t.description || '',
+      })
     }
+  } catch {
+    // Ignore errors - templates just won't be listed
   }
 
   return templates

package/src/templates/processor.js

@@ -0,0 +1,247 @@
+/**
+ * Template processor - handles file copying and Handlebars substitution
+ */
+
+import fs from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import Handlebars from 'handlebars'
+
+// Cache for compiled templates
+const templateCache = new Map()
+
+// Store for version data (set by registerVersions)
+let versionData = {}
+
+// Track missing versions during processing
+const missingVersions = new Set()
+
+// Default fallback version when a package version is unknown
+const DEFAULT_FALLBACK_VERSION = '^0.1.0'
+
+/**
+ * Register version data for the {{version}} helper
+ *
+ * @param {Object} versions - Map of package names to version specs
+ */
+export function registerVersions(versions) {
+  versionData = versions || {}
+  missingVersions.clear()
+}
+
+/**
+ * Get the list of missing versions encountered during processing
+ *
+ * @returns {string[]} Array of package names that were missing versions
+ */
+export function getMissingVersions() {
+  return [...missingVersions]
+}
+
+/**
+ * Clear the missing versions set
+ */
+export function clearMissingVersions() {
+  missingVersions.clear()
+}
+
+/**
+ * Handlebars helper to get a package version
+ * Usage: {{version "@uniweb/build"}} or {{version "build"}}
+ */
+Handlebars.registerHelper('version', function(packageName) {
+  // Try exact match first
+  if (versionData[packageName]) {
+    return versionData[packageName]
+  }
+
+  // Try with @uniweb/ prefix
+  if (!packageName.startsWith('@') && versionData[`@uniweb/${packageName}`]) {
+    return versionData[`@uniweb/${packageName}`]
+  }
+
+  // Track the missing version and return a fallback
+  missingVersions.add(packageName)
+  return DEFAULT_FALLBACK_VERSION
+})
+
+// Text file extensions that should be processed for variables
+const TEXT_EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.json', '.yml', '.yaml', '.md', '.mdx',
+  '.html', '.htm', '.css', '.scss', '.less',
+  '.txt', '.xml', '.svg', '.vue', '.astro'
+])
+
+/**
+ * Check if string contains unresolved Handlebars placeholders
+ */
+function findUnresolvedPlaceholders(content) {
+  const patterns = [
+    /\{\{([^#/}>][^}]*)\}\}/g, // {{variable}} - not blocks or partials
+  ]
+
+  const unresolved = []
+  for (const pattern of patterns) {
+    const matches = content.matchAll(pattern)
+    for (const match of matches) {
+      const varName = match[1].trim()
+      // Skip helpers and expressions with spaces (likely intentional)
+      if (!varName.includes(' ')) {
+        unresolved.push(varName)
+      }
+    }
+  }
+  return [...new Set(unresolved)]
+}
+
+/**
+ * Load and compile a Handlebars template with caching
+ */
+async function loadTemplate(templatePath) {
+  if (templateCache.has(templatePath)) {
+    return templateCache.get(templatePath)
+  }
+
+  const template = await fs.readFile(templatePath, 'utf8')
+  const compiled = Handlebars.compile(template)
+  templateCache.set(templatePath, compiled)
+  return compiled
+}
+
+/**
+ * Process a single file - either copy or apply Handlebars
+ */
+async function processFile(sourcePath, targetPath, data, options = {}) {
+  const isHbs = sourcePath.endsWith('.hbs')
+  const ext = path.extname(isHbs ? sourcePath.slice(0, -4) : sourcePath)
+  const isTextFile = TEXT_EXTENSIONS.has(ext)
+
+  if (isHbs) {
+    // Process Handlebars template
+    const template = await loadTemplate(sourcePath)
+    const content = template(data)
+
+    // Check for unresolved placeholders
+    const unresolved = findUnresolvedPlaceholders(content)
+    if (unresolved.length > 0 && options.onWarning) {
+      options.onWarning(`Unresolved placeholders in ${path.basename(targetPath)}: ${unresolved.join(', ')}`)
+    }
+
+    await fs.writeFile(targetPath, content)
+  } else if (isTextFile && options.processAllText) {
+    // Optionally process non-hbs text files for simple replacements
+    let content = await fs.readFile(sourcePath, 'utf8')
+    // Simple {{var}} replacement without full Handlebars
+    for (const [key, value] of Object.entries(data)) {
+      if (typeof value === 'string') {
+        content = content.replaceAll(`{{${key}}}`, value)
+      }
+    }
+    await fs.writeFile(targetPath, content)
+  } else {
+    // Binary or non-template file - just copy
+    await fs.copyFile(sourcePath, targetPath)
+  }
+}
+
+/**
+ * Copy a directory structure recursively, processing templates
+ *
+ * @param {string} sourcePath - Source template directory
+ * @param {string} targetPath - Destination directory
+ * @param {Object} data - Template variables
+ * @param {Object} options - Processing options
+ * @param {string|null} options.variant - Template variant to use
+ * @param {Function} options.onWarning - Warning callback
+ * @param {Function} options.onProgress - Progress callback
+ */
+export async function copyTemplateDirectory(sourcePath, targetPath, data, options = {}) {
+  const { variant = null, onWarning, onProgress } = options
+
+  await fs.mkdir(targetPath, { recursive: true })
+  const entries = await fs.readdir(sourcePath, { withFileTypes: true })
+
+  // Build a set of base names that have variant-specific directories
+  const variantBases = new Set()
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const variantMatch = entry.name.match(/^(.+)\.([^.]+)$/)
+      if (variantMatch) {
+        variantBases.add(variantMatch[1]) // e.g., 'foundation' from 'foundation.tailwind4'
+      }
+    }
+  }
+
+  for (const entry of entries) {
+    const sourceName = entry.name
+
+    // Check if this is a variant-specific item (e.g., "dir.variant")
+    const variantMatch = entry.isDirectory()
+      ? sourceName.match(/^(.+)\.([^.]+)$/)
+      : null
+
+    if (entry.isDirectory()) {
+      if (variantMatch) {
+        const [, baseName, dirVariant] = variantMatch
+
+        // When no variant is specified, skip all variant directories
+        if (!variant) {
+          continue
+        }
+
+        // When variant is specified, skip directories that don't match
+        if (dirVariant !== variant) {
+          continue
+        }
+
+        // Use the base name without variant suffix for the target
+        const sourceFullPath = path.join(sourcePath, sourceName)
+        const targetFullPath = path.join(targetPath, baseName)
+
+        await copyTemplateDirectory(sourceFullPath, targetFullPath, data, options)
+      } else {
+        // Regular directory - skip if a variant override exists and we're using that variant
+        if (variant && variantBases.has(sourceName)) {
+          // Skip this directory because a variant-specific version exists
+          continue
+        }
+
+        const sourceFullPath = path.join(sourcePath, sourceName)
+        const targetFullPath = path.join(targetPath, sourceName)
+
+        await copyTemplateDirectory(sourceFullPath, targetFullPath, data, options)
+      }
+    } else {
+      // File processing
+      // Remove .hbs extension for target filename
+      const targetName = sourceName.endsWith('.hbs')
+        ? sourceName.slice(0, -4)
+        : sourceName
+
+      const sourceFullPath = path.join(sourcePath, sourceName)
+      const targetFullPath = path.join(targetPath, targetName)
+
+      // Skip if target already exists (don't overwrite)
+      if (existsSync(targetFullPath)) {
+        if (onWarning) {
+          onWarning(`Skipping ${targetFullPath} - file already exists`)
+        }
+        continue
+      }
+
+      if (onProgress) {
+        onProgress(`Creating ${targetName}`)
+      }
+
+      await processFile(sourceFullPath, targetFullPath, data, { onWarning })
+    }
+  }
+}
+
+/**
+ * Clear the template cache
+ */
+export function clearCache() {
+  templateCache.clear()
+}

package/src/templates/validator.js

@@ -0,0 +1,206 @@
+/**
+ * Template validation - checks template.json and compatibility
+ */
+
+import fs from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Simple semver satisfaction check
+ * Supports: >=x.y.z, ^x.y.z, ~x.y.z, x.y.z, x.y.x, *, latest
+ */
+export function satisfiesVersion(version, range) {
+  if (!range || range === '*' || range === 'latest') {
+    return true
+  }
+
+  const parseVersion = (v) => {
+    const match = v.match(/^(\d+)\.(\d+)\.(\d+)/)
+    if (!match) return null
+    return {
+      major: parseInt(match[1], 10),
+      minor: parseInt(match[2], 10),
+      patch: parseInt(match[3], 10)
+    }
+  }
+
+  const current = parseVersion(version)
+  if (!current) return true // Can't parse, assume compatible
+
+  // Handle different range formats
+  if (range.startsWith('>=')) {
+    const min = parseVersion(range.slice(2))
+    if (!min) return true
+    if (current.major > min.major) return true
+    if (current.major < min.major) return false
+    if (current.minor > min.minor) return true
+    if (current.minor < min.minor) return false
+    return current.patch >= min.patch
+  }
+
+  if (range.startsWith('^')) {
+    // ^x.y.z means >=x.y.z and <(x+1).0.0
+    const min = parseVersion(range.slice(1))
+    if (!min) return true
+    if (current.major !== min.major) return current.major > min.major && min.major === 0
+    if (current.minor > min.minor) return true
+    if (current.minor < min.minor) return false
+    return current.patch >= min.patch
+  }
+
+  if (range.startsWith('~')) {
+    // ~x.y.z means >=x.y.z and <x.(y+1).0
+    const min = parseVersion(range.slice(1))
+    if (!min) return true
+    if (current.major !== min.major) return false
+    if (current.minor !== min.minor) return false
+    return current.patch >= min.patch
+  }
+
+  // Exact version or x.y.x pattern
+  if (range.includes('x')) {
+    const parts = range.split('.')
+    const min = parseVersion(range.replace(/x/g, '0'))
+    if (!min) return true
+    if (parts[0] !== 'x' && current.major !== min.major) return false
+    if (parts[1] !== 'x' && current.minor !== min.minor) return false
+    return true
+  }
+
+  // Exact match
+  const exact = parseVersion(range)
+  if (!exact) return true
+  return current.major === exact.major &&
+         current.minor === exact.minor &&
+         current.patch === exact.patch
+}
+
+/**
+ * Validation error with structured details
+ */
+export class ValidationError extends Error {
+  constructor(message, code, details = {}) {
+    super(message)
+    this.name = 'ValidationError'
+    this.code = code
+    this.details = details
+  }
+}
+
+export const ErrorCodes = {
+  MISSING_TEMPLATE_JSON: 'MISSING_TEMPLATE_JSON',
+  INVALID_TEMPLATE_JSON: 'INVALID_TEMPLATE_JSON',
+  MISSING_TEMPLATE_DIR: 'MISSING_TEMPLATE_DIR',
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+  VERSION_MISMATCH: 'VERSION_MISMATCH',
+}
+
+/**
+ * Validate a template directory structure and metadata
+ *
+ * @param {string} templateRoot - Path to the template root (contains template.json)
+ * @param {Object} options - Validation options
+ * @param {string} options.uniwebVersion - Current Uniweb version to check compatibility
+ * @returns {Object} Parsed and validated template metadata
+ */
+export async function validateTemplate(templateRoot, options = {}) {
+  const { uniwebVersion } = options
+
+  // Check for template.json
+  const metadataPath = path.join(templateRoot, 'template.json')
+  if (!existsSync(metadataPath)) {
+    throw new ValidationError(
+      `Missing template.json in ${templateRoot}`,
+      ErrorCodes.MISSING_TEMPLATE_JSON,
+      { path: templateRoot }
+    )
+  }
+
+  // Parse template.json
+  let metadata
+  try {
+    const content = await fs.readFile(metadataPath, 'utf8')
+    metadata = JSON.parse(content)
+  } catch (err) {
+    throw new ValidationError(
+      `Invalid template.json: ${err.message}`,
+      ErrorCodes.INVALID_TEMPLATE_JSON,
+      { path: metadataPath, error: err.message }
+    )
+  }
+
+  // Check required fields
+  if (!metadata.name) {
+    throw new ValidationError(
+      'template.json missing required field: name',
+      ErrorCodes.MISSING_REQUIRED_FIELD,
+      { field: 'name' }
+    )
+  }
+
+  // Check for template/ directory
+  const templateDir = path.join(templateRoot, 'template')
+  if (!existsSync(templateDir)) {
+    throw new ValidationError(
+      `Missing template/ directory in ${templateRoot}`,
+      ErrorCodes.MISSING_TEMPLATE_DIR,
+      { path: templateRoot }
+    )
+  }
+
+  // Check version compatibility
+  if (uniwebVersion && metadata.uniweb) {
+    if (!satisfiesVersion(uniwebVersion, metadata.uniweb)) {
+      throw new ValidationError(
+        `Template requires Uniweb ${metadata.uniweb}, but current version is ${uniwebVersion}`,
+        ErrorCodes.VERSION_MISMATCH,
+        { required: metadata.uniweb, current: uniwebVersion }
+      )
+    }
+  }
+
+  return {
+    ...metadata,
+    templateDir,
+    metadataPath
+  }
+}
+
+/**
+ * Get list of available templates in a templates directory
+ *
+ * @param {string} templatesDir - Path to directory containing templates
+ * @returns {Array<Object>} List of template metadata
+ */
+export async function listTemplates(templatesDir) {
+  if (!existsSync(templatesDir)) {
+    return []
+  }
+
+  const entries = await fs.readdir(templatesDir, { withFileTypes: true })
+  const templates = []
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+
+    const templatePath = path.join(templatesDir, entry.name)
+    const metadataPath = path.join(templatePath, 'template.json')
+
+    if (existsSync(metadataPath)) {
+      try {
+        const content = await fs.readFile(metadataPath, 'utf8')
+        const metadata = JSON.parse(content)
+        templates.push({
+          id: entry.name,
+          ...metadata,
+          path: templatePath
+        })
+      } catch {
+        // Skip invalid templates
+      }
+    }
+  }
+
+  return templates
+}

package/src/versions.js

@@ -0,0 +1,146 @@
+/**
+ * Version resolution utility
+ *
+ * Reads package versions from the CLI's own dependencies to ensure
+ * generated projects use compatible versions.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// Cache for resolved versions
+let resolvedVersions = null
+
+/**
+ * Get the CLI's own package.json
+ */
+function getCliPackageJson() {
+  const packagePath = join(__dirname, '..', 'package.json')
+  return JSON.parse(readFileSync(packagePath, 'utf8'))
+}
+
+/**
+ * Extract version number from version spec (e.g., "^0.1.4" -> "0.1.4")
+ */
+function extractVersion(spec) {
+  if (!spec) return null
+  // Remove ^, ~, >=, etc. prefixes
+  return spec.replace(/^[\^~>=<]+/, '')
+}
+
+/**
+ * Resolve a version spec to an npm-compatible version
+ * Handles workspace:* and other pnpm-specific protocols
+ *
+ * @param {string} spec - Version spec (e.g., "workspace:*", "^0.1.0")
+ * @param {string} fallback - Fallback version if spec is not resolvable
+ * @returns {string} npm-compatible version spec
+ */
+function resolveVersionSpec(spec, fallback) {
+  if (!spec) return fallback
+  // workspace:* is pnpm-specific, use fallback for npm compatibility
+  if (spec.startsWith('workspace:')) return fallback
+  return spec
+}
+
+/**
+ * Get resolved versions for @uniweb/* packages
+ *
+ * Returns versions that should be used in generated projects,
+ * based on the CLI's own dependencies.
+ *
+ * Note: In development (pnpm workspace), versions may be "workspace:*"
+ * which we convert to npm-compatible fallback versions.
+ *
+ * @returns {Object} Map of package names to version specs
+ */
+export function getResolvedVersions() {
+  if (resolvedVersions) return resolvedVersions
+
+  const pkg = getCliPackageJson()
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+  resolvedVersions = {
+    // Direct CLI dependencies - use fallbacks for workspace:* versions
+    '@uniweb/build': resolveVersionSpec(deps['@uniweb/build'], '^0.1.4'),
+    '@uniweb/templates': resolveVersionSpec(deps['@uniweb/templates'], '^0.1.6'),
+
+    // These come from @uniweb/build's dependencies, use compatible versions
+    '@uniweb/runtime': '^0.1.0',
+    '@uniweb/core': '^0.1.0',
+
+    // Foundation utility library (used by official templates)
+    '@uniweb/kit': '^0.1.0',
+
+    // CLI itself (use current version)
+    'uniweb': `^${pkg.version}`,
+  }
+
+  return resolvedVersions
+}
+
+/**
+ * Get a specific package version
+ *
+ * @param {string} packageName - Package name (e.g., "@uniweb/build")
+ * @returns {string} Version spec (e.g., "^0.1.4")
+ */
+export function getVersion(packageName) {
+  const versions = getResolvedVersions()
+  return versions[packageName] || null
+}
+
+/**
+ * Get all versions as a flat object for template data
+ *
+ * @returns {Object} Versions keyed by simplified names
+ */
+export function getVersionsForTemplates() {
+  const versions = getResolvedVersions()
+
+  return {
+    // Full package names
+    ...versions,
+
+    // Simplified names for templates (e.g., {{versions.build}})
+    build: versions['@uniweb/build'],
+    runtime: versions['@uniweb/runtime'],
+    core: versions['@uniweb/core'],
+    kit: versions['@uniweb/kit'],
+    templates: versions['@uniweb/templates'],
+    cli: versions['uniweb'],
+  }
+}
+
+/**
+ * Update @uniweb/* versions in a package.json object
+ *
+ * @param {Object} pkg - Package.json object
+ * @returns {Object} Updated package.json object
+ */
+export function updatePackageVersions(pkg) {
+  const versions = getResolvedVersions()
+
+  const updateDeps = (deps) => {
+    if (!deps) return deps
+    const updated = { ...deps }
+    for (const [name, version] of Object.entries(updated)) {
+      if (name.startsWith('@uniweb/') || name === 'uniweb') {
+        if (versions[name]) {
+          updated[name] = versions[name]
+        }
+      }
+    }
+    return updated
+  }
+
+  return {
+    ...pkg,
+    dependencies: updateDeps(pkg.dependencies),
+    devDependencies: updateDeps(pkg.devDependencies),
+    peerDependencies: updateDeps(pkg.peerDependencies),
+  }
+}