uniweb 0.9.2 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,13 +41,13 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/runtime": "0.7.2",
     "@uniweb/core": "0.6.1",
+    "@uniweb/runtime": "0.7.3",
     "@uniweb/kit": "0.8.1"
   },
   "peerDependencies": {
+    "@uniweb/build": "0.9.3",
     "@uniweb/content-reader": "1.1.4",
-    "@uniweb/build": "0.9.2",
     "@uniweb/semantic-parser": "1.1.9"
   },
   "peerDependenciesMeta": {

package/src/templates/official-templates.snapshot.json

@@ -0,0 +1,50 @@
+{
+  "version": "1.0.0",
+  "templates": {
+    "marketing": {
+      "name": "Marketing Starter",
+      "description": "Landing pages and marketing sites with Tailwind CSS v4",
+      "tags": ["marketing", "landing-page", "tailwind"]
+    },
+    "academic": {
+      "name": "Academic",
+      "description": "Academic sites for researchers, labs, and departments",
+      "tags": ["academic", "research", "portfolio"]
+    },
+    "docs": {
+      "name": "Documentation",
+      "description": "Documentation sites with navigation levels",
+      "tags": ["docs", "documentation", "technical"]
+    },
+    "international": {
+      "name": "International Business",
+      "description": "Multilingual corporate website with English, Spanish, and French",
+      "tags": ["i18n", "multilingual", "corporate", "business", "localization"]
+    },
+    "dynamic": {
+      "name": "Dynamic Data",
+      "description": "Live API data fetching with loading states, transforms, and the portable data pattern",
+      "tags": ["data", "api", "fetch", "loading-states", "dynamic"]
+    },
+    "store": {
+      "name": "Solis Artisans - Store",
+      "description": "Artisan e-commerce with product collections, Shopify Buy Button, journal blog, and stone-amber design",
+      "tags": ["store", "e-commerce", "shopify", "artisan", "products"]
+    },
+    "learning": {
+      "name": "Learning Platform",
+      "description": "Course-based learning site with quizzes, code challenges, and AI grading integration",
+      "tags": ["learning", "course", "education", "quiz", "lms", "tutorial"]
+    },
+    "extensions": {
+      "name": "Extensions Demo",
+      "description": "Primary foundation with a visual effects extension, demonstrating multi-foundation sites",
+      "tags": ["extensions", "multi-foundation", "visual-effects", "runtime"]
+    },
+    "cv": {
+      "name": "CV (Docusite)",
+      "description": "An academic CV as a docusite — a URL whose content is also a downloadable Microsoft Word document. Ships with a full Charles Darwin sample CV and demonstrates the one-foundation-many-tenants pattern for download-time theming.",
+      "tags": ["cv", "resume", "docusite", "academic", "document", "press"]
+    }
+  }
+}

package/src/templates/resolver.js

@@ -2,11 +2,76 @@
  * 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))
+
 // Built-in templates (programmatic, not file-based)
 export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
 
-// Official templates from @uniweb/templates package (downloaded from GitHub releases)
-export const OFFICIAL_TEMPLATES = ['marketing', 'academic', 'docs', 'international', 'dynamic', 'store', 'learning', 'extensions', 'cv']
+/**
+ * Load the list of official template names.
+ *
+ * There are two sources of truth depending on where the CLI is running:
+ *
+ * 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`.
+ *
+ * 2. **Published CLI (npm-installed)** — the monorepo isn't on disk, so
+ *    we read a vendored snapshot file (`./official-templates.snapshot.json`)
+ *    that the publish script rewrites from the workspace manifest just
+ *    before `pnpm publish` runs. The snapshot is committed so every CLI
+ *    version in git carries the template list it shipped with.
+ *
+ * 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.
+ *
+ * The previous implementation hardcoded a string array here, which
+ * silently duplicated `framework/templates/manifest.json` and required
+ * a two-repo edit whenever a template was added.
+ */
+function loadOfficialTemplateList() {
+  // 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 = tryReadManifest(workspaceManifest)
+  if (picked) return picked
+
+  // Published CLI fallback: vendored snapshot next to this file
+  const snapshotPath = join(__dirname, 'official-templates.snapshot.json')
+  const snapshot = tryReadManifest(snapshotPath)
+  if (snapshot) return snapshot
+
+  // If both fail, return an empty list rather than a stale hardcoded
+  // array. 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 tryReadManifest(path) {
+  try {
+    if (!statSync(path).isFile()) return null
+    const manifest = JSON.parse(readFileSync(path, 'utf8'))
+    if (manifest && manifest.templates && typeof manifest.templates === 'object') {
+      return Object.keys(manifest.templates)
+    }
+  } catch {}
+  return null
+}
+
+// Official templates from the templates repo. Derived from manifest.json
+// at module load time — see loadOfficialTemplateList() for the two source
+// paths (local workspace vs. vendored snapshot). If the list needs to
+// reflect a just-added template, restart the CLI process or rerun the
+// scaffolder; this constant is read once per process.
+export const OFFICIAL_TEMPLATES = loadOfficialTemplateList()
 
 /**
  * Parse a template identifier and determine its source type

package/src/utils/scaffold.js

@@ -10,6 +10,7 @@ import { existsSync, readdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import yaml from 'js-yaml'
+import Handlebars from 'handlebars'
 import { copyTemplateDirectory, registerVersions } from '../templates/processor.js'
 import { getVersionsForTemplates, getCliVersion } from '../versions.js'
 
@@ -157,19 +158,38 @@ async function copyContentRecursive(sourceDir, targetDir, context, structuralFil
         newContent = template(context)
       }
 
-      // Merge config files instead of overwriting
+      // Merge config files instead of overwriting.
+      //
+      // The "merge" here is narrow: take the content template's output
+      // as the source of truth (so comments, formatting, and the full
+      // educational structure of the content template survive) and
+      // override only the specific top-level keys listed in
+      // preserveKeys with the values from the already-scaffolded base
+      // file (so the user's chosen project name and foundation ref
+      // don't get replaced by whatever the content template hardcoded).
+      //
+      // Earlier versions of this code parsed both files through
+      // js-yaml, merged the objects, and re-emitted the result via
+      // yaml.dump() — which stripped every comment and blank line on
+      // the way through. For templates like `cv/site/site.yml.hbs`
+      // whose comments are the template's educational payload, that
+      // was devastating. The line-level override below preserves the
+      // content template's text verbatim except for the preserved keys.
       const preserveKeys = mergeFiles[outputName]
       if (preserveKeys && existsSync(targetPath)) {
         const existingContent = await fs.readFile(targetPath, 'utf-8')
         const existing = yaml.load(existingContent) || {}
-        const incoming = yaml.load(newContent || await fs.readFile(sourcePath, 'utf-8')) || {}
+        let merged = newContent ?? await fs.readFile(sourcePath, 'utf-8')
 
-        // Template values as base, preserve specified keys from scaffolded version
-        const merged = { ...incoming }
         for (const key of preserveKeys) {
-          if (existing[key] !== undefined) merged[key] = existing[key]
+          if (existing[key] === undefined) continue
+          const baseLine = matchTopLevelLine(existingContent, key)
+          if (baseLine) {
+            merged = replaceTopLevelLine(merged, key, baseLine)
+          }
         }
-        await fs.writeFile(targetPath, yaml.dump(merged, { lineWidth: -1 }))
+
+        await fs.writeFile(targetPath, merged)
       } else if (newContent !== undefined) {
         await fs.writeFile(targetPath, newContent)
       } else {
@@ -208,14 +228,76 @@ export async function applyStarter(projectDir, context, options = {}) {
   await applyContent(siteContentDir, siteTargetDir, context, options)
 }
 
+/**
+ * Escape a string for safe inclusion in a RegExp literal. Used by the
+ * site.yml line-level merge path.
+ */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Find the verbatim text of a single-line top-level YAML entry like
+ * `name: foo bar` or `foundation: my-foundation`. Returns the matched
+ * line (including any inline comment) or null if the key isn't present.
+ * Multi-line values (block scalars, nested maps) are deliberately
+ * unsupported — the merge path only uses this for simple scalar keys.
+ */
+function matchTopLevelLine(content, key) {
+  const match = content.match(new RegExp(`^${escapeRegex(key)}:.*$`, 'm'))
+  return match ? match[0] : null
+}
+
+/**
+ * Replace the verbatim text of a single-line top-level YAML entry.
+ * Returns the content unchanged if the key isn't present. See
+ * matchTopLevelLine for scope.
+ */
+function replaceTopLevelLine(content, key, replacement) {
+  return content.replace(
+    new RegExp(`^${escapeRegex(key)}:.*$`, 'm'),
+    () => replacement,
+  )
+}
+
+/**
+ * Resolve a dependency version string from a template.json entry.
+ *
+ * Template authors can either hardcode a concrete spec (`"^0.2.1"`) or
+ * use the same `{{version}}` Handlebars helper that `package.json.hbs`
+ * uses (`"{{version \"@uniweb/press\"}}"`). The helper is populated
+ * earlier in the scaffold flow via `registerVersions()`, so by the time
+ * this runs `versionData` already holds the current on-disk versions
+ * of every `@uniweb/*` package.
+ *
+ * Plain strings without `{{…}}` pass through untouched. Strings that
+ * fail to compile (rare — e.g. malformed mustache) fall back to the
+ * original literal so a bad template.json doesn't break scaffolding.
+ */
+function resolveDependencyVersion(rawValue) {
+  if (typeof rawValue !== 'string' || !rawValue.includes('{{')) {
+    return rawValue
+  }
+  try {
+    return Handlebars.compile(rawValue)({})
+  } catch {
+    return rawValue
+  }
+}
+
 /**
  * Merge additional dependencies from a content template into a scaffolded package.json
  *
  * Reads the package.json at the given path, adds any deps not already present
  * (in either dependencies or devDependencies), and writes it back.
  *
+ * Each version string in `deps` is first processed through the shared
+ * Handlebars pipeline so template.json entries can reference live
+ * workspace versions via `{{version "@uniweb/press"}}` instead of
+ * hardcoding a spec that goes stale on the next publish.
+ *
  * @param {string} packageJsonPath - Absolute path to package.json
- * @param {Object} deps - Dependencies to merge (name → version)
+ * @param {Object} deps - Dependencies to merge (name → version spec)
  */
 export async function mergeTemplateDependencies(packageJsonPath, deps) {
   if (!deps || Object.keys(deps).length === 0) return
@@ -223,7 +305,7 @@ export async function mergeTemplateDependencies(packageJsonPath, deps) {
   if (!pkg.dependencies) pkg.dependencies = {}
   for (const [name, version] of Object.entries(deps)) {
     if (!pkg.dependencies[name] && !pkg.devDependencies?.[name]) {
-      pkg.dependencies[name] = version
+      pkg.dependencies[name] = resolveDependencyVersion(version)
     }
   }
   await fs.writeFile(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n')