uniweb 0.8.15 → 0.8.16

package/README.md

@@ -200,7 +200,7 @@ After creating your project:
 
 1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page folder contains `page.yml` (metadata) and `.md` files (sections).
 
-2. **Generate component docs** — Run `npx uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
+2. **Generate component docs** — Run `uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
 
 3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
 
@@ -267,31 +267,31 @@ Start simple. Add what you need, when you need it:
 cd my-site
 
 # Add a co-located foundation + site pair
-npx uniweb add project blog
+uniweb add project blog
 
 # Add a second foundation at root
-npx uniweb add foundation ui
+uniweb add foundation ui
 
 # Add a site wired to a specific foundation
-npx uniweb add site docs --foundation ui
+uniweb add site docs --foundation ui
 
 # Add an extension (auto-wired to the only site)
-npx uniweb add extension effects
+uniweb add extension effects
 
 # Scaffold + apply content from an official template
-npx uniweb add project marketing --from marketing
+uniweb add project marketing --from marketing
 ```
 
 The workspace grows organically. `add` handles placement, wires dependencies, updates workspace globs, and generates root scripts. The name you provide becomes both the directory name and the package name. Use `--path` to override default placement, or `--project` for explicit co-located layouts.
 
-> `npx uniweb` works before and after install. Once dependencies are installed, you can also use `pnpm uniweb` directly since `uniweb` is a project dependency.
+> **Install the CLI globally** with `npm i -g uniweb` for the best experience. You can also use `npx uniweb` or `pnpm uniweb` without a global install.
 
 **Or start blank and build up:**
 
 ```bash
 pnpm create uniweb acme --blank
 cd acme
-npx uniweb add project main
+uniweb add project main
 pnpm install
 pnpm dev
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.15",
+  "version": "0.8.16",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,11 +41,24 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.8.14",
-    "@uniweb/content-reader": "1.1.4",
-    "@uniweb/core": "0.5.10",
     "@uniweb/runtime": "0.6.11",
-    "@uniweb/kit": "0.7.10",
-    "@uniweb/semantic-parser": "1.1.6"
+    "@uniweb/core": "0.5.10",
+    "@uniweb/kit": "0.7.11"
+  },
+  "peerDependencies": {
+    "@uniweb/build": "0.8.15",
+    "@uniweb/semantic-parser": "1.1.6",
+    "@uniweb/content-reader": "1.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@uniweb/build": {
+      "optional": true
+    },
+    "@uniweb/content-reader": {
+      "optional": true
+    },
+    "@uniweb/semantic-parser": {
+      "optional": true
+    }
   }
 }

package/partials/agents.md

@@ -83,7 +83,7 @@ Use `--template <n>` for an official template (`none`, `starter`, `marketing`, `
 ### Adding a co-located project
 
 ```bash
-pnpm uniweb add project docs
+uniweb add project docs
 pnpm install
 ```
 
@@ -92,10 +92,10 @@ This creates `docs/foundation/` + `docs/site/` with package names `docs-foundati
 ### Adding individual packages
 
 ```bash
-pnpm uniweb add foundation           # First foundation → ./foundation/
-pnpm uniweb add foundation ui        # Named → ./ui/
-pnpm uniweb add site                 # First site → ./site/
-pnpm uniweb add site blog            # Named → ./blog/
+uniweb add foundation           # First foundation → ./foundation/
+uniweb add foundation ui        # Named → ./ui/
+uniweb add site                 # First site → ./site/
+uniweb add site blog            # Named → ./blog/
 ```
 
 The name is both the directory name and the package name. Use `--project <n>` to co-locate under a project directory (e.g., `--project docs` → `docs/foundation/`).
@@ -103,8 +103,8 @@ The name is both the directory name and the package name. Use `--project <n>` to
 ### Adding section types
 
 ```bash
-pnpm uniweb add section Hero
-pnpm uniweb add section Hero --foundation ui   # When multiple foundations exist
+uniweb add section Hero
+uniweb add section Hero --foundation ui   # When multiple foundations exist
 ```
 
 Creates `src/sections/Hero/index.jsx` and `meta.js` with a minimal CCA-proper starter. The dev server picks it up automatically — no build or install needed.
@@ -340,9 +340,9 @@ Check out [this](/a) link.     ← inline → stays in paragraphs as <a> tag
 This is [less important]{muted} context.
 ```
 
-`accent` (colored + bold) and `muted` (subtle) adapt to context automatically. Components receive HTML strings with spans applied: `<span accent="true">faster</span>`.
+`accent` (link-colored + bold), `callout` (accent-colored + bold), and `muted` (subtle) are built-in defaults that adapt to context automatically. Components receive HTML strings with spans applied: `<span accent="true">faster</span>`.
 
-Sites can define additional named styles in `theme.yml`'s `inline:` section.
+Sites can override these or define additional named styles in `theme.yml`'s `inline:` section.
 
 ### Fenced Code in Content
 
@@ -676,6 +676,9 @@ inline:
   accent:
     color: var(--link)
     font-weight: '600'
+  callout:
+    color: var(--accent)
+    font-weight: '600'
 
 vars:
   header-height: 5rem
@@ -1282,9 +1285,9 @@ Semantic tokens come from `theme-tokens.css` (populated from `theme.yml`). Use `
 
 **Content not appearing as expected?**
 ```bash
-pnpm uniweb inspect pages/home/hero.md         # Single section
-pnpm uniweb inspect pages/home/                 # Whole page
-pnpm uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
+uniweb inspect pages/home/hero.md         # Single section
+uniweb inspect pages/home/                 # Whole page
+uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 ```
 
 ## Learning from Official Templates
@@ -1292,7 +1295,7 @@ pnpm uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 When you're unsure how to implement a pattern — data fetching, i18n, layouts, insets, theming — install an official template as a reference project in your workspace:
 
 ```bash
-pnpm uniweb add project marketing --from marketing
+uniweb add project marketing --from marketing
 pnpm install
 ```
 

package/partials/components-docs.hbs

@@ -4,10 +4,10 @@ Generate up-to-date documentation for all foundation components:
 
 ```bash
 # From foundation directory
-pnpm uniweb docs
+uniweb docs
 
 # Or from site directory (auto-detects linked foundation)
-cd site && pnpm uniweb docs
+cd site && uniweb docs
 ```
 
 This creates `COMPONENTS.md` with details on each component's parameters, presets, and content elements. The documentation is generated from component `meta.js` files, so it's always current.

package/partials/config-reference.hbs

@@ -64,4 +64,4 @@ seo:
   priority: 0.8
 ```
 
-Run `pnpm uniweb docs site` or `pnpm uniweb docs page` for complete reference.
+Run `uniweb docs site` or `uniweb docs page` for complete reference.

package/src/commands/add.js

@@ -352,7 +352,7 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
     }, {
       onProgress: (msg) => info(`  ${msg}`),
     })
-    log(`  ${colors.yellow}⚠ No foundation wired. Add one later with: npx uniweb add foundation${colors.reset}`)
+    log(`  ${colors.yellow}⚠ No foundation wired. Add one later with: uniweb add foundation${colors.reset}`)
   }
 
   // Apply template content if --from specified

package/src/commands/doctor.js

@@ -379,7 +379,7 @@ export async function doctor(args = []) {
         message: `Foundation not built: ${matchingFoundation.name}`
       })
       warn(`Foundation not built yet`)
-      log(`  ${colors.dim}Run: npx uniweb build${colors.reset}`)
+      log(`  ${colors.dim}Run: uniweb build${colors.reset}`)
     } else {
       success(`Foundation built: dist/foundation.js exists`)
     }
@@ -431,7 +431,7 @@ export async function doctor(args = []) {
         message: `Extension not built: ${ext.name}`
       })
       warn(`Extension not built yet`)
-      log(`  ${colors.dim}Run: npx uniweb build${colors.reset}`)
+      log(`  ${colors.dim}Run: uniweb build${colors.reset}`)
     } else {
       success(`Extension built: dist/foundation.js exists`)
     }

package/src/index.js

@@ -5,20 +5,27 @@
  *
  * Scaffolds new Uniweb sites and foundations, builds projects, and generates docs.
  *
+ * Install globally:
+ *   npm i -g uniweb
+ *
  * Usage:
- *   npx uniweb create [project-name]
- *   npx uniweb create --template marketing
- *   npx uniweb add foundation [name]
- *   npx uniweb build
- *   npx uniweb docs                          # Generate COMPONENTS.md from schema
+ *   uniweb create [project-name]
+ *   uniweb create --template marketing
+ *   uniweb add foundation [name]
+ *   uniweb build
+ *   uniweb docs
+ *
+ * Global install delegation:
+ *   When installed globally, project-bound commands (build, docs, etc.) are
+ *   delegated to the project-local CLI if one exists in node_modules. This
+ *   ensures version alignment between the CLI and @uniweb/build.
  */
 
-import { existsSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { resolve, join, relative } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import { execSync, spawn as spawnChild } from 'node:child_process'
+import { resolve, join, relative, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import prompts from 'prompts'
-import { build } from './commands/build.js'
-import { docs } from './commands/docs.js'
 import { doctor } from './commands/doctor.js'
 import { i18n } from './commands/i18n.js'
 import { inspect } from './commands/inspect.js'
@@ -80,6 +87,108 @@ function title(message) {
   console.log(`\n${colors.cyan}${colors.bright}${message}${colors.reset}\n`)
 }
 
+// CLI version (read once, lazily)
+const __dirname = dirname(fileURLToPath(import.meta.url))
+let _cliVersion = null
+function getCliVersion() {
+  if (!_cliVersion) {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
+    _cliVersion = pkg.version
+  }
+  return _cliVersion
+}
+
+/**
+ * Commands that always run from the global CLI (no project context needed)
+ */
+const STANDALONE_COMMANDS = new Set([
+  'create', '--help', '-h', '--version', '-v', 'login',
+])
+
+/**
+ * Check if this CLI is running from a global install.
+ * When installed globally, process.argv[1] points outside any node_modules.
+ * When run via npx or as a local dependency, it's inside node_modules.
+ */
+function isGlobalInstall() {
+  const scriptPath = process.argv[1]
+  if (!scriptPath) return false
+  // Normalize path separators for Windows compatibility
+  return !scriptPath.split('/').includes('node_modules') &&
+         !scriptPath.split('\\').includes('node_modules')
+}
+
+/**
+ * Find the project-local CLI entry point, if one exists.
+ * Walks up from cwd looking for node_modules/uniweb/src/index.js.
+ */
+function findLocalCli() {
+  let dir = process.cwd()
+  while (true) {
+    const localCli = join(dir, 'node_modules', 'uniweb', 'src', 'index.js')
+    if (existsSync(localCli)) return localCli
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * Delegate execution to the project-local CLI.
+ * Spawns the local CLI with the same arguments and inherits stdio.
+ * Warns if the local version differs from the global version.
+ */
+function delegateToLocal(localCliPath) {
+  // Check for version mismatch between global and local CLI
+  try {
+    const localPkgPath = join(dirname(localCliPath), '..', 'package.json')
+    const localPkg = JSON.parse(readFileSync(localPkgPath, 'utf8'))
+    const globalVersion = getCliVersion()
+    if (localPkg.version && localPkg.version !== globalVersion) {
+      const yellow = '\x1b[33m'
+      const dim = '\x1b[2m'
+      const reset = '\x1b[0m'
+      console.error(`${yellow}Note:${reset} Global CLI is ${dim}${globalVersion}${reset}, project has ${dim}${localPkg.version}${reset} ${dim}(using project version)${reset}`)
+    }
+  } catch { /* ignore — version check is best-effort */ }
+
+  return new Promise((resolve, reject) => {
+    const child = spawnChild(
+      process.execPath,
+      [localCliPath, ...process.argv.slice(2)],
+      { stdio: 'inherit' }
+    )
+    child.on('close', (code) => process.exit(code ?? 0))
+    child.on('error', reject)
+  })
+}
+
+/**
+ * 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).
+ */
+async function importProjectCommand(modulePath) {
+  try {
+    return await import(modulePath)
+  } catch (err) {
+    if (err.code === 'ERR_MODULE_NOT_FOUND' && err.message?.includes('@uniweb/')) {
+      error('This command must be run from inside a Uniweb project.')
+      log('')
+      log(`Make sure you're in a project directory with dependencies installed:`)
+      log(`  ${colors.cyan}cd your-project${colors.reset}`)
+      log(`  ${colors.cyan}npm install${colors.reset}`)
+      log('')
+      log(`Or create a new project:`)
+      log(`  ${colors.cyan}uniweb create my-project${colors.reset}`)
+      process.exit(1)
+    }
+    throw err
+  }
+}
+
 /**
  * Create a project using the new package template flow (default)
  */
@@ -306,21 +415,55 @@ async function main() {
   const command = args[0]
   const pm = detectPackageManager()
 
+  // Handle --version / -v
+  if (command === '--version' || command === '-v') {
+    console.log(`uniweb ${getCliVersion()}`)
+    return
+  }
+
+  // Global install launcher: delegate project-bound commands to local CLI
+  const global = isGlobalInstall()
+  if (global && command && !STANDALONE_COMMANDS.has(command)) {
+    const localCli = findLocalCli()
+    if (localCli) {
+      await delegateToLocal(localCli)
+      return
+    }
+    // No local CLI found — fall through and try to run the command directly.
+    // Commands that need @uniweb/build will get a helpful error via importProjectCommand().
+  }
+
+  // Start non-blocking update check for global installs
+  let showUpdateNotification = () => {}
+  if (global) {
+    try {
+      const { startUpdateCheck } = await import('./utils/update-check.js')
+      showUpdateNotification = startUpdateCheck(getCliVersion())
+    } catch {
+      // Update check is optional — don't fail if the module is missing
+    }
+  }
+
   // Show help
   if (!command || command === '--help' || command === '-h') {
     showHelp()
+    await showUpdateNotification()
     return
   }
 
-  // Handle build command
+  // Handle build command (dynamic import — depends on @uniweb/build)
   if (command === 'build') {
+    const { build } = await importProjectCommand('./commands/build.js')
     await build(args.slice(1))
+    await showUpdateNotification()
     return
   }
 
-  // Handle docs command
+  // Handle docs command (dynamic import — depends on @uniweb/build)
   if (command === 'docs') {
+    const { docs } = await importProjectCommand('./commands/docs.js')
     await docs(args.slice(1))
+    await showUpdateNotification()
     return
   }
 
@@ -616,14 +759,16 @@ async function main() {
     log(`  ${colors.cyan}${runCmd(pm, 'dev')}${colors.reset}`)
   }
   log('')
+
+  await showUpdateNotification()
 }
 
 function showHelp() {
   log(`
-${colors.cyan}${colors.bright}Uniweb CLI${colors.reset}
+${colors.cyan}${colors.bright}Uniweb CLI${colors.reset} ${colors.dim}v${getCliVersion()}${colors.reset}
 
 ${colors.bright}Usage:${colors.reset}
-  npx uniweb <command> [options]
+  uniweb <command> [options]
 
 ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
@@ -654,6 +799,7 @@ ${colors.bright}Add Subcommands:${colors.reset}
   add section <name>      Add a section type to a foundation (--foundation)
 
 ${colors.bright}Global Options:${colors.reset}
+  --version, -v        Show version
   --non-interactive    Fail with usage info instead of prompting
                        Auto-detected when CI=true or no TTY (pipes, agents)
 
@@ -720,22 +866,26 @@ ${colors.bright}Template Types:${colors.reset}
   https://github.com/user/repo  GitHub URL
 
 ${colors.bright}Examples:${colors.reset}
-  npx uniweb create my-project                           # Foundation + site + starter content
-  npx uniweb create my-project --template none           # Foundation + site, no content
-  npx uniweb create my-project --blank                   # Empty workspace
-  npx uniweb create my-project --template marketing      # Official template
-  npx uniweb create my-project --template ./my-template  # Local template
+  uniweb create my-project                           # Foundation + site + starter content
+  uniweb create my-project --template none           # Foundation + site, no content
+  uniweb create my-project --blank                   # Empty workspace
+  uniweb create my-project --template marketing      # Official template
+  uniweb create my-project --template ./my-template  # Local template
 
   cd my-project
-  npx uniweb add project docs                            # Add docs/foundation/ + docs/site/
-  npx uniweb add project docs --from academic            # Co-located pair + academic content
-  npx uniweb add foundation                              # Add foundation at root
-  npx uniweb add site blog --foundation marketing        # Add site wired to marketing
-  npx uniweb add extension effects --site site           # Add extensions/effects/
-
-  npx uniweb build
-  npx uniweb build --target foundation
-  cd foundation && npx uniweb docs                       # Generate COMPONENTS.md
+  uniweb add project docs                            # Add docs/foundation/ + docs/site/
+  uniweb add project docs --from academic            # Co-located pair + academic content
+  uniweb add foundation                              # Add foundation at root
+  uniweb add site blog --foundation marketing        # Add site wired to marketing
+  uniweb add extension effects --site site           # Add extensions/effects/
+
+  uniweb build
+  uniweb build --target foundation
+  cd foundation && uniweb docs                       # Generate COMPONENTS.md
+
+${colors.bright}Install:${colors.reset}
+  npm i -g uniweb          Global install (recommended)
+  npx uniweb <command>     Run without installing
 `)
 }
 

package/src/utils/update-check.js

@@ -0,0 +1,105 @@
+/**
+ * Lightweight Update Notification
+ *
+ * Checks the npm registry for newer versions of the CLI.
+ * Runs at most once per day, caches results in ~/.uniweb/update-check.json.
+ * Uses Node 20+ built-in fetch — no external dependencies.
+ */
+
+import { homedir } from 'node:os'
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CHECK_INTERVAL = 24 * 60 * 60 * 1000 // 1 day
+const STATE_DIR = join(homedir(), '.uniweb')
+const STATE_FILE = join(STATE_DIR, 'update-check.json')
+
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareSemver(a, b) {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1
+  }
+  return 0
+}
+
+/**
+ * Read cached update check state.
+ */
+function readState() {
+  try {
+    if (existsSync(STATE_FILE)) {
+      return JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+    }
+  } catch { /* ignore corrupt cache */ }
+  return {}
+}
+
+/**
+ * Write update check state to disk.
+ */
+function writeState(state) {
+  try {
+    if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
+    writeFileSync(STATE_FILE, JSON.stringify(state))
+  } catch { /* ignore write errors */ }
+}
+
+/**
+ * Print update notification to stderr (doesn't interfere with piped output).
+ */
+function printNotification(current, latest) {
+  const yellow = '\x1b[33m'
+  const cyan = '\x1b[36m'
+  const dim = '\x1b[2m'
+  const reset = '\x1b[0m'
+  console.error('')
+  console.error(`${yellow}Update available:${reset} ${dim}${current}${reset} → ${cyan}${latest}${reset}`)
+  console.error(`${dim}Run${reset} npm i -g uniweb ${dim}to update${reset}`)
+}
+
+/**
+ * Start a non-blocking update check.
+ *
+ * Returns a function that, when called (optionally awaited), prints
+ * the notification if a newer version was found.
+ *
+ * @param {string} currentVersion - The currently running CLI version
+ * @returns {Function} Call at the end of command execution to show notification
+ */
+export function startUpdateCheck(currentVersion) {
+  let notification = null
+  const state = readState()
+
+  // Use cached result if checked recently
+  if (state.lastCheck && (Date.now() - state.lastCheck) < CHECK_INTERVAL) {
+    if (state.latestVersion && compareSemver(state.latestVersion, currentVersion) > 0) {
+      notification = state.latestVersion
+    }
+    return () => {
+      if (notification) printNotification(currentVersion, notification)
+    }
+  }
+
+  // Background fetch (non-blocking)
+  const fetchPromise = fetch('https://registry.npmjs.org/uniweb/latest')
+    .then(r => r.json())
+    .then(data => {
+      const latest = data.version
+      writeState({ lastCheck: Date.now(), latestVersion: latest })
+      if (compareSemver(latest, currentVersion) > 0) {
+        notification = latest
+      }
+    })
+    .catch(() => { /* network error — ignore silently */ })
+
+  return async () => {
+    await fetchPromise
+    if (notification) printNotification(currentVersion, notification)
+  }
+}

package/src/versions.js

@@ -61,7 +61,7 @@ export function getResolvedVersions() {
   if (resolvedVersions) return resolvedVersions
 
   const pkg = getCliPackageJson()
-  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }
 
   // All @uniweb/* packages are now direct dependencies of the CLI.
   // When publishing with pnpm, workspace:* gets resolved to actual versions.