uniweb 1.0.0 → 1.0.2

package/src/commands/add.js

@@ -0,0 +1,1900 @@
+/**
+ * Add Command
+ *
+ * Adds foundations, sites, extensions, section types, or co-located projects to an existing workspace.
+ *
+ * Usage:
+ *   uniweb add project [name] [--from <template>]
+ *   uniweb add foundation [name] [--from <template>] [--path <dir>] [--project <name>]
+ *   uniweb add site [name] [--from <template>] [--foundation <name>] [--path <dir>] [--project <name>]
+ *   uniweb add extension [name] [--from <template>] [--site <name>] [--path <dir>]
+ *   uniweb add section <name> [--foundation <name>]
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join, relative, basename } from 'node:path'
+import prompts from 'prompts'
+import yaml from 'js-yaml'
+import { resolveFoundationSrcPath, readFoundationName } from '@uniweb/build'
+import {
+  scaffoldFoundation,
+  scaffoldSite,
+  applyContent,
+  applyStarter,
+  mergeTemplateDependencies
+} from '../utils/scaffold.js'
+import {
+  resolvePlacement,
+  SITE_KIND,
+  FOUNDATION_KIND,
+  EXTENSION_KIND
+} from '../utils/placement.js'
+import {
+  readWorkspaceConfig,
+  addWorkspaceGlob,
+  updateRootScripts
+} from '../utils/config.js'
+import { discoverFoundations, discoverSites } from '../utils/discover.js'
+import { generateStarter, reportStarter, declarationFor } from './starter.js'
+import {
+  validatePackageName,
+  getExistingPackageNames,
+  resolveUniqueName
+} from '../utils/names.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import {
+  normalizeFoundationName,
+  ensureFoundationName
+} from '../utils/foundation-name.js'
+import {
+  detectPackageManager,
+  detectWorkspacePm,
+  detectInstalledPnpmVersion,
+  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,
+  resolveCiPnpmVersion,
+  resolveCiNodeVersion
+} from '../versions.js'
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
+}
+
+// Porcelain (`--json`) mode: stdout carries ONLY the JSON, so every human line
+// diverts to stderr — the convention `register.js` already follows and
+// `families.js` states ("stdout carries JSON and nothing else, so it pipes").
+//
+// ⛔ It is set per run rather than only when true, because a module-level flag
+// that is only ever turned ON leaks into the next call in the same process —
+// which is every call in the test suite.
+let jsonMode = false
+export function setAddJsonMode(on) {
+  jsonMode = Boolean(on)
+}
+
+function log(message) {
+  if (jsonMode) console.error(message)
+  else console.log(message)
+}
+function success(message) {
+  log(`${colors.green}✓${colors.reset} ${message}`)
+}
+function error(message) {
+  console.error(`${colors.red}✗${colors.reset} ${message}`)
+}
+function info(message) {
+  log(`${colors.dim}${message}${colors.reset}`)
+}
+
+/**
+ * Parse add command arguments
+ */
+function parseArgs(args) {
+  const result = {
+    subcommand: args[0], // foundation, site, extension, ci, …
+    name: null,
+    path: null,
+    project: null,
+    foundation: null,
+    site: null,
+    from: null,
+    host: null,
+    force: false,
+    domain: null,
+    // `add ci` only: what the workflow publishes ('site' | 'foundation'),
+    // the name to register under on the host, and whether to also
+    // scaffold PR-preview workflows.
+    target: null,
+    projectName: null,
+    previews: true,
+    // `add section` only: generate starter content for the section type from
+    // its `content:` declaration, and which preset's params to frontmatter it
+    // with. `--write` sends the markdown to a file instead of stdout.
+    starter: false,
+    preset: null,
+    write: null,
+    json: false
+  }
+
+  // Booleans (no value) consumed up-front so the value-flag loop below
+  // doesn't accidentally swallow the next positional.
+  const BOOLEAN_FLAGS = new Set(['--force', '--no-previews', '--starter', '--json'])
+
+  // Value flags, mapped to their result key. Both spellings are accepted:
+  // `--host github-pages` and `--host=github-pages`.
+  //
+  // The `=` form used to be dropped silently — every branch matched on an
+  // exact `args[i] === '--flag'`, so `--host=github-pages` fell through
+  // and left `host` null. It went unnoticed because `add ci` defaulted to
+  // github-pages when no host was given, making the one command our docs
+  // print (`uniweb add ci --host=github-pages`) appear to work while
+  // actually ignoring the flag. Requiring a real host surfaced it.
+  const VALUE_FLAGS = {
+    '--path': 'path',
+    '--project': 'project',
+    '--foundation': 'foundation',
+    '--site': 'site',
+    '--from': 'from',
+    '--host': 'host',
+    '--domain': 'domain',
+    '--target': 'target',
+    '--project-name': 'projectName',
+    '--preset': 'preset',
+    '--write': 'write'
+  }
+
+  /** Split `--flag=value` into [flag, value]; `--flag` into [flag, null]. */
+  const splitFlag = (arg) => {
+    const eq = arg.indexOf('=')
+    return eq === -1 ? [arg, null] : [arg.slice(0, eq), arg.slice(eq + 1)]
+  }
+
+  // Find positional name (first arg after subcommand that's not a flag).
+  for (let i = 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const [flag, inlineValue] = splitFlag(args[i])
+      // Only skip the next arg when the value is genuinely separate.
+      // Previously an `=`-form flag also consumed the following arg,
+      // which could swallow the positional name.
+      if (!BOOLEAN_FLAGS.has(flag) && inlineValue === null) i++
+      continue
+    }
+    if (!result.name) {
+      result.name = args[i]
+    }
+  }
+
+  // Parse flags
+  for (let i = 1; i < args.length; i++) {
+    const [flag, inlineValue] = splitFlag(args[i])
+    const key = VALUE_FLAGS[flag]
+    if (key) {
+      if (inlineValue !== null) {
+        result[key] = inlineValue
+      } else if (args[i + 1] !== undefined && !args[i + 1].startsWith('--')) {
+        result[key] = args[++i]
+      }
+    } else if (flag === '--force') {
+      result.force = true
+    } else if (flag === '--no-previews') {
+      result.previews = false
+    } else if (flag === '--starter') {
+      result.starter = true
+    } else if (flag === '--json') {
+      result.json = true
+    }
+  }
+
+  return result
+}
+
+/**
+ * Main add command handler
+ */
+export async function add(rawArgs) {
+  const nonInteractive = isNonInteractive(rawArgs)
+  const args = stripNonInteractiveFlag(rawArgs)
+
+  const pm = detectPackageManager()
+  const prefix = getCliPrefix()
+
+  // Find workspace root
+  const rootDir = findWorkspaceRoot()
+  if (!rootDir) {
+    error(
+      'Not in a Uniweb workspace. Run this command from a project directory.'
+    )
+    error('Use "uniweb create" to create a new project first.')
+    process.exit(1)
+  }
+
+  // Interactive subcommand chooser when no args given
+  let parsed
+  if (!args.length || (args[0] && args[0].startsWith('--'))) {
+    if (nonInteractive) {
+      error(`Missing subcommand.\n`)
+      log(
+        formatOptions([
+          {
+            label: 'project',
+            description: 'Co-located foundation + site pair'
+          },
+          {
+            label: 'foundation',
+            description: 'Component system for content authors'
+          },
+          { label: 'site', description: 'Content site' },
+          { label: 'extension', description: 'Additional component package' },
+          { label: 'section', description: 'Section type in a foundation' },
+          {
+            label: 'ci',
+            description: 'CI deploy workflow for a host (e.g., GitHub Pages)'
+          }
+        ])
+      )
+      log('')
+      log(
+        `Usage: ${prefix} add <project|foundation|site|extension|section|ci> [name]`
+      )
+      process.exit(1)
+    }
+
+    const response = await prompts(
+      {
+        type: 'select',
+        name: 'subcommand',
+        message: 'What would you like to add?',
+        choices: [
+          {
+            title: 'Project',
+            value: 'project',
+            description: 'Co-located foundation + site pair'
+          },
+          {
+            title: 'Foundation',
+            value: 'foundation',
+            description: 'Component system for content authors'
+          },
+          { title: 'Site', value: 'site', description: 'Content site' },
+          {
+            title: 'Extension',
+            value: 'extension',
+            description: 'Additional component package'
+          },
+          {
+            title: 'Section',
+            value: 'section',
+            description: 'Section type in a foundation'
+          },
+          {
+            title: 'CI workflow',
+            value: 'ci',
+            description: 'Deploy workflow for a host (e.g., GitHub Pages)'
+          }
+        ]
+      },
+      {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        }
+      }
+    )
+    parsed = parseArgs([response.subcommand, ...args])
+  } else {
+    parsed = parseArgs(args)
+  }
+
+  // Read root package.json for project name
+  const rootPkg = JSON.parse(
+    await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
+  )
+  const projectName = rootPkg.name || 'my-project'
+
+  switch (parsed.subcommand) {
+    case 'project':
+      await addProject(rootDir, projectName, parsed, pm)
+      break
+    case 'foundation':
+      await addFoundation(rootDir, projectName, parsed, pm)
+      break
+    case 'site':
+      await addSite(rootDir, projectName, parsed, pm)
+      break
+    case 'extension':
+      await addExtension(rootDir, projectName, parsed, pm)
+      break
+    case 'section':
+      await addSection(rootDir, parsed)
+      break
+    case 'ci':
+      // The scaffolded workflow must install the way THIS WORKSPACE
+      // installs, which is a property of the repo (its lockfile), not of
+      // how the CLI happened to be launched. `detectPackageManager()`
+      // reads npm_config_user_agent, so `npx uniweb add ci` in a pnpm
+      // workspace produced a workflow running `npm ci` — which fails on
+      // the first CI run, because there is no package-lock.json to
+      // install from. npx is a normal way to run the CLI, so this broke
+      // the common case. Fall back to the invocation only when the repo
+      // has no lockfile to read.
+      await addCi(rootDir, parsed, detectWorkspacePm(rootDir) || pm)
+      break
+    default:
+      error(`Unknown subcommand: ${parsed.subcommand}`)
+      log(
+        `Valid subcommands: project, foundation, site, extension, section, ci`
+      )
+      process.exit(1)
+  }
+}
+
+/**
+ * Add a foundation to the workspace
+ */
+async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
+  const name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Resolve placement first (path + package name) so we have everything we
+  // need to validate before scaffolding. Note: `name` here may be a bare
+  // name (`ui`) or a path (`foundations/ui`); resolvePlacement handles
+  // both. Format validation runs on the derived package name below, not
+  // on the raw input — slashes in the input are intentional path syntax.
+  const placement = resolvePlacement(rootDir, name, opts, FOUNDATION_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
+  const { relativePath } = placement
+  let { packageName } = placement
+  const fullPath = join(rootDir, relativePath)
+
+  // The foundation's own name — what it registers as, written to main.js — is
+  // the name asked for, before any workspace suffix below; with none (`src`),
+  // the project's.
+  const askedName =
+    normalizeFoundationName(packageName) || normalizeFoundationName(projectName)
+
+  // Validate the derived package name (format + reserved-name check). The
+  // auto-derived `src` default is grandfathered in (`src` IS reserved
+  // but `src` is the convention for "the package that lives in src/").
+  if (packageName !== 'src') {
+    const valid = validatePackageName(packageName)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
+
+  // Collision check 1: target folder already exists.
+  if (existsSync(fullPath)) {
+    error(
+      `Cannot create foundation: ${colors.bright}${relativePath}/${colors.reset} already exists.`
+    )
+    log('')
+    log(`Pick a different name, or pass --path to choose a different folder:`)
+    log(
+      `  ${colors.cyan}${getCliPrefix()} add foundation <name>${colors.reset}`
+    )
+    log(
+      `  ${colors.cyan}${getCliPrefix()} add foundation <name> --path <parent-dir>${colors.reset}`
+    )
+    process.exit(1)
+  }
+
+  // Collision check 2: a package with the same name already exists somewhere
+  // in the workspace.
+  //
+  // Cross-role collisions auto-resolve. If a *site* already owns this name,
+  // suffix the foundation with `-src` (matching the `add project` and
+  // `add extension` precedents). The site keeps its name; the foundation
+  // gets a self-documenting suffix that says "this is the source code for
+  // the site that owns this name." Same-role collisions stay an error —
+  // two foundations with the same name is a real "be more specific"
+  // situation, not a disambiguation case.
+  if (existingNames.has(packageName)) {
+    const sites = await discoverSites(rootDir)
+    const isSiteCollision = sites.some((s) => s.name === packageName)
+    if (isSiteCollision) {
+      const suffixed = `${packageName}-src`
+      if (existingNames.has(suffixed)) {
+        error(
+          `Cannot create foundation: both ${colors.bright}${packageName}${colors.reset} and ${colors.bright}${suffixed}${colors.reset} are taken in this workspace.`
+        )
+        log(`Pick a different name:`)
+        log(
+          `  ${colors.cyan}${getCliPrefix()} add foundation <other-name>${colors.reset}`
+        )
+        process.exit(1)
+      }
+      info(
+        `Package "${packageName}" is taken by a site; using "${suffixed}" for this foundation.`
+      )
+      packageName = suffixed
+    } else {
+      error(
+        `Cannot create foundation: a foundation named ${colors.bright}${packageName}${colors.reset} already exists in this workspace.`
+      )
+      log(`Pick a different name:`)
+      log(
+        `  ${colors.cyan}${getCliPrefix()} add foundation <other-name>${colors.reset}`
+      )
+      process.exit(1)
+    }
+  }
+
+  // Scaffold
+  const registryName = await unclaimedFoundationName(rootDir, [
+    askedName,
+    normalizeFoundationName(packageName)
+  ])
+  await scaffoldFoundation(
+    fullPath,
+    {
+      name: packageName,
+      registryName,
+      projectName,
+      isExtension: false
+    },
+    {
+      onProgress: (msg) => info(`  ${msg}`)
+    }
+  )
+
+  // Apply template content if --from specified. Its main.js replaces the
+  // scaffolded one, so the name is given again unless the template names it.
+  if (opts.from) {
+    await applyFromTemplate(opts.from, 'foundation', fullPath, projectName)
+    ensureFoundationName(fullPath, registryName)
+  }
+
+  // Register the package in pnpm-workspace.yaml — by exact path, not by glob.
+  // No glob inference: if the user wants `foundations/*` they can edit the
+  // workspace file themselves. This matches the "no assumptions" rule.
+  await addWorkspaceGlob(rootDir, relativePath)
+
+  // Update root scripts
+  const sites = await discoverSites(rootDir)
+  await updateRootScripts(rootDir, sites, pm)
+
+  success(
+    `Created foundation ${colors.bright}${packageName}${colors.reset} at ${relativePath}/`
+  )
+  log('')
+  log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
+}
+
+/**
+ * Add a site to the workspace
+ */
+async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
+  const name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Resolve placement first (path + package name); see notes in addFoundation.
+  const placement = resolvePlacement(rootDir, name, opts, SITE_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
+  const { relativePath } = placement
+  let siteName = placement.packageName
+  const fullPath = join(rootDir, relativePath)
+
+  // Validate the package name (skip for the auto-derived 'site' default).
+  if (siteName !== 'site') {
+    const valid = validatePackageName(siteName)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
+
+  // Collision check 1: target folder exists.
+  if (existsSync(fullPath)) {
+    error(
+      `Cannot create site: ${colors.bright}${relativePath}/${colors.reset} already exists.`
+    )
+    log('')
+    log(`Pick a different name, or pass --path to choose a different folder:`)
+    log(`  ${colors.cyan}${getCliPrefix()} add site <name>${colors.reset}`)
+    log(
+      `  ${colors.cyan}${getCliPrefix()} add site <name> --path <parent-dir>${colors.reset}`
+    )
+    process.exit(1)
+  }
+
+  // Collision check 2: cross-role collisions auto-resolve with `-site`
+  // suffix; same-role collisions error. See the symmetric logic in
+  // addFoundation for the rationale.
+  if (existingNames.has(siteName)) {
+    const foundations = await discoverFoundations(rootDir)
+    const isFoundationCollision = foundations.some((f) => f.name === siteName)
+    if (isFoundationCollision) {
+      const suffixed = `${siteName}-site`
+      if (existingNames.has(suffixed)) {
+        error(
+          `Cannot create site: both ${colors.bright}${siteName}${colors.reset} and ${colors.bright}${suffixed}${colors.reset} are taken in this workspace.`
+        )
+        log(`Pick a different name:`)
+        log(
+          `  ${colors.cyan}${getCliPrefix()} add site <other-name>${colors.reset}`
+        )
+        process.exit(1)
+      }
+      info(
+        `Package "${siteName}" is taken by a foundation; using "${suffixed}" for this site.`
+      )
+      siteName = suffixed
+    } else {
+      error(
+        `Cannot create site: a site named ${colors.bright}${siteName}${colors.reset} already exists in this workspace.`
+      )
+      log(`Pick a different name:`)
+      log(
+        `  ${colors.cyan}${getCliPrefix()} add site <other-name>${colors.reset}`
+      )
+      process.exit(1)
+    }
+  }
+
+  // Resolve foundation
+  const foundation = await resolveFoundation(rootDir, opts.foundation)
+
+  if (foundation) {
+    // Compute relative path from site to foundation
+    const foundationPath = computeFoundationPath(relativePath, foundation.path)
+
+    // Scaffold
+    await scaffoldSite(
+      fullPath,
+      {
+        name: siteName,
+        projectName,
+        foundationName: foundation.name,
+        foundationPath,
+        foundationRef: foundation.name
+      },
+      {
+        onProgress: (msg) => info(`  ${msg}`)
+      }
+    )
+  } else {
+    // No foundation — scaffold without wiring
+    await scaffoldSite(
+      fullPath,
+      {
+        name: siteName,
+        projectName,
+        foundationName: '',
+        foundationPath: ''
+      },
+      {
+        onProgress: (msg) => info(`  ${msg}`)
+      }
+    )
+    log(
+      `  ${colors.yellow}⚠ No foundation wired. Add one later with: uniweb add foundation${colors.reset}`
+    )
+  }
+
+  // Apply template content if --from specified
+  if (opts.from) {
+    await applyFromTemplate(opts.from, 'site', fullPath, projectName)
+  }
+
+  // Register the package by exact path. No glob inference.
+  await addWorkspaceGlob(rootDir, relativePath)
+
+  // Update root scripts (discover sites after registration — includes the new one)
+  const sites = await discoverSites(rootDir)
+  if (!sites.find((s) => s.path === relativePath)) {
+    sites.push({ name: siteName, path: relativePath })
+  }
+  await updateRootScripts(rootDir, sites, pm)
+
+  if (foundation) {
+    success(
+      `Created site ${colors.bright}${siteName}${colors.reset} at ${relativePath}/ → foundation '${foundation.name}'`
+    )
+  } else {
+    success(
+      `Created site ${colors.bright}${siteName}${colors.reset} at ${relativePath}/`
+    )
+  }
+  log('')
+  log(
+    `Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${siteName}${colors.reset}`
+  )
+  if (!opts.from) {
+    log('')
+    log(
+      `${colors.dim}To add your first page, create ${relativePath}/pages/home/page.yml and a .md file.${colors.reset}`
+    )
+    log(
+      `${colors.dim}Or use --from to start with template content: uniweb add site --from starter${colors.reset}`
+    )
+  }
+}
+
+/**
+ * Add an extension to the workspace
+ */
+async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
+  let name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // A name is asked for unless one is given, or `--path` names the folder.
+  if (!name && !opts.path) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing extension name.\n`)
+      log(`Usage: ${getCliPrefix()} add extension <name>`)
+      process.exit(1)
+    }
+
+    const response = await prompts(
+      {
+        type: 'text',
+        name: 'name',
+        message: 'Extension name:',
+        validate: (value) => validatePackageName(value)
+      },
+      {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        }
+      }
+    )
+    name = response.name
+  }
+
+  // ⭐ Placed by the rule `add foundation` follows (utils/placement.js): the folder
+  // you name is the folder created — `effects` → effects/, `extensions/effects` →
+  // extensions/effects/ — and `--path` is the folder it goes in.
+  const placement = resolvePlacement(rootDir, name, opts, EXTENSION_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
+  const { relativePath } = placement
+  // The extension's own name: the last segment of the folder.
+  name = placement.packageName
+
+  // Reject reserved names (format + reserved check only — collisions handled at package name level)
+  const valid = validatePackageName(name)
+  if (valid !== true) {
+    error(valid)
+    process.exit(1)
+  }
+
+  // Auto-suffix package name if it collides with an existing package
+  const extensionPackageName = existingNames.has(name)
+    ? resolveUniqueName(name, '-ext', existingNames)
+    : name
+
+  const fullPath = join(rootDir, relativePath)
+
+  if (existsSync(fullPath)) {
+    error(
+      `Cannot create extension: ${colors.bright}${relativePath}/${colors.reset} already exists.`
+    )
+    log('')
+    log(`Pick a different name, or pass --path to choose a different folder.`)
+    process.exit(1)
+  }
+
+  // Scaffold foundation with extension flag. Its name — what it registers as —
+  // is the one asked for, not the package's suffixed one, unless a foundation in
+  // the workspace already registers as that.
+  const registryName = await unclaimedFoundationName(rootDir, [
+    normalizeFoundationName(name),
+    normalizeFoundationName(extensionPackageName)
+  ])
+  await scaffoldFoundation(
+    fullPath,
+    {
+      name: extensionPackageName,
+      registryName,
+      projectName,
+      isExtension: true
+    },
+    {
+      onProgress: (msg) => info(`  ${msg}`)
+    }
+  )
+
+  // Apply template content if --from specified
+  if (opts.from) {
+    await applyFromTemplate(opts.from, 'extension', fullPath, projectName)
+    ensureFoundationName(fullPath, registryName)
+  }
+
+  // Register the folder it is in, as add foundation does
+  await addWorkspaceGlob(rootDir, relativePath)
+
+  // Wire extension to site:
+  //   - --site <name>: explicit, wire it.
+  //   - exactly one site: silent auto-wire (intent is unambiguous).
+  //   - multiple sites, interactive: single-select prompt (extensions are
+  //     typically per-site specialization — pick which site).
+  //   - multiple sites, non-interactive: don't wire silently. Print a
+  //     warning so the user/agent knows wiring is pending, and exit 0
+  //     (the extension itself is fine).
+  //   - no sites: print a note and exit 0.
+  let wiredSite = null
+  let unwiredReason = null
+  // A site loads a workspace extension from `/<name>/entry.js`, which the build
+  // finds in `<name>/` or `extensions/<name>/` (wireExtensionToSite). An entry
+  // pointing anywhere else would build with a warning and 404 at runtime, so
+  // none is written.
+  const reachable = relativePath === name || relativePath === `extensions/${name}`
+  if (!reachable) {
+    unwiredReason =
+      `A site loads a workspace extension from /${name}/entry.js, which the build finds in ` +
+      `${name}/ or extensions/${name}/ — not ${relativePath}/. Move the folder to one of those, ` +
+      `or list a URL where the built extension is served under <site>/site.yml::extensions:.`
+  } else if (opts.site) {
+    wiredSite = await wireExtensionToSite(rootDir, opts.site, relativePath)
+  } else {
+    const sites = await discoverSites(rootDir)
+    if (sites.length === 1) {
+      wiredSite = await wireExtensionToSite(rootDir, sites[0].name, relativePath)
+    } else if (sites.length > 1) {
+      if (isNonInteractive(process.argv)) {
+        unwiredReason = `Multiple sites in workspace; extension not wired. Re-run with --site <name>, or edit <site>/site.yml::extensions: manually.`
+      } else {
+        const sortedSites = [...sites].sort((a, b) =>
+          a.name.localeCompare(b.name)
+        )
+        const response = await prompts(
+          {
+            type: 'select',
+            name: 'site',
+            message: 'Which site is this extension for?',
+            choices: sortedSites.map((s) => ({
+              title: s.name,
+              description: s.path,
+              value: s.name
+            }))
+          },
+          {
+            onCancel: () => {
+              log('\nCancelled.')
+              process.exit(0)
+            }
+          }
+        )
+        if (response.site) {
+          wiredSite = await wireExtensionToSite(rootDir, response.site, relativePath)
+        }
+      }
+    } else {
+      unwiredReason = `No site in this workspace yet. Wire this extension into a site's site.yml::extensions: once you create one.`
+    }
+  }
+
+  // Update root scripts
+  const sites = await discoverSites(rootDir)
+  await updateRootScripts(rootDir, sites, pm)
+
+  let msg = `Created extension '${name}' at ${relativePath}/`
+  if (wiredSite) {
+    msg += ` → wired to site '${wiredSite}'`
+  }
+  success(msg)
+  if (unwiredReason) {
+    log(`  ${colors.yellow}⚠ ${unwiredReason}${colors.reset}`)
+  }
+  log('')
+  log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
+}
+
+/**
+ * Add a co-located foundation + site pair to the workspace
+ */
+async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
+  let name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Validate name format
+  if (name) {
+    const valid = validatePackageName(name)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
+
+  // Interactive name prompt when name not provided
+  if (!name) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing project name.\n`)
+      log(`Usage: ${getCliPrefix()} add project <name>`)
+      process.exit(1)
+    }
+
+    const response = await prompts(
+      {
+        type: 'text',
+        name: 'name',
+        message: 'Project name:',
+        validate: (value) => validatePackageName(value)
+      },
+      {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        }
+      }
+    )
+    name = response.name
+  }
+
+  // Check directory doesn't already exist
+  const projectDir = join(rootDir, name)
+  if (existsSync(projectDir)) {
+    error(`Directory already exists: ${name}/`)
+    process.exit(1)
+  }
+
+  // Compute package names. Co-located projects use the `-src` / `-site`
+  // suffix convention so package names are unique within the workspace.
+  // The folder structure inside the project is `src/` + `site/`, mirroring
+  // the single-project default layout.
+  const foundationPkgName = `${name}-src`
+  const sitePkgName = `${name}-site`
+
+  // Check package name collisions
+  for (const pkgName of [foundationPkgName, sitePkgName]) {
+    if (existingNames.has(pkgName)) {
+      error(`Package name '${pkgName}' already exists in this workspace.`)
+      process.exit(1)
+    }
+  }
+
+  const progressCb = (msg) => info(`  ${msg}`)
+
+  // Scaffold foundation (folder: src/, package name: <project>-src, name — what
+  // it registers as — <project>)
+  info(`Creating foundation: ${foundationPkgName}...`)
+  const registryName = await unclaimedFoundationName(rootDir, [
+    normalizeFoundationName(name),
+    normalizeFoundationName(foundationPkgName)
+  ])
+  await scaffoldFoundation(
+    join(projectDir, 'src'),
+    {
+      name: foundationPkgName,
+      registryName,
+      projectName,
+      isExtension: false
+    },
+    { onProgress: progressCb }
+  )
+
+  // Scaffold site
+  info(`Creating site: ${sitePkgName}...`)
+  await scaffoldSite(
+    join(projectDir, 'site'),
+    {
+      name: sitePkgName,
+      projectName,
+      foundationName: foundationPkgName,
+      foundationPath: 'file:../src',
+      foundationRef: foundationPkgName
+    },
+    { onProgress: progressCb }
+  )
+
+  // Apply template content if --from specified
+  if (opts.from) {
+    await applyFromTemplate(
+      opts.from,
+      'foundation',
+      join(projectDir, 'src'),
+      projectName
+    )
+    ensureFoundationName(join(projectDir, 'src'), registryName)
+    await applyFromTemplate(
+      opts.from,
+      'site',
+      join(projectDir, 'site'),
+      projectName
+    )
+  }
+
+  // Update workspace globs for co-located layout
+  await addWorkspaceGlob(rootDir, '*/src')
+  await addWorkspaceGlob(rootDir, '*/site')
+
+  // Update root scripts
+  const sites = await discoverSites(rootDir)
+  if (!sites.find((s) => s.path === `${name}/site`)) {
+    sites.push({ name: sitePkgName, path: `${name}/site` })
+  }
+  await updateRootScripts(rootDir, sites, pm)
+
+  success(`Created project '${name}' at ${name}/`)
+  log(
+    `  ${colors.dim}Foundation: ${name}/src/ (${foundationPkgName})${colors.reset}`
+  )
+  log(`  ${colors.dim}Site: ${name}/site/ (${sitePkgName})${colors.reset}`)
+  log('')
+  log(
+    `Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${sitePkgName}${colors.reset}`
+  )
+}
+
+/**
+ * Resolve which foundation to wire a site to
+ */
+async function resolveFoundation(rootDir, foundationFlag) {
+  const foundations = await discoverFoundations(rootDir)
+
+  if (foundationFlag) {
+    // Find by name
+    const found = foundations.find((f) => f.name === foundationFlag)
+    if (found) return found
+
+    // Not found — could be a URL or new foundation
+    error(`Foundation '${foundationFlag}' not found in workspace.`)
+    log(
+      `Available foundations: ${foundations.map((f) => f.name).join(', ') || 'none'}`
+    )
+    process.exit(1)
+  }
+
+  if (foundations.length === 0) {
+    return null
+  }
+
+  if (foundations.length === 1) {
+    info(`Using foundation: ${foundations[0].name}`)
+    return foundations[0]
+  }
+
+  // Multiple foundations — prompt (or fail in non-interactive mode)
+  if (isNonInteractive(process.argv)) {
+    error(`Multiple foundations found. Specify which to use:\n`)
+    log(
+      formatOptions(
+        foundations.map((f) => ({
+          label: f.name,
+          description: f.path
+        }))
+      )
+    )
+    log('')
+    log(`Usage: ${getCliPrefix()} add site <name> --foundation <name>`)
+    process.exit(1)
+  }
+
+  const response = await prompts(
+    {
+      type: 'select',
+      name: 'foundation',
+      message: 'Which foundation should this site use?',
+      choices: foundations.map((f) => ({
+        title: f.name,
+        description: f.path,
+        value: f
+      }))
+    },
+    {
+      onCancel: () => {
+        log('\nCancelled.')
+        process.exit(0)
+      }
+    }
+  )
+
+  return response.foundation
+}
+
+/**
+ * Compute the file: path from site to foundation
+ */
+function computeFoundationPath(sitePath, foundationPath) {
+  // Compute relative path from site dir to foundation dir
+  const rel = relative(sitePath, foundationPath)
+  return `file:${rel}`
+}
+
+/**
+ * The first of `candidates` that no foundation or extension in the workspace
+ * registers as — null when each is taken or missing, and `uniweb register` asks.
+ *
+ * A package name is kept unique by suffixing (`ui-ext`), but what a package
+ * REGISTERS as is its main.js name: two foundations named `ui` in one workspace
+ * would both register `@org/ui`, and the second would land on the first's
+ * version. Compared without scope, so `@acme/ui` counts as `ui`.
+ *
+ * @param {string} rootDir
+ * @param {Array<string|null>} candidates
+ * @returns {Promise<string|null>}
+ */
+async function unclaimedFoundationName(rootDir, candidates) {
+  const taken = new Set()
+  for (const f of await discoverFoundations(rootDir)) {
+    try {
+      const { name } = await readFoundationName(join(rootDir, f.path))
+      if (name) taken.add(name.replace(/^@[^/]+\//, ''))
+    } catch {
+      // An unreadable main.js — the build reports it; it claims no name here.
+    }
+  }
+  return candidates.find((c) => c && !taken.has(c)) || null
+}
+
+/**
+ * Apply content from a template to a scaffolded package
+ *
+ * @param {string} templateId - Template identifier (official name, local path, npm, github)
+ * @param {string} packageType - 'foundation', 'site', or 'extension'
+ * @param {string} targetDir - Absolute path to the scaffolded package
+ * @param {string} projectName - Project name for template context
+ */
+async function applyFromTemplate(
+  templateId,
+  packageType,
+  targetDir,
+  projectName
+) {
+  info(`Resolving template: ${templateId}...`)
+
+  const resolved = await resolveTemplate(templateId, {
+    onProgress: (msg) => info(`  ${msg}`)
+  })
+
+  try {
+    const metadata = await validateTemplate(resolved.path)
+
+    // Look in contentDirs for matching package type
+    const match =
+      metadata.contentDirs.find((d) => d.type === packageType) ||
+      metadata.contentDirs.find((d) => d.name === packageType)
+    const contentDir = match ? match.dir : null
+
+    if (contentDir) {
+      info(`Applying ${metadata.name} content...`)
+      await applyContent(
+        contentDir,
+        targetDir,
+        {
+          projectName,
+          versions: getVersionsForTemplates()
+        },
+        { onProgress: (msg) => info(`  ${msg}`) }
+      )
+
+      // Merge template dependencies
+      if (metadata.dependencies) {
+        const deps =
+          metadata.dependencies[packageType] ||
+          metadata.dependencies[match?.name]
+        if (deps) {
+          await mergeTemplateDependencies(join(targetDir, 'package.json'), deps)
+        }
+      }
+
+      // If site content applied, inform about expected section types
+      if (packageType === 'site' && metadata.components) {
+        log('')
+        info(
+          `This template expects section types: ${metadata.components.join(', ')}`
+        )
+        info(`Make sure your foundation provides them.`)
+      }
+    } else {
+      info(
+        `Template '${metadata.name}' has no ${packageType} content to apply.`
+      )
+    }
+  } finally {
+    if (resolved.cleanup) await resolved.cleanup()
+  }
+}
+
+/**
+ * Wire an extension URL to a site's site.yml
+ */
+async function wireExtensionToSite(rootDir, siteName, extensionFolder) {
+  // Find the site directory
+  const sites = await discoverSites(rootDir)
+  const site = sites.find((s) => s.name === siteName)
+  if (!site) {
+    info(`Could not find site '${siteName}' to wire extension.`)
+    return null
+  }
+
+  const siteYmlPath = join(rootDir, site.path, 'site.yml')
+  if (!existsSync(siteYmlPath)) {
+    info(`No site.yml found at ${site.path}`)
+    return null
+  }
+
+  try {
+    const content = await readFile(siteYmlPath, 'utf-8')
+    const config = yaml.load(content) || {}
+
+    // ⭐ The site loads it from its own origin at `/<name>/entry.js`, `<name>`
+    // being the extension's folder: the build finds that extension's build in
+    // `<name>/` or `extensions/<name>/`, copies it into the site's output there,
+    // and prerender imports it from the same place (`@uniweb/build`,
+    // resolveExtensionDist) — the form the `extensions` template declares.
+    // ⛔ Until 2026-10-08 this wrote `/<folder>/dist/entry.js`, which that lookup
+    // reads as an extension named after the folder's FIRST segment —
+    // `/extensions/effects/dist/entry.js` as one named `extensions` — so the
+    // build warned it found no build, and the site 404'd on the file.
+    const extensionUrl = `/${basename(extensionFolder)}/entry.js`
+    if (!config.extensions) {
+      config.extensions = []
+    }
+    if (!config.extensions.includes(extensionUrl)) {
+      config.extensions.push(extensionUrl)
+    }
+
+    await writeFile(
+      siteYmlPath,
+      yaml.dump(config, { flowLevel: -1, quotingType: "'" })
+    )
+    return siteName
+  } catch (err) {
+    info(`Warning: Could not update site.yml: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Add a section type to a foundation
+ */
+async function addSection(rootDir, opts) {
+  setAddJsonMode(opts.json)
+  let name = opts.name
+
+  // Interactive name prompt when not provided
+  if (!name) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing section name.\n`)
+      log(`Usage: ${getCliPrefix()} add section <Name>`)
+      log(`\nSection names use PascalCase: Hero, FeatureGrid, CallToAction`)
+      process.exit(1)
+    }
+
+    const response = await prompts(
+      {
+        type: 'text',
+        name: 'name',
+        message: 'Section name (PascalCase):',
+        validate: (value) =>
+          /^[A-Z][a-zA-Z0-9]*$/.test(value) ||
+          'Use PascalCase: Hero, FeatureGrid, CallToAction'
+      },
+      {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        }
+      }
+    )
+    name = response.name
+  }
+
+  // Validate PascalCase
+  if (!/^[A-Z][a-zA-Z0-9]*$/.test(name)) {
+    error(
+      `Section name must be PascalCase (e.g., Hero, FeatureGrid, CallToAction).`
+    )
+    process.exit(1)
+  }
+
+  // Find the foundation
+  const foundations = await discoverFoundations(rootDir)
+  let foundation
+
+  if (foundations.length === 0) {
+    error('No foundation found in this workspace.')
+    log(`Create one first: ${getCliPrefix()} add foundation`)
+    process.exit(1)
+  } else if (foundations.length === 1) {
+    foundation = foundations[0]
+  } else if (opts.foundation) {
+    foundation = foundations.find((f) => f.name === opts.foundation)
+    if (!foundation) {
+      error(`Foundation '${opts.foundation}' not found.`)
+      log(`Available: ${foundations.map((f) => f.name).join(', ')}`)
+      process.exit(1)
+    }
+  } else if (isNonInteractive(process.argv)) {
+    error(`Multiple foundations found. Specify which to use:\n`)
+    log(
+      formatOptions(
+        foundations.map((f) => ({ label: f.name, description: f.path }))
+      )
+    )
+    log('')
+    log(`Usage: ${getCliPrefix()} add section ${name} --foundation <name>`)
+    process.exit(1)
+  } else {
+    const response = await prompts(
+      {
+        type: 'select',
+        name: 'foundation',
+        message: 'Which foundation?',
+        choices: foundations.map((f) => ({
+          title: f.name,
+          description: f.path,
+          value: f
+        }))
+      },
+      {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        }
+      }
+    )
+    foundation = response.foundation
+  }
+
+  // Resolve sections directory — source root comes from package.json::main
+  // (works for both nested `src/` layouts and flat layouts).
+  const foundationDir = join(rootDir, foundation.path)
+  const foundationSrc = resolveFoundationSrcPath(foundationDir)
+  const sectionsDir = join(foundationSrc, 'sections')
+  const sectionDir = join(sectionsDir, name)
+  const relSectionPath = relative(foundationDir, sectionDir)
+
+  // ⭐ `--starter` ON AN EXISTING SECTION IS NOT AN ERROR. The flag asks one
+  // question — *what content would an author start this section with?* — and a
+  // section type that already exists is the case where it has a real `content:`
+  // declaration to answer from. Refusing here would make the flag testable only
+  // against stubs, which is the one case where the answer is least interesting.
+  // Nothing is scaffolded and nothing is overwritten on this path.
+  if (existsSync(sectionDir)) {
+    if (opts.starter) {
+      const { markdown, result } = await generateStarter({
+        name,
+        sectionDir,
+        preset: opts.preset,
+        json: opts.json,
+        write: opts.write,
+      })
+      if (!opts.json) {
+        if (!opts.write) log('\n' + markdown.trimEnd())
+        reportStarter(result, { write: opts.write })
+      }
+      return
+    }
+    error(
+      `Section '${name}' already exists at ${foundation.path}/${relSectionPath}/`
+    )
+    log(`  ${colors.dim}--starter generates starter content for it without touching the files.${colors.reset}`)
+    process.exit(1)
+  }
+
+  // Create section directory and files
+  await mkdir(sectionDir, { recursive: true })
+
+  const componentContent = `import { H2, P, Link, cn } from '@uniweb/kit'
+
+export default function ${name}({ content, params }) {
+  const { title, paragraphs = [], links = [] } = content || {}
+
+  return (
+    <div className="max-w-4xl mx-auto px-6">
+      {title && <H2 text={title} className="text-heading text-3xl font-bold" />}
+      <P text={paragraphs} className="text-body mt-4" />
+      {links.length > 0 && (
+        <div className="mt-6 flex gap-3 flex-wrap">
+          {links.map((link, i) => (
+            <Link key={i} to={link.href} className={cn(
+              'px-5 py-2.5 rounded-lg font-medium transition-colors',
+              i === 0
+                ? 'bg-primary text-primary-foreground hover:bg-primary-hover'
+                : 'bg-secondary text-secondary-foreground hover:bg-secondary-hover'
+            )}>
+              {link.label}
+            </Link>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+`
+
+  // With `--starter`, the scaffold gets a `content:` declaration derived from
+  // the family the name resolves to — so the three pieces agree: a declaration,
+  // a component that reads it, and content that fills it. Without the flag the
+  // stub declares nothing, exactly as before.
+  let starterDeclaration = ''
+  let starterResult = null
+  if (opts.starter) {
+    const preview = await generateStarter({ name, sectionDir: sectionDir })
+    starterResult = preview.result
+    starterDeclaration = await declarationFor(preview.result)
+  }
+
+  const metaContent = `export default {
+  title: '${name}',
+  description: '',${starterDeclaration}
+  params: {},
+}
+`
+
+  await writeFile(join(sectionDir, 'index.jsx'), componentContent)
+  await writeFile(join(sectionDir, 'meta.js'), metaContent)
+
+  success(`Created section '${name}' at ${foundation.path}/${relSectionPath}/`)
+  log(
+    `  ${colors.dim}index.jsx${colors.reset}  — component (customize the JSX)`
+  )
+  log(
+    `  ${colors.dim}meta.js${colors.reset}    — metadata (add content expectations, params, presets)`
+  )
+  if (foundations.length === 1) {
+    log('')
+    log(
+      `${colors.dim}The dev server will pick it up automatically.${colors.reset}`
+    )
+  }
+
+  if (starterResult) {
+    // Regenerate against the declaration just written, so what is printed is
+    // what this section's own `meta.js` now asks for rather than the family's
+    // guess — the two agree here, and saying it from the file keeps them so.
+    const { markdown, result } = await generateStarter({
+      name,
+      sectionDir,
+      preset: opts.preset,
+      json: opts.json,
+      write: opts.write,
+    })
+    if (!opts.json) {
+      log('')
+      log(`${colors.dim}Starter content for a page section:${colors.reset}`)
+      if (!opts.write) log('\n' + markdown.trimEnd())
+      reportStarter(result, { write: opts.write })
+      // The stub component reads three elements. The declaration above may name
+      // more, because it comes from the family rather than from the stub — say
+      // so, rather than leave a developer wondering why half the content they
+      // were just handed renders as nothing.
+      const stubReads = new Set(['title', 'paragraphs', 'links'])
+      const unread = Object.keys(result.content).filter((slot) => !stubReads.has(slot))
+      if (unread.length) {
+        log(
+          `  ${colors.dim}index.jsx reads title, paragraphs and links — extend it for: ${unread.join(', ')}${colors.reset}`
+        )
+        log('')
+      }
+    }
+  }
+}
+
+/**
+ * Add a CI deploy workflow for a host adapter.
+ *
+ * Wires through the host-adapter registry: each adapter optionally
+ * 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,
+ * vercel, s3-cloudfront, generic-static) error out with a clear message
+ * and can plug in later.
+ */
+async function addCi(rootDir, opts, pm = 'pnpm') {
+  // Lazy-load the host registry so the CLI doesn't pay this import on
+  // every add invocation.
+  let getAdapter, listAdapters
+  try {
+    ;({ getAdapter, listAdapters } = await import('@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)
+  }
+
+  // What the workflow publishes. 'foundation' scaffolds the versioned
+  // distribution path (foundations/<name>/<version>/entry.js) — the free
+  // alternative to the catalog for a foundation product. Resolved BEFORE
+  // the host, because it narrows which hosts are even eligible.
+  const target = opts.target || 'site'
+  if (!['site', 'foundation'].includes(target)) {
+    error(`Unknown --target '${target}'. Expected 'site' or 'foundation'.`)
+    process.exit(1)
+  }
+
+  // Every adapter that can scaffold CI for this target. Derived from
+  // capability, never a hardcoded list — an adapter that grows an initCi
+  // shows up here with no edit to this file.
+  const ciHosts = listAdapters()
+    .map((name) => getAdapter(name))
+    .filter((a) => typeof a.initCi === 'function')
+    .filter((a) =>
+      target === 'foundation' ? a.display?.foundationCi === true : true
+    )
+    .sort((a, b) => (a.display?.order ?? 999) - (b.display?.order ?? 999))
+
+  if (ciHosts.length === 0) {
+    error(`No host can scaffold CI for a ${target}.`)
+    process.exit(1)
+  }
+
+  let host = opts.host
+  if (!host) {
+    if (ciHosts.length === 1) {
+      host = ciHosts[0].name
+    } else if (isNonInteractive(process.argv)) {
+      error('`uniweb add ci` needs a host.')
+      log(`Available: ${ciHosts.map((a) => a.name).join(', ')}`)
+      process.exit(1)
+    } else {
+      const choice = await prompts(
+        {
+          type: 'select',
+          name: 'host',
+          message: 'Which host should the workflow deploy to?',
+          choices: ciHosts.map((a) => ({
+            title:
+              `${a.display?.title || a.name} · ${a.display?.qualifier || ''}`
+                .trim()
+                .replace(/ ·\s*$/, ''),
+            description: a.display?.summary,
+            value: a.name
+          }))
+        },
+        {
+          onCancel: () => {
+            log('\nCancelled.')
+            process.exit(0)
+          }
+        }
+      )
+      host = choice.host
+    }
+  }
+
+  let adapter
+  try {
+    adapter = getAdapter(host)
+  } catch (err) {
+    error(err.message)
+    process.exit(1)
+  }
+
+  if (typeof adapter.initCi !== 'function') {
+    error(`Host '${host}' does not provide a CI workflow.`)
+    log(`Hosts that do: ${ciHosts.map((a) => a.name).join(', ')}`)
+    log(
+      `Others are dashboard-driven — connect the repo in the host's UI instead.`
+    )
+    process.exit(1)
+  }
+
+  // Guard the explicit-host case. Without this, `--host netlify --target
+  // foundation` would call an initCi that ignores `target` and silently
+  // scaffold a SITE workflow — the wrong artifact, with no error.
+  if (target === 'foundation' && adapter.display?.foundationCi !== true) {
+    error(`Host '${host}' cannot publish a foundation.`)
+    log(`Hosts that can: ${ciHosts.map((a) => a.name).join(', ')}`)
+    log('')
+    log('Foundation publishing needs permanent versioned URLs, which the')
+    log('gh-pages branch layout provides. Other hosts overwrite on deploy.')
+    process.exit(1)
+  }
+
+  if (target === 'foundation') {
+    return addFoundationCi(rootDir, { ...opts, host }, adapter, pm)
+  }
+
+  // Validate --domain (lightweight: must look like a hostname). The
+  // adapter decides what to do with it; today only github-pages uses
+  // it (writes a CNAME, switches UNIWEB_BASE to root).
+  if (opts.domain && !isLikelyDomain(opts.domain)) {
+    error(`Invalid --domain value: '${opts.domain}'`)
+    log(
+      `Expected a bare hostname (e.g., 'mysite.com' or 'docs.mysite.com'). No scheme, no path.`
+    )
+    process.exit(1)
+  }
+
+  // If --domain wasn't passed, fall back to whatever's already in
+  // deploy.yml's targets.<host>.domain. Lets re-running `add ci` (e.g.,
+  // to refresh the workflow after a CLI upgrade) keep the domain
+  // without the user re-typing it.
+  const { loadDeployYml } = await import('@uniweb/build/site')
+  let resolvedDomain = opts.domain
+
+  // Resolve site: --site flag, single site auto, prompt, or error.
+  const sites = await discoverSites(rootDir)
+  if (sites.length === 0) {
+    error(
+      'No site found in this workspace. Add one with `uniweb add site` first.'
+    )
+    process.exit(1)
+  }
+
+  let site
+  if (opts.site) {
+    site = sites.find((s) => s.name === opts.site)
+    if (!site) {
+      error(`Site '${opts.site}' not found.`)
+      log(`Available sites: ${sites.map((s) => s.name).join(', ')}`)
+      process.exit(1)
+    }
+  } else if (sites.length === 1) {
+    site = sites[0]
+  } else if (isNonInteractive(process.argv)) {
+    error(`Multiple sites in workspace. Specify --site <name>.`)
+    log(`Available sites: ${sites.map((s) => s.name).join(', ')}`)
+    process.exit(1)
+  } else {
+    const sortedSites = [...sites].sort((a, b) => a.name.localeCompare(b.name))
+    const response = await prompts(
+      {
+        type: 'select',
+        name: 'site',
+        message: 'Which site should the workflow build?',
+        choices: sortedSites.map((s) => ({
+          title: s.name,
+          description: s.path,
+          value: s
+        }))
+      },
+      {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        }
+      }
+    )
+    site = response.site
+  }
+
+  // Read node version from root package.json engines.node if pinned;
+  // otherwise default to 20 (matches the workspace template's >=20.19).
+  const rootPkg = JSON.parse(
+    await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
+  )
+  // CI must run the project's own toolchain. The pnpm major comes from
+  // its `packageManager` field when declared; the node major is the
+  // project's floor, raised if that pnpm needs more.
+  const installedPnpm = detectInstalledPnpmVersion(rootDir)
+  const pnpmVersion = resolveCiPnpmVersion(rootPkg, installedPnpm)
+  const nodeVersion = resolveCiNodeVersion(
+    rootPkg.engines?.node,
+    pm,
+    pnpmVersion
+  )
+  reportCiToolchain({
+    pm,
+    pnpmVersion,
+    nodeVersion,
+    source: rootPkg?.packageManager
+      ? 'declared'
+      : installedPnpm
+        ? 'installed'
+        : 'fallback'
+  })
+
+  const siteDir = join(rootDir, site.path)
+  if (!resolvedDomain) {
+    try {
+      const deployYml = await loadDeployYml(siteDir)
+      const remembered = deployYml?.targets?.[host]?.domain
+      if (remembered && isLikelyDomain(remembered)) {
+        resolvedDomain = remembered
+        info(`Using domain '${remembered}' from deploy.yml.`)
+      }
+    } catch {
+      // Malformed deploy.yml — surface elsewhere; don't block add ci.
+    }
+  }
+
+  const result = await adapter.initCi({
+    rootDir,
+    site,
+    target: 'site',
+    packageManager: pm,
+    nodeVersion,
+    pnpmVersion,
+    domain: resolvedDomain,
+    previews: opts.previews !== false,
+    projectName: resolveHostProjectName(
+      rootDir,
+      rootPkg,
+      site,
+      sites.length,
+      opts
+    )
+  })
+
+  await writeCiFiles(rootDir, result.files, opts.force)
+
+  // Persist the adapter's target config into deploy.yml so the user's
+  // intent (host + adapter-specific fields like `domain`) is remembered
+  // across CLI upgrades and re-runs. github-pages deploys via GHA, not
+  // via `uniweb deploy`, so without this its config would never reach
+  // deploy.yml. The writer:
+  //   - scaffolds a fresh deploy.yml on first call (this target is the
+  //     default), or
+  //   - merges into an existing targets.<targetName> without touching
+  //     `default`, `autoSave`, or other targets.
+  if (result.targetConfig) {
+    try {
+      const { recordTarget } = await import('@uniweb/build/site')
+      const writeResult = await recordTarget(siteDir, {
+        targetName: host,
+        targetConfig: result.targetConfig
+      })
+      success(
+        writeResult.action === 'scaffold'
+          ? `Wrote ${relative(rootDir, writeResult.path)} (default target: ${host})`
+          : `Updated ${relative(rootDir, writeResult.path)} (target: ${host})`
+      )
+    } catch (err) {
+      // deploy.yml persistence is best-effort: the workflow + CNAME
+      // are the load-bearing artifacts. Print a warning and continue.
+      info(`Warning: could not update deploy.yml: ${err.message}`)
+    }
+  }
+
+  if (result.postInstructions?.length) {
+    log('')
+    log(`${colors.bright}Next steps:${colors.reset}`)
+    for (const line of result.postInstructions) {
+      log(line ? `  ${line}` : '')
+    }
+  }
+}
+
+/**
+ * The name to register this site under on the host (Cloudflare Pages
+ * project, etc.).
+ *
+ * The site package is very often called literally `site` — the scaffold's
+ * default — which makes a terrible project name on a shared host. So:
+ * an explicit `--project-name` wins; otherwise prefer the workspace's own
+ * name (usually the repo name) when the site's name is one of the generic
+ * scaffold defaults; suffix with the site name only when the workspace
+ * holds more than one site and they'd otherwise collide.
+ */
+const GENERIC_SITE_NAMES = new Set(['site', 'sites', 'www', 'web', 'app'])
+
+/**
+ * Public URL segment for a foundation published to GitHub Pages.
+ *
+ * Same problem as the site project name, and it matters more here:
+ * this segment is baked into a PERMANENT url that consuming sites pin
+ * (`foundations/<name>/<version>/entry.js`), so `src` — the single-project
+ * scaffold's directory *and* package name — would be a poor forever-name.
+ * Prefer a meaningful package/directory name; fall back to the workspace
+ * name; disambiguate only when several foundations would collide.
+ */
+const GENERIC_FOUNDATION_NAMES = new Set([
+  'src',
+  'foundation',
+  'foundations',
+  'lib'
+])
+
+function resolveFoundationPublicNames(rootDir, rootPkg, foundations) {
+  const workspaceName = stripScope(rootPkg?.name) || basename(rootDir)
+
+  return foundations.map((f, i) => {
+    const pkgName = stripScope(f.name)
+    const dirName = basename(f.path)
+    const candidate = !GENERIC_FOUNDATION_NAMES.has(pkgName)
+      ? pkgName
+      : !GENERIC_FOUNDATION_NAMES.has(dirName)
+        ? dirName
+        : foundations.length > 1
+          ? `${workspaceName}-${i + 1}`
+          : workspaceName
+    return { name: candidate, path: f.path }
+  })
+}
+
+function resolveHostProjectName(rootDir, rootPkg, site, siteCount, opts) {
+  if (opts.projectName) return opts.projectName
+
+  const workspaceName = stripScope(rootPkg?.name) || basename(rootDir)
+  const siteName = stripScope(site.name)
+
+  if (!GENERIC_SITE_NAMES.has(siteName)) return siteName
+  if (siteCount > 1) return `${workspaceName}-${siteName}`
+  return workspaceName
+}
+
+function stripScope(name) {
+  if (!name || typeof name !== 'string') return null
+  return name.startsWith('@') ? name.split('/').pop() : name
+}
+
+/**
+ * Print the toolchain the generated workflow will install, and where each
+ * part came from.
+ *
+ * These values are resolved rather than stated whenever the project is
+ * silent, and a silent resolution is what let a broken pnpm/Node pairing
+ * ship unnoticed. Naming the source matters too: "we read this from your
+ * install" invites a different reaction than "we guessed", and only the
+ * latter needs an override hint.
+ */
+function reportCiToolchain({ pm, pnpmVersion, nodeVersion, source }) {
+  if (pm !== 'pnpm') {
+    info(`CI will use ${pm} + Node ${nodeVersion}`)
+    return
+  }
+  const origin =
+    {
+      declared: '',
+      installed: ' (matching your install)',
+      fallback: ' (no pnpm detected — using the default)'
+    }[source] ?? ''
+  info(`CI will use pnpm ${pnpmVersion} + Node ${nodeVersion}${origin}`)
+  if (source === 'fallback') {
+    info(
+      `Pin with "packageManager": "pnpm@<version>" in package.json to choose a major.`
+    )
+  }
+}
+
+/**
+ * Write scaffolded CI files. Refuses to overwrite without --force so
+ * re-running doesn't silently clobber edits the user made to a workflow.
+ */
+async function writeCiFiles(rootDir, files, force) {
+  for (const file of files) {
+    const fullPath = join(rootDir, file.path)
+    if (existsSync(fullPath) && !force) {
+      error(`File already exists: ${file.path}`)
+      log(`Re-run with --force to overwrite.`)
+      process.exit(1)
+    }
+    await mkdir(join(fullPath, '..'), { recursive: true })
+    await writeFile(fullPath, file.content)
+    success(`Wrote ${file.path}`)
+  }
+}
+
+/**
+ * `uniweb add ci --target foundation` — scaffold the workflow that
+ * publishes built foundations at permanent versioned URLs.
+ *
+ * This is the free distribution path for a foundation product: sites
+ * reference `https://<user>.github.io/<repo>/foundations/<name>/<ver>/entry.js`
+ * from site.yml. No catalog, no propagation, no license gating — but no
+ * cost either, and the URLs never break.
+ *
+ * Unlike the site path there is no deploy.yml to write: deploy.yml
+ * records where a *site* is deployed, and a foundation isn't a site.
+ */
+async function addFoundationCi(rootDir, opts, adapter, pm) {
+  const all = await discoverFoundations(rootDir)
+  if (all.length === 0) {
+    error('No foundation found in this workspace.')
+    log('Add one with `uniweb add foundation` first.')
+    process.exit(1)
+  }
+
+  // --foundation <name> narrows to one; otherwise publish them all,
+  // which is what a multi-foundation repo almost always wants (each gets
+  // its own versioned directory, so there's no collision).
+  let foundations = all
+  if (opts.foundation) {
+    const match = all.find(
+      (f) => f.name === opts.foundation || basename(f.path) === opts.foundation
+    )
+    if (!match) {
+      error(`Foundation '${opts.foundation}' not found.`)
+      log(`Available: ${all.map((f) => f.name).join(', ')}`)
+      process.exit(1)
+    }
+    foundations = [match]
+  }
+
+  const rootPkg = JSON.parse(
+    await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
+  )
+  // CI must run the project's own toolchain. The pnpm major comes from
+  // its `packageManager` field when declared; the node major is the
+  // project's floor, raised if that pnpm needs more.
+  const installedPnpm = detectInstalledPnpmVersion(rootDir)
+  const pnpmVersion = resolveCiPnpmVersion(rootPkg, installedPnpm)
+  const nodeVersion = resolveCiNodeVersion(
+    rootPkg.engines?.node,
+    pm,
+    pnpmVersion
+  )
+  reportCiToolchain({
+    pm,
+    pnpmVersion,
+    nodeVersion,
+    source: rootPkg?.packageManager
+      ? 'declared'
+      : installedPnpm
+        ? 'installed'
+        : 'fallback'
+  })
+
+  let result
+  try {
+    result = await adapter.initCi({
+      rootDir,
+      foundations: resolveFoundationPublicNames(rootDir, rootPkg, foundations),
+      target: 'foundation',
+      packageManager: pm,
+      nodeVersion,
+      pnpmVersion
+    })
+  } catch (err) {
+    error(err.message)
+    process.exit(1)
+  }
+
+  await writeCiFiles(rootDir, result.files, opts.force)
+
+  if (result.postInstructions?.length) {
+    log('')
+    log(`${colors.bright}Next steps:${colors.reset}`)
+    for (const line of result.postInstructions) {
+      log(line ? `  ${line}` : '')
+    }
+  }
+}
+
+function isLikelyDomain(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 253)
+    return false
+  // Reject schemes, paths, ports, whitespace, leading/trailing dots/hyphens.
+  // Each label is 1–63 chars of [a-z0-9-], no leading/trailing hyphen.
+  // The TLD must be at least 2 characters of letters.
+  return /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i.test(
+    value
+  )
+}
+
+function parseNodeMajor(engines) {
+  if (!engines) return null
+  const match = String(engines).match(/(\d+)/)
+  return match ? match[1] : null
+}
+