uniweb 1.0.0 → 1.0.2

package/src/utils/interactive.js

@@ -0,0 +1,118 @@
+/**
+ * Non-Interactive Mode Detection
+ *
+ * Detects when the CLI is running without a TTY (AI agents, CI, piped input)
+ * and provides helpers for printing actionable error messages.
+ */
+
+/**
+ * Detect if the CLI is running in non-interactive mode.
+ * True when --non-interactive flag, CI env var, or no TTY.
+ * @param {string[]} args - Command line arguments
+ * @returns {boolean}
+ */
+export function isNonInteractive(args) {
+  if (args.includes('--non-interactive')) return true
+  if (process.env.CI) return true
+  if (!process.stdin.isTTY) return true
+  return false
+}
+
+/**
+ * Minimal yes/no prompt. Returns `defaultYes` on an empty answer.
+ *
+ * Shared rather than per-command: every verb that can stop and ask needs one, and
+ * three hand-rolled copies would eventually disagree about what a bare Enter means
+ * — which is the answer the user gives most often and thinks about least.
+ *
+ * ⛔ Callers must decide NOT to ask before calling: this always reads stdin, and a
+ * prompt in a non-interactive run hangs a pipeline. Gate on `isNonInteractive(args)`
+ * (and on any --yes/--force style skip the verb defines).
+ */
+export async function confirm(question, defaultYes = false) {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const a = (
+      await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)
+    )
+      .trim()
+      .toLowerCase()
+    if (!a) return defaultYes
+    return a === 'y' || a === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
+/**
+ * Ask the user to pick one of a short list, returning `fallback` on an empty answer
+ * or anything unparseable.
+ *
+ * ⛔ **Prompts on STDERR**, like everything else a human reads here — `stdout` is the
+ * CLI's data channel and a prompt written there corrupts any caller piping it.
+ *
+ * ⛔ Callers must decide NOT to ask before calling (see `confirm`): this reads stdin,
+ * and a prompt in a non-interactive run hangs a pipeline.
+ *
+ * @param {string} question
+ * @param {string[]} options - shown in order, numbered from 1
+ * @param {string} fallback - returned for an empty or unparseable answer
+ * @returns {Promise<string>}
+ */
+export async function pickOne(question, options, fallback) {
+  if (!Array.isArray(options) || options.length === 0) return fallback
+  if (options.length === 1) return options[0]
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  try {
+    process.stderr.write(`${question}\n`)
+    options.forEach((o, i) => {
+      const mark = o === fallback ? ' \x1b[2m(default)\x1b[0m' : ''
+      process.stderr.write(`  \x1b[1m${i + 1}\x1b[0m) ${o}${mark}\n`)
+    })
+    const a = (await rl.question(`Choose [1-${options.length}]: `)).trim()
+    if (!a) return fallback
+    const n = Number.parseInt(a, 10)
+    if (Number.isInteger(n) && n >= 1 && n <= options.length) return options[n - 1]
+    // A pasted origin is a reasonable answer to a list of origins.
+    if (options.includes(a)) return a
+    return fallback
+  } finally {
+    rl.close()
+  }
+}
+
+/**
+ * Get the CLI invocation prefix to use in suggested commands.
+ * Mirrors however the user actually ran the CLI.
+ * @returns {string}
+ */
+export function getCliPrefix() {
+  const ua = process.env.npm_config_user_agent || ''
+  if (ua.startsWith('pnpm/')) return 'pnpm uniweb'
+  if (ua.startsWith('npm/')) return 'npx uniweb'
+  return 'uniweb'
+}
+
+/**
+ * Strip --non-interactive from an args array so it doesn't interfere
+ * with positional argument parsing.
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+export function stripNonInteractiveFlag(args) {
+  return args.filter((a) => a !== '--non-interactive')
+}
+
+/**
+ * Format a list of options with aligned descriptions for terminal output.
+ * @param {{ label: string, description: string }[]} options
+ * @returns {string}
+ */
+export function formatOptions(options) {
+  const maxLen = Math.max(...options.map((o) => o.label.length))
+  return options
+    .map((o) => `  ${o.label.padEnd(maxLen + 3)}${o.description}`)
+    .join('\n')
+}

package/src/utils/json-file.js

@@ -0,0 +1,72 @@
+/**
+ * Style-preserving JSON file writes.
+ *
+ * The CLI rewrites `package.json` in several places (`update`, `doctor`,
+ * `rename`, `add`). A naive `JSON.stringify(obj, null, 2)` reflows the
+ * *entire* file whenever the project happened to use tabs or 4-space
+ * indentation — turning a one-key version bump into a hundred-line diff
+ * (and a needless merge-conflict surface). `framework/CLAUDE.md` calls
+ * this out as an anti-pattern for human commits; the tooling shouldn't do
+ * it either. These helpers detect the file's existing indentation and
+ * trailing-newline convention and preserve both.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+
+/**
+ * Detect the indentation unit a JSON source string uses.
+ * @param {string} src
+ * @returns {number|string} A space count, or '\t' for tab-indented files.
+ *   Defaults to 2 when the file has no indented lines (e.g. `{}`).
+ */
+export function detectJsonIndent(src) {
+  const m = src.match(/\n([ \t]+)\S/)
+  if (!m) return 2
+  const lead = m[1]
+  if (lead.includes('\t')) return '\t'
+  return lead.length
+}
+
+/**
+ * Serialize `obj` to JSON using the indentation and trailing-newline
+ * convention of `originalSrc` (or of the file currently at `filePath`).
+ * @param {object} obj
+ * @param {string} originalSrc - The file's current text.
+ * @returns {string}
+ */
+export function stringifyJsonLike(obj, originalSrc) {
+  const indent = detectJsonIndent(originalSrc)
+  const body = JSON.stringify(obj, null, indent)
+  return originalSrc.endsWith('\n') ? body + '\n' : body
+}
+
+/**
+ * Write `obj` to `filePath` as JSON, preserving the file's existing
+ * indentation and trailing-newline convention. Pass `originalSrc` when
+ * the caller already has the file contents in hand (avoids a re-read);
+ * otherwise the file is read to sniff its style.
+ * @param {string} filePath
+ * @param {object} obj
+ * @param {string|null} [originalSrc]
+ */
+export function writeJsonPreservingStyle(filePath, obj, originalSrc = null) {
+  const src = originalSrc ?? readFileSync(filePath, 'utf8')
+  writeFileSync(filePath, stringifyJsonLike(obj, src))
+}
+
+/**
+ * Async counterpart to {@link writeJsonPreservingStyle}, for the CLI's
+ * many `node:fs/promises`-based call sites.
+ * @param {string} filePath
+ * @param {object} obj
+ * @param {string|null} [originalSrc]
+ */
+export async function writeJsonPreservingStyleAsync(
+  filePath,
+  obj,
+  originalSrc = null
+) {
+  const src = originalSrc ?? (await readFile(filePath, 'utf8'))
+  await writeFile(filePath, stringifyJsonLike(obj, src))
+}

package/src/utils/names.js

@@ -0,0 +1,91 @@
+/**
+ * Package Name Validation
+ *
+ * Validates package names for the `add` command — rejects reserved names
+ * and detects collisions with existing workspace packages.
+ */
+
+import { discoverFoundations, discoverSites } from './discover.js'
+
+/**
+ * Names that must not be used as package names.
+ * - JS module keywords: default, undefined, null, true, false
+ * - Node/filesystem: node_modules, package
+ * - Common build-output directories: dist, build (would shadow `dist/` /
+ *   `build/` references)
+ *
+ * Note: `src` is NOT reserved. A foundation in `src/` whose package name is
+ * also `src` is the default scaffold pattern — folder name and package name
+ * match. Multi-foundation co-located workspaces still use suffixes
+ * (`<project>-src`) because pnpm requires workspace-unique package names;
+ * that's a real constraint, not aesthetic.
+ */
+const RESERVED_NAMES = new Set([
+  'default',
+  'undefined',
+  'null',
+  'true',
+  'false',
+  'node_modules',
+  'package',
+  'dist',
+  'build'
+])
+
+/**
+ * Validate a package name.
+ * @param {string} name
+ * @param {Set<string>} [existingNames] - Names already in the workspace
+ * @returns {string|true} true if valid, or an error message string
+ */
+export function validatePackageName(name, existingNames) {
+  if (!name) return 'Name is required'
+  if (!/^[a-z0-9-]+$/.test(name))
+    return 'Use lowercase letters, numbers, and hyphens'
+  if (RESERVED_NAMES.has(name))
+    return `"${name}" is a reserved name — choose a different one`
+  if (existingNames?.has(name))
+    return `"${name}" already exists in this workspace`
+  return true
+}
+
+/**
+ * Discover all package names in the workspace (foundations + sites + extensions).
+ * @param {string} rootDir - Workspace root directory
+ * @returns {Promise<Set<string>>}
+ */
+export async function getExistingPackageNames(rootDir) {
+  const names = new Set()
+
+  // Foundations and sites via existing discovery
+  const foundations = await discoverFoundations(rootDir)
+  const sites = await discoverSites(rootDir)
+
+  // An extension is a foundation that declares `extension: true`, so the
+  // discovery above already has it, wherever its folder is. (A second scan of
+  // `extensions/*` stood here until 2026-10-08, when extensions stopped being
+  // placed there by default.)
+  for (const f of foundations) names.add(f.name)
+  for (const s of sites) names.add(s.name)
+
+  return names
+}
+
+/**
+ * Resolve a unique name by appending a suffix if there's a collision.
+ * @param {string} name - Proposed name
+ * @param {string} suffix - Suffix to append (e.g., '-site', '-foundation')
+ * @param {Set<string>} existingNames
+ * @returns {string} The resolved unique name
+ */
+export function resolveUniqueName(name, suffix, existingNames) {
+  if (!existingNames.has(name)) return name
+  const suffixed = `${name}${suffix}`
+  if (!existingNames.has(suffixed)) return suffixed
+  // Unlikely: both name and name-suffix taken — append number
+  for (let i = 2; i < 100; i++) {
+    const numbered = `${name}${suffix}-${i}`
+    if (!existingNames.has(numbered)) return numbered
+  }
+  return suffixed // give up
+}

package/src/utils/placement.js

@@ -0,0 +1,151 @@
+import { isAbsolute, relative, sep } from 'node:path'
+
+/**
+ * Package placement resolution — shared by `add` and `clone`.
+ *
+ * Kept dependency-free (no `@uniweb/build`, no fs) on purpose: `clone` imports
+ * it and must run from a global install before any project — anything that
+ * statically pulls in `@uniweb/build` would crash `npx uniweb@latest clone`
+ * (the same reason `utils/workspace.js` loads the classifier lazily).
+ */
+
+// `--path` is documented as a folder INSIDE the workspace, and every consumer of
+// the result treats it that way: the caller does `join(rootDir, relativePath)`
+// while the workspace manifests get `relativePath` verbatim. An ABSOLUTE path
+// silently satisfies neither — `join('/ws', '/tmp/x')` is `/ws/tmp/x`, so the
+// directory is created in one place while `package.json::workspaces` and
+// `pnpm-workspace.yaml` record `/tmp/x`. The two disagree, and the manifests are
+// committed files carrying a path that exists on exactly one machine.
+//
+// Reported by the backend lane 2026-09-18 from a `clone --path <abs>`: the site
+// landed under `company-websites/tmp/claude-502/clonetest/` and both manifests
+// gained the absolute string.
+//
+// So: accept an absolute path when it names a folder inside the root (people type
+// one, and it is unambiguous), by rewriting it to the root-relative form every
+// consumer already expects. Refuse it when it escapes — a workspace package cannot
+// live outside its workspace, and guessing which half the user meant is how you get
+// the split above.
+function normalizeParent(given, rootDir) {
+  const trimmed = String(given).replace(/\/+$/, '')
+  if (!isAbsolute(trimmed)) return { relative: trimmed }
+  const rel = relative(rootDir || '', trimmed)
+  if (!rel || rel === '..' || rel.startsWith('../')) return { outsideRoot: true, given: trimmed }
+  return { relative: rel.split(sep).join('/') }
+}
+
+/** Foundation placement defaults (folder `src/`, package `src`). */
+export const FOUNDATION_KIND = {
+  defaultDir: 'src',
+  defaultPkg: 'src',
+  projectSub: 'src'
+}
+
+/** Site placement defaults (folder `site/`, package `site`). */
+export const SITE_KIND = {
+  defaultDir: 'site',
+  defaultPkg: 'site',
+  projectSub: 'site'
+}
+
+/**
+ * Extension placement: no defaults — `add extension` always has a name, or a
+ * `--path` naming the folder, so neither a default folder nor the co-located
+ * `--project` form is reached. ⛔ Until 2026-10-08 an extension went to
+ * `extensions/<name>/` whatever was asked, `--path` named the folder itself
+ * rather than the one it goes in, and the workspace glob added was always
+ * `extensions/*` — so `--path elsewhere/fx` made a package pnpm never saw.
+ */
+export const EXTENSION_KIND = {
+  defaultDir: null,
+  defaultPkg: null,
+  projectSub: null
+}
+
+/**
+ * Resolve where a foundation or site should be placed, given the user's input.
+ *
+ * The rule: **the user names a folder, and we create exactly that folder.**
+ * No silent nesting under `foundations/` / `sites/`, no inferring layout from
+ * pre-existing globs. The framework doesn't require any particular folder
+ * structure (the build classifies packages by their contents, not their
+ * location), so the CLI shouldn't impose one.
+ *
+ * Resolution priority (foundation example, same shape for site):
+ *
+ *   1. `--path <dir>`                   → explicit folder. Name is the path's
+ *                                          last segment (used as the package
+ *                                          name unless `name` was also given).
+ *   2. `name` contains `/`              → treat as a path (e.g., `foundations/ui`).
+ *                                          Folder = the path, package name =
+ *                                          the last segment.
+ *   3. `name` (no slash)                → folder = `<name>/`, package name = `<name>`.
+ *   4. `--project <project>`            → folder = `<project>/<defaultSub>` and
+ *                                          package name = `<project>-<defaultSub>`
+ *                                          (the co-located convention; only this
+ *                                          one uses the `-src` / `-site` suffix).
+ *   5. (no input)                       → folder = `<defaultDir>/`, package name
+ *                                          = `<defaultPkg>` (`src/` + `src`
+ *                                          for foundations; `site/` + `site` for
+ *                                          sites).
+ *
+ * @param {string} rootDir
+ * @param {string|null} name - Either a bare name or a path-with-slash.
+ * @param {{ path?: string, project?: string }} opts
+ * @param {{ defaultDir: string, defaultPkg: string, projectSub: string }} kind
+ * @returns {{ relativePath: string, packageName: string }}
+ */
+export function resolvePlacement(rootDir, name, opts, kind) {
+  // 1. --path is a PARENT directory. The folder is `<path>/<name>` if a
+  //    name was given, or `<path>` itself if not (the path's last segment
+  //    is then taken as the package name).
+  if (opts.path) {
+    const parent = normalizeParent(opts.path, rootDir)
+    if (parent.outsideRoot) return { outsideRoot: parent.given, relativePath: null, packageName: null }
+    const dir = parent.relative
+    if (name) {
+      const last = name.split('/').filter(Boolean).pop()
+      return {
+        relativePath: `${dir}/${name}`.replace(/\/+/g, '/'),
+        packageName: last
+      }
+    }
+    const lastSegment = dir.split('/').filter(Boolean).pop() || dir
+    return {
+      relativePath: dir,
+      packageName: lastSegment
+    }
+  }
+
+  // 2. name contains a slash → treat as a path.
+  if (name && name.includes('/')) {
+    const relativePath = name.replace(/\/+$/, '')
+    const lastSegment = relativePath.split('/').filter(Boolean).pop()
+    return {
+      relativePath,
+      packageName: lastSegment
+    }
+  }
+
+  // 3. Bare name.
+  if (name) {
+    return {
+      relativePath: name,
+      packageName: name
+    }
+  }
+
+  // 4. --project (co-located convention with -src / -site suffix).
+  if (opts.project) {
+    return {
+      relativePath: `${opts.project}/${kind.projectSub}`,
+      packageName: `${opts.project}-${kind.projectSub}`
+    }
+  }
+
+  // 5. Default placement.
+  return {
+    relativePath: kind.defaultDir,
+    packageName: kind.defaultPkg
+  }
+}

package/src/utils/pm.js

@@ -0,0 +1,165 @@
+/**
+ * Package Manager Detection
+ *
+ * Detect whether the user ran the CLI via npm or pnpm,
+ * and generate PM-appropriate commands for output messages.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { execSync } from 'node:child_process'
+
+/**
+ * Detect which package manager invoked the CLI.
+ * Uses the standard npm_config_user_agent env var (same technique as create-vite, create-next-app).
+ *
+ * Note: this returns the *invoker* PM, which is empty when the user runs
+ * a global CLI binary directly from a shell. For the workspace's own PM
+ * (driven by lockfile presence), use `detectWorkspacePm`.
+ *
+ * @returns {'pnpm' | 'npm'}
+ */
+export function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent || ''
+  if (ua.startsWith('pnpm/')) return 'pnpm'
+  return 'npm'
+}
+
+/**
+ * Detect the workspace's package manager by inspecting lockfiles at the
+ * workspace root. This is the right signal for "what PM should I use to
+ * install in this workspace" — independent of how the CLI was invoked.
+ *
+ * @param {string} workspaceRoot - Absolute path to workspace root
+ * @returns {'pnpm' | 'yarn' | 'npm' | null} - null when no lockfile is present
+ */
+export function detectWorkspacePm(workspaceRoot) {
+  if (!workspaceRoot) return null
+  if (existsSync(join(workspaceRoot, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(join(workspaceRoot, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(workspaceRoot, 'package-lock.json'))) return 'npm'
+  return null
+}
+
+/**
+ * The pnpm major that actually installed this workspace.
+ *
+ * pnpm records the version it ran as in `node_modules/.modules.yaml`:
+ *
+ *     "packageManager": "pnpm@10.30.0"
+ *
+ * This is a *record of what happened*, not a guess about intent — which
+ * matters, because intent cannot be inferred. The documented way to
+ * scaffold is `npm create uniweb`, and plenty of people follow it with
+ * `pnpm install`; the invoking package manager therefore says nothing
+ * about the one the project uses. The lockfile says WHICH manager
+ * (`detectWorkspacePm`); this says which pnpm MAJOR, which the lockfile
+ * cannot — pnpm 10 and 11 both write `lockfileVersion: 9.0`.
+ *
+ * Despite the extension the file is JSON in current pnpm; `js-yaml`
+ * parses both, since YAML is a superset. Older pnpm wrote real YAML.
+ *
+ * @param {string} workspaceRoot
+ * @returns {string|null} pnpm major (e.g. '10'), or null when the file is
+ *   absent or unreadable — callers fall back to their own default.
+ */
+export function detectInstalledPnpmVersion(workspaceRoot) {
+  if (!workspaceRoot) return null
+  const path = join(workspaceRoot, 'node_modules', '.modules.yaml')
+  if (!existsSync(path)) return null
+  try {
+    // Cheap targeted read: the file is large (hoisted-dependency maps run
+    // to hundreds of KB) and we want exactly one field, so match it
+    // directly rather than parsing the whole document.
+    const text = readFileSync(path, 'utf8')
+    // Quotes optional on both key and value: current pnpm writes JSON
+    // (`"packageManager": "pnpm@10.30.0"`), but the file is named .yaml and
+    // YAML permits the bare form, so accept either rather than depending on
+    // which serializer the installing pnpm happened to use.
+    const match = text.match(/["']?packageManager["']?\s*:\s*["']?pnpm@(\d+)/)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Detect which package manager owns a *globally installed* `uniweb` CLI
+ * binary, by inspecting its install path (`process.argv[1]`). pnpm and
+ * yarn keep global packages under recognizable directory segments;
+ * everything else is assumed to be npm. Only meaningful when the CLI is
+ * actually a global install (see index.js::isGlobalInstall) — a
+ * project-local or npx-launched copy is updated differently.
+ *
+ * @returns {'pnpm' | 'yarn' | 'npm'}
+ */
+export function detectGlobalCliPm() {
+  const path = (process.argv[1] || '').toLowerCase().replace(/\\/g, '/')
+  if (path.includes('/pnpm/')) return 'pnpm'
+  if (path.includes('/yarn/')) return 'yarn'
+  return 'npm'
+}
+
+/**
+ * The command to (re)install the latest `uniweb` CLI globally with a
+ * given package manager.
+ * @param {'pnpm' | 'yarn' | 'npm'} pm
+ * @returns {string}
+ */
+export function globalCliUpdateCmd(pm) {
+  if (pm === 'pnpm') return 'pnpm add -g uniweb@latest'
+  if (pm === 'yarn') return 'yarn global add uniweb@latest'
+  return 'npm i -g uniweb@latest'
+}
+
+/**
+ * Generate a workspace-filtered command.
+ * pnpm: "pnpm --filter site dev"
+ * npm:  "npm -w site run dev"
+ * @param {'pnpm' | 'npm'} pm
+ * @param {string} pkg - Package name to filter to
+ * @param {string} cmd - Script name to run
+ * @returns {string}
+ */
+export function filterCmd(pm, pkg, cmd) {
+  return pm === 'pnpm'
+    ? `pnpm --filter ${pkg} ${cmd}`
+    : `npm -w ${pkg} run ${cmd}`
+}
+
+/**
+ * Whether pnpm is available on the current PATH. Used to recommend pnpm
+ * (the framework's package manager) in post-scaffold next steps while still
+ * falling back gracefully when it isn't installed. Mirrors the `git --version`
+ * probe the create flow already uses to feature-detect git.
+ * @returns {boolean}
+ */
+export function isPnpmAvailable() {
+  try {
+    execSync('pnpm --version', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Generate an install command.
+ * @param {'pnpm' | 'yarn' | 'npm'} pm
+ * @returns {string}
+ */
+export function installCmd(pm) {
+  if (pm === 'pnpm') return 'pnpm install'
+  if (pm === 'yarn') return 'yarn install'
+  return 'npm install'
+}
+
+/**
+ * Generate a run-script command.
+ * @param {'pnpm' | 'npm'} pm
+ * @param {string} script - Script name
+ * @returns {string}
+ */
+export function runCmd(pm, script) {
+  return pm === 'pnpm' ? `pnpm ${script}` : `npm run ${script}`
+}

package/src/utils/preview.js

@@ -0,0 +1,20 @@
+/**
+ * `site.yml::preview` — the site's card image — has two writers: an author, who
+ * writes an address (a URL, or a path to an image in the project), and the app,
+ * which writes a token naming an image it generated. This is the one test that
+ * tells them apart.
+ *
+ * It recognizes the author's shapes rather than the app's, so it does not depend
+ * on the token's format: a URL, a path starting `/`, `./` or `../`, or a relative
+ * path to an image file (`images/card.png`).
+ */
+
+const IMAGE_FILE = /\.(avif|gif|jpe?g|png|svg|webp)$/i
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} true when `value` is an author's address rather than the app's token
+ */
+export const isAuthoredPreview = (value) =>
+  typeof value === 'string' &&
+  (/^https?:\/\//i.test(value) || /^\.{0,2}\//.test(value) || IMAGE_FILE.test(value.trim()))