weloop-kosign 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weloop-kosign",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "CLI tool for installing Weloop UI components",
   "keywords": [
     "weloop",

package/scripts/cli-remote.js

@@ -33,21 +33,43 @@ const { execSync } = require('child_process');
 // CONFIGURATION
 // ============================================================================
 
+/**
+ * Determines the default registry URL to use.
+ * 
+ * Priority:
+ * 1. Local registry directory (if running in the component library project)
+ * 2. Environment variable WELOOP_REGISTRY_URL
+ * 3. Default remote GitLab URL
+ * 
+ * @returns {string} The registry URL or path
+ */
 function getDefaultRegistryUrl() {
   const localRegistryPath = path.join(__dirname, '../registry');
+  
+  // Check if we're running in the component library project itself
   if (fs.existsSync(localRegistryPath) && fs.existsSync(path.join(localRegistryPath, 'index.json'))) {
     return localRegistryPath;
   }
+  
+  // Fall back to environment variable or default remote URL
   return process.env.WELOOP_REGISTRY_URL || 
     'https://gitlab.com/Sophanithchrek/weloop-shadcn-next-app/-/raw/main/registry';
 }
 
 const DEFAULT_REGISTRY_URL = getDefaultRegistryUrl();
 
+// Network timeout constants (in milliseconds)
+const REQUEST_TIMEOUT = 15000;
+const RETRY_DELAY = 1000;
+
 // ============================================================================
-// UTILITIES
+// UTILITIES - Logging and File System Helpers
 // ============================================================================
 
+/**
+ * ANSI color codes for terminal output
+ * Makes the CLI output more readable with colored messages
+ */
 const colors = {
   reset: '\x1b[0m',
   green: '\x1b[32m',
@@ -57,52 +79,98 @@ const colors = {
   cyan: '\x1b[36m',
 };
 
+/**
+ * Logs a message with optional color formatting
+ * @param {string} message - The message to log
+ * @param {string} color - Color name from colors object
+ */
 function log(message, color = 'reset') {
   console.log(`${colors[color]}${message}${colors.reset}`);
 }
 
+/**
+ * Logs an error message in red
+ */
 function error(message) {
   log(`Error: ${message}`, 'red');
 }
 
+/**
+ * Logs a success message in green
+ */
 function success(message) {
   log(message, 'green');
 }
 
+/**
+ * Logs an informational message in blue
+ */
 function info(message) {
   log(message, 'blue');
 }
 
+/**
+ * Logs a warning message in yellow
+ */
 function warn(message) {
   log(`Warning: ${message}`, 'yellow');
 }
 
+/**
+ * Creates a directory if it doesn't exist
+ * Uses recursive option to create parent directories as needed
+ * @param {string} dirPath - Path to the directory
+ */
 function ensureDirectoryExists(dirPath) {
   if (!fs.existsSync(dirPath)) {
     fs.mkdirSync(dirPath, { recursive: true });
   }
 }
 
+/**
+ * Checks if a path is a local file path or a remote URL
+ * @param {string} pathOrUrl - Path or URL to check
+ * @returns {boolean} True if it's a local path, false if it's a URL
+ */
 function isLocalPath(pathOrUrl) {
   return !pathOrUrl.startsWith('http://') && !pathOrUrl.startsWith('https://');
 }
 
 // ============================================================================
-// PACKAGE MANAGEMENT
+// PACKAGE MANAGEMENT - Detecting and Installing Dependencies
 // ============================================================================
 
+/**
+ * Automatically detects which package manager the project is using
+ * 
+ * Detection order:
+ * 1. Check for lock files (most reliable)
+ * 2. Check npm user agent (fallback)
+ * 3. Default to npm
+ * 
+ * @returns {string} Package manager name: 'npm', 'yarn', or 'pnpm'
+ */
 function detectPackageManager() {
+  // Check for lock files first (most reliable indicator)
   if (fs.existsSync(path.join(process.cwd(), 'yarn.lock'))) return 'yarn';
   if (fs.existsSync(path.join(process.cwd(), 'pnpm-lock.yaml'))) return 'pnpm';
   if (fs.existsSync(path.join(process.cwd(), 'package-lock.json'))) return 'npm';
   
+  // Fallback: check npm user agent (set by npm/yarn/pnpm when running)
   const userAgent = process.env.npm_config_user_agent || '';
   if (userAgent.includes('yarn')) return 'yarn';
   if (userAgent.includes('pnpm')) return 'pnpm';
   
+  // Default to npm if we can't detect anything
   return 'npm';
 }
 
+/**
+ * Generates the install command for the given package manager
+ * @param {string} packageManager - 'npm', 'yarn', or 'pnpm'
+ * @param {string[]} packages - Array of package names to install
+ * @returns {string} The install command to run
+ */
 function getInstallCommand(packageManager, packages) {
   const packagesStr = packages.join(' ');
   switch (packageManager) {
@@ -113,36 +181,63 @@ function getInstallCommand(packageManager, packages) {
   }
 }
 
+/**
+ * Checks if a package is already installed in the project
+ * Searches both dependencies and devDependencies
+ * @param {string} packageName - Name of the package to check
+ * @returns {boolean} True if package is installed, false otherwise
+ */
 function checkPackageInstalled(packageName) {
   const packageJsonPath = path.join(process.cwd(), 'package.json');
   if (!fs.existsSync(packageJsonPath)) return false;
   
   try {
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    // Check both dependencies and devDependencies
     const allDeps = { ...packageJson.dependencies, ...packageJson.devDependencies };
     return !!allDeps[packageName];
   } catch (e) {
+    // If we can't read/parse package.json, assume package is not installed
     return false;
   }
 }
 
+/**
+ * Filters out dependencies that are already installed
+ * Handles scoped packages (e.g., @radix-ui/react-button)
+ * @param {string[]} requiredDeps - List of required package names
+ * @returns {string[]} List of packages that need to be installed
+ */
 function getMissingDependencies(requiredDeps) {
   const packageJsonPath = path.join(process.cwd(), 'package.json');
-  if (!fs.existsSync(packageJsonPath)) return requiredDeps;
+  if (!fs.existsSync(packageJsonPath)) {
+    // No package.json means we need to install everything
+    return requiredDeps;
+  }
   
   try {
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
     const allDeps = { ...packageJson.dependencies, ...packageJson.devDependencies };
     
     return requiredDeps.filter(dep => {
+      // For scoped packages like @radix-ui/react-button, also check @radix-ui
       const depName = dep.split('/').slice(0, 2).join('/');
       return !allDeps[dep] && !allDeps[depName];
     });
   } catch (e) {
+    // If we can't parse package.json, assume all deps are missing
     return requiredDeps;
   }
 }
 
+/**
+ * Installs npm packages using the detected package manager
+ * 
+ * For npm: Filters out ERESOLVE peer dependency warnings (common false positives)
+ * For yarn/pnpm: Uses standard execSync
+ * 
+ * @param {string[]} packages - Array of package names to install
+ */
 async function installPackages(packages) {
   if (packages.length === 0) return;
   
@@ -152,7 +247,8 @@ async function installPackages(packages) {
   try {
     const installCmd = getInstallCommand(packageManager, packages);
     
-    // Filter out ERESOLVE peer dependency warnings while keeping errors
+    // npm has noisy ERESOLVE warnings that aren't real errors
+    // We filter these out while keeping actual error messages
     if (packageManager === 'npm') {
       const { spawn } = require('child_process');
       const [cmd, ...args] = installCmd.split(' ');
@@ -167,7 +263,8 @@ async function installPackages(packages) {
         let stderr = '';
         proc.stderr.on('data', (data) => {
           const output = data.toString();
-          // Filter out ERESOLVE warnings but keep actual errors
+          // Filter out ERESOLVE peer dependency warnings (these are usually safe to ignore)
+          // but keep actual error messages visible to the user
           if (!output.includes('ERESOLVE overriding peer dependency') && 
               !output.includes('npm warn ERESOLVE')) {
             process.stderr.write(data);
@@ -177,13 +274,14 @@ async function installPackages(packages) {
         
         proc.on('close', (code) => {
           if (code !== 0) {
-            // Check if it's a real error (not just warnings)
+            // npm sometimes exits with non-zero code due to warnings, not real errors
+            // Check if there's an actual error message (not just ERESOLVE warnings)
             const hasRealError = stderr.includes('npm error') && 
                                  !stderr.match(/npm error.*ERESOLVE/);
             if (hasRealError) {
               reject(new Error(`Installation failed with code ${code}`));
             } else {
-              // Installation succeeded despite warnings
+              // Installation succeeded despite warnings - this is common with peer deps
               resolve();
             }
           } else {
@@ -206,13 +304,22 @@ async function installPackages(packages) {
 }
 
 // ============================================================================
-// FILE OPERATIONS
+// FILE OPERATIONS - Configuration and File Handling
 // ============================================================================
 
+/**
+ * Creates a default components.json configuration file
+ * 
+ * Auto-detects Next.js app directory structure and sets appropriate paths.
+ * This file stores project-specific settings like component paths and aliases.
+ * 
+ * @returns {object} The default configuration object
+ */
 function createDefaultComponentsConfig() {
   const configPath = path.join(process.cwd(), 'components.json');
   
-  // Detect if it's a Next.js app (app directory) or pages directory
+  // Detect Next.js project structure
+  // App Router uses 'app/globals.css', Pages Router uses 'styles/globals.css'
   const hasAppDir = fs.existsSync(path.join(process.cwd(), 'app'));
   const cssPath = hasAppDir ? 'app/globals.css' : 'styles/globals.css';
   
@@ -245,6 +352,12 @@ function createDefaultComponentsConfig() {
   return defaultConfig;
 }
 
+/**
+ * Loads the components.json configuration file
+ * Creates a default one if it doesn't exist
+ * 
+ * @returns {object} The configuration object
+ */
 function loadComponentsConfig() {
   const configPath = path.join(process.cwd(), 'components.json');
   
@@ -257,10 +370,25 @@ function loadComponentsConfig() {
   return JSON.parse(content);
 }
 
+/**
+ * Fetches and parses a JSON file from a local path or remote URL
+ * 
+ * Features:
+ * - Handles local files and remote URLs
+ * - Automatic retry on network errors
+ * - Follows HTTP redirects
+ * - Provides helpful error messages
+ * 
+ * @param {string} urlOrPath - Local file path or remote URL
+ * @param {number} retries - Number of retry attempts (default: 3)
+ * @returns {Promise<object>} Parsed JSON object
+ */
 async function fetchJSON(urlOrPath, retries = 3) {
+  // Handle local file paths
   if (isLocalPath(urlOrPath)) {
     return new Promise((resolve, reject) => {
       try {
+        // Resolve relative paths to absolute
         const fullPath = path.isAbsolute(urlOrPath) 
           ? urlOrPath 
           : path.join(process.cwd(), urlOrPath);
@@ -278,6 +406,7 @@ async function fetchJSON(urlOrPath, retries = 3) {
     });
   }
   
+  // Handle remote URLs
   return new Promise((resolve, reject) => {
     const client = urlOrPath.startsWith('https') ? https : http;
     let timeout;
@@ -287,10 +416,12 @@ async function fetchJSON(urlOrPath, retries = 3) {
       request = client.get(urlOrPath, (res) => {
         clearTimeout(timeout);
         
+        // Handle HTTP redirects (301, 302)
         if (res.statusCode === 302 || res.statusCode === 301) {
           return fetchJSON(res.headers.location, retries).then(resolve).catch(reject);
         }
         
+        // Provide helpful error messages for common HTTP status codes
         if (res.statusCode === 403) {
           reject(new Error(`Access forbidden (403). Repository may be private. Make it public in GitLab/GitHub settings, or use --registry with a public URL.`));
           return;
@@ -306,10 +437,12 @@ async function fetchJSON(urlOrPath, retries = 3) {
           return;
         }
         
+        // Collect response data
         let data = '';
         res.on('data', (chunk) => { data += chunk; });
         res.on('end', () => {
           try {
+            // Check if we got HTML instead of JSON (common when repo is private)
             if (data.trim().startsWith('<')) {
               reject(new Error('Received HTML instead of JSON. Repository may be private or URL incorrect.'));
               return;
@@ -321,36 +454,46 @@ async function fetchJSON(urlOrPath, retries = 3) {
         });
       });
       
+      // Handle network errors with automatic retry
       request.on('error', (err) => {
         clearTimeout(timeout);
         if (retries > 0 && (err.code === 'ECONNRESET' || err.code === 'ETIMEDOUT' || err.code === 'ENOTFOUND')) {
           info(`Connection error, retrying... (${retries} attempts left)`);
           setTimeout(() => {
             fetchJSON(urlOrPath, retries - 1).then(resolve).catch(reject);
-          }, 1000);
+          }, RETRY_DELAY);
         } else {
           reject(new Error(`Network error: ${err.message} (${err.code || 'UNKNOWN'})`));
         }
       });
       
+      // Set request timeout with retry logic
       timeout = setTimeout(() => {
         request.destroy();
         if (retries > 0) {
           info(`Request timeout, retrying... (${retries} attempts left)`);
           setTimeout(() => {
             fetchJSON(urlOrPath, retries - 1).then(resolve).catch(reject);
-          }, 1000);
+          }, RETRY_DELAY);
         } else {
           reject(new Error('Request timeout after multiple attempts'));
         }
-      }, 15000);
+      }, REQUEST_TIMEOUT);
     };
     
     makeRequest();
   });
 }
 
+/**
+ * Fetches text content (like CSS) from a local path or remote URL
+ * Similar to fetchJSON but returns raw text instead of parsing JSON
+ * 
+ * @param {string} urlOrPath - Local file path or remote URL
+ * @returns {Promise<string>} The file content as text
+ */
 async function fetchText(urlOrPath) {
+  // Handle local file paths
   if (isLocalPath(urlOrPath)) {
     if (!fs.existsSync(urlOrPath)) {
       throw new Error(`File not found: ${urlOrPath}`);
@@ -358,15 +501,18 @@ async function fetchText(urlOrPath) {
     return fs.readFileSync(urlOrPath, 'utf-8');
   }
   
+  // Handle remote URLs
   return new Promise((resolve, reject) => {
     const client = urlOrPath.startsWith('https') ? https : http;
     let data = '';
     
     const req = client.get(urlOrPath, (res) => {
+      // Follow redirects
       if (res.statusCode === 302 || res.statusCode === 301) {
         return fetchText(res.headers.location).then(resolve).catch(reject);
       }
       
+      // Handle common HTTP errors
       if (res.statusCode === 403) {
         reject(new Error('Access forbidden - repository may be private'));
         return;
@@ -382,8 +528,10 @@ async function fetchText(urlOrPath) {
         return;
       }
       
+      // Collect response data
       res.on('data', (chunk) => { data += chunk; });
       res.on('end', () => {
+        // Check if we got HTML instead of CSS (common when repo is private)
         if (data.trim().startsWith('<')) {
           reject(new Error('Received HTML instead of CSS'));
           return;
@@ -392,42 +540,70 @@ async function fetchText(urlOrPath) {
       });
     });
     
+    // Handle network errors with automatic retry
     req.on('error', (err) => {
       if (err.code === 'ECONNRESET' || err.code === 'ETIMEDOUT') {
         setTimeout(() => {
           fetchText(urlOrPath).then(resolve).catch(reject);
-        }, 1000);
+        }, RETRY_DELAY);
       } else {
         reject(err);
       }
     });
     
-    req.setTimeout(15000, () => {
+    // Set request timeout
+    req.setTimeout(REQUEST_TIMEOUT, () => {
       req.destroy();
       reject(new Error('Request timeout'));
     });
   });
 }
 
+/**
+ * Resolves the full path/URL for a registry file
+ * Handles both local paths and remote URLs
+ * 
+ * @param {string} baseUrl - Base registry URL or path
+ * @param {string} fileName - Name of the file to resolve
+ * @returns {string} Full path or URL to the file
+ */
 function resolveRegistryPath(baseUrl, fileName) {
   if (isLocalPath(baseUrl)) {
+    // Resolve local paths (absolute or relative)
     const basePath = path.isAbsolute(baseUrl) 
       ? baseUrl 
       : path.join(process.cwd(), baseUrl);
     return path.join(basePath, fileName);
   }
+  // For remote URLs, just append the filename
   return `${baseUrl}/${fileName}`;
 }
 
+/**
+ * Loads a component registry file from the registry
+ * Returns null if component not found (doesn't throw)
+ * 
+ * @param {string} componentName - Name of the component
+ * @param {string} registryBaseUrl - Base URL/path of the registry
+ * @returns {Promise<object|null>} Component registry object or null if not found
+ */
 async function loadRegistry(componentName, registryBaseUrl) {
   try {
     const registryPath = resolveRegistryPath(registryBaseUrl, `${componentName}.json`);
     return await fetchJSON(registryPath);
   } catch (err) {
+    // Component not found - return null instead of throwing
     return null;
   }
 }
 
+/**
+ * Loads the registry index file (lists all available components)
+ * Throws an error if index cannot be loaded
+ * 
+ * @param {string} registryBaseUrl - Base URL/path of the registry
+ * @returns {Promise<object>} Index object containing list of components
+ */
 async function loadIndex(registryBaseUrl) {
   const indexPath = resolveRegistryPath(registryBaseUrl, 'index.json');
   try {
@@ -439,31 +615,47 @@ async function loadIndex(registryBaseUrl) {
 }
 
 // ============================================================================
-// CSS PROCESSING
+// CSS PROCESSING - Style Installation and Formatting
 // ============================================================================
 
+/**
+ * Checks if CSS content contains Weloop design system variables
+ * Used to detect if styles have already been installed
+ * 
+ * @param {string} content - CSS content to check
+ * @returns {boolean} True if Weloop styles are present
+ */
 function hasWeloopStyles(content) {
-  return content.includes('--WLDS-PRM-') || 
-         content.includes('--WLDS-RED-') || 
-         content.includes('--WLDS-NTL-') ||
-         content.includes('--system-100') ||
+  // Check for Weloop-specific CSS variable prefixes
+  return content.includes('--WLDS-PRM-') ||  // Primary colors
+         content.includes('--WLDS-RED-') ||  // Red colors
+         content.includes('--WLDS-NTL-') ||   // Neutral colors
+         content.includes('--system-100') ||  // System colors
          content.includes('--system-200');
 }
 
+/**
+ * Removes duplicate tw-animate-css imports and keeps only one
+ * Ensures the import appears right after tailwindcss import
+ * 
+ * @param {string} cssContent - CSS content to clean
+ * @returns {string} CSS content with duplicates removed
+ */
 function removeDuplicateTwAnimateImports(cssContent) {
   const twAnimatePattern = /@import\s+["']tw-animate-css["'];?\s*\n?/g;
   const matches = cssContent.match(twAnimatePattern);
   
   if (matches && matches.length > 1) {
-    // Remove all occurrences
+    // Remove all occurrences first
     let cleaned = cssContent.replace(twAnimatePattern, '');
-    // Add it back once after tailwindcss import
+    // Add it back once, right after tailwindcss import if it exists
     if (cleaned.includes('@import "tailwindcss"') || cleaned.includes("@import 'tailwindcss'")) {
       cleaned = cleaned.replace(
         /(@import\s+["']tailwindcss["'];?\s*\n?)/,
         '$1@import "tw-animate-css";\n'
       );
     } else {
+      // If no tailwindcss import, add it at the beginning
       cleaned = '@import "tw-animate-css";\n' + cleaned;
     }
     return cleaned;
@@ -472,11 +664,19 @@ function removeDuplicateTwAnimateImports(cssContent) {
   return cssContent;
 }
 
+/**
+ * Removes duplicate @custom-variant declarations
+ * Keeps only one instance at the top
+ * 
+ * @param {string} cssContent - CSS content to clean
+ * @returns {string} CSS content with duplicates removed
+ */
 function removeDuplicateCustomVariant(cssContent) {
   const variantPattern = /@custom-variant\s+dark\s+\(&:is\(\.dark \*\)\);\s*\n?/g;
   const matches = cssContent.match(variantPattern);
 
   if (matches && matches.length > 1) {
+    // Remove all occurrences and add back one at the top
     const withoutVariants = cssContent.replace(variantPattern, '');
     return `@custom-variant dark (&:is(.dark *));\n\n${withoutVariants.trimStart()}`;
   }
@@ -484,11 +684,93 @@ function removeDuplicateCustomVariant(cssContent) {
   return cssContent;
 }
 
+/**
+ * Normalizes CSS format to ensure consistent structure
+ * 
+ * Format order:
+ * 1. @import statements (tailwindcss, then tw-animate-css, then others)
+ * 2. @custom-variant declaration
+ * 3. Rest of the CSS content
+ * 
+ * This ensures the CSS file always has the same structure regardless of
+ * how it was generated or merged.
+ * 
+ * @param {string} cssContent - CSS content to normalize
+ * @returns {string} Normalized CSS content
+ */
+function normalizeCSSFormat(cssContent) {
+  // Extract @custom-variant declaration
+  const variantPattern = /@custom-variant\s+dark\s+\(&:is\(\.dark \*\)\);\s*\n?/g;
+  const variantMatch = cssContent.match(variantPattern);
+  const hasVariant = variantMatch && variantMatch.length > 0;
+  
+  // Extract all @import statements
+  const importPattern = /@import\s+["'][^"']+["'];?\s*\n?/g;
+  const imports = cssContent.match(importPattern) || [];
+  
+  // Separate imports by type for proper ordering
+  const tailwindImport = imports.find(imp => imp.includes('tailwindcss'));
+  const twAnimateImport = imports.find(imp => imp.includes('tw-animate-css'));
+  const otherImports = imports.filter(imp => 
+    !imp.includes('tailwindcss') && !imp.includes('tw-animate-css')
+  );
+  
+  // Remove all imports and variant from content to get the rest
+  let content = cssContent
+    .replace(variantPattern, '')
+    .replace(importPattern, '')
+    .trim();
+  
+  // Build normalized format in the correct order
+  let normalized = '';
+  
+  // Step 1: Imports first (tailwindcss, then tw-animate-css, then others)
+  if (tailwindImport) {
+    normalized += tailwindImport.trim() + '\n';
+  }
+  if (twAnimateImport) {
+    normalized += twAnimateImport.trim() + '\n';
+  }
+  if (otherImports.length > 0) {
+    normalized += otherImports.join('') + '\n';
+  }
+  
+  // Step 2: @custom-variant second (if it exists)
+  if (hasVariant) {
+    if (normalized) {
+      normalized += '\n@custom-variant dark (&:is(.dark *));\n';
+    } else {
+      normalized += '@custom-variant dark (&:is(.dark *));\n';
+    }
+  }
+  
+  // Step 3: Rest of content (theme variables, etc.)
+  if (normalized && content) {
+    normalized += '\n' + content;
+  } else if (content) {
+    normalized = content;
+  }
+  
+  return normalized.trim() + (normalized ? '\n' : '');
+}
+
+/**
+ * Processes tw-animate-css import based on whether the package is installed
+ * 
+ * - If package is NOT installed: Removes the import to prevent build errors
+ * - If package IS installed: Ensures import exists and removes duplicates
+ * 
+ * @param {string} cssContent - CSS content to process
+ * @param {boolean} hasTwAnimate - Whether tw-animate-css package is installed
+ * @param {boolean} forceUpdate - Whether this is a forced update
+ * @returns {string} Processed CSS content
+ */
 function processTwAnimateImport(cssContent, hasTwAnimate, forceUpdate = false) {
   const twAnimatePattern = /@import\s+["']tw-animate-css["'];?\s*\n?/g;
   let processed = cssContent;
   
   if (!hasTwAnimate) {
+    // Package not installed - remove import to prevent build errors
     processed = cssContent.replace(twAnimatePattern, '');
     if (cssContent.includes('tw-animate-css') && !processed.includes('tw-animate-css')) {
       if (forceUpdate) {
@@ -502,10 +784,10 @@ function processTwAnimateImport(cssContent, hasTwAnimate, forceUpdate = false) {
       }
     }
   } else {
-    // Remove any duplicates first
+    // Package is installed - ensure import exists and remove duplicates
     processed = removeDuplicateTwAnimateImports(processed);
     
-    // Ensure import exists if package is installed (only if not already present)
+    // Add import if it doesn't exist (right after tailwindcss if present)
     if (!processed.match(/@import\s+["']tw-animate-css["'];?\s*\n?/)) {
       if (processed.includes('@import "tailwindcss"') || processed.includes("@import 'tailwindcss'")) {
         processed = processed.replace(
@@ -521,10 +803,25 @@ function processTwAnimateImport(cssContent, hasTwAnimate, forceUpdate = false) {
   return processed;
 }
 
+/**
+ * Removes tailwindcss import statements from CSS
+ * Used when merging styles to avoid duplicates
+ * 
+ * @param {string} cssContent - CSS content
+ * @returns {string} CSS content without tailwindcss imports
+ */
 function removeTailwindImport(cssContent) {
   return cssContent.replace(/@import\s+["']tailwindcss["'];?\s*\n?/g, '');
 }
 
+/**
+ * Ensures tw-animate-css import exists if the package is installed
+ * Adds it right after tailwindcss import if present
+ * 
+ * @param {string} cssContent - CSS content
+ * @param {boolean} hasTwAnimate - Whether tw-animate-css package is installed
+ * @returns {string} CSS content with tw-animate-css import ensured
+ */
 function ensureTwAnimateImport(cssContent, hasTwAnimate) {
   if (!hasTwAnimate) {
     return cssContent;
@@ -538,7 +835,7 @@ function ensureTwAnimateImport(cssContent, hasTwAnimate) {
     return cleaned;
   }
   
-  // Add import after tailwindcss if it exists
+  // Add import after tailwindcss if it exists, otherwise at the beginning
   if (cleaned.includes('@import "tailwindcss"') || cleaned.includes("@import 'tailwindcss'")) {
     return cleaned.replace(
       /(@import\s+["']tailwindcss["'];?\s*\n?)/,
@@ -549,21 +846,36 @@ function ensureTwAnimateImport(cssContent, hasTwAnimate) {
   return '@import "tw-animate-css";\n' + cleaned;
 }
 
+/**
+ * Merges Weloop styles with existing CSS that has Tailwind imports
+ * 
+ * Strategy:
+ * - Finds the tailwindcss import in existing CSS
+ * - Inserts Weloop styles right after it
+ * - Handles tw-animate-css import to avoid duplicates
+ * 
+ * @param {string} existing - Existing CSS content
+ * @param {string} weloopStyles - Weloop styles to merge in
+ * @param {boolean} hasTwAnimate - Whether tw-animate-css package is installed
+ * @returns {string} Merged CSS content
+ */
 function mergeCSSWithTailwind(existing, weloopStyles, hasTwAnimate) {
   const tailwindMatch = existing.match(/(@import\s+["']tailwindcss["'];?\s*\n?)/);
   if (!tailwindMatch) {
+    // No tailwindcss import found - just prepend Weloop styles
     return weloopStyles + '\n\n' + existing;
   }
   
+  // Split existing CSS around the tailwindcss import
   const beforeTailwind = existing.substring(0, existing.indexOf(tailwindMatch[0]));
   const afterTailwind = existing.substring(existing.indexOf(tailwindMatch[0]) + tailwindMatch[0].length);
   
-  // Check if tw-animate-css import already exists in existing or weloopStyles
+  // Check if tw-animate-css import already exists
   const hasTwAnimateInExisting = existing.match(/@import\s+["']tw-animate-css["'];?\s*\n?/);
   const hasTwAnimateInWeloop = weloopStyles.match(/@import\s+["']tw-animate-css["'];?\s*\n?/);
   
-  // If the existing file already has the tw-animate import, strip it from the
-  // Weloop styles to avoid duplicating it in the merge output.
+  // If existing file already has tw-animate import, remove it from Weloop styles
+  // to avoid duplicating it in the merge output
   let weloopStylesCleaned = weloopStyles;
   if (hasTwAnimateInExisting && hasTwAnimateInWeloop) {
     weloopStylesCleaned = weloopStyles.replace(
@@ -572,44 +884,75 @@ function mergeCSSWithTailwind(existing, weloopStyles, hasTwAnimate) {
     );
   }
   
+  // Add tw-animate import if needed (package installed but import missing)
   let importsToAdd = '';
   if (hasTwAnimate && !hasTwAnimateInExisting && !hasTwAnimateInWeloop) {
     importsToAdd = '@import "tw-animate-css";\n';
   }
 
+  // Merge: before tailwind + tailwind import + tw-animate (if needed) + Weloop styles + after tailwind
   return beforeTailwind + tailwindMatch[0] + importsToAdd + weloopStylesCleaned + '\n' + afterTailwind;
 }
 
+/**
+ * Replaces existing Weloop styles with new ones
+ * 
+ * Finds where Weloop styles start (usually @theme inline or :root)
+ * and replaces everything from there with the new styles.
+ * Preserves imports that come before the Weloop styles.
+ * 
+ * @param {string} existing - Existing CSS content
+ * @param {string} newStyles - New Weloop styles to replace with
+ * @param {boolean} hasTwAnimate - Whether tw-animate-css package is installed
+ * @returns {string} CSS content with Weloop styles replaced
+ */
 function replaceWeloopStyles(existing, newStyles, hasTwAnimate) {
   const importPattern = /(@import\s+["'][^"']+["'];?\s*\n?)/g;
   const imports = existing.match(importPattern) || [];
   const importsText = imports.join('');
   
+  // Find where Weloop styles start (look for @theme inline or :root)
   const weloopStartPattern = /(@theme\s+inline|:root\s*\{)/;
   const weloopStartMatch = existing.search(weloopStartPattern);
   
   if (weloopStartMatch === -1) {
+    // No existing Weloop styles found - just append
     return existing + '\n\n' + newStyles;
   }
   
+  // Extract content before Weloop styles
   let contentBeforeWeloop = existing.substring(0, weloopStartMatch);
+  // Keep non-Weloop imports (filter out tw-animate if package not installed)
   const nonWeloopImports = importsText.split('\n').filter(imp => 
     !imp.includes('tw-animate-css') || hasTwAnimate
   ).join('\n');
+  // Remove all imports from contentBeforeWeloop (we'll add them back)
   contentBeforeWeloop = nonWeloopImports + '\n' + contentBeforeWeloop.replace(importPattern, '');
   
+  // Return: preserved imports + content before Weloop + new Weloop styles
   return contentBeforeWeloop.trim() + '\n\n' + newStyles.trim();
 }
 
+/**
+ * Fetches the CSS file from the registry
+ * 
+ * For local paths: Looks for app/globals.css relative to registry directory
+ * For remote URLs: Constructs URL by replacing /registry with /app/globals.css
+ * 
+ * @param {string} registryUrl - Registry base URL or path
+ * @returns {Promise<string>} CSS file content
+ */
 async function fetchCSSFromRegistry(registryUrl) {
   let sourceCssPath;
   
   if (isLocalPath(registryUrl)) {
+    // Local path: find app/globals.css relative to registry directory
     const basePath = path.isAbsolute(registryUrl) 
       ? path.dirname(registryUrl) 
       : path.join(process.cwd(), path.dirname(registryUrl));
     sourceCssPath = path.join(basePath, 'app', 'globals.css');
   } else {
+    // Remote URL: replace /registry with /app/globals.css
     const baseUrl = registryUrl.replace('/registry', '');
     sourceCssPath = `${baseUrl}/app/globals.css`;
   }
@@ -617,17 +960,31 @@ async function fetchCSSFromRegistry(registryUrl) {
   return await fetchText(sourceCssPath);
 }
 
+/**
+ * Installs or updates CSS styles from the registry
+ * 
+ * Handles three scenarios:
+ * 1. --overwrite: Replaces entire file
+ * 2. Normal update: Intelligently merges with existing styles
+ * 3. New file: Creates file with Weloop styles
+ * 
+ * @param {object} config - Components configuration object
+ * @param {string} registryUrl - Registry base URL or path
+ * @param {boolean} forceUpdate - Whether to overwrite existing file
+ * @param {boolean} silent - Whether to suppress output messages
+ */
 async function installCSSStyles(config, registryUrl, forceUpdate = false, silent = false) {
   const cssPath = config.tailwind?.css || 'app/globals.css';
   const fullCssPath = path.join(process.cwd(), cssPath);
   
-  // Check if Weloop styles already exist
+  // Check if Weloop styles already exist in the file
   let hasWeloopStylesInFile = false;
   if (fs.existsSync(fullCssPath)) {
     const existingContent = fs.readFileSync(fullCssPath, 'utf-8');
     hasWeloopStylesInFile = hasWeloopStyles(existingContent);
     
-    // If styles already exist and not forcing update, skip silently
+    // If styles already exist and we're not forcing update, skip silently
+    // This prevents unnecessary updates when installing components
     if (hasWeloopStylesInFile && !forceUpdate && silent) {
       return;
     }
@@ -644,10 +1001,13 @@ async function installCSSStyles(config, registryUrl, forceUpdate = false, silent
     const hasTwAnimate = checkPackageInstalled('tw-animate-css');
     let processedCssContent = processTwAnimateImport(cssContent, hasTwAnimate, forceUpdate);
     
-    // Handle file installation
+    // Handle file installation based on mode and existing file state
     if (forceUpdate && fs.existsSync(fullCssPath)) {
-      // --overwrite: Replace entire file
-      fs.writeFileSync(fullCssPath, processedCssContent);
+      // Mode 1: --overwrite flag - Replace entire file with fresh styles
+      let normalized = normalizeCSSFormat(processedCssContent);
+      normalized = removeDuplicateTwAnimateImports(normalized);
+      normalized = removeDuplicateCustomVariant(normalized);
+      fs.writeFileSync(fullCssPath, normalized);
       if (!silent) {
         success(`Overwritten ${cssPath} with Weloop styles`);
         if (hasTwAnimate) {
@@ -655,34 +1015,36 @@ async function installCSSStyles(config, registryUrl, forceUpdate = false, silent
         }
       }
     } else if (fs.existsSync(fullCssPath)) {
-      // Normal mode: Merge intelligently
+      // Mode 2: Normal update - Intelligently merge with existing styles
       const existing = fs.readFileSync(fullCssPath, 'utf-8');
       const hasTailwindImport = existing.includes('@import "tailwindcss"') || 
                                 existing.includes('@tailwind base');
       
       if (hasWeloopStylesInFile) {
-        // Replace existing Weloop styles (only if different)
+        // Case 2a: Weloop styles already exist - replace them with updated versions
         let weloopStyles = removeTailwindImport(processedCssContent);
         weloopStyles = ensureTwAnimateImport(weloopStyles, hasTwAnimate);
         let finalContent = replaceWeloopStyles(existing, weloopStyles, hasTwAnimate);
         finalContent = removeDuplicateTwAnimateImports(finalContent);
         finalContent = removeDuplicateCustomVariant(finalContent);
+        finalContent = normalizeCSSFormat(finalContent);
         
-        // Only update if content actually changed
+        // Only write if content actually changed (prevents unnecessary file updates)
         if (finalContent !== existing) {
           fs.writeFileSync(fullCssPath, finalContent);
           if (!silent) {
             success(`Updated ${cssPath} with Weloop styles`);
           }
         }
-        // If no changes, silently skip
+        // If no changes, silently skip (file is already up to date)
       } else if (hasTailwindImport) {
-        // Merge after Tailwind imports
+        // Case 2b: No Weloop styles but Tailwind exists - merge after Tailwind imports
         let weloopStyles = removeTailwindImport(processedCssContent);
         weloopStyles = ensureTwAnimateImport(weloopStyles, hasTwAnimate);
         let merged = mergeCSSWithTailwind(existing, weloopStyles, hasTwAnimate);
         merged = removeDuplicateTwAnimateImports(merged);
         merged = removeDuplicateCustomVariant(merged);
+        merged = normalizeCSSFormat(merged);
         fs.writeFileSync(fullCssPath, merged);
         if (!silent) {
           success(`Updated ${cssPath} with Weloop styles`);
@@ -692,9 +1054,10 @@ async function installCSSStyles(config, registryUrl, forceUpdate = false, silent
           info(`   Your existing styles are preserved`);
         }
       } else {
-        // No Tailwind imports, prepend everything
+        // Case 2c: No Tailwind imports - prepend Weloop styles to existing content
         let finalCssContent = removeDuplicateTwAnimateImports(processedCssContent);
         
+        // Ensure tw-animate import exists if package is installed
         if (hasTwAnimate && !finalCssContent.match(/@import\s+["']tw-animate-css["'];?\s*\n?/)) {
           if (finalCssContent.includes('@import "tailwindcss"')) {
             finalCssContent = finalCssContent.replace(
@@ -705,7 +1068,9 @@ async function installCSSStyles(config, registryUrl, forceUpdate = false, silent
             finalCssContent = '@import "tailwindcss";\n@import "tw-animate-css";\n' + finalCssContent;
           }
         }
-        fs.writeFileSync(fullCssPath, finalCssContent + '\n\n' + existing);
+        let combined = finalCssContent + '\n\n' + existing;
+        combined = normalizeCSSFormat(combined);
+        fs.writeFileSync(fullCssPath, combined);
         if (!silent) {
           success(`Updated ${cssPath} with Weloop styles`);
           if (hasTwAnimate) {
@@ -714,8 +1079,11 @@ async function installCSSStyles(config, registryUrl, forceUpdate = false, silent
         }
       }
     } else {
-      // Create new file
-      fs.writeFileSync(fullCssPath, processedCssContent);
+      // Mode 3: File doesn't exist - create new file with Weloop styles
+      let normalized = normalizeCSSFormat(processedCssContent);
+      normalized = removeDuplicateTwAnimateImports(normalized);
+      normalized = removeDuplicateCustomVariant(normalized);
+      fs.writeFileSync(fullCssPath, normalized);
       if (!silent) {
         success(`Created ${cssPath} with Weloop styles`);
         if (hasTwAnimate) {
@@ -735,13 +1103,22 @@ async function installCSSStyles(config, registryUrl, forceUpdate = false, silent
 }
 
 // ============================================================================
-// COMPONENT INSTALLATION
+// COMPONENT INSTALLATION - Installing Components from Registry
 // ============================================================================
 
+/**
+ * Creates the utils.ts file if it doesn't exist
+ * 
+ * This file contains the 'cn' utility function used by all components
+ * for merging Tailwind classes. It's required for components to work.
+ * 
+ * @param {string} utilsPath - Path where utils.ts should be created
+ */
 function createUtilsFile(utilsPath) {
   if (fs.existsSync(utilsPath)) return;
   
   // Silently create utils file (matching shadcn/ui behavior)
+  // Don't overwrite if user has customized it
   ensureDirectoryExists(path.dirname(utilsPath));
   
   const utilsContent = `import { clsx, type ClassValue } from "clsx"
@@ -754,10 +1131,27 @@ export function cn(...inputs: ClassValue[]) {
   fs.writeFileSync(utilsPath, utilsContent);
 }
 
+/**
+ * Installs a component from the registry
+ * 
+ * Installation process:
+ * 1. Install base dependencies (clsx, tailwind-merge)
+ * 2. Install tw-animate-css for animations
+ * 3. Install/update CSS styles (silently if already installed)
+ * 4. Install component dependencies (recursive)
+ * 5. Install component files
+ * 6. Create utils.ts if needed
+ * 7. Install npm dependencies
+ * 
+ * @param {string} componentName - Name of the component to install
+ * @param {object} options - Installation options
+ * @param {boolean} options.overwrite - Whether to overwrite existing files
+ * @param {string} options.registryUrl - Registry URL or path
+ */
 async function installComponent(componentName, options = {}) {
   const { overwrite = false, registryUrl = DEFAULT_REGISTRY_URL } = options;
   
-  // Install base dependencies first (required for utils.ts)
+  // Step 1: Install base dependencies (required for utils.ts to work)
   const baseDeps = [];
   if (!checkPackageInstalled('clsx')) {
     baseDeps.push('clsx');
@@ -770,19 +1164,20 @@ async function installComponent(componentName, options = {}) {
     await installPackages(baseDeps);
   }
   
-  // Load or create components.json (after base deps are installed)
+  // Step 2: Load or create components.json configuration
   const config = loadComponentsConfig();
   
-  // Install tw-animate-css automatically (required for animations)
+  // Step 3: Install tw-animate-css automatically (required for component animations)
   if (!checkPackageInstalled('tw-animate-css')) {
     info('Installing tw-animate-css for animations...');
     await installPackages(['tw-animate-css']);
   }
   
-  // Install CSS styles early (before component installation) - silent if already installed
+  // Step 4: Install CSS styles early (before component installation)
+  // Silent mode prevents output when styles are already installed
   await installCSSStyles(config, registryUrl, false, true);
   
-  // Get paths from components.json
+  // Step 5: Resolve paths from components.json configuration
   const uiAlias = config.aliases?.ui || '@/components/ui';
   const utilsAlias = config.aliases?.utils || '@/lib/utils';
   
@@ -793,30 +1188,34 @@ async function installComponent(componentName, options = {}) {
   }
   utilsPath = path.join(process.cwd(), utilsPath);
   
-  // Load component registry
+  // Step 6: Load component registry from remote or local source
   const registry = await loadRegistry(componentName, registryUrl);
   
   if (!registry) {
     error(`Component "${componentName}" not found in registry.`);
     info('Available components:');
     try {
+      // Show available components to help user
       const index = await loadIndex(registryUrl);
       index.registry.forEach(comp => {
         console.log(`  - ${comp.name}`);
       });
     } catch (e) {
-      // Ignore if index fails
+      // Ignore if index fails - we already showed the error
     }
     process.exit(1);
   }
 
-  // Check if component already exists (silently skip if exists, matching shadcn/ui behavior)
+  // Step 7: Check if component already exists
+  // Silently skip if exists (matching shadcn/ui behavior)
+  // Only install if overwrite flag is set
   const componentPath = path.join(componentsDir, `${componentName}.tsx`);
   if (fs.existsSync(componentPath) && !overwrite) {
     return;
   }
 
-  // Install registry dependencies first
+  // Step 8: Install component dependencies first (recursive)
+  // Some components depend on other components (e.g., button-group depends on button)
   if (registry.registryDependencies && registry.registryDependencies.length > 0) {
     info(`Installing dependencies: ${registry.registryDependencies.join(', ')}`);
     for (const dep of registry.registryDependencies) {
@@ -824,7 +1223,8 @@ async function installComponent(componentName, options = {}) {
     }
   }
 
-  // Install component files
+  // Step 9: Install component files
+  // Components can have multiple files (e.g., component + types + styles)
   for (const file of registry.files) {
     const filePath = path.join(process.cwd(), file.path);
     ensureDirectoryExists(path.dirname(filePath));
@@ -832,10 +1232,11 @@ async function installComponent(componentName, options = {}) {
     success(`Installed: ${file.path}`);
   }
 
-  // Create utils.ts if needed
+  // Step 10: Create utils.ts if it doesn't exist
+  // This is required for all components to work
   createUtilsFile(utilsPath);
 
-  // Install npm dependencies
+  // Step 11: Install npm dependencies required by the component
   if (registry.dependencies && registry.dependencies.length > 0) {
     const missingDeps = getMissingDependencies(registry.dependencies);
     if (missingDeps.length > 0) {
@@ -849,15 +1250,22 @@ async function installComponent(componentName, options = {}) {
 }
 
 // ============================================================================
-// COMMANDS
+// COMMANDS - CLI Command Handlers
 // ============================================================================
 
+/**
+ * Lists all available components from the registry
+ * Shows component names and their dependencies
+ * 
+ * @param {string} registryUrl - Registry URL or path
+ */
 async function listComponents(registryUrl = DEFAULT_REGISTRY_URL) {
   try {
     const index = await loadIndex(registryUrl);
     
     console.log('\nAvailable components:\n');
     index.registry.forEach(comp => {
+      // Show dependencies if component has any
       const deps = comp.registryDependencies && comp.registryDependencies.length > 0
         ? ` (depends on: ${comp.registryDependencies.join(', ')})`
         : '';
@@ -871,24 +1279,39 @@ async function listComponents(registryUrl = DEFAULT_REGISTRY_URL) {
 }
 
 // ============================================================================
-// MAIN
+// MAIN - CLI Entry Point
 // ============================================================================
 
+/**
+ * Main CLI entry point
+ * 
+ * Parses command line arguments and routes to appropriate command handler:
+ * - add: Install a component
+ * - list: List available components
+ * - css: Install/update CSS styles
+ * 
+ * Supports options:
+ * - --registry: Custom registry URL or path
+ * - --overwrite / -f: Overwrite existing files
+ */
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
   const componentName = args[1];
   
+  // Parse --registry option if provided
   const registryIndex = args.indexOf('--registry');
   const registryUrl = registryIndex !== -1 && args[registryIndex + 1]
     ? args[registryIndex + 1]
     : DEFAULT_REGISTRY_URL;
   
+  // Build options object
   const options = {
     overwrite: args.includes('--overwrite') || args.includes('-f'),
     registryUrl: registryUrl,
   };
 
+  // Show usage if no command provided
   if (!command) {
     console.log(`
 Usage:
@@ -910,6 +1333,7 @@ Examples:
     process.exit(0);
   }
 
+  // Route to appropriate command handler
   switch (command) {
     case 'add':
       if (!componentName) {
@@ -926,6 +1350,7 @@ Examples:
     
     case 'css':
     case 'styles':
+      // Both 'css' and 'styles' commands do the same thing
       const config = loadComponentsConfig();
       await installCSSStyles(config, registryUrl, options.overwrite, false);
       break;
@@ -937,6 +1362,7 @@ Examples:
   }
 }
 
+// Run main function and handle errors
 main().catch(err => {
   error(`Error: ${err.message}`);
   process.exit(1);