uniweb 0.9.2 → 0.9.4

package/package.json

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

package/src/framework-index.json

@@ -0,0 +1,203 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-04-15T22:47:02.926Z",
+  "packages": {
+    "@uniweb/build": {
+      "version": "0.9.3",
+      "path": "framework/build",
+      "deps": [
+        "@uniweb/content-reader",
+        "@uniweb/core",
+        "@uniweb/runtime",
+        "@uniweb/schemas",
+        "@uniweb/theming"
+      ]
+    },
+    "@uniweb/content-reader": {
+      "version": "1.1.4",
+      "path": "framework/content-reader",
+      "deps": []
+    },
+    "@uniweb/content-writer": {
+      "version": "0.2.3",
+      "path": "framework/content-writer",
+      "deps": []
+    },
+    "@uniweb/core": {
+      "version": "0.6.1",
+      "path": "framework/core",
+      "deps": [
+        "@uniweb/semantic-parser",
+        "@uniweb/theming"
+      ]
+    },
+    "@uniweb/frame-bridge": {
+      "version": "0.2.3",
+      "path": "framework/frame-bridge",
+      "deps": []
+    },
+    "@uniweb/icons": {
+      "version": "0.1.0",
+      "path": "framework/icons",
+      "deps": []
+    },
+    "@uniweb/kit": {
+      "version": "0.8.1",
+      "path": "framework/kit",
+      "deps": [
+        "@uniweb/core"
+      ]
+    },
+    "@uniweb/loom": {
+      "version": "0.2.1",
+      "path": "framework/loom",
+      "deps": []
+    },
+    "@uniweb/press": {
+      "version": "0.2.1",
+      "path": "framework/press",
+      "deps": []
+    },
+    "@uniweb/runtime": {
+      "version": "0.7.3",
+      "path": "framework/runtime",
+      "deps": [
+        "@uniweb/core",
+        "@uniweb/theming"
+      ]
+    },
+    "@uniweb/schemas": {
+      "version": "0.2.1",
+      "path": "framework/schemas",
+      "deps": []
+    },
+    "@uniweb/scholar": {
+      "version": "0.2.1",
+      "path": "framework/scholar",
+      "deps": []
+    },
+    "@uniweb/semantic-parser": {
+      "version": "1.1.9",
+      "path": "framework/semantic-parser",
+      "deps": []
+    },
+    "@uniweb/templates": {
+      "version": "0.7.23",
+      "path": "framework/templates",
+      "deps": []
+    },
+    "@uniweb/theming": {
+      "version": "0.1.3",
+      "path": "framework/theming",
+      "deps": []
+    }
+  },
+  "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"
+      ]
+    },
+    "cv-loom": {
+      "name": "CV (Loom-instantiated)",
+      "description": "A single-page narrative CV whose prose is written with {placeholder} expressions and instantiated at render time via the foundation content handler and @uniweb/loom. Reference implementation of the handler hook.",
+      "tags": [
+        "cv",
+        "loom",
+        "template-engine",
+        "content-handler",
+        "dynamic-prose",
+        "academic"
+      ]
+    }
+  }
+}

package/src/templates/resolver.js

@@ -2,11 +2,81 @@
  * 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 the vendored framework index at `../framework-index.json`,
+ *    which the publish pipeline's pre-publish hook rewrites just before
+ *    `pnpm publish` runs. 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.
+ *
+ * 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. The one before THAT
+ * (v0.9.3) used a separate `./official-templates.snapshot.json` file;
+ * it has been retired in favor of the shared framework index.
+ */
+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 = tryReadTemplateKeys(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 = tryReadTemplateKeys(indexPath)
+  if (fromIndex) return fromIndex
+
+  // If both sources 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 tryReadTemplateKeys(path) {
+  try {
+    if (!statSync(path).isFile()) return null
+    const data = JSON.parse(readFileSync(path, 'utf8'))
+    if (data && data.templates && typeof data.templates === 'object') {
+      return Object.keys(data.templates)
+    }
+  } catch {}
+  return null
+}
+
+// Official templates from the templates repo. Derived from manifest.json
+// (local dev) or framework-index.json (published CLI) at module load
+// time — see loadOfficialTemplateList() for details. 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')

package/src/versions.js

@@ -96,12 +96,61 @@ function readWorkspaceVersion(packageName) {
   return null
 }
 
+/**
+ * Load the vendored framework index file (see
+ * `./framework-index.json`). The index is a snapshot of the framework
+ * state taken at CLI publish time — every `@uniweb/*` package name,
+ * version, path, and inter-package dep edges, plus the template list.
+ *
+ * The snapshot is the only way a published CLI (running from
+ * `node_modules/uniweb/…`, with no workspace on disk) can resolve
+ * versions for packages it doesn't directly import (press, loom,
+ * scholar, etc.). Without it, Handlebars helpers like
+ * `{{version "@uniweb/press"}}` fall through to a bogus default.
+ *
+ * Returns null if the file doesn't exist, is unparseable, or has a
+ * schema version we don't understand. Callers treat null as "no
+ * snapshot available" and fall back to their next source.
+ */
+function loadFrameworkIndex() {
+  const indexPath = join(__dirname, 'framework-index.json')
+  try {
+    const raw = readFileSync(indexPath, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (parsed && parsed.schemaVersion === 1 && parsed.packages) {
+      return parsed
+    }
+  } catch {}
+  return null
+}
+
+/**
+ * Pull `@uniweb/*` package versions out of the framework index's
+ * `packages` field and format them as caret ranges. Used as the
+ * published-CLI fallback source after the CLI's own deps and the live
+ * workspace walk both come up empty.
+ */
+function readIndexPackages() {
+  const index = loadFrameworkIndex()
+  if (!index) return {}
+  const result = {}
+  for (const [name, entry] of Object.entries(index.packages)) {
+    if (entry && entry.version) {
+      result[name] = `^${entry.version}`
+    }
+  }
+  return result
+}
+
 /**
  * Enumerate every `@uniweb/*` package under `framework/*` and return a
  * map of `{ name: '^version' }`. Used to seed the resolved-versions
  * cache so that packages not explicitly listed in the CLI's own deps
  * (press, loom, scholar, schemas, etc.) still have a version available
  * to templates that reference them.
+ *
+ * Works only in the monorepo. Published CLIs fall through to the
+ * framework-index snapshot via readIndexPackages() instead.
  */
 function discoverWorkspacePackages() {
   const root = getFrameworkRoot()
@@ -145,17 +194,23 @@ function resolveVersionSpec(spec, packageName) {
  * Get resolved versions for @uniweb/* packages.
  *
  * Priority (highest first):
+ *
  *   1. A concrete version spec already in the CLI's own `package.json`
- *      (the state after an npm publish: `workspace:*` is resolved to a
- *      real version).
- *   2. The on-disk version of the matching workspace package (the state
- *      during local development).
- *   3. Discovery fallback — every `@uniweb/*` package found under
- *      `framework/*`, for packages that aren't in the CLI's own deps.
+ *      (the state after an npm publish: `workspace:*` is resolved by
+ *      pnpm to a real version).
+ *   2. Live workspace walk — every `@uniweb/*` package found under
+ *      `framework/*` at CLI invocation time. This is the path that
+ *      matters for local dev: a freshly-added package becomes
+ *      reachable from every locally-run CLI without republishing.
+ *   3. Framework index snapshot — `./framework-index.json`, written by
+ *      the publish pipeline's pre-publish hook. This is the path that
+ *      matters for published CLIs: the monorepo isn't on disk, so the
+ *      snapshot is how the CLI knows about packages it doesn't import
+ *      directly (press, loom, scholar, schemas, …).
  *
- * The return shape is stable across both paths: a map of package names to
- * npm-compatible version specs, plus the CLI's own version under the key
- * `uniweb`.
+ * The return shape is stable across all paths: a map of package names
+ * to npm-compatible version specs, plus the CLI's own version under
+ * the key `uniweb`.
  *
  * @returns {Object} Map of package names to version specs
  */
@@ -173,14 +228,24 @@ export function getResolvedVersions() {
     if (resolved) result[name] = resolved
   }
 
-  // Merge in anything under framework/* that the CLI didn't list explicitly.
-  // A newly-added package (e.g. @uniweb/press) becomes reachable via
-  // {{version "@uniweb/press"}} without touching the CLI's package.json.
+  // Layer in the live workspace walk. Overrides nothing (dev versions
+  // are fresher than anything in the CLI's own deps), but fills in
+  // packages the CLI doesn't reference directly.
   const discovered = discoverWorkspacePackages()
   for (const [name, version] of Object.entries(discovered)) {
     if (!result[name]) result[name] = version
   }
 
+  // Final fallback: the vendored framework index snapshot. Only hits
+  // when the workspace walk came up empty for a package (published
+  // CLI running outside the monorepo). The snapshot is refreshed at
+  // publish time, so its view of the world is current as of the CLI's
+  // own publish.
+  const indexed = readIndexPackages()
+  for (const [name, version] of Object.entries(indexed)) {
+    if (!result[name]) result[name] = version
+  }
+
   // CLI itself. Caret on the current version — templates referencing
   // `{{version "uniweb"}}` pick up whatever patch/minor ships in the
   // same publish cycle as the template.