initkit 1.1.0

package/src/utils/errorHandler.js

@@ -0,0 +1,275 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs-extra';
+
+
+/**
+ * Custom error class for CLI operations
+ */
+export class CLIError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = 'CLIError';
+    this.code = code;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Error codes for different types of failures
+ */
+export const ERROR_CODES = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  DIRECTORY_EXISTS: 'DIRECTORY_EXISTS',
+  CREATION_FAILED: 'CREATION_FAILED',
+  INSTALL_FAILED: 'INSTALL_FAILED',
+  GIT_INIT_FAILED: 'GIT_INIT_FAILED',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+};
+
+/**
+ * Format and display error messages with helpful context
+ * @param {Error} error - The error object
+ * @param {Object} context - Additional context about the error
+ */
+export function displayError(error, context = {}) {
+  console.log('\n');
+  console.log(chalk.red('╔════════════════════════════════════════════════════════════╗'));
+  console.log(chalk.red('║') + chalk.red.bold('                    ❌ Error                             ') + chalk.red('║'));
+  console.log(chalk.red('╚════════════════════════════════════════════════════════════╝'));
+  console.log('');
+  
+  if (error instanceof CLIError) {
+    console.error(chalk.red.bold('  ' + error.message));
+    
+    // Display error code
+    if (error.code) {
+      console.error(chalk.gray(`\n  Error code: ${error.code}`));
+    }
+
+    // Display additional details
+    if (Object.keys(error.details).length > 0) {
+      console.log(chalk.yellow('\n  📋 Details:'));
+      Object.entries(error.details).forEach(([key, value]) => {
+        console.log(chalk.yellow(`     • ${key}: ${value}`));
+      });
+    }
+
+    // Display helpful suggestions based on error type
+    console.log('');
+    displayErrorSuggestions(error.code, context);
+  } else {
+    console.error(chalk.red.bold('  Unexpected error: ') + chalk.red(error.message));
+    
+    if (process.env.DEBUG) {
+      console.error(chalk.gray('\n  Stack trace:'));
+      console.error(chalk.gray(error.stack));
+    }
+  }
+
+  console.log('\n');
+}
+
+/**
+ * Display helpful suggestions based on error type
+ * @param {string} errorCode - The error code
+ * @param {Object} context - Additional context
+ */
+function displayErrorSuggestions(errorCode, context) {
+  const suggestions = {
+    [ERROR_CODES.VALIDATION_ERROR]: [
+      '💡 Tip: Project names should be lowercase with hyphens (e.g., my-awesome-app)',
+      '💡 Valid characters: letters, numbers, hyphens (-) and underscores (_)',
+      '💡 Spaces are not allowed - use hyphens instead!',
+    ],
+    [ERROR_CODES.DIRECTORY_EXISTS]: [
+      `🤔 Oops! That folder already exists here.`,
+      `💡 Try a different name, or remove the existing one first`,
+      `   Command: rm -rf ${context.projectName || 'project-name'}`,
+    ],
+    [ERROR_CODES.CREATION_FAILED]: [
+      '😕 Hmm, couldn\'t create the project folder.',
+      '💡 Check if you have permission to write here',
+      '💡 Make sure you have enough disk space',
+      '💡 Try running in a different directory',
+    ],
+    [ERROR_CODES.INSTALL_FAILED]: [
+      '📦 Package installation hit a snag!',
+      '💡 Check your internet connection and try again',
+      '💡 You can install packages later with: npm install',
+      '💡 Or use --no-install flag to skip installation',
+    ],
+    [ERROR_CODES.GIT_INIT_FAILED]: [
+      '🔧 Git initialization failed.',
+      '💡 Make sure Git is installed: git --version',
+      '💡 Or skip Git setup with: --no-git flag',
+    ],
+    [ERROR_CODES.PERMISSION_DENIED]: [
+      'You may need elevated permissions to write to this directory',
+      'Try running in a different directory where you have write access',
+    ],
+  };
+
+  const errorSuggestions = suggestions[errorCode];
+  if (errorSuggestions && errorSuggestions.length > 0) {
+    console.log(chalk.cyan('\n   Suggestions:'));
+    errorSuggestions.forEach((suggestion) => {
+      console.log(chalk.cyan(`   • ${suggestion}`));
+    });
+  }
+}
+
+/**
+ * Rollback project creation on failure
+ * @param {string} projectPath - Path to the project directory
+ * @param {Object} options - Rollback options
+ */
+export async function rollbackProject(projectPath, options = {}) {
+  const { verbose = false } = options;
+  
+  if (!projectPath || !fs.existsSync(projectPath)) {
+    return;
+  }
+
+  const spinner = ora({
+    text: 'Cleaning up...',
+    color: 'yellow',
+  }).start();
+
+  try {
+    // Remove the project directory
+    await fs.remove(projectPath);
+    
+    spinner.succeed(chalk.yellow('Cleaned up incomplete project'));
+    
+    if (verbose) {
+      console.log(chalk.gray(`   Removed: ${projectPath}`));
+    }
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to clean up'));
+    
+    if (verbose) {
+      console.error(chalk.gray(`   Error: ${error.message}`));
+      console.log(chalk.yellow(`\n   Please manually remove: ${projectPath}`));
+    }
+  }
+}
+
+/**
+ * Wrap an async operation with error handling and rollback
+ * @param {Function} operation - The async operation to execute
+ * @param {Object} options - Options for error handling
+ * @returns {Promise<any>}
+ */
+export async function withErrorHandling(operation, options = {}) {
+  const {
+    projectPath = null,
+    rollback = true,
+    errorCode = ERROR_CODES.UNKNOWN_ERROR,
+    context = {},
+  } = options;
+
+  try {
+    return await operation();
+  } catch (error) {
+    // Perform rollback if requested
+    if (rollback && projectPath) {
+      await rollbackProject(projectPath, { verbose: true });
+    }
+
+    // Throw a CLI error with proper formatting
+    if (error instanceof CLIError) {
+      throw error;
+    }
+
+    throw new CLIError(
+      error.message || 'An unexpected error occurred',
+      errorCode,
+      { originalError: error.name, ...context }
+    );
+  }
+}
+
+/**
+ * Handle process termination signals gracefully
+ * @param {string} projectPath - Path to clean up on termination
+ */
+export function setupGracefulShutdown(projectPath) {
+  const cleanup = async (signal) => {
+    console.log(chalk.yellow(`\n\nReceived ${signal}. Cleaning up...`));
+    
+    if (projectPath && fs.existsSync(projectPath)) {
+      await rollbackProject(projectPath, { verbose: false });
+    }
+    
+    process.exit(0);
+  };
+
+  // Handle SIGINT (Ctrl+C)
+  process.on('SIGINT', () => cleanup('SIGINT'));
+  
+  // Handle SIGTERM
+  process.on('SIGTERM', () => cleanup('SIGTERM'));
+}
+
+/**
+ * Validate and handle errors for a specific operation
+ * @param {Function} validator - Validation function that returns { valid, errors }
+ * @param {string} errorMessage - Custom error message
+ */
+export function handleValidationError(validator, errorMessage) {
+  const result = validator();
+  
+  if (!result.valid) {
+    const errorDetails = {};
+    Object.entries(result.errors).forEach(([key, errors]) => {
+      errorDetails[key] = errors.join(', ');
+    });
+
+    throw new CLIError(
+      errorMessage,
+      ERROR_CODES.VALIDATION_ERROR,
+      errorDetails
+    );
+  }
+}
+
+/**
+ * Create a safe wrapper for file operations
+ * @param {Function} operation - File operation to wrap
+ * @param {string} operationName - Name of the operation for error messages
+ */
+export async function safeFileOperation(operation, operationName = 'File operation') {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error.code === 'EACCES') {
+      throw new CLIError(
+        `Permission denied: ${operationName}`,
+        ERROR_CODES.PERMISSION_DENIED,
+        { systemError: error.code }
+      );
+    } else if (error.code === 'ENOENT') {
+      throw new CLIError(
+        `Path not found: ${operationName}`,
+        ERROR_CODES.CREATION_FAILED,
+        { systemError: error.code }
+      );
+    } else if (error.code === 'ENOSPC') {
+      throw new CLIError(
+        'Not enough disk space',
+        ERROR_CODES.CREATION_FAILED,
+        { systemError: error.code }
+      );
+    }
+    
+    throw new CLIError(
+      `${operationName} failed: ${error.message}`,
+      ERROR_CODES.CREATION_FAILED,
+      { systemError: error.code || 'UNKNOWN' }
+    );
+  }
+}

package/src/utils/git.js

@@ -0,0 +1,69 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs-extra';
+import path from 'path';
+
+const execAsync = promisify(exec);
+
+/**
+ * Initialize a Git repository and create first commit
+ * 
+ * Performs the following operations:
+ * 1. Runs `git init` to create a new repository
+ * 2. Creates .gitignore file with common patterns (if not exists)
+ * 3. Stages all files with `git add .`
+ * 4. Creates initial commit with message "Initial commit"
+ * 
+ * Note: Catches and warns if Git is not installed or initialization fails.
+ * 
+ * @param {string} projectPath - Absolute path to the project directory
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * await initGit('/path/to/my-project');
+ * // Creates .git directory and initial commit
+ * 
+ * @throws {Error} Logs warning but does not throw - Git init is optional
+ */
+async function initGit(projectPath) {
+  try {
+    // Initialize git repo
+    await execAsync('git init', { cwd: projectPath });
+
+    // Create .gitignore if it doesn't exist
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    if (!(await fs.pathExists(gitignorePath))) {
+      const gitignoreContent = `# Dependencies
+node_modules/
+
+# Environment variables
+.env
+.env.local
+
+# Build outputs
+dist/
+build/
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+`;
+      await fs.writeFile(gitignorePath, gitignoreContent);
+    }
+
+    // Initial commit
+    await execAsync('git add .', { cwd: projectPath });
+    await execAsync('git commit -m "Initial commit"', { cwd: projectPath });
+  } catch (error) {
+    console.warn('Warning: Could not initialize Git repository');
+  }
+}
+
+export { initGit };

package/src/utils/packageManager.js

@@ -0,0 +1,90 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import ora from 'ora';
+import chalk from 'chalk';
+import path from 'path';
+
+const execAsync = promisify(exec);
+
+/**
+ * Install project dependencies using the specified package manager
+ *
+ * Executes the package manager's install command in the project directory.
+ * Shows a spinner during installation and provides helpful error messages
+ * with manual installation instructions if the operation fails.
+ *
+ * @param {string} projectPath - Absolute path to the project directory
+ * @param {string} [packageManager='npm'] - Package manager to use ('npm'|'yarn'|'pnpm'|'bun')
+ * @param {Object} [options={}] - Installation options
+ * @param {boolean} [options.verbose=false] - Show detailed command output
+ *
+ * @returns {Promise<void>}
+ * @throws {Error} If dependency installation fails
+ *
+ * @example
+ * // Basic usage with npm
+ * await installDependencies('/path/to/project');
+ *
+ * @example
+ * // With specific package manager and verbose output
+ * await installDependencies('/path/to/project', 'yarn', { verbose: true });
+ */
+async function installDependencies(projectPath, packageManager = 'npm', options = {}) {
+  const { verbose = false } = options;
+  const spinner = ora(`Installing dependencies with ${packageManager}...`).start();
+
+  try {
+    const installCommand = getInstallCommand(packageManager);
+
+    if (verbose) {
+      spinner.info(chalk.gray(`Running: ${installCommand}`));
+      spinner.start('Installing...');
+    }
+
+    await execAsync(installCommand, {
+      cwd: projectPath,
+      maxBuffer: 1024 * 1024 * 10, // 10MB buffer
+    });
+
+    spinner.succeed(chalk.green('Dependencies installed successfully'));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to install dependencies'));
+    console.log(chalk.yellow('\nYou can install them manually by running:'));
+    console.log(chalk.cyan(`  cd ${path.basename(projectPath)}`));
+    console.log(chalk.cyan(`  ${packageManager} install\n`));
+
+    if (verbose) {
+      console.log(chalk.gray(`Error details: ${error.message}`));
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Get the install command for the specified package manager
+ *
+ * Returns the correct install command syntax for different package managers.
+ * Defaults to 'npm install' if an unknown package manager is specified.
+ *
+ * @param {string} packageManager - Package manager name ('npm'|'yarn'|'pnpm'|'bun')
+ * @returns {string} The complete install command to execute
+ *
+ * @example
+ * getInstallCommand('npm');    // Returns: 'npm install'
+ * getInstallCommand('yarn');   // Returns: 'yarn install'
+ * getInstallCommand('pnpm');   // Returns: 'pnpm install'
+ * getInstallCommand('unknown'); // Returns: 'npm install' (fallback)
+ */
+function getInstallCommand(packageManager) {
+  const commands = {
+    npm: 'npm install',
+    yarn: 'yarn install',
+    pnpm: 'pnpm install',
+    bun: 'bun install',
+  };
+
+  return commands[packageManager] || commands.npm;
+}
+
+export { installDependencies, getInstallCommand };