uifolio 0.4.0 → 0.5.3

package/cli/uifolio.mjs

@@ -1,35 +1,39 @@
 #!/usr/bin/env node
 /**
- * uifolio — CLI façon shadcn : copie les composants de la librairie
- * dans un autre projet, avec les helpers dont ils dépendent.
+ * uifolio — shadcn-like CLI: copies the library components into another
+ * project, along with the helpers they depend on.
  *
- * Commandes :
- *   uifolio list                          liste des composants disponibles
- *   uifolio init [--cwd dir]              écrit uifolio.json (config cible)
- *   uifolio add <noms...> [options]       copie les composants + helpers
- *                                        --page <chemin>  crée ou adapte la page cible
+ * Commands:
+ *   uifolio list                          list available components
+ *   uifolio init [--cwd dir]              write uifolio.json (target config)
+ *   uifolio add <names...> [options]      copy components + helpers, write the
+ *                                        Tailwind tokens and use the
+ *                                        component in a page
  *
- * Options :
- *   --cwd <dir>          projet cible (défaut : répertoire courant)
- *   --dir <chemin>       dossier des composants (défaut : src/components/ui)
- *   --lib <chemin>       dossier des helpers (défaut : src/lib)
- *   --alias <alias>      alias d'import cible (défaut : @)
- *   --color <hex>        intègre cette couleur aux fichiers copiés (plus de --primary)
- *   --radius <px>        écrit --radius dans uifolio-theme.css
- *   --force              écrase les fichiers existants
- *   --page <chemin>      chemin de la page (ex : src/pages/calendar.tsx)
- *                        crée la page si elle n'existe pas, sinon y ajoute
- *                        l'import et un appel de composant
- *   --dry-run            affiche ce qui serait copié sans rien écrire
+ * Options:
+ *   --cwd <dir>          target project (default: current directory)
+ *   --dir <path>         components folder (default: src/components/ui)
+ *   --lib <path>         helpers folder (default: src/lib)
+ *   --alias <alias>      target import alias (default: @)
+ *   --color <hex>        primary color, written in the Tailwind tokens (@theme)
+ *   --radius <px>        writes --radius in uifolio-theme.css
+ *   --page <path>        file where the component is used (created if missing)
+ *   --interactive        ask the questions even when stdin is not a terminal
+ *   --force              overwrite existing files
+ *   --dry-run            print what would be copied without writing anything
  *
- * Exemples :
- *   node cli/uifolio.mjs add calendar otp --cwd ../mon-projet
+ * Without --dir / --page, the CLI asks interactively (terminal) which folder
+ * receives the components and where to use them.
+ *
+ * Examples:
+ *   node cli/uifolio.mjs add calendar otp --cwd ../my-project
  *   node cli/uifolio.mjs add calendar --color "#10B981" --page src/pages/calendar.tsx
  *   node cli/uifolio.mjs add video-player --alias "#lib" --dry-run
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
@@ -37,7 +41,18 @@ const REGISTRY_SRC = resolve(HERE, '..', 'src')
 const REGISTRY_UI = join(REGISTRY_SRC, 'components', 'ui')
 const CONFIG_NAME = 'uifolio.json'
 
-const LIB_DEPS = ['clsx', 'tailwind-merge'] // cn() — toujours copié avec les helpers
+const LIB_DEPS = ['clsx', 'tailwind-merge'] // cn() — always copied with the helpers
+
+const DEFAULT_ACCENT = '#10b981'
+const DEFAULT_COMPONENTS_DIR = 'src/components/ui'
+const THEME_FILE = 'uifolio-theme.css'
+
+/** Global CSS candidates for wiring the Tailwind theme. */
+const GLOBAL_CSS_CANDIDATES = [
+  'src/index.css',
+  'src/app.css',
+  'src/globals.css',
+]
 
 /* -------------------------------------------------------------------------- */
 /* Utilitaires                                                                */
@@ -77,6 +92,31 @@ function parseArgs(argv) {
   return { positional, flags }
 }
 
+/** A “folder” answer must not be a file path (page.tsx, index.css…). */
+const FILE_LIKE = /\.(?:[cm]?[jt]sx?|css|scss|sass|less|html|json|md|vue|svelte)$/i
+
+function looksLikeFile(value) {
+  return FILE_LIKE.test(value.trim())
+}
+
+/** « ./src/ui/ » → « src/ui » */
+function normalizeComponentsDir(value) {
+  return value.trim().replace(/^\.\//, '').replace(/\/+$/, '')
+}
+
+/** Readable write error instead of a stack trace (EACCES, ENOTDIR…). */
+function writeFailure(error, target) {
+  const reasons = {
+    EACCES: 'permission denied',
+    EPERM: 'permission denied',
+    EROFS: 'read-only filesystem',
+    ENOSPC: 'no space left on device',
+    ENOTDIR: 'a file is in the way',
+    ENOENT: 'path not found',
+  }
+  fail(`Cannot write ${target}: ${reasons[error?.code] ?? error?.message ?? error}.`)
+}
+
 function listComponents() {
   if (!existsSync(REGISTRY_UI)) return []
   return readdirSync(REGISTRY_UI)
@@ -109,7 +149,7 @@ function localImports(source) {
   return [...specifiers]
 }
 
-/** Dépendances npm externes (hors React) d'un fichier source. */
+/** External npm dependencies (excluding React) of a source file. */
 function externalDeps(source) {
   const deps = new Set()
   const importRe = /from\s+['"]([^'"]+)['"]/g
@@ -124,21 +164,19 @@ function externalDeps(source) {
   return [...deps]
 }
 
-/**
- * Liste les pages cx (fichiers .tsx dans src/pages/) du projet cible.
- */
+/** Real exported name of the file (otp-input → OtpInput). */
+function componentExportName(source, fallback) {
+  const matches = [...source.matchAll(/export\s+function\s+([A-Z][A-Za-z0-9_]*)/g)].map((match) => match[1])
+  return matches[0] ?? fallback
+}
+
+/** .tsx files under src/pages of the target project, sorted. */
 function listPagesInCwd(cwd) {
-  if (!cwd || typeof cwd !== 'string') return []
   try {
-    const cwdPath = resolve(cwd)
-    const srcRoot = join(cwdPath, 'src')
-    if (!existsSync(srcRoot)) return []
-    const pagesDir = join(srcRoot, 'pages')
+    const pagesDir = join(resolve(cwd), 'src', 'pages')
     if (!existsSync(pagesDir)) return []
-    const entries = readdirSync(pagesDir)
-    if (!Array.isArray(entries)) return []
-    return entries
-      .filter((name) => typeof name === 'string' && name.endsWith('.tsx'))
+    return readdirSync(pagesDir)
+      .filter((name) => name.endsWith('.tsx'))
       .map((name) => join('src', 'pages', name))
       .sort()
   } catch {
@@ -146,81 +184,88 @@ function listPagesInCwd(cwd) {
   }
 }
 
+/** Files where the component usage may land (flags shown). */
+function usageCandidates(cwd) {
+  const app = existsSync(join(resolve(cwd), 'src', 'App.tsx')) ? 'src/App.tsx' : null
+  const pages = listPagesInCwd(cwd).filter((page) => page !== app)
+  return app ? [app, ...pages] : pages
+}
+
 /**
- * Demande interactivement à l'utilisateur quelle page utiliser, ou retourne
- * null si l'entrée n'est pas valide / la saisie est vide.
+ * Saisie interactive : uniquement sur un terminal (ou avec --interactive),
+ * never in CI / pipe without data, to avoid blocking the installation.
  */
-function choosePageInteraction(pages, cwd) {
-  if (!Array.isArray(pages) || pages.length === 0) return null
-  if (pages.length === 1) {
-    info(`Une page existe déjà : ${pages[0]} (utilisée par défaut)`)
-    try {
-      return join(resolve(cwd), pages[0])
-    } catch {
-      return null
+function createPrompter(flags) {
+  const allowed = Boolean(flags.interactive) || process.stdin.isTTY === true
+  if (!allowed) return null
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const queued = []
+  let waiting = null
+  let closed = false
+
+  rl.on('line', (line) => {
+    if (waiting) {
+      const resolveLine = waiting
+      waiting = null
+      resolveLine(line)
+    } else {
+      queued.push(line)
+    }
+  })
+  rl.on('close', () => {
+    closed = true
+    if (waiting) {
+      const resolveLine = waiting
+      waiting = null
+      resolveLine(null)
     }
-  }
-  let cwdPath = cwd
-  try {
-    cwdPath = resolve(cwd)
-  } catch {
-    cwdPath = process.cwd()
-  }
-
-  console.log('\nPlusieurs pages existent dans src/pages/. Choisis celle où importer le/des composant(s) :')
-  pages.forEach((p, index) => {
-    console.log(`  ${index + 1}. ${p}`)
   })
-  console.log('  0. Ne pas importer dans une page')
 
-  const answer = promptPageChoice()
-  if (answer === null) {
-    info('Aucune page sélectionnée : les composants seront copiés sans être importés dans une page.')
-    return null
-  }
-  if (answer === 0) {
-    info('Import dans une page annulé.')
-    return null
-  }
-  const selected = pages[answer - 1]
-  if (!selected) {
-    info('Choix invalide : aucune page sélectionnée.')
-    return null
-  }
-  info(`Page retenue : ${selected}`)
-  try {
-    return join(cwdPath, selected)
-  } catch {
-    return null
+  async function ask(question, fallback) {
+    const suffix = fallback ? ` (${fallback})` : ''
+    process.stdout.write(`\n  \x1b[36m?\x1b[0m ${question}${suffix} : `)
+
+    let answer
+    if (queued.length > 0) answer = queued.shift()
+    else if (closed) answer = null
+    else
+      answer = await new Promise((resolveLine) => {
+        waiting = resolveLine
+      })
+
+    // stdin closed (pipe without data): keep the default value.
+    if (answer === null) return fallback
+    const trimmed = answer.trim()
+    return trimmed === '' ? fallback : trimmed
   }
-}
 
-/**
- * Lecture synchrone d'une ligne depuis stdin (pour l'interaction CLI).
- * Retourne null en cas d'erreur de lecture ou d'EOF.
- */
-function promptPageChoice() {
-  const chunk = Buffer.alloc(1024)
-  try {
-    const n = process.stdin.read(0, chunk.length, chunk)
-    if (n <= 0) return null
-    const text = chunk.toString('utf8', 0, n).trim()
-    if (text === '') return null
-    const parsed = Number(text)
-    if (!Number.isInteger(parsed)) return null
-    return parsed
-  } catch {
-    return null
+  return {
+    ask,
+    /** y / yes / n / no (French values tolerated as fallback). */
+    async confirm(question, fallback = false) {
+      const answer = await ask(`${question} (y/n)`)
+      const value = String(answer ?? '')
+        .trim()
+        .toLowerCase()
+      if (['y', 'yes', 'o', 'oui'].includes(value)) return true
+      if (['n', 'no', 'non'].includes(value)) return false
+      return fallback
+    },
+    close() {
+      if (closed) return
+      closed = true
+      rl.close()
+    },
   }
 }
 
 /**
- * Résolution transitive : un composant importe des helpers (@/lib/…)
- * qui peuvent eux-mêmes importer d'autres fichiers locaux.
+ * Transitive resolution: a component imports helpers (@/lib/…)
+ * which may themselves import other local files.
  */
 function collectFiles(entryPath, srcRoot) {
   const queue = [entryPath]
-  const visited = new Map() // chemin absolu -> chemin relatif à src/
+  const visited = new Map() // absolute path -> relative path from src/
 
   while (queue.length > 0) {
     const current = queue.shift()
@@ -238,7 +283,7 @@ function collectFiles(entryPath, srcRoot) {
       ]
       const found = candidates.find((candidate) => existsSync(candidate))
       if (found) queue.push(found)
-      else fail(`Import local introuvable : ${specifier} (depuis ${relative(srcRoot, current)})`)
+      else fail(`Local import not found: ${specifier} (from ${relative(srcRoot, current)})`)
     }
   }
 
@@ -250,47 +295,6 @@ function rewriteAlias(source, targetAlias) {
   return source.replace(/(['"])@\//g, `$1${targetAlias}/`)
 }
 
-/**
- * Remplace les tokens `--primary` par la couleur choisie, directement dans le code
- * copié : `bg-primary` → `bg-[#10b981]`, `var(--primary)` → `#10b981`.
- * Le composant garde alors la couleur demandée sans dépendre de la variable du projet.
- */
-function personalizeColor(source, accent) {
-  if (!accent) return source
-  const foreground = isLightHex(accent) ? '#0f172a' : '#ffffff'
-  return source
-    .replace(/var\(--primary-foreground\)/g, foreground)
-    .replace(/var\(--primary\)/g, accent)
-    .replace(
-      /\b((?:[a-z0-9-]+:)*)(bg|text|border(?:-[xytrblse])?|ring(?:-offset)?|fill|stroke|from|via|to|divide|outline|shadow|accent|caret|decoration|placeholder)-primary(-foreground)?(\/\d+)?\b/g,
-      (_match, prefix, utility, isForeground, opacity = '') =>
-        `${prefix}${utility}-[${isForeground ? foreground : accent}]${opacity}`,
-    )
-}
-
-function copyFile({ to, source, dryRun, force, targetAlias, accent }) {
-  if (existsSync(to) && !force) return 'skipped'
-  if (!dryRun) {
-    mkdirSync(dirname(to), { recursive: true })
-    writeFileSync(to, rewriteAlias(personalizeColor(source, accent), targetAlias), 'utf8')
-  }
-  return 'written'
-}
-
-/* -------------------------------------------------------------------------- */
-/* Commandes                                                                  */
-/* -------------------------------------------------------------------------- */
-
-const ALIASES = {
-  otp: 'otp-input',
-  editor: 'rich-text-editor',
-  panels: 'resizable',
-  shortcuts: 'command-menu',
-  upload: 'file-upload',
-  video: 'video-player',
-}
-
-
 function normalizeHex(value) {
   let next = String(value).trim()
   if (!next.startsWith('#')) next = `#${next}`
@@ -311,286 +315,572 @@ function isLightHex(hex) {
   return 0.299 * r + 0.587 * g + 0.114 * b > 160
 }
 
+/* -------------------------------------------------------------------------- */
+/* Tailwind CSS 4 theme                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Les composants utilisent uniquement des classes Tailwind (`bg-primary`,
+ * `text-muted-foreground`, `border-border`…). Pour que ces classes existent,
+ * Tailwind 4 must discover the tokens via `@theme`: a plain `:root`
+ * generates no utility class.
+ */
+function buildThemeCss({ accent, radius }) {
+  const foreground = isLightHex(accent) ? '#0f172a' : '#ffffff'
+  const rootTokens = [
+    '  --background: #f8fafc;',
+    '  --foreground: #0f172a;',
+    '  --card: #ffffff;',
+    '  --card-foreground: #0f172a;',
+    '  --muted: #f1f5f9;',
+    '  --muted-foreground: #64748b;',
+    '  --border: #e2e8f0;',
+    `  --primary: ${accent};`,
+    `  --primary-foreground: ${foreground};`,
+    `  --accent: color-mix(in oklab, ${accent} 18%, var(--background));`,
+    '  --accent-foreground: var(--foreground);',
+    `  --ring: ${accent}80;`,
+  ]
+  if (radius !== undefined) rootTokens.push(`  --radius: ${radius}px;`)
+
+  const darkTokens = [
+    '  --background: #0b1220;',
+    '  --foreground: #e2e8f0;',
+    '  --card: #101a2b;',
+    '  --card-foreground: #e2e8f0;',
+    '  --muted: #1e293b;',
+    '  --muted-foreground: #94a3b8;',
+    '  --border: rgba(255, 255, 255, 0.12);',
+    `  --primary: ${accent};`,
+    `  --primary-foreground: ${foreground};`,
+    `  --accent: color-mix(in oklab, ${accent} 24%, #0b1220);`,
+    '  --accent-foreground: #e2e8f0;',
+    `  --ring: ${accent}80;`,
+    '  color-scheme: dark;',
+  ]
+
+  return `/* uifolio — Tailwind CSS 4 tokens: bg-primary, text-muted-foreground… come from here. */
+:root {
+${rootTokens.join('\n')}
+}
+
+.dark {
+${darkTokens.join('\n')}
+}
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-ring: var(--ring);
+}
+`
+}
+
+/** CSS global du projet (celui qui importe Tailwind), sinon null. */
+function findGlobalCss(cwd) {
+  for (const candidate of GLOBAL_CSS_CANDIDATES) {
+    const file = join(cwd, candidate)
+    if (!existsSync(file)) continue
+    const source = readFileSync(file, 'utf8')
+    if (/@import\s+['"]tailwindcss|@tailwind\b/.test(source)) return file
+  }
+  for (const candidate of GLOBAL_CSS_CANDIDATES) {
+    const file = join(cwd, candidate)
+    if (existsSync(file)) return file
+  }
+  return null
+}
+
+/** Adds `@import './uifolio-theme.css';` right after the Tailwind import. */
+function wireThemeImport(source, specifier) {
+  const line = `@import '${specifier}';`
+  if (source.includes(specifier)) return source
+  const lines = source.split('\n')
+  const at = lines.findIndex((entry) => /@import\s+['"]tailwindcss|@tailwind\s/.test(entry))
+  if (at === -1) return `${line}\n${source}`
+  lines.splice(at + 1, 0, line)
+  return lines.join('\n')
+}
+
+/** `--primary` already defined in a CSS (hex only), otherwise null. */
+function existingAccent(file) {
+  if (!file || !existsSync(file)) return null
+  const match = /--primary:\s*(#[0-9a-f]{6})\s*;/i.exec(readFileSync(file, 'utf8'))
+  return match ? match[1].toLowerCase() : null
+}
+
+/** `--radius` already defined in a CSS, otherwise undefined. */
+function existingRadius(file) {
+  if (!file || !existsSync(file)) return undefined
+  const match = /--radius:\s*(\d+(?:\.\d+)?)px\s*;/.exec(readFileSync(file, 'utf8'))
+  return match ? Math.round(Number(match[1])) : undefined
+}
+
 function writeTheme({ cwd, accent, radius, dryRun }) {
-  if (!accent && radius === undefined) return
+  const globalCss = findGlobalCss(cwd)
+  const themeFile = globalCss
+    ? join(dirname(globalCss), THEME_FILE)
+    : join(cwd, THEME_FILE)
+  // Without --color / --radius, keep the theme already in place (project or UIfolio).
+  const finalAccent = accent ?? existingAccent(themeFile) ?? existingAccent(globalCss) ?? DEFAULT_ACCENT
+  const finalRadius = radius ?? existingRadius(themeFile)
+  const css = buildThemeCss({ accent: finalAccent, radius: finalRadius })
+  const label = relative(cwd, themeFile)
+
+  if (dryRun) {
+    ok(`[dry-run] Tailwind theme would have been written to ${label}`)
+    if (globalCss) info(`[dry-run] imported in ${relative(cwd, globalCss)}`)
+    return
+  }
 
-  const rounded = radius === undefined ? null : Math.round(Number(radius))
-  if (rounded !== null && (!Number.isFinite(rounded) || rounded < 0 || rounded > 24)) {
-    fail(`Arrondi invalide : ${radius}. Utilise une valeur entre 0 et 24.`)
+  writeFileSync(themeFile, css, 'utf8')
+  ok(`Tailwind theme written to ${label}`)
+  info(`--primary: ${finalAccent}${finalRadius === undefined ? '' : ` · --radius: ${finalRadius}px`}`)
+
+  if (globalCss) {
+    const source = readFileSync(globalCss, 'utf8')
+    const specifier = `./${basename(themeFile)}`
+    const updated = wireThemeImport(source, specifier)
+    if (updated !== source) writeFileSync(globalCss, updated, 'utf8')
+    info(`imported in ${relative(cwd, globalCss)} — no hard-coded colors in the components`)
+  } else {
+    info(`Add "@import './${THEME_FILE}';", at the top of your global CSS (the Tailwind one).`)
   }
+}
 
-  const tokens = []
-  // La couleur est déjà écrite dans les fichiers copiés : on n'écrit pas de token.
-  if (!accent) {
-    const fallback = '#10b981'
-    tokens.push(
-      `  --primary: ${fallback};`,
-      '  --primary-foreground: #ffffff;',
-      `  --ring: ${fallback}80;`,
-      `  --accent: color-mix(in oklab, ${fallback} 18%, var(--background));`,
-      '  --accent-foreground: var(--foreground);',
-    )
+/* -------------------------------------------------------------------------- */
+/* Usage du composant dans une page                                           */
+/* -------------------------------------------------------------------------- */
+
+/** Chemin d'import relatif, sans extension, en slashs. */
+function importSpecifier(fromDir, target) {
+  const rel = relative(fromDir, target).replace(/\\/g, '/')
+  return rel.startsWith('.') ? rel : `./${rel}`
+}
+
+/** Inserts the imports after the last import of the file. */
+function addImports(source, lines) {
+  const missing = lines.filter((line) => !source.includes(line))
+  if (missing.length === 0) return source
+
+  const all = source.split('\n')
+  let last = -1
+  for (let index = 0; index < all.length; index += 1) {
+    if (/^\s*import\s/.test(all[index])) last = index
+  }
+  if (last === -1) return `${missing.join('\n')}\n\n${source}`
+
+  // An import can span several lines: advance to the end of it.
+  let end = last
+  while (
+    end < all.length - 1 &&
+    end - last < 20 &&
+    !/from\s+['"][^'"]+['"];?\s*$/.test(all[end]) &&
+    !/^import\s+['"][^'"]+['"];?\s*$/.test(all[end])
+  ) {
+    end += 1
   }
-  if (rounded !== null) tokens.push(`  --radius: ${rounded}px;`)
-  if (tokens.length === 0) return
 
-  const file = join(cwd, 'uifolio-theme.css')
-  if (!dryRun) writeFileSync(file, `:root {\n${tokens.join('\n')}\n}\n`, 'utf8')
-  ok(`${dryRun ? '[dry-run] ' : ''}Thème écrit dans ${relative(cwd, file)}`)
-  if (accent) info(`couleur ${accent} : déjà intégrée aux composants copiés`)
-  if (rounded !== null) info(`arrondi ${rounded}px`)
-  info(`Importe ${relative(cwd, file)} dans ton CSS global.`)
+  all.splice(end + 1, 0, ...missing)
+  return all.join('\n')
+}
+
+/**
+ * End of the opening tag from `<` to `start`, without being tricked by the
+ * `>`/apostrophes des attributs et des textes JSX.
+ */
+function findOpeningTagEnd(source, start) {
+  let braceDepth = 0
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index]
+    if (braceDepth === 0 && (char === '"' || char === "'")) {
+      const closing = source.indexOf(char, index + 1)
+      if (closing === -1) return null
+      index = closing
+      continue
+    }
+    if (char === '{') braceDepth += 1
+    else if (char === '}') braceDepth = Math.max(0, braceDepth - 1)
+    else if (char === '>' && braceDepth === 0) {
+      return { end: index, selfClosing: source[index - 1] === '/' }
+    }
+  }
+  return null
+}
+
+/** Adds `<Composant />` in the returned JSX, otherwise an exported demo. */
+function addJsxUsage(source, exportNames) {
+  const missing = exportNames.filter((name) => !new RegExp(`<${name}[\\s/>]`).test(source))
+  if (missing.length === 0) return { source, added: [] }
+
+  const returnMatch = /\breturn\b/.exec(source)
+  let cursor = returnMatch ? returnMatch.index + returnMatch[0].length : -1
+  while (cursor !== -1 && cursor < source.length && /[\s(]/.test(source[cursor])) cursor += 1
+  const rootIndex = cursor !== -1 && source[cursor] === '<' ? cursor : -1
+  const tag = rootIndex === -1 ? null : findOpeningTagEnd(source, rootIndex)
+
+  if (tag) {
+    const lineStart = source.lastIndexOf('\n', rootIndex) + 1
+    const indent = /^\s*/.exec(source.slice(lineStart, rootIndex))?.[0] ?? ''
+    const childIndent = `${indent}  `
+    const children = missing.map((name) => `${childIndent}<${name} />`).join('\n')
+
+    // Fragment already present: insert right after `<>`.
+    if (source.startsWith('<>', rootIndex)) {
+      const next = `${source.slice(0, rootIndex + 2)}\n${children}${source.slice(rootIndex + 2)}`
+      return { source: next, added: missing }
+    }
+
+    // Racine auto-fermante : on l'enveloppe dans un fragment.
+    if (tag.selfClosing) {
+      const element = source.slice(rootIndex, tag.end + 1)
+      const next =
+        `${source.slice(0, rootIndex)}<>\n${children}\n${indent}${element}\n${indent}</>${source.slice(tag.end + 1)}`
+      return { source: next, added: missing }
+    }
+
+    // Opening element: the components become its first children.
+    const next = `${source.slice(0, tag.end + 1)}\n${children}${source.slice(tag.end + 1)}`
+    return { source: next, added: missing }
+  }
+
+  // JSX introuvable (page sans `return` JSX) : on laisse un exemple utilisable.
+  const example = missing
+    .map((name) => `\nexport function ${name}Example() {\n  return <${name} />\n}\n`)
+    .join('\n')
+  return { source: `${source.trimEnd()}\n${example}`, added: missing }
+}
+
+/**
+ * Writes (or completes) the chosen file: imports from the real folder of the
+ * composants + appel `<Composant />` dans le JSX.
+ */
+function writeUsage({ cwd, target, componentsDir, components, dryRun }) {
+  if (existsSync(target) && statSync(target).isDirectory()) {
+    fail(`${relative(cwd, target)} is a folder: give a file (e.g. src/pages/${components[0].name}.tsx).`)
+  }
+  const created = !existsSync(target)
+  const lines = components.map(({ name, exportName }) =>
+    `import { ${exportName} } from '${importSpecifier(dirname(target), join(resolve(cwd, componentsDir), name))}'`,
+  )
+  const label = relative(cwd, target)
+  const names = components.map((component) => component.exportName)
+
+  if (created) {
+    const body = [
+      ...lines,
+      '',
+      `export default function ${names[0]}Page() {`,
+      '  return (',
+      '    <main className="space-y-6 p-6">',
+      ...names.map((name) => `      <${name} />`),
+      '    </main>',
+      '  )',
+      '}',
+      '',
+    ].join('\n')
+    if (!dryRun) {
+      try {
+        mkdirSync(dirname(target), { recursive: true })
+        writeFileSync(target, body, 'utf8')
+      } catch (error) {
+        writeFailure(error, label)
+      }
+    }
+    ok(`${dryRun ? '[dry-run] ' : ''}page created: ${label}`)
+  } else {
+    const source = readFileSync(target, 'utf8')
+    const withImports = addImports(source, lines)
+    const { source: updated, added } = addJsxUsage(withImports, names)
+    if (!dryRun) {
+      try {
+        writeFileSync(target, updated, 'utf8')
+      } catch (error) {
+        writeFailure(error, label)
+      }
+    }
+    ok(`${dryRun ? '[dry-run] ' : ''}usage added to ${label}`)
+    if (added.length < names.length) {
+      const already = names.filter((name) => !added.includes(name))
+      info(`already present, not duplicated: ${already.join(', ')}`)
+    }
+  }
+
+  for (const name of names) info(`· <${name} />`)
+}
+
+/* -------------------------------------------------------------------------- */
+/* Commandes                                                                  */
+/* -------------------------------------------------------------------------- */
+
+const ALIASES = {
+  otp: 'otp-input',
+  editor: 'rich-text-editor',
+  panels: 'resizable',
+  shortcuts: 'command-menu',
+  upload: 'file-upload',
+  video: 'video-player',
 }
 
 function commandList() {
   const components = listComponents()
-  if (components.length === 0) fail('Aucun composant trouvé dans le registre.')
-  console.log('\nComposants disponibles :\n')
+  if (components.length === 0) fail('No component found in the registry.')
+  console.log('\nAvailable components:\n')
   for (const name of components) {
     console.log(`  \x1b[36m${name.padEnd(20)}\x1b[0m src/components/ui/${name}.tsx`)
   }
-  console.log('\nUsage : uifolio add <nom> [--cwd <projet cible>]\n')
+  console.log('\nUsage: uifolio add <name> [--cwd <target project>]\n')
 }
 
 function commandInit({ flags }) {
   const cwd = resolve(flags.cwd ?? process.cwd())
   const file = join(cwd, CONFIG_NAME)
-  if (existsSync(file) && !flags.force) fail(`${CONFIG_NAME} existe déjà (utilise --force).`)
+  if (existsSync(file) && !flags.force) fail(`${CONFIG_NAME} already exists (use --force).`)
 
   const config = {
     $schema: 'https://uifolio.dev/schema.json',
-    dir: typeof flags.dir === 'string' ? flags.dir : 'src/components/ui',
+    dir: typeof flags.dir === 'string' ? flags.dir : DEFAULT_COMPONENTS_DIR,
     lib: typeof flags.lib === 'string' ? flags.lib : 'src/lib',
     alias: typeof flags.alias === 'string' ? flags.alias : '@',
   }
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
-  ok(`${CONFIG_NAME} écrit dans ${cwd}`)
+  ok(`${CONFIG_NAME} written to ${cwd}`)
   info(`dir: ${config.dir} · lib: ${config.lib} · alias: ${config.alias}`)
-  info('Puis : uifolio add video-player calendar …')
+  info('Next: uifolio add video-player calendar …')
 }
 
+/**
+ * Asks where the component should be used, right after installation:
+ * an existing file, a new folder + import file, or no file at all.
+ */
+async function chooseUsageTarget({ prompter, cwd, names, exportNames }) {
+  const suggestion = `src/pages/${names[0]}.tsx`
+  const pathFormat = `e.g. ${suggestion}`
+  const label = exportNames.join(', ')
+  const candidates = usageCandidates(cwd)
+  if (candidates.length > 0) info(`existing files: ${candidates.join(', ')}`)
+
+  const ready = await prompter.confirm(
+    `Do you already have a file ready to receive the component (${label})?`,
+    false,
+  )
+
+  let answer
+  if (ready) {
+    answer = await prompter.ask(`In which file should the component (${label}) be copied? (${pathFormat})`, suggestion)
+  } else {
+    const create = await prompter.confirm('Would you like to create a new folder and an import file?', true)
+    if (!create) {
+      info('the component is installed but not used in any file.')
+      return null
+    }
+    answer = await prompter.ask(`Please specify the new path (${pathFormat})`, suggestion)
+  }
 
-function commandAdd({ positional, flags }) {
-  const names = positional.map((name) => ALIASES[name] ?? name)
+  // “ - ”: installation only, like the “no” answer.
+  if (!answer || answer === '-') {
+    info('the component is installed but not used in any file.')
+    return null
+  }
+  return resolve(cwd, answer)
+}
 
-  if (names.length === 0) fail('Aucun composant demandé. Ex. : uifolio add calendar otp')
+async function commandAdd({ positional, flags }) {
+  const names = positional.map((name) => ALIASES[name] ?? name)
+  if (names.length === 0) fail('No component requested. E.g.: uifolio add calendar otp')
 
   const cwd = resolve(flags.cwd ?? process.cwd())
   const config = readConfig(cwd) ?? {}
-  const pageFlag = typeof flags.page === 'string' ? flags.page : undefined
-  let pageTarget = pageFlag ? resolve(cwd, pageFlag) : null
-
-  // Détermine la page cible effective : --page explicite, choix interactif, ou aucune.
-  if (!pageTarget) {
-    const pages = listPagesInCwd(cwd)
-    if (pages.length > 0) {
-      const chosen = choosePageInteraction(pages, cwd)
-      if (chosen) pageTarget = chosen
-    }
-  }
-
-  const createPage = Boolean(pageTarget) && !existsSync(pageTarget)
-  let pageImports = []
-
-  const componentsDir = typeof flags.dir === 'string' ? flags.dir : config.dir ?? 'src/components/ui'
-  const libDir = typeof flags.lib === 'string' ? flags.lib : config.lib ?? 'src/lib'
-  const targetAlias = typeof flags.alias === 'string' ? flags.alias : config.alias ?? '@'
   const dryRun = Boolean(flags['dry-run'])
   const force = Boolean(flags.force)
+  const targetAlias = typeof flags.alias === 'string' ? flags.alias : config.alias ?? '@'
+  const libDir = typeof flags.lib === 'string' ? flags.lib : config.lib ?? 'src/lib'
+
   const colorFlag = typeof flags.color === 'string' ? flags.color : undefined
   const accent = colorFlag === undefined ? null : normalizeHex(colorFlag)
   if (colorFlag !== undefined && !accent) {
-    fail(`Couleur invalide : ${colorFlag}. Utilise un hex comme #10B981.`)
+    fail(`Invalid color: ${colorFlag}. Use a hex value like #10B981.`)
+  }
+
+  let radius
+  if (typeof flags.radius === 'string') {
+    radius = Math.round(Number(flags.radius))
+    if (!Number.isFinite(radius) || radius < 0 || radius > 24) {
+      fail(`Invalid radius: ${flags.radius}. Use a value between 0 and 24.`)
+    }
   }
 
   const known = listComponents()
   const unknown = names.filter((name) => !known.includes(name))
   if (unknown.length > 0) {
-    fail(`Composant(s) inconnu(s) : ${unknown.join(', ')}. Lance « uifolio list ».`)
-  }
-
-  if (!dryRun && !existsSync(cwd)) fail(`Répertoire cible introuvable : ${cwd}`)
-  if (pageTarget && !existsSync(pageTarget) && !dryRun) {
-    const bad = pageFlag ?? relative(cwd, pageTarget)
-    fail(`Page cible introuvable : ${bad}.`)
+    fail(`Unknown component(s): ${unknown.join(', ')}. Run "uifolio list".`)
   }
-  if (pageTarget && !existsSync(pageTarget) && dryRun) {
-    info(`[dry-run] page cible introuvable : ${pageFlag ?? relative(cwd, pageTarget)} (simulation uniquement).`)
-    pageTarget = null
-  }
-
-  const deps = new Set(LIB_DEPS)
-  const written = new Set()
-  const skipped = []
-
-  // Prépare les imports qui seront injectés dans la page cible.
-  for (const name of names) {
-    if (!pageTarget) continue
-    const importPath = relative(cwd, join(componentsDir, `${name}.tsx`))
-    pageImports.push({ name, importPath })
-  }
-
-  for (const name of names) {
-    const entry = join(REGISTRY_UI, `${name}.tsx`)
-    const files = collectFiles(entry, REGISTRY_SRC)
+  if (!dryRun && !existsSync(cwd)) fail(`Target directory not found: ${cwd}`)
 
-    for (const [absolute, relativePath] of files) {
-      const isUi = relativePath.startsWith(join('components', 'ui'))
-      const destinationRoot = isUi ? resolve(cwd, componentsDir) : resolve(cwd, libDir)
-      const destination = join(destinationRoot, relativePath.replace(/^(components\/ui|lib)\//, ''))
+  const prompter = createPrompter(flags)
+  try {
+    // 1. Dossier d'import des composants.
+    let componentsDir = normalizeComponentsDir(
+      typeof flags.dir === 'string' ? flags.dir : config.dir ?? DEFAULT_COMPONENTS_DIR,
+    )
+    if (prompter && typeof flags.dir !== 'string') {
+      // A file path was already accepted here (mkdir relative to the root).
+      for (let attempts = 0; ; attempts += 1) {
+        const fallback = attempts === 0 ? componentsDir : DEFAULT_COMPONENTS_DIR
+        const answer = await prompter.ask('In which folder should the components be copied?', fallback)
+        componentsDir = normalizeComponentsDir(answer ?? DEFAULT_COMPONENTS_DIR)
+        if (!looksLikeFile(componentsDir) || attempts >= 2) break
+        info(`"${componentsDir}" is a file, not a folder: give a folder, e.g. ${DEFAULT_COMPONENTS_DIR}.`)
+      }
+    }
+    if (looksLikeFile(componentsDir)) {
+      fail(`"${componentsDir}" is a file: give a folder (e.g. ${DEFAULT_COMPONENTS_DIR}).`)
+    }
 
-      if (written.has(destination)) continue
+    // 2. Copie des fichiers + helpers.
+    const deps = new Set(LIB_DEPS)
+    const written = new Set()
+    const destinations = new Set()
+    const skipped = []
+    const components = []
+
+    for (const name of names) {
+      const entry = join(REGISTRY_UI, `${name}.tsx`)
+      const files = collectFiles(entry, REGISTRY_SRC)
+      components.push({ name, exportName: componentExportName(readFileSync(entry, 'utf8'), name) })
+
+      for (const [absolute, relativePath] of files) {
+        const isUi = relativePath.startsWith(join('components', 'ui'))
+        const destinationRoot = isUi ? resolve(cwd, componentsDir) : resolve(cwd, libDir)
+        const destination = join(destinationRoot, relativePath.replace(/^(components\/ui|lib)\//, ''))
+        if (destinations.has(destination)) continue
+        destinations.add(destination)
+
+        const source = readFileSync(absolute, 'utf8')
+        for (const dep of externalDeps(source)) deps.add(dep)
+
+        const label = relative(cwd, destination)
+        const shouldWrite = force || !existsSync(destination)
+        if (shouldWrite) {
+          if (!dryRun) {
+            try {
+              mkdirSync(dirname(destination), { recursive: true })
+              writeFileSync(destination, rewriteAlias(source, targetAlias), 'utf8')
+            } catch (error) {
+              writeFailure(error, label)
+            }
+          }
+          written.add(label)
+        } else {
+          skipped.push(label)
+        }
+      }
+    }
 
-      const source = readFileSync(absolute, 'utf8')
-      for (const dep of externalDeps(source)) deps.add(dep)
+    ok(`${written.size} file(s) ${dryRun ? 'would be copied [dry-run]' : 'copied'}:`)
+    for (const label of [...written].sort()) info(`· ${label}`)
+    if (skipped.length > 0) {
+      info(`${skipped.length} file(s) already present, skipped: ${skipped.join(', ')} (use --force to overwrite)`)
+    }
 
-      const status = copyFile({
-        to: destination,
-        source,
-        dryRun,
-        force,
-        targetAlias,
-        accent,
+    // 3. Tokens Tailwind : les classes bg-primary & co fonctionnent partout.
+    writeTheme({ cwd, accent, radius, dryRun })
+
+    // 4. Component usage, after installation.
+    let pageTarget = typeof flags.page === 'string' ? resolve(cwd, flags.page) : null
+    if (!pageTarget && prompter) {
+      pageTarget = await chooseUsageTarget({
+        prompter,
+        cwd,
+        names,
+        exportNames: components.map((component) => component.exportName),
       })
-
-      const label = relative(cwd, destination)
-      if (status === 'written') written.add(label)
-      else skipped.push(label)
     }
-  }
-
-  const action = dryRun ? '[dry-run] auraient été copiés' : 'copié(s)'
-  ok(`${written.size} fichier(s) ${action} :`)
-  for (const label of [...written].sort()) info(`· ${label}`)
-  if (skipped.length > 0) {
-    info(`${skipped.length} fichier(s) déjà présent(s), ignoré(s) : ${skipped.join(', ')} (–force pour écraser)`)
-  }
-  if (accent && written.size > 0) {
-    info(`couleur ${accent} intégrée (bg-primary → bg-[${accent}]), aucun --primary requis`)
-  }
+    if (pageTarget) writeUsage({ cwd, target: pageTarget, componentsDir, components, dryRun })
 
-  writeTheme({
-    cwd,
-    accent,
-    radius: typeof flags.radius === 'string' ? flags.radius : undefined,
-    dryRun,
-  })
-
-  if (written.size > 0 || dryRun) {
-    console.log('\n  Dépendances npm détectées :')
-    info(`npm install ${[...deps].sort().join(' ')}`)
-    if (targetAlias !== '@') {
-      info(`Pense à aligner l'alias ${targetAlias} dans ton tsconfig/vite (remplace de @/).`)
-    }
-    console.log('')
-  }  // Crée ou adapte la page cible si une page cible a été sélectionnée.
-  if (pageTarget) {
-    const dir = dirname(pageTarget)
-    if (createPage) {
-      if (!dryRun) {
-        mkdirSync(dir, { recursive: true })
-        writeFileSync(
-          pageTarget,
-          `import { ${pageImports.map((p) => p.name).join(', ')} } from '${relative(dir, join(cwd, componentsDir)).replace(/\\/g, '/')}'\n'\n` +
-            `export default function Page() {\n` +
-            `  return (<>\n` +
-            pageImports.map((p) => `    <${p.name} />`).join('\n') +
-            `\n  </>)\n` +
-            `}\n`,
-          'utf8',
-        )
-      }
-      ok(`${dryRun ? '[dry-run] ' : ''}Page créée : ${relative(cwd, pageTarget)}`)
-      for (const p of pageImports) {
-        info(`· <${p.name} /> importé depuis ${relative(cwd, join(componentsDir, `${p.name}.tsx`))}`)
-      }
-    } else {
-      if (dryRun) {
-        info(`[dry-run] page existante détectée : ${relative(cwd, pageTarget)}`)
-      } else {
-        const source = readFileSync(pageTarget, 'utf8')
-        const rendered =
-          pageImports.map((p) => `import { ${p.name} } from '${relative(dirname(pageTarget), join(cwd, componentsDir)).replace(/\\/g, '/')}';`).join('\n')
-        const functionPoint = source.indexOf('function ')
-        const insertPoint =
-          functionPoint !== -1 ? functionPoint : source.lastIndexOf('</')
-        const updatedSource =
-          insertPoint === -1
-            ? source + '\n' + rendered + '\n' + pageImports.map((p) => `<${p.name} />`).join('\n')
-            : source.slice(0, insertPoint) + '\n' + rendered + '\n' + source.slice(insertPoint)
-        writeFileSync(pageTarget, updatedSource, 'utf8')
+    if (written.size > 0 || dryRun) {
+      console.log('\n  Detected npm dependencies:')
+      info(`npm install ${[...deps].sort().join(' ')}`)
+      if (targetAlias !== '@') {
+        info(`Remember to align the ${targetAlias} alias in your tsconfig/vite (instead of @/).`)
       }
-      ok(`Page existante mise à jour : ${relative(cwd, pageTarget)}`)
+      console.log('')
     }
+  } finally {
+    prompter?.close()
   }
 }
 
 /* -------------------------------------------------------------------------- */
-/* Entrée                                                                     */
+/* Prompting                                                                  */
 /* -------------------------------------------------------------------------- */
 
 function usage() {
   console.log(`
-\x1b[1muifolio\x1b[0m — installe les composants UIfolio dans un projet
-
-  \x1b[36muifolio list\x1b[0m                     composants disponibles
-  \x1b[36muifolio init [options]\x1b[0m           écrit uifolio.json dans le projet cible
-  \x1b[36muifolio add <noms...> [options]\x1b[0m  copie les composants + leurs helpers
-
-Options :
-  --cwd <dir>       projet cible (défaut : répertoire courant)
-  --dir <chemin>    dossier composants (défaut : src/components/ui)
-  --lib <chemin>    dossier helpers (défaut : src/lib)
-  --alias <alias>   alias d'import cible (défaut : @)
-  --color <hex>     intègre cette couleur aux fichiers copiés (sans --primary)
-  --radius <px>     arrondi global (0–24) dans uifolio-theme.css
-  --force           écrase les fichiers existants
-  --dry-run         simule sans écrire
-  --page <chemin>   page cible (ex : src/pages/calendar.tsx). Avec --page, la CLI crée la page
-                    si elle n'existe pas, ou y ajoute l'import + l'appel du/des composant(s).
-                    Sans --page et quand des pages existent déjà dans src/pages, la CLI demande
-                    interactivement laquelle utiliser avant d'importer.
-
-Exemples :
-  node cli/uifolio.mjs add video-player calendar otp --cwd ../mon-projet
+\x1b[1muifolio\x1b[0m — installs the UIfolio components into a project
+
+  \x1b[36muifolio list\x1b[0m                     list available components
+  \x1b[36muifolio init [options]\x1b[0m           write uifolio.json in the target project
+  \x1b[36muifolio add <names...> [options]\x1b[0m  copy the components + their helpers
+
+Options:
+  --cwd <dir>       target project (default: current directory)
+  --dir <path>      components folder (default: src/components/ui)
+  --lib <path>      helpers folder (default: src/lib)
+  --alias <alias>   target import alias (default: @)
+  --color <hex>     primary color, written in the Tailwind tokens (@theme)
+  --radius <px>     global radius (0–24) in uifolio-theme.css
+  --page <path>     file where the component is used (e.g. src/pages/calendar.tsx);
+                    created if missing, otherwise the import + <Component /> are added
+  --interactive     ask the questions outside a terminal
+  --force           overwrite existing files
+  --dry-run         simulate without writing
+
+Without --dir or --page, the CLI asks in which folder to copy the components,
+then whether a file is already ready to receive them. The component is either
+added to an existing file, added to a new folder + import file, or installed
+only. Colors go through a Tailwind CSS 4 theme (uifolio-theme.css, @theme), so
+classes like bg-primary and text-muted-foreground stay in the code.
+
+Examples:
+  node cli/uifolio.mjs add video-player calendar otp --cwd ../my-project
   node cli/uifolio.mjs add otp --color "#10B981" --radius 8
-  node cli/uifolio.mjs add otp --alias "#lib" --dry-run
   node cli/uifolio.mjs add calendar --page src/pages/calendar.tsx
 `)
 }
 
-const { positional, flags } = parseArgs(process.argv.slice(2))
-const command = positional.shift()
-
-// Requête interactive de la page cible avant toute écriture, sauf si --page est déjà passé.
-if (command === 'add' && typeof flags.page !== 'string') {
-  let cwd
-  try {
-    cwd = resolve(flags.cwd ?? process.cwd())
-  } catch {
-    cwd = process.cwd()
-  }
-  const pages = listPagesInCwd(cwd)
-  if (pages.length > 0) {
-    const target = choosePageInteraction(pages, cwd)
-    if (target) flags.page = target
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2))
+  const command = positional.shift()
+
+  switch (command) {
+    case 'list':
+      commandList()
+      break
+    case 'init':
+      commandInit({ positional, flags })
+      break
+    case 'add':
+      await commandAdd({ positional, flags })
+      break
+    case undefined:
+    case 'help':
+      usage()
+      break
+    default:
+      fail(`Commande inconnue : ${command}. Lance « uifolio » sans argument.`)
   }
 }
 
-switch (command) {
-  case 'list':
-    commandList()
-    break
-  case 'init':
-    commandInit({ positional, flags })
-    break
-  case 'add':
-    commandAdd({ positional, flags })
-    break
-  case undefined:
-  case 'help':
-    usage()
-    break
-  default:
-    fail(`Commande inconnue : ${command}. Lance « uifolio » sans argument.`)
-}
+await main()