uniweb 0.48.0 → 0.48.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.48.0",
+  "version": "0.48.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,14 +42,14 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "^0.24.2",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/kit": "^0.18.0",
+    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/runtime": "^0.19.3"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.44.0",
-    "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/content-reader": "^1.2.4"
+    "@uniweb/build": "^0.44.1",
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/commands/add.js

@@ -1249,8 +1249,16 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
   let getAdapter, listAdapters
   try {
     ;({ getAdapter, listAdapters } = await import('@uniweb/build/hosts'))
-  } catch {
-    error('Failed to load host adapter registry from @uniweb/build/hosts.')
+  } catch (err) {
+    // ⛔ Keep the reason. A bare `catch {}` here printed one line for three
+    // different failures — the package is absent, the `./hosts` subpath is
+    // not exported by the installed version, or the module threw while
+    // evaluating — and they have different remedies.
+    error(`Failed to load the host adapter registry from @uniweb/build/hosts.`)
+    error(`  ${err.message}`)
+    if (err.code === 'ERR_MODULE_NOT_FOUND') {
+      error(`  Install the workspace's dependencies, or upgrade @uniweb/build.`)
+    }
     process.exit(1)
   }
 

package/src/commands/template.js

@@ -1,5 +1,5 @@
 /**
- * template — RESERVED (not available on the new backend yet).
+ * template — `list` is live; `register` is RESERVED (not on the new backend yet).
  *
  * `uniweb template publish` submitted a site as a cloud template to the legacy
  * registry (the PHP backend + Cloudflare Worker) the CLI no longer talks to. A
@@ -9,9 +9,35 @@
  *
  * (Unrelated: scaffolding FROM a template — `uniweb create --template <name>` —
  * is a separate path and is unaffected.)
+ *
+ * ⭐ `list` exists so a SCRIPT can enumerate the official templates. The
+ * interactive picker in `create` has always shown this list; `--json` is the
+ * same data, second rendering, for tooling that scaffolds several templates in
+ * a row and needs their names first.
+ *
+ * ⚠️ IT REPORTS A BUNDLED SNAPSHOT, NOT A LIVE FETCH — the roster is baked into
+ * the CLI at publish time (`src/framework-index.json`, rewritten from
+ * `templates/manifest.json` by the pre-publish hook). So it answers "which
+ * official templates does THIS CLI know", which is the right question when the
+ * next step is resolving one of those names with the same CLI. `cliVersion` is
+ * in the JSON for exactly that reason. A newer template than your CLI will not
+ * appear — and an unknown name is not fatal either way, since `create` falls
+ * through to npm `@uniweb/template-<name>`, so this is the OFFICIAL roster
+ * rather than the set of resolvable names.
  */
 
-export async function template() {
+import { OFFICIAL_TEMPLATE_MAP } from '../templates/resolver.js'
+import { getCliVersion } from '../versions.js'
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m'
+}
+
+function reserved() {
   console.error(
     "\x1b[31m✗\x1b[0m `uniweb template register` isn't available on the new backend yet."
   )
@@ -24,7 +50,69 @@ export async function template() {
   console.error(
     '  (Scaffolding FROM a template still works: `uniweb create --template <name>`.)'
   )
+  console.error('')
+  console.error('  To list the official templates: `uniweb template list`.')
   process.exit(1)
 }
 
+function listTemplates(args) {
+  const entries = Object.entries(OFFICIAL_TEMPLATE_MAP).map(([id, info]) => ({
+    id,
+    name: info?.name || id,
+    description: info?.description || '',
+    tags: info?.tags || []
+  }))
+
+  if (args.includes('--json')) {
+    // ⛔ stdout carries JSON and nothing else, so it pipes. Every human-facing
+    // line in this command goes to stderr for the same reason.
+    process.stdout.write(
+      JSON.stringify(
+        { cliVersion: getCliVersion(), count: entries.length, templates: entries },
+        null,
+        2
+      ) + '\n'
+    )
+    return
+  }
+
+  if (entries.length === 0) {
+    // Not a crash: a CLI whose snapshot failed to load falls back to an empty
+    // map, and `create` then routes every name to npm. Say which happened.
+    console.error(
+      `${colors.red}✗${colors.reset} No official templates found in this CLI's bundled index.`
+    )
+    console.error(
+      `  ${colors.dim}A template name will still resolve through npm as @uniweb/template-<name>.${colors.reset}`
+    )
+    process.exit(1)
+  }
+
+  const width = Math.max(...entries.map((e) => e.id.length))
+  console.log('')
+  console.log(
+    `${colors.bright}Official templates${colors.reset} ${colors.dim}(uniweb ${getCliVersion()})${colors.reset}`
+  )
+  console.log('')
+  for (const e of entries) {
+    console.log(
+      `  ${colors.cyan}${e.id.padEnd(width)}${colors.reset}  ${e.description || e.name}`
+    )
+  }
+  console.log('')
+  console.log(
+    `  ${colors.dim}uniweb create <project> --template <name>${colors.reset}`
+  )
+  console.log(
+    `  ${colors.dim}--json for scripts. This is the roster THIS CLI ships with, not a live fetch.${colors.reset}`
+  )
+  console.log('')
+}
+
+export async function template(args = []) {
+  const sub = args.find((a) => !a.startsWith('-'))
+  if (sub === 'list') return listTemplates(args)
+  return reserved()
+}
+
 export default template

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-09T20:26:27.202Z",
+  "generatedAt": "2026-09-09T22:45:28.403Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.2.13",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.44.0",
+      "version": "0.44.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -120,7 +120,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.9.11",
+      "version": "0.9.12",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -55,6 +55,7 @@ import {
 } from './utils/scaffold.js'
 import {
   detectPackageManager,
+  detectWorkspacePm,
   filterCmd,
   installCmd,
   runCmd,
@@ -224,32 +225,98 @@ function delegateToLocal(localCliPath) {
 }
 
 /**
- * Import a command module that may depend on @uniweb/build.
- * Provides a helpful error when the dependency can't be resolved
- * (e.g., running a project-bound command from a global install
- * outside a project directory).
+ * Import a command module that may depend on an optional @uniweb/* peer
+ * (`@uniweb/build` above all). Sixteen commands load through here, so this
+ * is the error most users meet when something is not installed.
+ *
+ * ⛔ IT MUST NOT NAME A CAUSE IT HAS NOT CHECKED. This said "This command
+ * must be run from inside a Uniweb project" for every `ERR_MODULE_NOT_FOUND`
+ * on a `@uniweb/*` specifier — a guess, and wrong in the two cases that do
+ * not involve your location at all: a workspace whose dependencies are simply
+ * not installed, and a CLI installed on its own (the optional peers are not
+ * installed with it, so `npm install uniweb --prefix X` yields exactly this).
+ * Project resolution is cwd-based (`findWorkspaceRoot`) and always was, so
+ * the check the message needed was one call away and already imported here.
+ *
+ * ⚠️ A wrong cause is worse than a vague one: it does not merely fail to
+ * explain, it DIRECTS the investigation. Reported 2026-09-09 by a consumer
+ * who lost an hour testing the cause this text named, having already done
+ * the `cd` and the install it advised.
  */
 async function importProjectCommand(modulePath) {
   try {
     return await import(modulePath)
   } catch (err) {
     if (
-      err.code === 'ERR_MODULE_NOT_FOUND' &&
-      err.message?.includes('@uniweb/')
+      err.code !== 'ERR_MODULE_NOT_FOUND' ||
+      !err.message?.includes('@uniweb/')
     ) {
-      error('This command must be run from inside a Uniweb project.')
+      throw err
+    }
+
+    // Name the package that actually failed to resolve, rather than making
+    // the reader guess which of the optional peers this command needed.
+    const missing =
+      err.message.match(/'(@uniweb\/[^']+)'/)?.[1] ?? 'a @uniweb/* package'
+    const root = findWorkspaceRoot(process.cwd())
+
+    // ⛔ THREE STATES, and the second and third look identical from here — the
+    // import failed either way. Discriminate on what is ON DISK, because
+    // "declared but not installed" and "installed but not reachable from where
+    // THIS CLI lives" have opposite remedies, and telling a fully-installed
+    // workspace to run its installer is the same wrong-cause defect again.
+    const workspaceModules = root ? join(root, 'node_modules') : null
+    const workspaceInstalled = !!workspaceModules && existsSync(workspaceModules)
+    const localCli = root ? join(workspaceModules, '.bin', 'uniweb') : null
+
+    error(`Cannot load ${missing}, which this command needs.`)
+    log('')
+
+    if (!root) {
+      log(
+        `No Uniweb workspace found above ${colors.dim}${process.cwd()}${colors.reset}.`
+      )
+      log(`  ${colors.cyan}cd${colors.reset} into a project, or create one:`)
+      log(`  ${colors.cyan}uniweb create my-project${colors.reset}`)
       log('')
       log(
-        `Make sure you're in a project directory with dependencies installed:`
+        `${colors.dim}Driving projects from a standalone CLI? ${missing} is an optional${colors.reset}`
+      )
+      log(
+        `${colors.dim}peer, so a bare \`npm i uniweb\` does not bring it:${colors.reset}`
       )
-      log(`  ${colors.cyan}cd your-project${colors.reset}`)
-      log(`  ${colors.cyan}npm install${colors.reset}`)
+      log(`  ${colors.cyan}npm install uniweb ${missing}${colors.reset}`)
+    } else if (!workspaceInstalled) {
+      // Declared, not on disk. Prefer the workspace's own package manager,
+      // read off its lockfile — but a workspace that has NEVER been installed
+      // has no lockfile to read, so fall back the same way `create` does
+      // rather than to whichever PM happens to be running this process.
+      const pm =
+        detectWorkspacePm(root) ||
+        (isPnpmAvailable() ? 'pnpm' : detectPackageManager())
+      log(`Uniweb workspace: ${colors.dim}${root}${colors.reset}`)
+      log(`Its dependencies are not installed:`)
+      log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
+    } else {
+      // Installed, and still unreachable: Node resolves a command's imports
+      // from the CLI's own location, so a CLI installed elsewhere cannot see
+      // this workspace's copy. Both remedies are real; the local bin is the
+      // one that guarantees the project's own pinned toolchain does the work.
+      log(
+        `Uniweb workspace: ${colors.dim}${root}${colors.reset} ${colors.dim}(dependencies are installed)${colors.reset}`
+      )
+      log(
+        `This CLI resolves its imports from its own install location, not from`
+      )
+      log(`the workspace, so it cannot see the workspace's ${missing}.`)
       log('')
-      log(`Or create a new project:`)
-      log(`  ${colors.cyan}uniweb create my-project${colors.reset}`)
-      process.exit(1)
+      log(`Use the project's own CLI:`)
+      log(`  ${colors.cyan}${localCli}${colors.reset}`)
+      log(`or install the peer next to this one:`)
+      log(`  ${colors.cyan}npm install uniweb ${missing}${colors.reset}`)
     }
-    throw err
+
+    process.exit(1)
   }
 }
 
@@ -1640,11 +1707,26 @@ The site-handoff flow was retired with the legacy backend.
 Manage client sites from the Uniweb app for now.
 `,
     template: `
-${colors.cyan}${colors.bright}uniweb template${colors.reset} ${colors.dim}— (reserved; not available on the new backend yet)${colors.reset}
+${colors.cyan}${colors.bright}uniweb template${colors.reset} ${colors.dim}— Official templates${colors.reset}
 
-Submitting a site as a cloud template was retired with the legacy backend.
-When rebuilt, a template is REGISTERED (like a foundation) — \`publish\` is for
-sites only. Scaffolding FROM a template still works: \`uniweb create --template <name>\`.
+${colors.bright}Usage:${colors.reset}
+  uniweb template list           List the official templates
+  uniweb template list --json    Same, machine-readable (for scripts)
+
+${colors.bright}What \`list\` reports:${colors.reset}
+  The roster ${colors.bright}this CLI ships with${colors.reset} — a snapshot baked in at publish time,
+  not a live fetch. That is the right question when the next step is resolving
+  one of those names with the same CLI, which is why \`--json\` stamps
+  \`cliVersion\`. A template newer than your CLI will not be listed.
+
+  It is the ${colors.bright}official${colors.reset} roster, not the set of resolvable names: an unknown
+  name is not fatal, since \`create\` falls through to npm \`@uniweb/template-<name>\`.
+
+${colors.bright}Reserved:${colors.reset}
+  \`uniweb template register\` is not available on the new backend yet. Submitting
+  a site as a cloud template was retired with the legacy backend; when rebuilt, a
+  template is REGISTERED (like a foundation) — \`publish\` is for sites only.
+  Scaffolding FROM a template is unaffected: \`uniweb create --template <name>\`.
 `,
     docs: `
 ${colors.cyan}${colors.bright}uniweb docs${colors.reset} ${colors.dim}— Generate component documentation${colors.reset}