uniweb 0.12.40 → 0.12.42

package/README.md

@@ -347,10 +347,11 @@ Markdown in a git repo and content in the Uniweb apps can share the same site. D
 | Command | What it does |
 | --- | --- |
 | `uniweb add ci --host=<adapter>` | Scaffold a CI workflow in your repo (today: `github-pages`). The host runs `uniweb build` on each push. |
-| `uniweb deploy` | Deploy to Uniweb hosting (default). With `--host=<adapter>`, push directly to a static host — builds, uploads, invalidates in one step. |
+| `uniweb publish` | Go live on Uniweb hosting (paid) — syncs content, brings the site's foundation along, and serves dynamically. The canonical verb for Uniweb hosting. |
+| `uniweb deploy --host=<adapter>` | Ship to a third-party static host in one step — builds `dist/`, uploads, invalidates. |
 | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
 | `uniweb register --scope @org` | Register a foundation to the registry (path 2). |
-| `uniweb build` | Inspect a build locally. For shipping, use `deploy` or `export`. |
+| `uniweb build` | Inspect a build locally. For shipping, use `publish` (Uniweb hosting) or `deploy`/`export` (static hosts). |
 | `uniweb update` | Align this project with the CLI you're running: bump `@uniweb/*` deps in every `package.json` to the CLI's matrix (then install), and refresh `AGENTS.md`. Pins to *this* CLI's matrix — run `npx uniweb@latest update` to align to the latest release. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`). |
 
 `--host=<adapter>` is the same option across `deploy`, `export`, and `add ci`. Built-in adapters: `cloudflare-pages`, `netlify`, `github-pages`, `vercel`, `s3-cloudfront`, `generic-static`. Each adapter implements only the operations it supports — `add ci` is currently `github-pages`-only because it's the only one that needs a workflow file in the repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.40",
+  "version": "0.12.42",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -46,8 +46,8 @@
     "@uniweb/runtime": "0.8.22"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.23",
     "@uniweb/content-reader": "1.1.12",
+    "@uniweb/build": "0.14.24",
     "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {

package/src/commands/add.js

@@ -31,7 +31,7 @@ import { detectPackageManager, filterCmd, installCmd } from '../utils/pm.js'
 import { isNonInteractive, getCliPrefix, stripNonInteractiveFlag, formatOptions } from '../utils/interactive.js'
 import { resolveTemplate } from '../templates/index.js'
 import { validateTemplate } from '../templates/validator.js'
-import { getVersionsForTemplates } from '../versions.js'
+import { getVersionsForTemplates, PNPM_VERSION } from '../versions.js'
 
 // Colors for terminal output
 const colors = {
@@ -952,7 +952,7 @@ export default function ${name}({ content, params }) {
  * Add a CI deploy workflow for a host adapter.
  *
  * Wires through the host-adapter registry: each adapter optionally
- * exports `initCi({ rootDir, site, packageManager, nodeVersion })`
+ * exports `initCi({ rootDir, site, packageManager, nodeVersion, pnpmVersion })`
  * returning `{ files, postInstructions }`. The CLI handles file writes,
  * --force overwrite, and consistent output. Today only github-pages
  * implements initCi; the registry's other adapters (cloudflare-pages,
@@ -1069,6 +1069,7 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
     site,
     packageManager: pm,
     nodeVersion,
+    pnpmVersion: PNPM_VERSION,
     domain: resolvedDomain,
   })
 

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-13T17:29:11.603Z",
+  "generatedAt": "2026-07-14T12:34:40.728Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.23",
+      "version": "0.14.24",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -89,7 +89,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.7.42",
+      "version": "0.7.44",
       "path": "framework/templates",
       "deps": []
     },
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.30",
+      "version": "0.4.32",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",
@@ -112,7 +112,7 @@
   },
   "templates": {
     "marketing": {
-      "name": "Marketing Starter",
+      "name": "Marketing",
       "description": "Landing pages and marketing sites with Tailwind CSS v4",
       "tags": [
         "marketing",
@@ -130,7 +130,7 @@
       ]
     },
     "docs": {
-      "name": "Documentation",
+      "name": "Docs",
       "description": "Documentation sites with navigation levels",
       "tags": [
         "docs",
@@ -139,7 +139,7 @@
       ]
     },
     "international": {
-      "name": "International Business",
+      "name": "International",
       "description": "Multilingual corporate website with English, Spanish, and French",
       "tags": [
         "i18n",
@@ -161,7 +161,7 @@
       ]
     },
     "dynamic": {
-      "name": "Dynamic Data",
+      "name": "Dynamic",
       "description": "Live API data fetching with loading states, transforms, and the portable data pattern",
       "tags": [
         "data",
@@ -172,7 +172,7 @@
       ]
     },
     "store": {
-      "name": "Solis Artisans - Store",
+      "name": "Store",
       "description": "Artisan e-commerce with product collections, Shopify Buy Button, journal blog, and stone-amber design",
       "tags": [
         "store",
@@ -183,7 +183,7 @@
       ]
     },
     "learning": {
-      "name": "Learning Platform",
+      "name": "Learning",
       "description": "Course-based learning site with quizzes, code challenges, and AI grading integration",
       "tags": [
         "learning",
@@ -195,7 +195,7 @@
       ]
     },
     "extensions": {
-      "name": "Extensions Demo",
+      "name": "Extensions",
       "description": "Primary foundation with a visual effects extension, demonstrating multi-foundation sites",
       "tags": [
         "extensions",
@@ -205,7 +205,7 @@
       ]
     },
     "cv-loom": {
-      "name": "CV (Loom-instantiated)",
+      "name": "CV (Loom)",
       "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",
@@ -217,7 +217,7 @@
       ]
     },
     "monograph": {
-      "name": "Monograph (Press showcase)",
+      "name": "Monograph",
       "description": "A richly illustrated long-form document — numbered chapters with nested subsections, figures with captions, data-driven specimen and measurement tables, and a citestyle bibliography. The same JSX drives the themed web preview and a branded .docx with headers, footers, and page numbers. Ships with Darwin's Galapagos observations as sample content.",
       "tags": [
         "monograph",
@@ -230,7 +230,7 @@
       ]
     },
     "academic-metrics": {
-      "name": "Academic Metrics (xlsx showcase)",
+      "name": "Academic Metrics",
       "description": "A docusite whose content is also a downloadable Excel workbook. Aggregates academic metrics (publications, funding, supervisions) across multiple members of a university unit. Rich web previews + flat tabular xlsx sheets from the same data. Ships with three 19th-century naturalists as sample members.",
       "tags": [
         "academic-metrics",
@@ -244,7 +244,7 @@
       ]
     },
     "business-docs": {
-      "name": "Business documents",
+      "name": "Business Documents",
       "description": "A complete business-document site: invoice and SOW collections, per-record preview pages, and a filtered engagement report with XLSX export. Built on @uniweb/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
       "tags": [
         "business-docs",
@@ -256,6 +256,17 @@
         "docx",
         "pagedjs"
       ]
+    },
+    "paste": {
+      "name": "Paste a Design (Level 0)",
+      "description": "Bring an existing React design (AI-generated or hand-built) into Uniweb with zero rewiring — replace App.jsx and run. Ships lucide-react preinstalled and SPA-first. The Level 0 conversion starting point.",
+      "tags": [
+        "paste",
+        "level-0",
+        "convert",
+        "ai-generated",
+        "starter"
+      ]
     }
   }
 }

package/src/index.js

@@ -41,10 +41,11 @@ import { template } from './commands/template.js'
 import {
   resolveTemplate,
   parseTemplateId,
+  buildTemplateChoices,
 } from './templates/index.js'
 import { validateTemplate } from './templates/validator.js'
 import { scaffoldWorkspace, scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies, getWorkspaceTemplateOutputs } from './utils/scaffold.js'
-import { detectPackageManager, filterCmd, installCmd, runCmd } from './utils/pm.js'
+import { detectPackageManager, filterCmd, installCmd, runCmd, isPnpmAvailable } from './utils/pm.js'
 import { isNonInteractive, getCliPrefix, stripNonInteractiveFlag, formatOptions } from './utils/interactive.js'
 import { findWorkspaceRoot } from './utils/workspace.js'
 
@@ -59,19 +60,11 @@ const colors = {
   red: '\x1b[31m',
 }
 
-// Template choices for interactive prompt
-const TEMPLATE_CHOICES = [
-  { title: 'None', value: 'none', description: 'Foundation + site with no content' },
-  { title: 'Starter', value: 'starter', description: 'Foundation + site + sample content' },
-  { title: 'Marketing', value: 'marketing', description: 'Landing page, features, pricing, testimonials' },
-  { title: 'Docs', value: 'docs', description: 'Documentation with sidebar and search' },
-  { title: 'Academic', value: 'academic', description: 'Research site with publications and team' },
-  { title: 'Dynamic', value: 'dynamic', description: 'Live API data fetching with loading states' },
-  { title: 'International', value: 'international', description: 'Multilingual site with i18n and blog' },
-  { title: 'Store', value: 'store', description: 'E-commerce with product grid' },
-  { title: 'Extensions', value: 'extensions', description: 'Multi-foundation with visual effects extension' },
-  { title: 'Blank workspace', value: 'blank', description: 'Empty workspace — grow with uniweb add' },
-]
+// Template choices for the interactive prompt — built-ins first, then every
+// official template from the shared manifest (so the list never drifts from
+// framework/templates/manifest.json), with "Blank" last. Composed by
+// buildTemplateChoices() in templates/resolver.js.
+const TEMPLATE_CHOICES = buildTemplateChoices()
 
 // Files that may pre-exist in the target dir during `uniweb create .` and
 // will be silently overwritten by the scaffold. Anything else colliding
@@ -1054,23 +1047,28 @@ async function main() {
   // Success message
   title('Project created successfully!')
 
+  // Recommend pnpm (the framework's package manager) when it's installed,
+  // otherwise fall back to however the user invoked the CLI. The scaffold
+  // supports both — the root package.json declares npm `workspaces` and a
+  // pnpm-workspace.yaml ships next to it.
+  const recPm = isPnpmAvailable() ? 'pnpm' : pm
+
   if (isBlank) {
     log(`Next steps:\n`)
     if (!inPlace) log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
     log(`  ${colors.cyan}${prefix} add project${colors.reset}`)
-    log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
-    log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
+    log(`  ${colors.cyan}${installCmd(recPm)}${colors.reset}`)
+    log(`  ${colors.cyan}${runCmd(recPm, 'dev')}${colors.reset}   ${colors.dim}# start the dev server${colors.reset}`)
   } else {
     log(`Next steps:\n`)
     if (!inPlace) log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
-    log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
-    log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
+    log(`  ${colors.cyan}${installCmd(recPm)}${colors.reset}`)
+    log(`  ${colors.cyan}${runCmd(recPm, 'dev')}${colors.reset}   ${colors.dim}# start the dev server${colors.reset}`)
+  }
+  if (recPm !== 'pnpm') {
+    log('')
+    log(`  ${colors.dim}Tip: pnpm is recommended (https://pnpm.io) — npm works too.${colors.reset}`)
   }
-  log('')
-  log(`When ready to ship:\n`)
-  log(`  ${colors.cyan}${prefix} deploy${colors.reset}                     ${colors.dim}# Uniweb hosting (default; uniweb login first)${colors.reset}`)
-  log(`  ${colors.cyan}${prefix} deploy --host=<adapter>${colors.reset}    ${colors.dim}# cloudflare-pages, netlify, vercel, github-pages, s3-cloudfront${colors.reset}`)
-  log(`  ${colors.cyan}${prefix} export${colors.reset}                     ${colors.dim}# Build dist/ for any static host (no Uniweb account)${colors.reset}`)
   log('')
   log(`  ${colors.dim}See ${colors.reset}${colors.cyan}${prefix} <command> --help${colors.reset}${colors.dim} for command-specific options.${colors.reset}`)
   log('')

package/src/templates/index.js

@@ -7,7 +7,7 @@ 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 } from './resolver.js'
+import { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES, buildTemplateChoices } from './resolver.js'
 import { fetchNpmTemplate } from './fetchers/npm.js'
 import { fetchGitHubTemplate } from './fetchers/github.js'
 import { fetchOfficialTemplate, listOfficialTemplates } from './fetchers/release.js'
@@ -182,4 +182,4 @@ export async function listAvailableTemplates() {
 }
 
 // Re-export for convenience
-export { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES }
+export { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES, buildTemplateChoices }

package/src/templates/resolver.js

@@ -12,7 +12,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
 
 /**
- * Load the list of official template names.
+ * 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:
  *
@@ -24,59 +25,93 @@ export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
  *
  * 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.
+ *    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.
  *
  * 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.
+ * 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.)
  */
-function loadOfficialTemplateList() {
+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 = tryReadTemplateKeys(workspaceManifest)
+  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 = tryReadTemplateKeys(indexPath)
+  const fromIndex = tryReadTemplateMap(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
+  // 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 []
+  return {}
 }
 
-function tryReadTemplateKeys(path) {
+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 Object.keys(data.templates)
+      return 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()
+// 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 ids, e.g. ['marketing', 'docs', 'academic', …].
+export const OFFICIAL_TEMPLATES = Object.keys(OFFICIAL_TEMPLATE_MAP)
+
+// Built-in (programmatic) picker entries — not in the manifest; the CLI
+// generates these itself. "Blank" trails the official templates.
+const BUILTIN_LEAD_CHOICES = [
+  { title: 'None', value: 'none', description: 'Foundation + site with no content' },
+  { title: 'Starter', value: 'starter', description: 'Foundation + site + sample content' }
+]
+const BLANK_CHOICE = {
+  title: 'Blank workspace',
+  value: 'blank',
+  description: 'Empty workspace — grow with uniweb add'
+}
+
+/**
+ * Build the choices for the interactive `create` template prompt: the
+ * built-in leads (None, Starter), then every official template from the
+ * shared manifest in manifest order, then Blank last. Deriving the official
+ * entries from OFFICIAL_TEMPLATE_MAP keeps the picker in lockstep with
+ * framework/templates/manifest.json — adding a template there (and
+ * republishing the CLI) is all it takes for it to appear here.
+ *
+ * @returns {Array<{title: string, value: string, description: string}>}
+ */
+export function buildTemplateChoices() {
+  const official = Object.entries(OFFICIAL_TEMPLATE_MAP).map(([id, info]) => ({
+    title: info?.name || id,
+    value: id,
+    description: info?.description || ''
+  }))
+  return [...BUILTIN_LEAD_CHOICES, ...official, BLANK_CHOICE]
+}
 
 /**
  * Parse a template identifier and determine its source type

package/src/utils/pm.js

@@ -7,6 +7,7 @@
 
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+import { execSync } from 'node:child_process'
 
 /**
  * Detect which package manager invoked the CLI.
@@ -84,6 +85,22 @@ export function filterCmd(pm, pkg, cmd) {
     : `npm -w ${pkg} run ${cmd}`
 }
 
+/**
+ * Whether pnpm is available on the current PATH. Used to recommend pnpm
+ * (the framework's package manager) in post-scaffold next steps while still
+ * falling back gracefully when it isn't installed. Mirrors the `git --version`
+ * probe the create flow already uses to feature-detect git.
+ * @returns {boolean}
+ */
+export function isPnpmAvailable() {
+  try {
+    execSync('pnpm --version', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Generate an install command.
  * @param {'pnpm' | 'yarn' | 'npm'} pm

package/src/versions.js

@@ -52,6 +52,18 @@ let resolvedVersions = null
  */
 export const REACT_VERSION = '^19.0.0'
 
+/**
+ * The pnpm major the framework's generated CI standardizes on.
+ *
+ * Scaffolded CI workflows (`uniweb add ci --host=github-pages`) pin pnpm
+ * through `pnpm/action-setup`. This is the one place that value lives, so the
+ * pin tracks a single supported major instead of drifting as a hardcoded
+ * literal inside each host adapter. A bare major installs the latest patch of
+ * that major at CI run time. Bump this when the framework moves to a new pnpm
+ * major (latest stable is 11.x as of this writing; pnpm 12 is still alpha).
+ */
+export const PNPM_VERSION = '11'
+
 /**
  * Get the CLI's own package.json
  */