uniweb 1.0.0 → 1.0.2

package/src/templates/processor.js

@@ -0,0 +1,333 @@
+/**
+ * Template processor - handles file copying and Handlebars substitution
+ */
+
+import fs from 'node:fs/promises'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Handlebars from 'handlebars'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// Cache for compiled templates
+const templateCache = new Map()
+
+// Track if partials have been registered
+let partialsRegistered = false
+
+// Store for version data (set by registerVersions)
+let versionData = {}
+
+// 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 || {}
+}
+
+/**
+ * Register Handlebars partials from the partials directory
+ * Partials are available as {{> partial-name}} in templates
+ */
+function registerPartials() {
+  if (partialsRegistered) return
+
+  const partialsDir = path.join(__dirname, '..', '..', 'partials')
+
+  if (!existsSync(partialsDir)) {
+    partialsRegistered = true
+    return
+  }
+
+  try {
+    const files = readdirSync(partialsDir)
+
+    for (const file of files) {
+      if (file.endsWith('.hbs') || file.endsWith('.md')) {
+        const partialName = file.replace(/\.(hbs|md)$/, '')
+        const partialPath = path.join(partialsDir, file)
+        const partialContent = readFileSync(partialPath, 'utf8')
+
+        Handlebars.registerPartial(partialName, partialContent)
+      }
+    }
+
+    partialsRegistered = true
+  } catch (err) {
+    console.warn('Warning: Could not register partials:', err.message)
+    partialsRegistered = true
+  }
+}
+
+/**
+ * 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}`]
+  }
+
+  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) {
+  // Ensure partials are registered before first template load
+  registerPartials()
+
+  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) {
+    // Process text files for simple variable 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)
+  }
+}
+
+/**
+ * Rename a leading single underscore to a dot: `_gitignore` → `.gitignore`,
+ * `_vscode` → `.vscode`.
+ *
+ * Dotfiles live in the template source under a `_`-prefixed name for two
+ * reasons: (1) so they aren't swept up by the template repo's own git ignore
+ * rules, and (2) — critically — so they survive `npm publish`. npm strips any
+ * file literally named `.gitignore` from the package tarball (it's treated as
+ * an ignore-source, not shippable content), so a template that needs to ship a
+ * `.gitignore` MUST store it as `_gitignore` and rename it at scaffold time.
+ * `.gitkeep` and other dotfiles ship fine; `.gitignore` is the trap.
+ *
+ * `__name` (double underscore) is left untouched, matching the prior
+ * directory-only behavior.
+ */
+function dotfileRename(name) {
+  return name.startsWith('_') && !name.startsWith('__')
+    ? `.${name.slice(1)}`
+    : name
+}
+
+/**
+ * Compute a template file's scaffolded output name: strip the `.hbs`
+ * Handlebars suffix, then apply {@link dotfileRename}. So `_gitignore` →
+ * `.gitignore` and `_env.local.hbs` → `.env.local`.
+ */
+function templateOutputName(sourceName) {
+  const base = sourceName.endsWith('.hbs')
+    ? sourceName.slice(0, -4)
+    : sourceName
+  return dotfileRename(base)
+}
+
+/**
+ * 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 {Function} options.onWarning - Warning callback
+ * @param {Function} options.onProgress - Progress callback
+ */
+export async function copyTemplateDirectory(
+  sourcePath,
+  targetPath,
+  data,
+  options = {}
+) {
+  const { onWarning, onProgress, skip } = options
+
+  await fs.mkdir(targetPath, { recursive: true })
+  const entries = await fs.readdir(sourcePath, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const sourceName = entry.name
+
+    if (entry.isDirectory()) {
+      const sourceFullPath = path.join(sourcePath, sourceName)
+      // Rename _prefix directories to .prefix (e.g., _vscode → .vscode).
+      const targetFullPath = path.join(targetPath, dotfileRename(sourceName))
+
+      await copyTemplateDirectory(sourceFullPath, targetFullPath, data, {
+        onWarning,
+        onProgress,
+        skip
+      })
+    } else {
+      // Skip template.json as it's metadata for the template, not for the output
+      if (sourceName === 'template.json') {
+        continue
+      }
+
+      // Output name: strip `.hbs`, then rename a leading `_` to `.`
+      // (e.g. `_gitignore` → `.gitignore`). Used for both the skip check and
+      // the written filename so they can't drift.
+      const targetName = templateOutputName(sourceName)
+      if (skip?.includes(targetName)) {
+        continue
+      }
+
+      const sourceFullPath = path.join(sourcePath, sourceName)
+      const targetFullPath = path.join(targetPath, targetName)
+
+      if (onProgress) {
+        onProgress(`Creating ${targetName}`)
+      }
+
+      await processFile(sourceFullPath, targetFullPath, data, { onWarning })
+    }
+  }
+}
+
+/**
+ * Enumerate the output paths a template directory would write, without
+ * touching disk. Mirrors `copyTemplateDirectory`'s naming rules:
+ *   - `.hbs` extension is stripped
+ *   - a leading `_` is renamed to `.` for both files and directories
+ *     (e.g. `_gitignore` → `.gitignore`, `_vscode` → `.vscode`); `__name`
+ *     is preserved
+ *   - `template.json` is excluded
+ *   - `skip` filenames are excluded by their post-rename name
+ *
+ * Returns relative paths (POSIX-style separators on POSIX, native on Windows
+ * — `path.join` semantics). Used by the in-place create flow to detect
+ * conflicts before any I/O begins.
+ *
+ * @param {string} sourcePath - Source template directory
+ * @param {Object} [options]
+ * @param {string[]} [options.skip] - Output filenames to exclude
+ * @returns {Promise<string[]>}
+ */
+export async function enumerateTemplateOutputs(sourcePath, options = {}) {
+  const { skip = [] } = options
+  const outputs = []
+  await enumerateInto(sourcePath, '', outputs, skip)
+  return outputs
+}
+
+async function enumerateInto(sourcePath, relPath, outputs, skip) {
+  const entries = await fs.readdir(sourcePath, { withFileTypes: true })
+  for (const entry of entries) {
+    const sourceName = entry.name
+    if (entry.isDirectory()) {
+      const targetName = dotfileRename(sourceName)
+      await enumerateInto(
+        path.join(sourcePath, sourceName),
+        relPath ? path.join(relPath, targetName) : targetName,
+        outputs,
+        skip
+      )
+    } else {
+      if (sourceName === 'template.json') continue
+      const outputName = templateOutputName(sourceName)
+      if (skip.includes(outputName)) continue
+      outputs.push(relPath ? path.join(relPath, outputName) : outputName)
+    }
+  }
+}
+
+/**
+ * Clear the template cache
+ */
+export function clearCache() {
+  templateCache.clear()
+}

package/src/templates/resolver.js

@@ -0,0 +1,232 @@
+/**
+ * Template resolver - parses template identifiers and determines source type
+ */
+
+import { loadFrameworkIndex } from '../versions.js'
+
+// Built-in templates (programmatic, not file-based)
+export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
+
+/**
+ * THE OFFICIAL TEMPLATES THIS CLI SCAFFOLDS — one snapshot.
+ *
+ * `../framework-index.json` is written when the CLI is published: the
+ * templates' manifest (`{ id: { name, description, tags } }`) and, in
+ * `packages`, the `@uniweb/templates` version whose release holds their
+ * content. The interactive picker, `uniweb template list` and the download in
+ * `create` all read it, so the CLI offers exactly the templates it can fetch,
+ * and fetches the content released with the package versions it pins. A CLI
+ * goes on scaffolding the templates it was published with until it is
+ * updated — consistent, not newest.
+ *
+ * ⛔ Until 2026-10-08 a CLI run from a source checkout listed the templates
+ * repo's working manifest instead, and every CLI downloaded from the `latest`
+ * release. So a CLI could offer a template its release did not hold, and
+ * scaffold content newer than the packages it pinned: a template using a kit
+ * export the CLI's kit did not have yet failed to build.
+ *
+ * (An earlier version still hardcoded the picker's list, which silently
+ * drifted whenever a template was added — the reason no list is written here.)
+ */
+const INDEX = loadFrameworkIndex()
+
+// Official template metadata keyed by id. Empty when the snapshot did not load:
+// an unknown name then falls through to the npm `@uniweb/template-<name>`
+// lookup, the path for third-party templates, rather than to a stale list.
+export const OFFICIAL_TEMPLATE_MAP =
+  INDEX?.templates && typeof INDEX.templates === 'object' ? INDEX.templates : {}
+
+// Official template ids, e.g. ['marketing', 'docs', 'academic', …].
+export const OFFICIAL_TEMPLATES = Object.keys(OFFICIAL_TEMPLATE_MAP)
+
+// The release the official templates download from — `v<@uniweb/templates
+// version>`, the repo's tag — or null when the snapshot names none.
+const TEMPLATES_VERSION = INDEX?.packages?.['@uniweb/templates']?.version
+export const OFFICIAL_TEMPLATES_RELEASE = TEMPLATES_VERSION ? `v${TEMPLATES_VERSION}` : null
+
+// Built-in (programmatic) picker entries — not in the manifest; the CLI
+// generates these itself. "Blank" trails the official templates.
+const BUILTIN_LEAD_CHOICES = [
+  {
+    title: 'None',
+    value: 'none',
+    description: 'Foundation + site with no content'
+  },
+  {
+    title: 'Starter',
+    value: 'starter',
+    description: 'Foundation + site + sample content'
+  }
+]
+const BLANK_CHOICE = {
+  title: 'Blank workspace',
+  value: 'blank',
+  description: 'Empty workspace — grow with uniweb add'
+}
+
+/**
+ * Build the choices for the interactive `create` template prompt: the
+ * built-in leads (None, Starter), then every official template from the
+ * shared manifest in manifest order, then Blank last. Deriving the official
+ * entries from OFFICIAL_TEMPLATE_MAP keeps the picker in lockstep with
+ * framework/templates/manifest.json — adding a template there (and
+ * republishing the CLI) is all it takes for it to appear here.
+ *
+ * @returns {Array<{title: string, value: string, description: string}>}
+ */
+export function buildTemplateChoices() {
+  const official = Object.entries(OFFICIAL_TEMPLATE_MAP).map(([id, info]) => ({
+    title: info?.name || id,
+    value: id,
+    description: info?.description || ''
+  }))
+  return [...BUILTIN_LEAD_CHOICES, ...official, BLANK_CHOICE]
+}
+
+/**
+ * How many options the `create` picker shows at once: all of them, when the
+ * terminal has the rows. prompts shows 10 by default and scrolls the rest, and
+ * past ten choices that put most of the official templates below the fold —
+ * a template you have to scroll to find reads as one that is not there.
+ *
+ * Seven rows are kept back: the question, and the highlighted choice's
+ * description, which wraps under it when it is long.
+ *
+ * @param {number} count - the picker's choices
+ * @param {number} [rows] - the terminal's height, when it reports one
+ * @returns {number}
+ */
+export function templatePickerPageSize(count, rows = process.stdout.rows) {
+  const room = Number.isFinite(rows) && rows > 0 ? rows - 7 : count
+  return Math.max(10, Math.min(count, room))
+}
+
+/**
+ * Parse a template identifier and determine its source type
+ *
+ * @param {string} identifier - Template identifier (e.g., 'blank', 'marketing', 'github:user/repo')
+ * @returns {Object} Parsed template info
+ */
+export function parseTemplateId(identifier) {
+  if (!identifier || typeof identifier !== 'string') {
+    throw new Error('Template identifier is required')
+  }
+
+  identifier = identifier.trim()
+
+  // Built-in templates
+  if (BUILTIN_TEMPLATES.includes(identifier)) {
+    return {
+      type: 'builtin',
+      name: identifier
+    }
+  }
+
+  // Official templates from @uniweb/templates
+  if (OFFICIAL_TEMPLATES.includes(identifier)) {
+    return {
+      type: 'official',
+      name: identifier
+    }
+  }
+
+  // GitHub shorthand: github:user/repo or github:user/repo#ref
+  if (identifier.startsWith('github:')) {
+    const rest = identifier.slice(7) // Remove 'github:'
+    return parseGitHubIdentifier(rest)
+  }
+
+  // GitHub URL: https://github.com/user/repo
+  if (
+    identifier.startsWith('https://github.com/') ||
+    identifier.startsWith('http://github.com/')
+  ) {
+    const url = new URL(identifier)
+    const pathParts = url.pathname.split('/').filter(Boolean)
+    if (pathParts.length >= 2) {
+      const [owner, repo] = pathParts
+      // Check for tree/branch in URL
+      const treeIndex = pathParts.indexOf('tree')
+      const ref =
+        treeIndex >= 0 && pathParts[treeIndex + 1]
+          ? pathParts[treeIndex + 1]
+          : undefined
+      return {
+        type: 'github',
+        owner,
+        repo: repo.replace(/\.git$/, ''),
+        ref
+      }
+    }
+    throw new Error(`Invalid GitHub URL: ${identifier}`)
+  }
+
+  // Scoped npm package: @scope/package-name
+  if (identifier.startsWith('@')) {
+    return {
+      type: 'npm',
+      package: identifier
+    }
+  }
+
+  // Local path (relative, absolute, or home directory)
+  if (
+    identifier.startsWith('./') ||
+    identifier.startsWith('../') ||
+    identifier.startsWith('/') ||
+    identifier.startsWith('~')
+  ) {
+    return {
+      type: 'local',
+      path: identifier
+    }
+  }
+
+  // Unscoped name - assume it's an npm package with @uniweb/template- prefix
+  // This allows users to type `uniweb create foo --template blog` for @uniweb/template-blog
+  return {
+    type: 'npm',
+    package: `@uniweb/template-${identifier}`
+  }
+}
+
+/**
+ * Parse GitHub identifier: user/repo or user/repo#ref
+ */
+function parseGitHubIdentifier(identifier) {
+  const [repoPath, ref] = identifier.split('#')
+  const [owner, repo] = repoPath.split('/')
+
+  if (!owner || !repo) {
+    throw new Error(
+      `Invalid GitHub identifier: ${identifier}. Expected format: user/repo or user/repo#ref`
+    )
+  }
+
+  return {
+    type: 'github',
+    owner,
+    repo: repo.replace(/\.git$/, ''),
+    ref: ref || undefined
+  }
+}
+
+/**
+ * Get a display name for a template identifier
+ */
+export function getTemplateDisplayName(parsed) {
+  switch (parsed.type) {
+    case 'builtin':
+      return `Built-in: ${parsed.name}`
+    case 'official':
+      return `Official: ${parsed.name}`
+    case 'npm':
+      return parsed.package
+    case 'github':
+      return `${parsed.owner}/${parsed.repo}${parsed.ref ? `#${parsed.ref}` : ''}`
+    case 'local':
+      return `Local: ${parsed.path}`
+    default:
+      return 'Unknown'
+  }
+}