uifolio 0.5.1 → 0.5.3

package/cli/uifolio.mjs

@@ -1,37 +1,37 @@
 #!/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,
- *                                        écrit les tokens Tailwind et utilise
- *                                        le composant dans une page
+ * 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>        couleur primaire, écrite dans les tokens Tailwind (@theme)
- *   --radius <px>        écrit --radius dans uifolio-theme.css
- *   --page <chemin>      fichier où utiliser le composant (créé s'il n'existe pas)
- *   --interactive        force les questions même quand stdin n'est pas un terminal
- *   --force              écrase les fichiers existants
- *   --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
  *
- * Sans --dir / --page, la CLI demande interactivement (terminal) dans quel
- * dossier copier les composants et dans quel fichier les utiliser.
+ * Without --dir / --page, the CLI asks interactively (terminal) which folder
+ * receives the components and where to use them.
  *
- * Exemples :
- *   node cli/uifolio.mjs add calendar otp --cwd ../mon-projet
+ * 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 { 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'
@@ -41,21 +41,17 @@ 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'
 
-/** Fichiers CSS globaux candidats pour brancher le thème Tailwind. */
+/** Global CSS candidates for wiring the Tailwind theme. */
 const GLOBAL_CSS_CANDIDATES = [
   'src/index.css',
   'src/app.css',
   'src/globals.css',
-  'src/styles.css',
-  'src/main.css',
-  'app/globals.css',
-  'styles/globals.css',
 ]
 
 /* -------------------------------------------------------------------------- */
@@ -96,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)
@@ -128,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
@@ -143,13 +164,13 @@ function externalDeps(source) {
   return [...deps]
 }
 
-/** Nom réellement exporté par le fichier (otp-input → OtpInput). */
+/** 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
 }
 
-/** Fichiers .tsx de src/pages/ du projet cible, triés. */
+/** .tsx files under src/pages of the target project, sorted. */
 function listPagesInCwd(cwd) {
   try {
     const pagesDir = join(resolve(cwd), 'src', 'pages')
@@ -163,7 +184,7 @@ function listPagesInCwd(cwd) {
   }
 }
 
-/** Fichiers où l'usage du composant peut atterrir (indices affichés). */
+/** 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)
@@ -172,7 +193,7 @@ function usageCandidates(cwd) {
 
 /**
  * Saisie interactive : uniquement sur un terminal (ou avec --interactive),
- * jamais en CI / pipe sans données, pour ne pas bloquer l'installation.
+ * never in CI / pipe without data, to avoid blocking the installation.
  */
 function createPrompter(flags) {
   const allowed = Boolean(flags.interactive) || process.stdin.isTTY === true
@@ -200,22 +221,35 @@ function createPrompter(flags) {
     }
   })
 
-  return {
-    async 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) => {
+  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 fermé (pipe sans données) : on garde la valeur par défaut.
-      if (answer === null) return fallback
-      const trimmed = answer.trim()
-      return trimmed === '' ? fallback : trimmed
+    // stdin closed (pipe without data): keep the default value.
+    if (answer === null) return fallback
+    const trimmed = answer.trim()
+    return trimmed === '' ? fallback : trimmed
+  }
+
+  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
@@ -226,12 +260,12 @@ function createPrompter(flags) {
 }
 
 /**
- * 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()
@@ -249,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)})`)
     }
   }
 
@@ -282,14 +316,14 @@ function isLightHex(hex) {
 }
 
 /* -------------------------------------------------------------------------- */
-/* Thème Tailwind CSS 4                                                       */
+/* 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 doit connaître les tokens via `@theme` : un simple `:root`
- * ne génère aucune classe utilitaire.
+ * 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'
@@ -325,7 +359,7 @@ function buildThemeCss({ accent, radius }) {
     '  color-scheme: dark;',
   ]
 
-  return `/* uifolio — tokens Tailwind CSS 4 : les classes bg-primary, text-muted-foreground… viennent d'ici. */
+  return `/* uifolio — Tailwind CSS 4 tokens: bg-primary, text-muted-foreground… come from here. */
 :root {
 ${rootTokens.join('\n')}
 }
@@ -368,7 +402,7 @@ function findGlobalCss(cwd) {
   return null
 }
 
-/** Ajoute `@import './uifolio-theme.css';` juste après l'import de Tailwind. */
+/** Adds `@import './uifolio-theme.css';` right after the Tailwind import. */
 function wireThemeImport(source, specifier) {
   const line = `@import '${specifier}';`
   if (source.includes(specifier)) return source
@@ -379,14 +413,14 @@ function wireThemeImport(source, specifier) {
   return lines.join('\n')
 }
 
-/** `--primary` déjà défini dans un CSS (hex uniquement), sinon null. */
+/** `--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` déjà défini dans un CSS, sinon undefined. */
+/** `--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'))
@@ -398,20 +432,20 @@ function writeTheme({ cwd, accent, radius, dryRun }) {
   const themeFile = globalCss
     ? join(dirname(globalCss), THEME_FILE)
     : join(cwd, THEME_FILE)
-  // Sans --color / --radius, on garde le thème déjà en place (projet ou UIfolio).
+  // 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] thème Tailwind aurait été écrit dans ${label}`)
-    if (globalCss) info(`[dry-run] importé dans ${relative(cwd, globalCss)}`)
+    ok(`[dry-run] Tailwind theme would have been written to ${label}`)
+    if (globalCss) info(`[dry-run] imported in ${relative(cwd, globalCss)}`)
     return
   }
 
   writeFileSync(themeFile, css, 'utf8')
-  ok(`thème Tailwind écrit dans ${label}`)
+  ok(`Tailwind theme written to ${label}`)
   info(`--primary: ${finalAccent}${finalRadius === undefined ? '' : ` · --radius: ${finalRadius}px`}`)
 
   if (globalCss) {
@@ -419,9 +453,9 @@ function writeTheme({ cwd, accent, radius, dryRun }) {
     const specifier = `./${basename(themeFile)}`
     const updated = wireThemeImport(source, specifier)
     if (updated !== source) writeFileSync(globalCss, updated, 'utf8')
-    info(`importé dans ${relative(cwd, globalCss)} — aucune couleur en dur dans les composants`)
+    info(`imported in ${relative(cwd, globalCss)} — no hard-coded colors in the components`)
   } else {
-    info(`Ajoute « @import './${THEME_FILE}'; » en haut de ton CSS global (celui de Tailwind).`)
+    info(`Add "@import './${THEME_FILE}';", at the top of your global CSS (the Tailwind one).`)
   }
 }
 
@@ -435,7 +469,7 @@ function importSpecifier(fromDir, target) {
   return rel.startsWith('.') ? rel : `./${rel}`
 }
 
-/** Insère les imports après le dernier import du fichier. */
+/** 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
@@ -447,7 +481,7 @@ function addImports(source, lines) {
   }
   if (last === -1) return `${missing.join('\n')}\n\n${source}`
 
-  // Un import peut tenir sur plusieurs lignes : on avance jusqu'à la fin.
+  // An import can span several lines: advance to the end of it.
   let end = last
   while (
     end < all.length - 1 &&
@@ -463,7 +497,7 @@ function addImports(source, lines) {
 }
 
 /**
- * Fin de la balise ouvrante du `<` à `start`, sans se laisser piéger par les
+ * End of the opening tag from `<` to `start`, without being tricked by the
  * `>`/apostrophes des attributs et des textes JSX.
  */
 function findOpeningTagEnd(source, start) {
@@ -485,7 +519,7 @@ function findOpeningTagEnd(source, start) {
   return null
 }
 
-/** Ajoute `<Composant />` dans le JSX retourné, sinon un exemple exporté. */
+/** 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: [] }
@@ -502,7 +536,7 @@ function addJsxUsage(source, exportNames) {
     const childIndent = `${indent}  `
     const children = missing.map((name) => `${childIndent}<${name} />`).join('\n')
 
-    // Fragment déjà présent : on insère juste après `<>`.
+    // 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 }
@@ -516,7 +550,7 @@ function addJsxUsage(source, exportNames) {
       return { source: next, added: missing }
     }
 
-    // Élément ouvrant : les composants deviennent ses premiers enfants.
+    // 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 }
   }
@@ -529,10 +563,13 @@ function addJsxUsage(source, exportNames) {
 }
 
 /**
- * Écrit (ou complète) le fichier choisi : imports depuis le dossier réel des
+ * 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))}'`,
@@ -554,19 +591,29 @@ function writeUsage({ cwd, target, componentsDir, components, dryRun }) {
       '',
     ].join('\n')
     if (!dryRun) {
-      mkdirSync(dirname(target), { recursive: true })
-      writeFileSync(target, body, 'utf8')
+      try {
+        mkdirSync(dirname(target), { recursive: true })
+        writeFileSync(target, body, 'utf8')
+      } catch (error) {
+        writeFailure(error, label)
+      }
     }
-    ok(`${dryRun ? '[dry-run] ' : ''}page créée : ${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) writeFileSync(target, updated, 'utf8')
-    ok(`${dryRun ? '[dry-run] ' : ''}usage ajouté dans ${label}`)
+    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(`déjà présent(s), non dupliqué(s) : ${already.join(', ')}`)
+      info(`already present, not duplicated: ${already.join(', ')}`)
     }
   }
 
@@ -588,18 +635,18 @@ const ALIASES = {
 
 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',
@@ -608,26 +655,42 @@ function commandInit({ flags }) {
     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 …')
 }
 
 /**
- * Demande le fichier où utiliser le composant, après l'installation.
- * La page proposée par défaut est créée si elle n'existe pas.
+ * 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 }) {
+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(`fichiers existants : ${candidates.join(', ')}`)
+  if (candidates.length > 0) info(`existing files: ${candidates.join(', ')}`)
 
-  const answer = await prompter.ask(
-    `Dans quel fichier utiliser ${names.join(', ')} ? « - » pour ne pas l'utiliser`,
-    suggestion,
+  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)
+  }
+
+  // “ - ”: installation only, like the “no” answer.
   if (!answer || answer === '-') {
-    info('le composant est installé mais n’est utilisé dans aucun fichier.')
+    info('the component is installed but not used in any file.')
     return null
   }
   return resolve(cwd, answer)
@@ -635,7 +698,7 @@ async function chooseUsageTarget({ prompter, cwd, names }) {
 
 async function commandAdd({ positional, flags }) {
   const names = positional.map((name) => ALIASES[name] ?? name)
-  if (names.length === 0) fail('Aucun composant demandé. Ex. : uifolio add calendar otp')
+  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) ?? {}
@@ -647,33 +710,43 @@ async function commandAdd({ positional, flags }) {
   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(`Arrondi invalide : ${flags.radius}. Utilise une valeur entre 0 et 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 ».`)
+    fail(`Unknown component(s): ${unknown.join(', ')}. Run "uifolio list".`)
   }
-  if (!dryRun && !existsSync(cwd)) fail(`Répertoire cible introuvable : ${cwd}`)
+  if (!dryRun && !existsSync(cwd)) fail(`Target directory not found: ${cwd}`)
 
   const prompter = createPrompter(flags)
   try {
     // 1. Dossier d'import des composants.
-    let componentsDir = typeof flags.dir === 'string' ? flags.dir : config.dir ?? DEFAULT_COMPONENTS_DIR
+    let componentsDir = normalizeComponentsDir(
+      typeof flags.dir === 'string' ? flags.dir : config.dir ?? DEFAULT_COMPONENTS_DIR,
+    )
     if (prompter && typeof flags.dir !== 'string') {
-      const answer = await prompter.ask('Dans quel dossier copier les composants', componentsDir)
-      if (answer) componentsDir = answer
+      // 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}).`)
     }
-    componentsDir = componentsDir.replace(/^\.\//, '').replace(/\/+$/, '')
 
     // 2. Copie des fichiers + helpers.
     const deps = new Set(LIB_DEPS)
@@ -701,8 +774,12 @@ async function commandAdd({ positional, flags }) {
         const shouldWrite = force || !existsSync(destination)
         if (shouldWrite) {
           if (!dryRun) {
-            mkdirSync(dirname(destination), { recursive: true })
-            writeFileSync(destination, rewriteAlias(source, targetAlias), 'utf8')
+            try {
+              mkdirSync(dirname(destination), { recursive: true })
+              writeFileSync(destination, rewriteAlias(source, targetAlias), 'utf8')
+            } catch (error) {
+              writeFailure(error, label)
+            }
           }
           written.add(label)
         } else {
@@ -711,27 +788,32 @@ async function commandAdd({ positional, flags }) {
       }
     }
 
-    ok(`${written.size} fichier(s) ${dryRun ? '[dry-run] auraient été copiés' : 'copié(s)'} :`)
+    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} fichier(s) déjà présent(s), ignoré(s) : ${skipped.join(', ')} (–force pour écraser)`)
+      info(`${skipped.length} file(s) already present, skipped: ${skipped.join(', ')} (use --force to overwrite)`)
     }
 
     // 3. Tokens Tailwind : les classes bg-primary & co fonctionnent partout.
     writeTheme({ cwd, accent, radius, dryRun })
 
-    // 4. Utilisation du composant, après installation.
+    // 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 })
+      pageTarget = await chooseUsageTarget({
+        prompter,
+        cwd,
+        names,
+        exportNames: components.map((component) => component.exportName),
+      })
     }
     if (pageTarget) writeUsage({ cwd, target: pageTarget, componentsDir, components, dryRun })
 
     if (written.size > 0 || dryRun) {
-      console.log('\n  Dépendances npm détectées :')
+      console.log('\n  Detected npm dependencies:')
       info(`npm install ${[...deps].sort().join(' ')}`)
       if (targetAlias !== '@') {
-        info(`Pense à aligner l'alias ${targetAlias} dans ton tsconfig/vite (remplace de @/).`)
+        info(`Remember to align the ${targetAlias} alias in your tsconfig/vite (instead of @/).`)
       }
       console.log('')
     }
@@ -741,37 +823,38 @@ async function commandAdd({ positional, flags }) {
 }
 
 /* -------------------------------------------------------------------------- */
-/* 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>     couleur primaire, écrite dans les tokens Tailwind (@theme)
-  --radius <px>     arrondi global (0–24) dans uifolio-theme.css
-  --page <chemin>   fichier où utiliser le composant (ex : src/pages/calendar.tsx) ;
-                    créé s'il n'existe pas, sinon l'import + <Composant /> y sont ajoutés
-  --interactive     force les questions (dossier, fichier) hors terminal
-  --force           écrase les fichiers existants
-  --dry-run         simule sans écrire
-
-Sans --dir ni --page, la CLI demande dans quel dossier copier les composants
-puis dans quel fichier les utiliser — l'installation ne s'arrête pas à la copie.
-Les couleurs passent par un thème Tailwind CSS 4 (uifolio-theme.css, @theme) :
-les classes bg-primary, text-muted-foreground… restent dans le code.
-
-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 calendar --page src/pages/calendar.tsx
 `)