uniweb 0.87.4 → 0.88.1

package/src/templates/fetchers/release.js

@@ -14,43 +14,32 @@ import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.
 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
+ * Fetch manifest.json from one release of the official templates.
+ *
+ * ⛔ Always a named release — the one the CLI was published with — and never
+ * `latest`: the latest templates can be newer than the packages this CLI pins
+ * (templates/resolver.js, OFFICIAL_TEMPLATES_RELEASE).
  *
  * @param {Object} options - Fetch options
- * @param {string} options.version - Specific version tag (default: latest)
+ * @param {string} options.version - The release tag, e.g. `v0.18.4`
  * @param {Function} options.onProgress - Progress callback
- * @returns {Promise<Object>} { version, templates, downloadUrl }
+ * @returns {Promise<Object>} { version, templates, downloadUrlBase }
  */
 export async function fetchManifest(options = {}) {
   const { version, onProgress } = options
-
-  // Return cached manifest if available and no specific version requested
-  if (manifestCache && !version) {
-    return manifestCache
-  }
+  if (!version) throw new Error('fetchManifest needs the release tag to read')
 
   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()
-  })
+  const releaseResponse = await fetchWithRetry(
+    `${GITHUB_API}/repos/${TEMPLATES_REPO}/releases/tags/${version}`,
+    { 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}`
-      )
+      throw new Error(`Release ${version} not found for ${TEMPLATES_REPO}`)
     }
     await handleGitHubError(releaseResponse)
   }
@@ -80,28 +69,20 @@ export async function fetchManifest(options = {}) {
 
   const manifest = await manifestResponse.json()
 
-  // Build result with download URL base
-  const result = {
+  return {
     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
+ * 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 - Specific version tag (default: latest)
+ * @param {string} options.version - The release tag, e.g. `v0.18.4`
  * @param {Function} options.onProgress - Progress callback
  * @returns {Promise<Object>} { tempDir, version, metadata }
  */
@@ -166,33 +147,6 @@ export async function fetchOfficialTemplate(name, options = {}) {
   }
 }
 
-/**
- * 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
  */

package/src/templates/index.js

@@ -12,15 +12,13 @@ import {
   getTemplateDisplayName,
   BUILTIN_TEMPLATES,
   OFFICIAL_TEMPLATES,
-  buildTemplateChoices
+  OFFICIAL_TEMPLATES_RELEASE,
+  buildTemplateChoices,
+  templatePickerPageSize
 } from './resolver.js'
 import { fetchNpmTemplate } from './fetchers/npm.js'
 import { fetchGitHubTemplate } from './fetchers/github.js'
-import {
-  fetchOfficialTemplate,
-  listOfficialTemplates
-} from './fetchers/release.js'
-import { validateTemplate } from './validator.js'
+import { fetchOfficialTemplate } from './fetchers/release.js'
 
 /**
  * Resolve a template identifier and return the template path
@@ -61,12 +59,20 @@ export async function resolveTemplate(identifier, options = {}) {
 }
 
 /**
- * Resolve an official template from GitHub releases
+ * 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
   })
 
@@ -173,35 +179,12 @@ async function resolveLocalTemplate(templatePath, options = {}) {
   }
 }
 
-/**
- * List all available templates
- */
-export async function listAvailableTemplates() {
-  const 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
-}
-
 // Re-export for convenience
 export {
   parseTemplateId,
   getTemplateDisplayName,
   BUILTIN_TEMPLATES,
   OFFICIAL_TEMPLATES,
-  buildTemplateChoices
+  buildTemplateChoices,
+  templatePickerPageSize
 }

package/src/templates/resolver.js

@@ -2,93 +2,48 @@
  * Template resolver - parses template identifiers and determines source type
  */
 
-import { readFileSync, statSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
+import { loadFrameworkIndex } from '../versions.js'
 
 // Built-in templates (programmatic, not file-based)
 export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
 
 /**
- * Load the official template metadata map — `{ id: { name, description,
- * tags } }`, keyed by template id.
- *
- * There are two sources of truth depending on where the CLI is running:
+ * THE OFFICIAL TEMPLATES THIS CLI SCAFFOLDS — one snapshot.
  *
- * 1. **Local dev inside the Uniweb monorepo** — the authoritative file
- *    is `framework/templates/manifest.json`. Adding a new template
- *    there makes it immediately reachable from any locally-run CLI
- *    without republishing. This is the only path that matters for
- *    `node scripts/framework/sandbox.js create`.
+ * `../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.
  *
- * 2. **Published CLI (npm-installed)** — the monorepo isn't on disk, so
- *    we read the vendored framework index at `../framework-index.json`,
- *    which the publish pipeline rewrites just before `pnpm publish` runs,
- *    copying the manifest's `templates` verbatim. The framework index is a
- *    single snapshot file that also carries `@uniweb/*` package versions
- *    (consumed by versions.js), so both the template list and the version
- *    resolver share one source of truth.
+ * ⛔ 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.
  *
- * When both sources are available (local dev with a committed snapshot),
- * the live workspace manifest wins so newly-added templates are visible
- * without waiting for a CLI republish.
- *
- * Both files store `templates` as the same `{ id: { name, description,
- * tags } }` shape, so one map feeds both name-resolution
- * (OFFICIAL_TEMPLATES) and the interactive picker (buildTemplateChoices) —
- * neither hardcodes a list. (An earlier version returned only the keys and
- * left the `create` picker with its own hardcoded array, which silently
- * drifted out of sync whenever a template was added.)
+ * (An earlier version still hardcoded the picker's list, which silently
+ * drifted whenever a template was added — the reason no list is written here.)
  */
-function loadOfficialTemplateMap() {
-  // Local dev: framework/templates/manifest.json relative to this file
-  // at framework/cli/src/templates/resolver.js
-  const workspaceManifest = join(
-    __dirname,
-    '..',
-    '..',
-    '..',
-    'templates',
-    'manifest.json'
-  )
-  const picked = tryReadTemplateMap(workspaceManifest)
-  if (picked) return picked
-
-  // Published CLI fallback: the framework index snapshot, one directory
-  // up at framework/cli/src/framework-index.json.
-  const indexPath = join(__dirname, '..', 'framework-index.json')
-  const fromIndex = tryReadTemplateMap(indexPath)
-  if (fromIndex) return fromIndex
-
-  // If both sources fail, return an empty map rather than a stale
-  // hardcoded list. An unknown template name then falls through to
-  // the npm `@uniweb/template-<name>` lookup path, which is the
-  // intended behavior for third-party templates.
-  return {}
-}
-
-function tryReadTemplateMap(path) {
-  try {
-    if (!statSync(path).isFile()) return null
-    const data = JSON.parse(readFileSync(path, 'utf8'))
-    if (data && data.templates && typeof data.templates === 'object') {
-      return data.templates
-    }
-  } catch {}
-  return null
-}
+const INDEX = loadFrameworkIndex()
 
-// Official template metadata keyed by id. Derived from manifest.json (local
-// dev) or framework-index.json (published CLI) at module load time — see
-// loadOfficialTemplateMap() for details. Read once per process; to reflect a
-// just-added template, restart the CLI or rerun the scaffolder.
-export const OFFICIAL_TEMPLATE_MAP = loadOfficialTemplateMap()
+// 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 = [
@@ -128,6 +83,24 @@ export function buildTemplateChoices() {
   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
  *

package/src/templates/validator.js

@@ -1,84 +1,25 @@
 /**
- * Template validation - checks template.json and compatibility
+ * Template validation — reads template.json and finds the content directories
+ *
+ * ⛔ Two things this used to do are retired [2026-10-08]:
+ *   - `compatible` (alias `uniweb`), a CLI version range a template declared. It
+ *     was checked only when a caller passed the CLI's version, and none ever
+ *     did. An official template now comes from the release its CLI was
+ *     published with (resolver.js), so it cannot be newer than that CLI.
+ *   - Unwrapping a package folder that keeps its code under `src/` — the layout of
+ *     the v0.7 releases (`foundation/src/foundation.js`). Such a folder is now
+ *     REFUSED, naming the fix (validateTemplate). ⛔ The unwrap went in 0.88.0
+ *     with a note that the official templates were flat, but its condition was any
+ *     `src/main.js` too, and `extensions/effects/` still relied on it: 0.88.0
+ *     copied that folder nested, and every project made from `extensions` failed
+ *     to build, saying only that it found no section types. The template is flat
+ *     since templates 0.18.6.
  */
 
 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
  */
@@ -96,20 +37,16 @@ export const ErrorCodes = {
   INVALID_TEMPLATE_JSON: 'INVALID_TEMPLATE_JSON',
   MISSING_CONTENT_DIR: 'MISSING_CONTENT_DIR',
   MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
-  VERSION_MISMATCH: 'VERSION_MISMATCH'
+  NESTED_PACKAGE_CODE: 'NESTED_PACKAGE_CODE'
 }
 
 /**
  * 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
-
+export async function validateTemplate(templateRoot) {
   // Check for template.json
   const metadataPath = path.join(templateRoot, 'template.json')
   if (!existsSync(metadataPath)) {
@@ -142,18 +79,6 @@ export async function validateTemplate(templateRoot, options = {}) {
     )
   }
 
-  // Check version compatibility (support both `compatible` and `uniweb` fields)
-  const versionRange = metadata.compatible || metadata.uniweb
-  if (uniwebVersion && versionRange) {
-    if (!satisfiesVersion(uniwebVersion, versionRange)) {
-      throw new ValidationError(
-        `Template requires Uniweb ${versionRange}, but current version is ${uniwebVersion}`,
-        ErrorCodes.VERSION_MISMATCH,
-        { required: versionRange, current: uniwebVersion }
-      )
-    }
-  }
-
   // Format 2: content template — foundation/ and/or site/ directories alongside template.json
   const contentDirs = resolveContentDirs(templateRoot, metadata)
 
@@ -165,6 +90,23 @@ export async function validateTemplate(templateRoot, options = {}) {
     )
   }
 
+  // A foundation or extension folder is copied over the package the CLI
+  // scaffolds, as it is. Code kept under src/ would land beside the scaffold's
+  // own empty sections/, and the project would fail to build saying only that it
+  // found no section types — so it stops here, saying what to move.
+  for (const { type, name, dir } of contentDirs) {
+    if (type !== 'foundation' && type !== 'extension') continue
+    if (['main.js', 'foundation.js'].some((file) => existsSync(path.join(dir, 'src', file)))) {
+      throw new ValidationError(
+        `The template's ${name}/ keeps its code in ${name}/src/, a layout this CLI does not scaffold. ` +
+          `A foundation or extension folder holds main.js, sections/ and styles.css at its root: ` +
+          `move ${name}/src/'s contents up into ${name}/.`,
+        ErrorCodes.NESTED_PACKAGE_CODE,
+        { dir }
+      )
+    }
+  }
+
   return {
     ...metadata,
     format: 2,
@@ -178,7 +120,7 @@ export async function validateTemplate(templateRoot, options = {}) {
  *
  * @param {string} templateRoot - Root of the template (contains template.json)
  * @param {Object} metadata - Parsed template.json
- * @returns {Array<Object>} Content directories: [{ type, name, dir, foundation?, renames? }]
+ * @returns {Array<Object>} Content directories: [{ type, name, dir, foundation? }]
  */
 export function resolveContentDirs(templateRoot, metadata) {
   const dirs = []
@@ -188,29 +130,19 @@ export function resolveContentDirs(templateRoot, metadata) {
     for (const pkg of metadata.packages) {
       const dir = path.join(templateRoot, pkg.name)
       if (existsSync(dir)) {
-        const entry = {
+        dirs.push({
           type: pkg.type,
           name: pkg.name,
           dir,
           ...(pkg.foundation ? { foundation: pkg.foundation } : {})
-        }
-        if (entry.type === 'foundation' || entry.type === 'extension') {
-          applyLegacyFoundationLayout(entry)
-        }
-        dirs.push(entry)
+        })
       }
     }
   } else {
     // Standard template: look for foundation/ and site/
     const foundationDir = path.join(templateRoot, 'foundation')
     if (existsSync(foundationDir)) {
-      const entry = {
-        type: 'foundation',
-        name: 'foundation',
-        dir: foundationDir
-      }
-      applyLegacyFoundationLayout(entry)
-      dirs.push(entry)
+      dirs.push({ type: 'foundation', name: 'foundation', dir: foundationDir })
     }
 
     const siteDir = path.join(templateRoot, 'site')
@@ -221,83 +153,3 @@ export function resolveContentDirs(templateRoot, metadata) {
 
   return dirs
 }
-
-/**
- * Detect and unwrap the legacy foundation layout.
- *
- * Old templates (published in the `uniweb/templates` releases up to
- * v0.7.x) shipped foundation content nested one level deeper, with the
- * package source under `foundation/src/` and the user-authored
- * declarations file named `foundation.js`:
- *
- *     <template>/foundation/src/foundation.js
- *     <template>/foundation/src/sections/...
- *     <template>/foundation/src/components/...
- *
- * The current layout is flat — the foundation package root contains
- * the source directly, and the declarations file is named `main.js`:
- *
- *     <template>/foundation/main.js
- *     <template>/foundation/sections/...
- *
- * The CLI scaffolds the new flat shape into the project's `src/`
- * directory, so an unmodified copy of an old-format template would
- * land at `src/src/foundation.js` (extra `src/` layer + old name).
- *
- * This helper detects the legacy marker (`<dir>/src/foundation.js`),
- * mutates the contentDir entry to point at the inner `src/` directory,
- * and records a top-level rename so `foundation.js` is written as
- * `main.js`. Once `uniweb/templates` is republished with the flat
- * layout, this branch becomes a no-op.
- */
-function applyLegacyFoundationLayout(entry) {
-  const innerSrc = path.join(entry.dir, 'src')
-  if (!existsSync(innerSrc)) return
-
-  const legacyMain = path.join(innerSrc, 'foundation.js')
-  const newMain = path.join(innerSrc, 'main.js')
-  if (!existsSync(legacyMain) && !existsSync(newMain)) return
-
-  entry.dir = innerSrc
-  if (existsSync(legacyMain)) {
-    entry.renames = { ...(entry.renames || {}), 'foundation.js': 'main.js' }
-  }
-}
-
-/**
- * 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
-}