@uniweb/templates 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@uniweb/templates",
+  "version": "0.1.0",
+  "description": "Template processing engine and official templates for Uniweb",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./templates/*": "./templates/*"
+  },
+  "files": [
+    "src",
+    "templates"
+  ],
+  "keywords": [
+    "uniweb",
+    "templates",
+    "scaffolding"
+  ],
+  "author": "Uniweb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniweb/templates.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.8"
+  }
+}

package/src/index.js

@@ -0,0 +1,120 @@
+/**
+ * @uniweb/templates - Template processing engine and official templates
+ *
+ * Provides utilities for applying file-based templates with Handlebars
+ * variable substitution and variant support.
+ */
+
+import path from 'node:path'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { copyTemplateDirectory, clearCache } from './processor.js'
+import {
+  validateTemplate,
+  listTemplates,
+  satisfiesVersion,
+  ValidationError,
+  ErrorCodes
+} from './validator.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const TEMPLATES_DIR = path.join(__dirname, '../templates')
+
+/**
+ * Get the path to the built-in templates directory
+ */
+export function getTemplatesDirectory() {
+  return TEMPLATES_DIR
+}
+
+/**
+ * Get a specific template by name from the built-in templates
+ *
+ * @param {string} name - Template name (e.g., 'marketing', 'docs')
+ * @returns {string|null} Path to template directory, or null if not found
+ */
+export function getTemplatePath(name) {
+  const templatePath = path.join(TEMPLATES_DIR, name)
+  return templatePath
+}
+
+/**
+ * List all available built-in templates
+ *
+ * @returns {Promise<Array<Object>>} List of template metadata
+ */
+export async function listBuiltinTemplates() {
+  return listTemplates(TEMPLATES_DIR)
+}
+
+/**
+ * Check if a built-in template exists
+ *
+ * @param {string} name - Template name
+ * @returns {boolean}
+ */
+export function hasTemplate(name) {
+  const templatePath = path.join(TEMPLATES_DIR, name)
+  return existsSync(path.join(templatePath, 'template.json'))
+}
+
+/**
+ * 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 })
+
+  // Apply default variables
+  const templateData = {
+    year: new Date().getFullYear(),
+    ...data
+  }
+
+  // Copy template files
+  await copyTemplateDirectory(
+    metadata.templateDir,
+    targetPath,
+    templateData,
+    { variant, onWarning, onProgress }
+  )
+
+  return metadata
+}
+
+/**
+ * Apply a built-in template by name
+ *
+ * @param {string} name - Template name (e.g., 'marketing')
+ * @param {string} targetPath - Destination directory
+ * @param {Object} data - Template variables
+ * @param {Object} options - Apply options
+ * @returns {Promise<Object>} Template metadata
+ */
+export async function applyBuiltinTemplate(name, targetPath, data = {}, options = {}) {
+  const templatePath = getTemplatePath(name)
+  return applyTemplate(templatePath, targetPath, data, options)
+}
+
+// Re-export utilities
+export {
+  copyTemplateDirectory,
+  clearCache,
+  validateTemplate,
+  listTemplates,
+  satisfiesVersion,
+  ValidationError,
+  ErrorCodes
+}

package/src/processor.js

@@ -0,0 +1,184 @@
+/**
+ * Template processor - handles file copying and Handlebars substitution
+ * Adapted from Proximify dev-tools template system
+ */
+
+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()
+
+// 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 a path is a directory
+ */
+async function isDirectory(filePath) {
+  try {
+    const stats = await fs.stat(filePath)
+    return stats.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 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 })
+
+  for (const entry of entries) {
+    const sourceName = entry.name
+
+    // Check if this is a variant-specific item (e.g., "dir.variant" or "file.variant.ext")
+    const variantMatch = entry.isDirectory()
+      ? sourceName.match(/^(.+)\.([^.]+)$/)
+      : null
+
+    if (entry.isDirectory()) {
+      if (variantMatch) {
+        const [, baseName, dirVariant] = variantMatch
+
+        // Skip directories that don't match our variant
+        if (variant && 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
+        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/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/templates/marketing/template/README.md.hbs

@@ -0,0 +1,56 @@
+# {{projectName}}
+
+A marketing site built with [Uniweb](https://uniweb.io).
+
+## Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Build for production
+pnpm build
+```
+
+## Project Structure
+
+```
+{{projectName}}/
+├── foundation/     # Component library
+│   └── src/
+│       └── components/
+│           ├── Hero/
+│           ├── Features/
+│           ├── Pricing/
+│           ├── Testimonials/
+│           └── CTA/
+└── site/          # Marketing site
+    └── pages/
+        └── home/
+            ├── 1-hero.md
+            ├── 2-features.md
+            ├── 3-pricing.md
+            ├── 4-testimonials.md
+            └── 5-cta.md
+```
+
+## Components
+
+- **Hero** - Eye-catching header with headline, description, and call-to-action
+- **Features** - Showcase product features with icons and descriptions
+- **Pricing** - Pricing table with multiple tiers
+- **Testimonials** - Customer quotes and social proof
+- **CTA** - Call-to-action section to drive conversions
+
+## Customization
+
+Edit the markdown files in `site/pages/` to update content. Each section file has YAML frontmatter for configuration and markdown body for content.
+
+Edit component styles in `foundation/src/components/*/index.jsx`.
+
+---
+
+Created with the Uniweb Marketing Template

package/templates/marketing/template/foundation/package.json.hbs

@@ -0,0 +1,34 @@
+{
+  "name": "{{projectName}}-foundation",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles": "./src/styles.css",
+    "./dist": "./dist/foundation.js",
+    "./dist/styles": "./dist/assets/style.css"
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "dev": "vite",
+    "build": "uniweb build",
+    "build:vite": "vite build",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.18",
+    "postcss": "^8.4.35",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tailwindcss": "^3.4.1",
+    "uniweb": "^0.2.0",
+    "vite": "^5.1.0",
+    "vite-plugin-svgr": "^4.2.0"
+  }
+}

package/templates/marketing/template/foundation/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}