uniweb 0.2.2 → 0.2.3

package/README.md

@@ -40,7 +40,7 @@ my-project/
                 └── index.jsx
 ```
 
-**Pages are folders.** Create `pages/about/` with a markdown file inside → visit `/about`. That's the whole routing model.
+**Pages are folders.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
 
 ### Content as Markdown
 
@@ -240,7 +240,7 @@ A monorepo for multi-site or multi-foundation development.
 ```
 my-workspace/
 ├── package.json              # Workspace root (includes workspaces field for npm)
-├── pnpm-workspace.yaml       # Same config as site template
+├── pnpm-workspace.yaml       # Same config as single template
 │
 ├── sites/
 │   ├── marketing/            # Main marketing site

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -32,6 +32,8 @@
   },
   "dependencies": {
     "@uniweb/build": "^0.1.0",
-    "prompts": "^2.4.2"
+    "@uniweb/templates": "workspace:*",
+    "prompts": "^2.4.2",
+    "tar": "^7.0.0"
   }
 }

package/src/index.js

@@ -18,6 +18,13 @@ import { resolve, join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import prompts from 'prompts'
 import { build } from './commands/build.js'
+import {
+  resolveTemplate,
+  applyExternalTemplate,
+  parseTemplateId,
+  listAvailableTemplates,
+  BUILTIN_TEMPLATES,
+} from './templates/index.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -93,9 +100,11 @@ async function main() {
   const templateIndex = args.indexOf('--template')
   if (templateIndex !== -1 && args[templateIndex + 1]) {
     templateType = args[templateIndex + 1]
-    if (!templates[templateType]) {
-      error(`Unknown template: ${templateType}`)
-      log(`Available templates: ${Object.keys(templates).join(', ')}`)
+    // Validate template identifier (will throw if invalid)
+    try {
+      parseTemplateId(templateType)
+    } catch (err) {
+      error(`Invalid template: ${err.message}`)
       process.exit(1)
     }
   }
@@ -155,16 +164,40 @@ async function main() {
     process.exit(1)
   }
 
-  log(`\nCreating ${templates[templateType].name.toLowerCase()}...`)
+  // Resolve and create project based on template
+  const parsed = parseTemplateId(templateType)
 
-  // Generate project based on template
-  switch (templateType) {
-    case 'single':
-      await createSingleProject(projectDir, projectName)
-      break
-    case 'multi':
-      await createMultiProject(projectDir, projectName)
-      break
+  if (parsed.type === 'builtin') {
+    log(`\nCreating ${templates[templateType].name.toLowerCase()}...`)
+
+    // Generate project based on built-in template
+    switch (templateType) {
+      case 'single':
+        await createSingleProject(projectDir, projectName)
+        break
+      case 'multi':
+        await createMultiProject(projectDir, projectName)
+        break
+    }
+  } else {
+    // External template (official, npm, or github)
+    log(`\nResolving template: ${templateType}...`)
+
+    try {
+      const resolved = await resolveTemplate(templateType, {
+        onProgress: (msg) => log(`  ${colors.dim}${msg}${colors.reset}`),
+      })
+
+      log(`\nCreating project from ${resolved.name || resolved.package || `${resolved.owner}/${resolved.repo}`}...`)
+
+      await applyExternalTemplate(resolved, projectDir, { projectName }, {
+        onProgress: (msg) => log(`  ${colors.dim}${msg}${colors.reset}`),
+        onWarning: (msg) => log(`  ${colors.yellow}Warning: ${msg}${colors.reset}`),
+      })
+    } catch (err) {
+      error(`Failed to apply template: ${err.message}`)
+      process.exit(1)
+    }
   }
 
   // Success message
@@ -189,22 +222,27 @@ ${colors.bright}Commands:${colors.reset}
   build              Build the current project
 
 ${colors.bright}Create Options:${colors.reset}
-  --template <type>  Project template (single, multi)
+  --template <type>  Project template
 
 ${colors.bright}Build Options:${colors.reset}
   --target <type>    Build target (foundation, site) - auto-detected if not specified
   --platform <name>  Deployment platform (e.g., vercel) for platform-specific output
 
+${colors.bright}Template Types:${colors.reset}
+  single                        One site + one foundation (default)
+  multi                         Multiple sites and foundations
+  marketing                     Official marketing template
+  @scope/template-name          npm package
+  github:user/repo              GitHub repository
+  https://github.com/user/repo  GitHub URL
+
 ${colors.bright}Examples:${colors.reset}
   npx uniweb create my-project
   npx uniweb create my-project --template single
-  npx uniweb create my-workspace --template multi
+  npx uniweb create my-project --template marketing
+  npx uniweb create my-project --template github:myorg/template
   npx uniweb build
   npx uniweb build --target foundation
-
-${colors.bright}Templates:${colors.reset}
-  single       One site + one foundation in site/ and foundation/ (default)
-  multi        Multiple sites and foundations in sites/* and foundations/*
 `)
 }
 
@@ -843,7 +881,7 @@ async function createFoundation(projectDir, projectName, isWorkspace = false) {
     files: ['dist', 'src'],
     scripts: {
       dev: 'vite',
-      build: 'npx uniweb build',
+      build: 'uniweb build',
       'build:vite': 'vite build',
       preview: 'vite preview',
     },
@@ -858,6 +896,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',
       vite: '^5.1.0',
       'vite-plugin-svgr': '^4.2.0',
     },

package/src/templates/fetchers/github.js

@@ -0,0 +1,98 @@
+/**
+ * GitHub fetcher - downloads templates from GitHub repositories
+ */
+
+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'
+
+/**
+ * Fetch a template from a GitHub repository
+ *
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {Object} options - Fetch options
+ * @param {string} options.ref - Branch, tag, or commit (default: HEAD)
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} { tempDir, ref }
+ */
+export async function fetchGitHubTemplate(owner, repo, options = {}) {
+  const { ref = 'HEAD', onProgress } = options
+
+  const displayRef = ref === 'HEAD' ? 'latest' : ref
+  onProgress?.(`Fetching ${owner}/${repo}@${displayRef} from GitHub...`)
+
+  // GitHub provides tarballs without requiring git
+  const tarballUrl = `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`
+
+  const tempDir = await mkdtemp(join(tmpdir(), 'uniweb-template-'))
+
+  try {
+    const response = await fetchWithRetry(tarballUrl, {
+      headers: {
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': 'uniweb-cli',
+        // Support private repos if GITHUB_TOKEN is set
+        ...(process.env.GITHUB_TOKEN && {
+          'Authorization': `Bearer ${process.env.GITHUB_TOKEN}`
+        }),
+      },
+    })
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new Error(`Repository not found: ${owner}/${repo}`)
+      }
+      if (response.status === 403) {
+        const remaining = response.headers.get('x-ratelimit-remaining')
+        if (remaining === '0') {
+          throw new Error(
+            'GitHub API rate limit exceeded. Set GITHUB_TOKEN environment variable for higher limits.'
+          )
+        }
+      }
+      throw new Error(`GitHub API error: ${response.status}`)
+    }
+
+    onProgress?.(`Downloading and extracting...`)
+
+    await pipeline(
+      response.body,
+      createGunzip(),
+      tar.extract({ cwd: tempDir, strip: 1 }) // strip 'owner-repo-sha/' prefix
+    )
+
+    onProgress?.(`Extracted to ${tempDir}`)
+
+    return {
+      tempDir,
+      ref: displayRef,
+    }
+  } catch (err) {
+    // Clean up on error
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    throw err
+  }
+}
+
+/**
+ * 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,
+        signal: AbortSignal.timeout(60000), // 60s timeout for GitHub (can be slow)
+      })
+      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/fetchers/npm.js

@@ -0,0 +1,96 @@
+/**
+ * npm package fetcher - downloads and extracts templates from npm registry
+ */
+
+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'
+
+/**
+ * Fetch a template from npm registry
+ *
+ * @param {string} packageName - npm package name (e.g., '@uniweb/template-marketing')
+ * @param {Object} options - Fetch options
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} { tempDir, version, metadata }
+ */
+export async function fetchNpmTemplate(packageName, options = {}) {
+  const { onProgress } = options
+
+  onProgress?.(`Fetching package info for ${packageName}...`)
+
+  // Query npm registry for package metadata
+  const registryUrl = `https://registry.npmjs.org/${encodeURIComponent(packageName).replace('%40', '@')}`
+
+  const metaResponse = await fetchWithRetry(registryUrl)
+  if (!metaResponse.ok) {
+    if (metaResponse.status === 404) {
+      throw new Error(`Package not found: ${packageName}`)
+    }
+    throw new Error(`npm registry error: ${metaResponse.status}`)
+  }
+
+  const pkgMeta = await metaResponse.json()
+  const version = pkgMeta['dist-tags']?.latest
+  if (!version) {
+    throw new Error(`No published versions found for ${packageName}`)
+  }
+
+  const versionMeta = pkgMeta.versions[version]
+  const tarballUrl = versionMeta?.dist?.tarball
+  if (!tarballUrl) {
+    throw new Error(`No tarball URL found for ${packageName}@${version}`)
+  }
+
+  onProgress?.(`Downloading ${packageName}@${version}...`)
+
+  // Download and extract tarball
+  const tempDir = await mkdtemp(join(tmpdir(), 'uniweb-template-'))
+
+  try {
+    const tarballResponse = await fetchWithRetry(tarballUrl)
+    if (!tarballResponse.ok) {
+      throw new Error(`Failed to download tarball: ${tarballResponse.status}`)
+    }
+
+    await pipeline(
+      tarballResponse.body,
+      createGunzip(),
+      tar.extract({ cwd: tempDir, strip: 1 }) // strip 'package/' prefix
+    )
+
+    onProgress?.(`Extracted to ${tempDir}`)
+
+    return {
+      tempDir,
+      version,
+      metadata: versionMeta,
+    }
+  } catch (err) {
+    // Clean up on error
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    throw err
+  }
+}
+
+/**
+ * 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,
+        signal: AbortSignal.timeout(30000), // 30s 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

@@ -0,0 +1,209 @@
+/**
+ * Template resolution and application for the CLI
+ */
+
+import { rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+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
+}
+
+/**
+ * Resolve a template identifier and return the template path
+ *
+ * @param {string} identifier - Template identifier
+ * @param {Object} options - Resolution options
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} { type, path, metadata, cleanup }
+ */
+export async function resolveTemplate(identifier, options = {}) {
+  const { onProgress } = options
+  const parsed = parseTemplateId(identifier)
+
+  switch (parsed.type) {
+    case 'builtin':
+      return {
+        type: 'builtin',
+        name: parsed.name,
+        // Built-in templates are handled programmatically by the CLI
+        // No path or cleanup needed
+      }
+
+    case 'official':
+      return resolveOfficialTemplate(parsed.name, options)
+
+    case 'npm':
+      return resolveNpmTemplate(parsed.package, options)
+
+    case 'github':
+      return resolveGitHubTemplate(parsed, options)
+
+    default:
+      throw new Error(`Unknown template type: ${parsed.type}`)
+  }
+}
+
+/**
+ * Resolve an official template from @uniweb/templates
+ */
+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`
+    )
+  }
+
+  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}`)
+
+  return {
+    type: 'official',
+    name,
+    path: templatePath,
+    cleanup: async () => {}, // Nothing to clean up
+  }
+}
+
+/**
+ * Resolve a template from npm
+ */
+async function resolveNpmTemplate(packageName, options = {}) {
+  const { onProgress } = options
+
+  onProgress?.(`Resolving npm template: ${packageName}`)
+
+  const { tempDir, version, metadata } = await fetchNpmTemplate(packageName, { onProgress })
+
+  return {
+    type: 'npm',
+    package: packageName,
+    version,
+    path: tempDir,
+    cleanup: async () => {
+      await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    },
+  }
+}
+
+/**
+ * Resolve a template from GitHub
+ */
+async function resolveGitHubTemplate(parsed, options = {}) {
+  const { onProgress } = options
+  const { owner, repo, ref } = parsed
+
+  onProgress?.(`Resolving GitHub template: ${owner}/${repo}`)
+
+  const { tempDir } = await fetchGitHubTemplate(owner, repo, { ref, onProgress })
+
+  return {
+    type: 'github',
+    owner,
+    repo,
+    ref,
+    path: tempDir,
+    cleanup: async () => {
+      await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    },
+  }
+}
+
+/**
+ * Apply an external template to a target directory
+ *
+ * @param {Object} resolved - Resolved template from resolveTemplate()
+ * @param {string} targetPath - Target directory
+ * @param {Object} data - Template variables
+ * @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'
+    )
+  }
+
+  try {
+    const metadata = await templatesPackage.applyTemplate(
+      resolved.path,
+      targetPath,
+      data,
+      { onProgress, onWarning }
+    )
+
+    return metadata
+  } finally {
+    // Clean up temp directory if there is one
+    if (resolved.cleanup) {
+      await resolved.cleanup()
+    }
+  }
+}
+
+/**
+ * List all available templates
+ */
+export async function listAvailableTemplates() {
+  const templates = []
+
+  // Built-in templates
+  for (const name of BUILTIN_TEMPLATES) {
+    templates.push({
+      type: 'builtin',
+      id: name,
+      name: name.charAt(0).toUpperCase() + name.slice(1),
+      description: name === 'single'
+        ? 'One site + one foundation'
+        : 'Multiple sites and foundations',
+    })
+  }
+
+  // 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
+    }
+  }
+
+  return templates
+}
+
+// Re-export for convenience
+export { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES }

package/src/templates/resolver.js

@@ -0,0 +1,116 @@
+/**
+ * Template resolver - parses template identifiers and determines source type
+ */
+
+// Built-in templates that are generated programmatically
+export const BUILTIN_TEMPLATES = ['single', 'multi']
+
+// Official templates from @uniweb/templates package
+export const OFFICIAL_TEMPLATES = ['marketing', 'docs', 'learning']
+
+/**
+ * Parse a template identifier and determine its source type
+ *
+ * @param {string} identifier - Template identifier (e.g., 'single', '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,
+    }
+  }
+
+  // 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}` : ''}`
+    default:
+      return 'Unknown'
+  }
+}