uniweb 1.0.0 → 1.0.2

package/src/templates/fetchers/github.js

@@ -0,0 +1,113 @@
+/**
+ * GitHub fetcher — downloads a template from a GitHub repository
+ * (`github:owner/repo[#ref]`).
+ *
+ * ⭐ Without a token it downloads from GitHub's archive host —
+ * `codeload.github.com/<owner>/<repo>/tar.gz/<ref>`, `HEAD` naming the default
+ * branch — which is not the REST API, so the API's anonymous limit (60 requests an
+ * hour per address) does not apply. With GITHUB_TOKEN set it uses the API's
+ * tarball endpoint, which a private repository needs and which then counts
+ * against the token's own, higher limit. ⛔ Until 2026-10-08 every download went
+ * through the API, token or not.
+ */
+
+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'
+import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
+
+/**
+ * Where to download a repository's tarball from, and with which headers.
+ *
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} [ref='HEAD'] - Branch, tag, or commit
+ * @param {string|null} [token] - GITHUB_TOKEN, when set
+ * @returns {{ url: string, headers: Record<string, string> }}
+ */
+export function githubTarballRequest(owner, repo, ref = 'HEAD', token = null) {
+  if (token) {
+    return {
+      url: `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`,
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'uniweb-cli',
+        Authorization: `Bearer ${token}`
+      }
+    }
+  }
+  return {
+    url: `https://codeload.github.com/${owner}/${repo}/tar.gz/${ref}`,
+    headers: { 'User-Agent': 'uniweb-cli' }
+  }
+}
+
+/**
+ * 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 token = process.env.GITHUB_TOKEN || null
+  const { url, headers } = githubTarballRequest(owner, repo, ref, token)
+
+  const tempDir = await mkdtemp(join(tmpdir(), 'uniweb-template-'))
+
+  try {
+    const response = await fetchWithRetry(url, { headers })
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        const at = ref === 'HEAD' ? '' : ` at ${ref}`
+        throw new Error(
+          `Repository not found: ${owner}/${repo}${at}` +
+            (token ? '' : ' — a private repository needs GITHUB_TOKEN')
+        )
+      }
+      if (response.status === 403 && response.headers.get('x-ratelimit-remaining') === '0') {
+        throw new Error('GitHub API rate limit exceeded for this GITHUB_TOKEN.')
+      }
+      throw new Error(`GitHub download failed: HTTP ${response.status}`)
+    }
+
+    onProgress?.(`Downloading and extracting...`)
+
+    await pipeline(
+      response.body,
+      createGunzip(),
+      tar.extract({ cwd: tempDir, strip: 1 }) // the archive's one top folder: 'repo-ref/' (codeload) or 'owner-repo-sha/' (API)
+    )
+
+    onProgress?.(`Extracted to ${tempDir}`)
+
+    return {
+      tempDir,
+      ref: displayRef
+    }
+  } catch (err) {
+    // Clean up on error
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    throw err
+  }
+}
+
+// Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
+// This file carried its own copy, as did the other two fetchers — three
+// byte-identical implementations, and none reachable from the upload paths
+// that had no retry at all. The wrapper keeps this caller's own timeout.
+const fetchWithRetry = (url, options = {}, maxRetries = 3) =>
+  sharedFetchWithRetry(url, { ...options }, { retries: maxRetries, timeoutMs: 60000 })

package/src/templates/fetchers/npm.js

@@ -0,0 +1,85 @@
+/**
+ * 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'
+import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
+
+/**
+ * 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
+  }
+}
+
+// Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
+// This file carried its own copy, as did the other two fetchers — three
+// byte-identical implementations, and none reachable from the upload paths
+// that had no retry at all. The wrapper keeps this caller's own timeout.
+const fetchWithRetry = (url, options = {}, maxRetries = 3) =>
+  sharedFetchWithRetry(url, { ...options }, { retries: maxRetries, timeoutMs: 30000 })

package/src/templates/fetchers/release.js

@@ -0,0 +1,92 @@
+/**
+ * Release fetcher — downloads an official template from the release of the
+ * templates repo this CLI was published with.
+ *
+ * ⭐ ONE REQUEST, AND NOT TO GITHUB'S API. The release is pinned
+ * (templates/resolver.js, OFFICIAL_TEMPLATES_RELEASE) and a release's files sit
+ * at fixed URLs, so the template's tarball is downloaded from its release URL
+ * directly. The name was checked against this CLI's own roster before anything
+ * is fetched, and a tarball the release lacks answers 404.
+ *
+ * ⛔ Until 2026-10-08 a `create` first asked the REST API for the release, to find
+ * its manifest.json, then downloaded the manifest to check the name, then the
+ * tarball: three requests, the first counted against the API's anonymous limit of
+ * 60 an hour per address — which a shared network or a CI runner can spend, and
+ * `create` then failed with "rate limit exceeded".
+ */
+
+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'
+import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
+
+// GitHub repository for official templates
+const TEMPLATES_REPO = 'uniweb/templates'
+
+/**
+ * The URL a release serves one template's tarball at.
+ *
+ * @param {string} name - Template name (e.g., 'marketing')
+ * @param {string} version - The release tag, e.g. `v0.18.6`
+ */
+export function officialTemplateUrl(name, version) {
+  return `https://github.com/${TEMPLATES_REPO}/releases/download/${version}/${name}.tar.gz`
+}
+
+/**
+ * Fetch a template from one release of the official templates
+ *
+ * @param {string} name - Template name (e.g., 'marketing')
+ * @param {Object} options - Fetch options
+ * @param {string} options.version - The release tag, e.g. `v0.18.6`
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<Object>} { tempDir, baseTempDir, version }
+ */
+export async function fetchOfficialTemplate(name, options = {}) {
+  const { version, onProgress } = options
+  if (!version) throw new Error('fetchOfficialTemplate needs the release tag to download from')
+
+  onProgress?.(`Downloading ${name} template (${version})...`)
+
+  const response = await fetchWithRetry(officialTemplateUrl(name, version), {
+    headers: { 'User-Agent': 'uniweb-cli' }
+  })
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`Release ${version} of ${TEMPLATES_REPO} has no template "${name}".`)
+    }
+    throw new Error(`Could not download the ${name} template (HTTP ${response.status}).`)
+  }
+
+  // Extract to temp directory
+  const tempDir = await mkdtemp(join(tmpdir(), 'uniweb-template-'))
+
+  try {
+    onProgress?.('Extracting template...')
+
+    await pipeline(response.body, createGunzip(), tar.extract({ cwd: tempDir, strip: 0 }))
+
+    // The tarball holds the template in a folder named after it:
+    // marketing.tar.gz extracts to marketing/template.json
+    return {
+      tempDir: join(tempDir, name),
+      baseTempDir: tempDir, // For cleanup
+      version
+    }
+  } catch (err) {
+    // Clean up on error
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    throw err
+  }
+}
+
+// Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
+// This file carried its own copy, as did the other two fetchers — three
+// byte-identical implementations, and none reachable from the upload paths
+// that had no retry at all. The wrapper keeps this caller's own timeout.
+const fetchWithRetry = (url, options = {}, maxRetries = 3) =>
+  sharedFetchWithRetry(url, { redirect: 'follow', ...options }, { retries: maxRetries, timeoutMs: 60000 })

package/src/templates/index.js

@@ -0,0 +1,190 @@
+/**
+ * Template resolution and application for the CLI
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+
+import {
+  parseTemplateId,
+  getTemplateDisplayName,
+  BUILTIN_TEMPLATES,
+  OFFICIAL_TEMPLATES,
+  OFFICIAL_TEMPLATES_RELEASE,
+  buildTemplateChoices,
+  templatePickerPageSize
+} from './resolver.js'
+import { fetchNpmTemplate } from './fetchers/npm.js'
+import { fetchGitHubTemplate } from './fetchers/github.js'
+import { fetchOfficialTemplate } from './fetchers/release.js'
+
+/**
+ * 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)
+
+    case 'local':
+      return resolveLocalTemplate(parsed.path, options)
+
+    default:
+      throw new Error(`Unknown template type: ${parsed.type}`)
+  }
+}
+
+/**
+ * Resolve an official template from the release this CLI was published with —
+ * never `latest`, so its content matches the package versions the scaffold pins
+ * (resolver.js, OFFICIAL_TEMPLATES_RELEASE).
+ */
+async function resolveOfficialTemplate(name, options = {}) {
+  const { onProgress } = options
+
+  if (!OFFICIAL_TEMPLATES_RELEASE) {
+    throw new Error(
+      "This CLI's framework index names no @uniweb/templates release to download from."
+    )
+  }
+  const { tempDir, baseTempDir, version } = await fetchOfficialTemplate(name, {
+    version: OFFICIAL_TEMPLATES_RELEASE,
+    onProgress
+  })
+
+  onProgress?.(`Using official template: ${name} (${version})`)
+
+  return {
+    type: 'official',
+    name,
+    version,
+    path: tempDir,
+    cleanup: async () => {
+      // Clean up the base temp directory (parent of the template)
+      await rm(baseTempDir, { recursive: true, force: true }).catch(() => {})
+    }
+  }
+}
+
+/**
+ * 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(() => {})
+    }
+  }
+}
+
+/**
+ * Resolve a local template from a filesystem path
+ */
+async function resolveLocalTemplate(templatePath, options = {}) {
+  const { onProgress } = options
+
+  // Expand ~ to home directory
+  let resolvedPath = templatePath.startsWith('~')
+    ? templatePath.replace(/^~/, homedir())
+    : templatePath
+
+  // Resolve to absolute path
+  resolvedPath = resolve(resolvedPath)
+
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`Local template not found: ${resolvedPath}`)
+  }
+
+  onProgress?.(`Using local template: ${resolvedPath}`)
+
+  // Read template.json for name
+  const metaPath = join(resolvedPath, 'template.json')
+  let name = templatePath
+  if (existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(await readFile(metaPath, 'utf-8'))
+      name = meta.name || templatePath
+    } catch {
+      // Use path as name if template.json can't be parsed
+    }
+  }
+
+  return {
+    type: 'local',
+    name,
+    path: resolvedPath,
+    cleanup: null
+  }
+}
+
+// Re-export for convenience
+export {
+  parseTemplateId,
+  getTemplateDisplayName,
+  BUILTIN_TEMPLATES,
+  OFFICIAL_TEMPLATES,
+  buildTemplateChoices,
+  templatePickerPageSize
+}