uniweb 0.12.9 → 0.12.11

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-05-04T22:31:28.093Z",
+  "generatedAt": "2026-05-05T20:43:37.314Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.1",
+      "version": "0.14.2",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -24,7 +24,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.7.10",
+      "version": "0.7.11",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -42,7 +42,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.10",
+      "version": "0.9.11",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core"
@@ -59,7 +59,7 @@
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.8.11",
+      "version": "0.8.13",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -92,7 +92,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.5",
+      "version": "0.4.7",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -199,12 +199,16 @@ async function createFromPackageTemplates(projectDir, projectName, options = {})
 
   onProgress?.('Setting up workspace...')
 
-  // 1. Scaffold workspace
+  // 1. Scaffold workspace.
+  // dev/build go through `uniweb` verbs so the scripts stay PM-agnostic
+  // (the verb resolves the right PM at runtime instead of locking the
+  // root scripts to whichever PM ran `npx uniweb create`). preview stays
+  // PM-filtered until a `uniweb preview` verb exists.
   await scaffoldWorkspace(projectDir, {
     projectName,
     workspaceGlobs: ['site', 'src'],
     scripts: {
-      dev: filterCmd(pm, 'site', 'dev'),
+      dev: 'uniweb dev',
       build: 'uniweb build',
       preview: filterCmd(pm, 'site', 'preview'),
     },
@@ -286,17 +290,19 @@ async function createFromContentTemplate(projectDir, projectName, metadata, temp
   const scripts = {
     build: 'uniweb build',
   }
+  // dev goes through `uniweb` (PM-agnostic; see computeRootScripts).
+  // preview stays PM-filtered until a `uniweb preview` verb exists.
   if (sites.length === 1) {
-    scripts.dev = filterCmd(pm, sites[0].name, 'dev')
+    scripts.dev = 'uniweb dev'
     scripts.preview = filterCmd(pm, sites[0].name, 'preview')
   } else {
     for (const s of sites) {
-      scripts[`dev:${s.name}`] = filterCmd(pm, s.name, 'dev')
+      scripts[`dev:${s.name}`] = `uniweb dev ${s.name}`
       scripts[`preview:${s.name}`] = filterCmd(pm, s.name, 'preview')
     }
     // First site gets unqualified aliases
     if (sites.length > 0) {
-      scripts.dev = filterCmd(pm, sites[0].name, 'dev')
+      scripts.dev = 'uniweb dev'
       scripts.preview = filterCmd(pm, sites[0].name, 'preview')
     }
   }
@@ -452,12 +458,26 @@ async function main() {
     // Commands that need @uniweb/build will get a helpful error via importProjectCommand().
   }
 
-  // Start non-blocking update check for global installs
+  // Start non-blocking update check for global installs.
+  //
+  // Two surfaces:
+  //   - showUpdateNotification (soft, trailing): printed at command end for
+  //     any verb. Doesn't interrupt the user's workflow.
+  //   - eager (loud, leading): printed BEFORE staleness-sensitive verbs do
+  //     their work. Today: only `create` (templates ship with the CLI, so
+  //     a stale CLI scaffolds stale starter content; the user needs to know
+  //     before files hit disk). Other verbs are insensitive — `deploy` etc.
+  //     are project-bound (delegated to local node_modules), and the
+  //     local-vs-global mismatch warning in delegateToLocal already covers
+  //     that case.
   let showUpdateNotification = () => {}
   if (global) {
     try {
-      const { startUpdateCheck } = await import('./utils/update-check.js')
+      const { startUpdateCheck, maybeEagerNotification } = await import('./utils/update-check.js')
       showUpdateNotification = startUpdateCheck(getCliVersion())
+      if (command === 'create') {
+        maybeEagerNotification(getCliVersion())
+      }
     } catch {
       // Update check is optional — don't fail if the module is missing
     }
@@ -470,6 +490,23 @@ async function main() {
     return
   }
 
+  // Per-command --help: short-circuit BEFORE the command's side effects run.
+  // Critical for `deploy --help` (used to open a browser to production for
+  // login because deploy.js doesn't parse --help and ensureAuth ran first).
+  // Falls back to the global help when a command has no dedicated block.
+  if (args.slice(1).some(a => a === '--help' || a === '-h')) {
+    const printed = printCommandHelp(command)
+    if (printed) {
+      await showUpdateNotification()
+      return
+    }
+    // No dedicated block — show global help as a useful fallback rather
+    // than executing the command (which often has side effects).
+    showHelp()
+    await showUpdateNotification()
+    return
+  }
+
   // Handle build command (dynamic import — depends on @uniweb/build)
   if (command === 'build') {
     const { build } = await importProjectCommand('./commands/build.js')
@@ -478,6 +515,16 @@ async function main() {
     return
   }
 
+  // Handle dev command — thin wrapper that shells to the package manager's
+  // workspace-filtered `dev` script (mirrors what `uniweb create` writes
+  // into the root package.json::scripts.dev). Lazy import keeps startup
+  // fast when the user is not running dev.
+  if (command === 'dev') {
+    const { dev } = await import('./commands/dev.js')
+    await dev(args.slice(1))
+    return
+  }
+
   // Handle docs command (dynamic import — depends on @uniweb/build)
   if (command === 'docs') {
     const { docs } = await importProjectCommand('./commands/docs.js')
@@ -807,18 +854,307 @@ async function main() {
     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}${runCmd(pm, 'dev')}${colors.reset}`)
+    log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
   } else {
     log(`Next steps:\n`)
     log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
     log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
-    log(`  ${colors.cyan}${runCmd(pm, 'dev')}${colors.reset}`)
+    log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${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('')
 
   await showUpdateNotification()
 }
 
+/**
+ * Print help for a specific command. Returns true if a dedicated help
+ * block exists for the command, false to signal "fall back to global
+ * help."
+ *
+ * Help text intentionally lives next to the dispatcher rather than in
+ * the per-command files because most help-seekers haven't run that
+ * command yet — keeping it here means `uniweb foo --help` prints
+ * without loading @uniweb/build or any project context.
+ */
+function printCommandHelp(command) {
+  const blocks = {
+    deploy: `
+${colors.cyan}${colors.bright}uniweb deploy${colors.reset} ${colors.dim}— Deploy a site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb deploy [options]
+
+The host is determined by the resolved deploy.yml target. Defaults to
+${colors.cyan}uniweb${colors.reset} hosting (link-mode, edge JIT prerender) when no deploy.yml exists.
+
+${colors.bright}Hosts:${colors.reset}
+  uniweb              Uniweb hosting (default; requires \`uniweb login\`)
+  cloudflare-pages    Cloudflare Pages (build artifact + adapter postBuild)
+  netlify             Netlify (alias of cloudflare-pages adapter)
+  vercel              Vercel (build-only — deploy via \`npx vercel\`)
+  github-pages        GitHub Pages (build-only — push dist/ to gh-pages)
+  s3-cloudfront       AWS S3 + CloudFront (uploads + invalidates via CLI)
+  generic-static      Plain static-host build, no host-specific helpers
+
+${colors.bright}Options:${colors.reset}
+  --target <name>     Pick a target from deploy.yml (default: deploy.yml's \`default:\`)
+  --host <name>       Override the resolved target's host (does not persist)
+  --host              No value → interactive picker (TTY only)
+  --dry-run           Resolve site.yml + foundation/runtime; print summary; no writes
+  --no-auto-publish   Don't auto-publish workspace-local foundation as part of deploy
+  --no-save           Skip the auto-save of lastDeploy in deploy.yml
+  --local             Internal: target the unicloud mock (see workspace root CLAUDE.md)
+  --non-interactive   Fail with usage info instead of prompting
+
+${colors.bright}Auth:${colors.reset}
+  \`host: uniweb\` requires authentication. Run \`uniweb login\` first, set
+  \`UNIWEB_TOKEN=<bearer>\` env var, or use a static-host adapter that
+  doesn't need a Uniweb account. CI / agents / piped stdin auto-detect
+  non-interactive mode and bail with an actionable error instead of
+  hanging on a browser callback.
+
+${colors.bright}Examples:${colors.reset}
+  uniweb deploy                              # Default (host=uniweb)
+  uniweb deploy --dry-run                    # Print summary, no writes
+  uniweb deploy --host=cloudflare-pages      # One-off override
+  uniweb deploy --target=preview             # Pick named target from deploy.yml
+`,
+    publish: `
+${colors.cyan}${colors.bright}uniweb publish${colors.reset} ${colors.dim}— Publish a foundation to the catalog${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb publish [@org/name] [options]
+
+For site-bound foundations (one foundation, one site), use \`uniweb deploy\`
+instead — it auto-publishes under a site-scoped slot, no naming ceremony.
+
+${colors.bright}Options:${colors.reset}
+  --catalog          Confirm publish to the public catalog (required in CI)
+  --propagate        Walk trusting sites' policy waves (default: silent)
+  --name <id>        Foundation id (overrides package.json::uniweb.id)
+  --namespace <ns>   Force org-scope namespace (overrides package.json)
+  --local            Internal: publish to the unicloud mock (see workspace root CLAUDE.md)
+  --registry <url>   Use a specific registry URL
+  --edit-access <p>  "open" or "restricted" (default: restricted)
+  --dry-run          Show what would be published without uploading
+  --non-interactive  Fail with usage info instead of prompting
+`,
+    create: `
+${colors.cyan}${colors.bright}uniweb create${colors.reset} ${colors.dim}— Create a new project${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb create [name] [options]
+
+${colors.bright}Options:${colors.reset}
+  --template <type>  Project template (default: starter)
+                     Built-in: starter, none, marketing
+                     Local:    ./path/to/template
+                     npm:      @scope/template-name
+                     GitHub:   github:user/repo or https://github.com/user/repo
+  --blank            Create an empty workspace (grow with \`uniweb add\`)
+  --name <name>      Project display name
+  --no-git           Skip git repository initialization
+
+${colors.bright}Examples:${colors.reset}
+  uniweb create my-project                       # Foundation + site + starter content
+  uniweb create my-project --template marketing  # Official template
+  uniweb create my-project --blank               # Empty workspace
+`,
+    dev: `
+${colors.cyan}${colors.bright}uniweb dev${colors.reset} ${colors.dim}— Start a dev server for a site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb dev                  Start dev server for the (single) site
+  uniweb dev <site>           Start dev server for a specific site
+  uniweb dev --site <name>    Same, with explicit flag form
+
+Thin wrapper around the package manager's workspace-filtered \`dev\`
+script (\`pnpm --filter <site> dev\` or \`npm -w <site> run dev\`). Picks
+the single site automatically; for multi-site workspaces the first
+site runs by default with a notice pointing at \`--site\` for explicit
+selection.
+`,
+    build: `
+${colors.cyan}${colors.bright}uniweb build${colors.reset} ${colors.dim}— Build the current project${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb build [options]
+
+At workspace root, builds all foundations first, then all sites.
+Pre-rendering is enabled by default when build.prerender: true in site.yml.
+
+${colors.bright}Options:${colors.reset}
+  --target <type>    Build target (foundation, site) — auto-detected if not specified
+  --prerender        Force pre-rendering (overrides site.yml)
+  --no-prerender     Skip pre-rendering (overrides site.yml)
+  --foundation-dir   Path to foundation directory (for prerendering)
+  --host <name>      Apply host-specific postBuild (e.g., cloudflare-pages emits _redirects)
+  --platform <name>  (Deprecated alias for --host)
+`,
+    add: `
+${colors.cyan}${colors.bright}uniweb add${colors.reset} ${colors.dim}— Add a foundation, site, or extension${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  add project [name]      Add a co-located foundation + site pair
+  add foundation [name]   Add a foundation (--from, --path, --project)
+  add site [name]         Add a site (--from, --foundation, --path, --project)
+  add extension <name>    Add an extension (--from, --site, --path)
+  add section <name>      Add a section type to a foundation (--foundation)
+
+${colors.bright}Common options:${colors.reset}
+  --from <template>       Source content from a template
+  --path <dir>            Override default folder location
+  --foundation <name>     Wire site/extension to this foundation (CI-friendly)
+  --site <name>           Wire extension to this site (CI-friendly)
+  --non-interactive       Fail with usage info instead of prompting
+`,
+    export: `
+${colors.cyan}${colors.bright}uniweb export${colors.reset} ${colors.dim}— Export a self-contained site for third-party hosting${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb export [options]
+
+Builds dist/ and prints upload examples for common static hosts. No login,
+no deploy step — you push the artifact to your host of choice yourself.
+For Uniweb-hosted sites, use \`uniweb deploy\`.
+
+${colors.bright}Options:${colors.reset}
+  --no-prerender     Skip per-page prerendered HTML
+  --host <name>      Apply host-specific postBuild (cloudflare-pages, github-pages, …)
+`,
+    doctor: `
+${colors.cyan}${colors.bright}uniweb doctor${colors.reset} ${colors.dim}— Diagnose project configuration issues${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb doctor [options]
+
+${colors.bright}Options:${colors.reset}
+  --fix              Apply fixes for safely-fixable issues
+  --fix <issue-id>   Apply fix for a specific issue id only
+  --non-interactive  Fail with usage info instead of prompting
+
+Exit code is 1 if errors are found (warnings only → exit 0).
+`,
+    rename: `
+${colors.cyan}${colors.bright}uniweb rename${colors.reset} ${colors.dim}— Rename a workspace package${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb rename foundation <old> <new>
+
+Today supports renaming foundations only. Updates folder name, foundation
+package.json::name, every dependent site's site.yml::foundation, every
+dependent site's package.json::dependencies, pnpm-workspace.yaml, and
+package.json::workspaces. Transactional — bails on conflict before any
+filesystem mutation.
+`,
+    login: `
+${colors.cyan}${colors.bright}uniweb login${colors.reset} ${colors.dim}— Log in to your Uniweb account${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb login [options]
+
+Opens a browser to hub.uniweb.app for OAuth-style login, then captures
+the token via a loopback callback. Falls back to a paste-token prompt
+if the browser flow fails.
+
+${colors.bright}Options:${colors.reset}
+  --backend <url>    Override the auth backend (default: https://hub.uniweb.app)
+
+In non-interactive mode (CI / no TTY / --non-interactive), this command
+errors out — set the \`UNIWEB_TOKEN\` env var instead, or run \`login\`
+once on a machine with a browser to seed ~/.uniweb/auth.json.
+`,
+    invite: `
+${colors.cyan}${colors.bright}uniweb invite${colors.reset} ${colors.dim}— Create a foundation invite for a client${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb invite <email> [options]
+
+${colors.bright}Options:${colors.reset}
+  --uses <n>         Max sites per invite (default: 1)
+  --expires <days>   Days until expiry (default: 30)
+  --version <n>      Major version to license (default: current)
+  --list             List invites for your foundation
+  --revoke <id>      Revoke an invite
+  --resend <id>      Resend an invite
+`,
+    handoff: `
+${colors.cyan}${colors.bright}uniweb handoff${colors.reset} ${colors.dim}— Hand off a site to a client${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb handoff <email> [options]
+
+${colors.bright}Options:${colors.reset}
+  --site <id>        Site identifier (default: auto-generated)
+  --web              Show web-based handoff instructions instead
+`,
+    template: `
+${colors.cyan}${colors.bright}uniweb template${colors.reset} ${colors.dim}— Manage cloud templates${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  template publish        Publish a site as a cloud template
+
+${colors.bright}Publish Options:${colors.reset}
+  --name <name>      Template registry name (overrides site.yml template: field)
+  --title <title>    Display title (overrides site.yml name: field)
+  --description <t>  Description
+  --registry <url>   Registry URL (default: http://localhost:4001)
+`,
+    docs: `
+${colors.cyan}${colors.bright}uniweb docs${colors.reset} ${colors.dim}— Generate component documentation${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  docs               Generate COMPONENTS.md from foundation schema
+  docs site          Show site.yml configuration reference
+  docs page          Show page.yml configuration reference
+  docs meta          Show component meta.js reference
+
+${colors.bright}Options:${colors.reset}
+  --output <file>    Output filename (default: COMPONENTS.md)
+  --from-source      Read meta.js files directly instead of schema.json
+`,
+    i18n: `
+${colors.cyan}${colors.bright}uniweb i18n${colors.reset} ${colors.dim}— Internationalization workflow${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  i18n extract       Extract translatable strings to manifest
+  i18n sync          Update manifest with content changes
+  i18n status        Show translation coverage per locale
+`,
+    inspect: `
+${colors.cyan}${colors.bright}uniweb inspect${colors.reset} ${colors.dim}— Inspect parsed content shape${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb inspect <path>
+
+Prints the parsed content shape of a markdown file or folder — the
+{ content, params, items, … } object that components actually receive.
+Useful for debugging "why isn't my section getting X?".
+`,
+    update: `
+${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Update AGENTS.md to match installed CLI version${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb update
+
+Refreshes the project's AGENTS.md from the CLI's bundled version. Run
+after upgrading the \`uniweb\` package to pick up new content authoring
+patterns and platform documentation.
+`,
+  }
+
+  if (!blocks[command]) return false
+  log(blocks[command])
+  return true
+}
+
 function showHelp() {
   log(`
 ${colors.cyan}${colors.bright}Uniweb CLI${colors.reset} ${colors.dim}v${getCliVersion()}${colors.reset}
@@ -830,6 +1166,7 @@ ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
   add <type> [name]  Add a foundation, site, or extension to a project
   rename <type>      Rename a workspace package (foundation today)
+  dev                Start a dev server for a site
   build              Build the current project
   deploy             Deploy a site to Uniweb hosting
   export             Export a self-contained site for third-party hosting
@@ -896,21 +1233,34 @@ ${colors.bright}Template Options:${colors.reset}
   --registry <url>   Registry URL (default: http://localhost:4001)
 
 ${colors.bright}Deploy Options:${colors.reset}
+  --target <name>    Pick a target from deploy.yml (default: deploy.yml's \`default:\`)
+  --host <name>      Override the resolved target's host (does not persist).
+                     Without a value, opens an interactive picker (TTY only).
+                     Hosts: uniweb, cloudflare-pages, netlify, vercel,
+                     github-pages, s3-cloudfront, generic-static.
   --dry-run          Resolve site.yml + foundation/runtime; print summary; no writes
   --no-auto-publish  Don't auto-publish workspace-local foundation as part of deploy
+  --no-save          Skip the auto-save of lastDeploy in deploy.yml
+
+${colors.bright}Dev Options:${colors.reset}
+  <site>             Site name to run (positional)
+  --site <name>      Site name to run (explicit form)
 
 ${colors.bright}Export Options:${colors.reset}
   --no-prerender     Skip per-page prerendered HTML
+  --host <name>      Apply host-specific postBuild (cloudflare-pages, github-pages, …)
 
 ${colors.bright}Build Options:${colors.reset}
-  --target <type>    Build target (foundation, site) - auto-detected if not specified
+  --target <type>    Build target (foundation, site) — auto-detected if not specified
   --prerender        Force pre-rendering (overrides site.yml)
   --no-prerender     Skip pre-rendering (overrides site.yml)
   --foundation-dir   Path to foundation directory (for prerendering)
-  --platform <name>  Deployment platform (e.g., vercel) for platform-specific output
+  --host <name>      Apply host-specific postBuild (cloudflare-pages, s3-cloudfront, …)
+  --platform <name>  (Deprecated alias for --host)
 
   At workspace root, builds all foundations first, then all sites.
-  Pre-rendering is enabled by default when build.prerender: true in site.yml
+  Pre-rendering is enabled by default when build.prerender: true in site.yml.
+  See \`uniweb <command> --help\` for command-specific detail and examples.
 
 ${colors.bright}Docs Subcommands:${colors.reset}
   docs               Generate COMPONENTS.md from foundation schema

package/src/utils/args.js

@@ -0,0 +1,37 @@
+/**
+ * argv parsing helpers shared across CLI commands.
+ */
+
+/**
+ * Read `--flag value` from argv. Accepts both `--flag value` and
+ * `--flag=value`.
+ *
+ * Returns:
+ *   - undefined when the flag is absent
+ *   - null when the flag is present without a value (last arg, next is
+ *     another flag, or `--flag=` empty form)
+ *   - string when the flag carries a value
+ *
+ * The three-state return lets callers distinguish "not given" (e.g.,
+ * fall back to a default) from "given but empty" (e.g., trigger an
+ * interactive prompt).
+ *
+ * @param {string[]} args
+ * @param {string} name — Including the leading dashes, e.g. '--host'.
+ * @returns {string | null | undefined}
+ */
+export function readFlagValue(args, name) {
+  const eqPrefix = name + '='
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === name) {
+      const next = args[i + 1]
+      if (next === undefined || next.startsWith('--')) return null
+      return next
+    }
+    if (args[i].startsWith(eqPrefix)) {
+      const v = args[i].slice(eqPrefix.length)
+      return v === '' ? null : v
+    }
+  }
+  return undefined
+}

package/src/utils/auth.js

@@ -153,17 +153,45 @@ export function isExpired(auth) {
  * Ensure the user is authenticated. If not, prompt inline login.
  * Returns the auth token on success, exits the process on cancel.
  *
+ * In non-interactive mode (CI, no TTY, or --non-interactive in args),
+ * bails with an actionable error instead of opening a browser. The browser
+ * login flow waits 120 seconds for a callback that can never arrive without
+ * a user, then drops to a token-paste prompt that pipes can't answer —
+ * silently burning two minutes per invocation. CI / agent / piped callers
+ * must set `UNIWEB_TOKEN`, run `uniweb login` interactively first, or use
+ * `--local` for the unicloud mock (see workspace root CLAUDE.md).
+ *
  * @param {Object} options
  * @param {string} options.command - The command that needs auth (for messaging)
+ * @param {string[]} [options.args] - Argv slice; checked for --non-interactive
  * @returns {Promise<string>} Bearer token
  */
-export async function ensureAuth({ command = 'This command' } = {}) {
+export async function ensureAuth({ command = 'This command', args = [] } = {}) {
+  // Honor explicit token from env — useful for CI and agents.
+  if (process.env.UNIWEB_TOKEN) {
+    return process.env.UNIWEB_TOKEN
+  }
+
   const auth = await readAuth()
 
   if (auth?.token && !isExpired(auth)) {
     return auth.token
   }
 
+  // Non-interactive bail: don't open a browser, don't wait 120s, don't
+  // prompt for a token paste. Print an actionable error and exit.
+  const { isNonInteractive, getCliPrefix } = await import('./interactive.js')
+  if (isNonInteractive(args)) {
+    const prefix = getCliPrefix()
+    const reason = auth && isExpired(auth) ? 'Session expired.' : 'Not logged in.'
+    console.error(`\x1b[31m✗\x1b[0m ${reason} ${command} requires a Uniweb account, and the CLI is in non-interactive mode (CI / no TTY / --non-interactive).`)
+    console.error(`  Options:`)
+    console.error(`    • Run \`${prefix} login\` interactively first, then re-run.`)
+    console.error(`    • Set the \`UNIWEB_TOKEN\` env var to a bearer token.`)
+    console.error(`    • Use \`--local\` to target the unicloud mock (internal testing only — see workspace root CLAUDE.md).`)
+    process.exit(1)
+  }
+
   // Need to log in — delegate to the login command
   if (auth && isExpired(auth)) {
     console.log(`\x1b[33mSession expired.\x1b[0m ${command} requires a Uniweb account.\n`)

package/src/utils/config.js

@@ -157,9 +157,17 @@ export async function writeRootPackageJson(rootDir, pkg) {
 }
 
 /**
- * Compute root scripts based on discovered sites
+ * Compute root scripts based on discovered sites.
+ *
+ * `dev` and `build` route through the uniweb CLI verb (PM-agnostic — they
+ * resolve `uniweb` from the project's local node_modules/.bin, so `pnpm
+ * dev` and `npm run dev` both work without locking the scripts to one PM
+ * at create-time). `preview` stays on a PM-specific filter because there
+ * isn't a `uniweb preview` verb yet (the site's own `vite preview` is what
+ * runs); switch it over when one ships.
+ *
  * @param {Array<{name: string, path: string}>} sites - Discovered sites
- * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager
+ * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager (used only for preview)
  * @returns {Object} Scripts object for package.json
  */
 export function computeRootScripts(sites, pm = 'pnpm') {
@@ -172,16 +180,17 @@ export function computeRootScripts(sites, pm = 'pnpm') {
   }
 
   if (sites.length === 1) {
-    scripts.dev = filterCmd(pm, sites[0].name, 'dev')
+    scripts.dev = 'uniweb dev'
     scripts.preview = filterCmd(pm, sites[0].name, 'preview')
   } else {
-    // First site gets unqualified dev/preview
-    scripts.dev = filterCmd(pm, sites[0].name, 'dev')
+    // First site gets unqualified dev/preview (matches `uniweb dev`'s
+    // default-to-first-site behavior).
+    scripts.dev = 'uniweb dev'
     scripts.preview = filterCmd(pm, sites[0].name, 'preview')
 
     // Subsequent sites get qualified dev:{name}/preview:{name}
     for (let i = 1; i < sites.length; i++) {
-      scripts[`dev:${sites[i].name}`] = filterCmd(pm, sites[i].name, 'dev')
+      scripts[`dev:${sites[i].name}`] = `uniweb dev ${sites[i].name}`
       scripts[`preview:${sites[i].name}`] = filterCmd(pm, sites[i].name, 'preview')
     }
   }