projxo 1.0.0 → 1.0.2

package/index.js

@@ -6,8 +6,8 @@
  * Entry point for the CLI application
  * This file should remain minimal, with all logic in src/cli.js
  * 
- * @author Your Name
- * @version 1.0.0
+ * @author Sasanga Chathumal
+ * @version 1.0.1
  */
 
 // Import the main CLI function

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projxo",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Cross-platform CLI tool to quickly create React, Next.js, Angular, and React Native projects with automatic IDE integration",
   "main": "index.js",
   "bin": {
@@ -44,6 +44,7 @@
   "homepage": "https://github.com/sasangachathumal/ProjXO#readme",
   "files": [
     "index.js",
+    "src/**/*",
     "README.md",
     "LICENSE"
   ],

package/src/cli.js

@@ -0,0 +1,173 @@
+/**
+ * Main CLI orchestration
+ * Coordinates the project creation workflow
+ */
+
+const inquirer = require('inquirer');
+const logger = require('./utils/logger');
+const { pathExists } = require('./utils/fileSystem');
+const { getProjectType } = require('./config/projectTypes');
+const {
+  getProjectTypePrompt,
+  getProjectNamePrompt,
+  getDirectoryPrompt,
+  getIDEPrompt,
+  getOverwritePrompt
+} = require('./prompts/questions');
+const { 
+  createProject, 
+  displaySuccessMessage,
+  validateProjectParams 
+} = require('./handlers/projectCreator');
+const { openInIDE } = require('./handlers/ideOpener');
+
+/**
+ * Main CLI function
+ * Orchestrates the entire project creation flow
+ */
+async function run() {
+  try {
+    // Display welcome banner
+    displayBanner();
+
+    // Get user inputs through prompts
+    const answers = await getUserInputs();
+
+    // Validate inputs
+    const validation = validateProjectParams(answers);
+    if (!validation.valid) {
+      logger.error(validation.error);
+      process.exit(1);
+    }
+
+    // Check if project exists and handle overwrite
+    const shouldProceed = await handleExistingProject(answers);
+    if (!shouldProceed) {
+      logger.warning('Operation cancelled');
+      process.exit(0);
+    }
+
+    // Create the project
+    const projectPath = await createProject({
+      projectType: answers.projectType,
+      projectName: answers.projectName,
+      directory: answers.directory
+    });
+
+    // Display success message
+    displaySuccessMessage(projectPath, answers.projectType);
+
+    // Open in IDE if selected
+    if (answers.selectedIDE !== 'skip') {
+      await openInIDE(projectPath, answers.selectedIDE);
+    }
+
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+/**
+ * Display welcome banner
+ */
+function displayBanner() {
+  logger.newLine();
+  logger.log('═══════════════════════════════════════════════════', 'bright');
+  logger.log('   ProjXO - Quick Project Setup', 'brightCyan');
+  logger.log('═══════════════════════════════════════════════════', 'bright');
+  logger.newLine();
+}
+
+/**
+ * Get user inputs through interactive prompts
+ * @returns {Promise<Object>} User answers
+ */
+async function getUserInputs() {
+  const defaultDirectory = process.cwd();
+
+  // Get project type
+  const { projectType } = await inquirer.prompt([getProjectTypePrompt()]);
+  
+  const config = getProjectType(projectType);
+  logger.success(`Selected: ${config.name}`);
+  logger.newLine();
+
+  // Get project name
+  const { projectName } = await inquirer.prompt([getProjectNamePrompt()]);
+
+  // Get directory
+  const { directory } = await inquirer.prompt([getDirectoryPrompt(defaultDirectory)]);
+
+  // Get IDE choice
+  const { selectedIDE } = await inquirer.prompt([getIDEPrompt()]);
+
+  return {
+    projectType,
+    projectName,
+    directory,
+    selectedIDE
+  };
+}
+
+/**
+ * Handle existing project scenario
+ * @param {Object} answers - User answers containing projectName and directory
+ * @returns {Promise<boolean>} True if should proceed, false if cancelled
+ */
+async function handleExistingProject({ projectName, directory }) {
+  const { expandHomePath, getProjectPath } = require('./utils/fileSystem');
+  const expandedDir = expandHomePath(directory);
+  const fullPath = getProjectPath(expandedDir, projectName);
+
+  if (pathExists(fullPath)) {
+    logger.warning(`Project "${projectName}" already exists at: ${fullPath}`);
+    
+    const { overwrite } = await inquirer.prompt([getOverwritePrompt(projectName)]);
+    
+    if (!overwrite) {
+      return false;
+    }
+    
+    logger.info('Proceeding with overwrite...');
+  }
+
+  return true;
+}
+
+/**
+ * Handle errors gracefully
+ * @param {Error} error - Error object
+ */
+function handleError(error) {
+  logger.newLine();
+  
+  if (error.isTtyError) {
+    logger.error('Prompt could not be rendered in this environment');
+    logger.info('Please ensure you are running in an interactive terminal');
+  } else if (error.message === 'PROJECT_EXISTS') {
+    // This shouldn't happen as we handle it, but just in case
+    logger.error('Project already exists');
+  } else {
+    logger.error(`An error occurred: ${error.message}`);
+    
+    // Show stack trace in debug mode
+    if (process.env.DEBUG) {
+      console.error(error);
+    }
+  }
+  
+  logger.newLine();
+  process.exit(1);
+}
+
+/**
+ * Handle graceful shutdown on SIGINT (Ctrl+C)
+ */
+process.on('SIGINT', () => {
+  logger.newLine();
+  logger.warning('Operation cancelled by user');
+  logger.newLine();
+  process.exit(0);
+});
+
+module.exports = { run };

package/src/config/ides.js

@@ -0,0 +1,129 @@
+/**
+ * IDE/Editor configurations
+ * Defines supported IDEs and their command-line commands
+ * 
+ * To add a new IDE:
+ * 1. Add a new key to IDES object
+ * 2. Specify name and command
+ * 3. Optionally add installation instructions in getIDEInstallInstructions
+ */
+
+/**
+ * IDE configuration object
+ * @typedef {Object} IDEConfig
+ * @property {string} name - Display name for the IDE
+ * @property {string|null} command - Command-line command to open IDE (null for 'skip')
+ * @property {string} [description] - Optional description
+ */
+
+const IDES = {
+  'vscode': {
+    name: 'VS Code',
+    command: 'code',
+    description: 'Visual Studio Code'
+  },
+  
+  'cursor': {
+    name: 'Cursor',
+    command: 'cursor',
+    description: 'Cursor AI Editor'
+  },
+  
+  'webstorm': {
+    name: 'WebStorm',
+    command: 'webstorm',
+    description: 'JetBrains WebStorm IDE'
+  },
+  
+  'idea': {
+    name: 'IntelliJ IDEA',
+    command: 'idea',
+    description: 'JetBrains IntelliJ IDEA'
+  },
+  
+  'sublime': {
+    name: 'Sublime Text',
+    command: 'subl',
+    description: 'Sublime Text Editor'
+  },
+  
+  'atom': {
+    name: 'Atom',
+    command: 'atom',
+    description: 'GitHub Atom Editor'
+  },
+  
+  'skip': {
+    name: 'Skip (open manually)',
+    command: null,
+    description: 'Do not open in any IDE'
+  }
+};
+
+/**
+ * Get IDE configuration
+ * @param {string} ideKey - IDE key
+ * @returns {IDEConfig|null} Configuration object or null if not found
+ */
+function getIDE(ideKey) {
+  return IDES[ideKey] || null;
+}
+
+/**
+ * Get all IDEs as an array
+ * @returns {Array<{key: string, config: IDEConfig}>}
+ */
+function getAllIDEs() {
+  return Object.entries(IDES).map(([key, config]) => ({
+    key,
+    config
+  }));
+}
+
+/**
+ * Get formatted choices for inquirer prompts
+ * @returns {Array<{name: string, value: string}>}
+ */
+function getIDEChoices() {
+  return Object.entries(IDES).map(([key, config]) => ({
+    name: config.name,
+    value: key,
+    short: config.name
+  }));
+}
+
+/**
+ * Check if an IDE key is valid
+ * @param {string} ideKey - IDE key to check
+ * @returns {boolean}
+ */
+function isValidIDE(ideKey) {
+  return ideKey in IDES;
+}
+
+/**
+ * Get installation instructions for an IDE command
+ * @param {string} ideKey - IDE key
+ * @returns {string} Installation instructions
+ */
+function getIDEInstallInstructions(ideKey) {
+  const instructions = {
+    'vscode': 'Install "Shell Command: Install \'code\' command in PATH" from Command Palette (Cmd/Ctrl+Shift+P)',
+    'cursor': 'Cursor command is usually available after installation',
+    'webstorm': 'Enable in WebStorm: Tools → Create Command-line Launcher',
+    'idea': 'Enable in IntelliJ IDEA: Tools → Create Command-line Launcher',
+    'sublime': 'Create symlink: ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl',
+    'atom': 'Install shell commands from Atom: Atom → Install Shell Commands'
+  };
+  
+  return instructions[ideKey] || 'Please refer to your IDE\'s documentation for command-line setup';
+}
+
+module.exports = {
+  IDES,
+  getIDE,
+  getAllIDEs,
+  getIDEChoices,
+  isValidIDE,
+  getIDEInstallInstructions
+};

package/src/config/projectTypes.js

@@ -0,0 +1,145 @@
+/**
+ * Project type configurations
+ * Defines all supported project types and their creation commands
+ * 
+ * To add a new project type:
+ * 1. Add a new key to PROJECT_TYPES object
+ * 2. Specify name, command, getArgs function, and postInstall flag
+ * 3. Add corresponding help text to getNextSteps function
+ */
+
+/**
+ * Project type configuration object
+ * @typedef {Object} ProjectTypeConfig
+ * @property {string} name - Display name for the project type
+ * @property {string} command - Command to execute (npm, npx, etc.)
+ * @property {Function} getArgs - Function that returns command arguments
+ * @property {boolean} postInstall - Whether to run npm install after creation
+ * @property {string} [description] - Optional description
+ */
+
+const PROJECT_TYPES = {
+  'react-vite': {
+    name: 'React + Vite',
+    description: 'React with Vite bundler (JavaScript)',
+    command: 'npm',
+    getArgs: (name) => ['create', 'vite@latest', name, '--', '--template', 'react'],
+    postInstall: true
+  },
+  
+  'react-vite-ts': {
+    name: 'React + Vite (TypeScript)',
+    description: 'React with Vite bundler and TypeScript',
+    command: 'npm',
+    getArgs: (name) => ['create', 'vite@latest', name, '--', '--template', 'react-ts'],
+    postInstall: true
+  },
+  
+  'nextjs': {
+    name: 'Next.js',
+    description: 'React framework for production',
+    command: 'npx',
+    getArgs: (name) => ['create-next-app@latest', name],
+    postInstall: false // create-next-app already installs dependencies
+  },
+  
+  'angular': {
+    name: 'Angular',
+    description: 'Platform for building web applications',
+    command: 'npx',
+    getArgs: (name) => ['@angular/cli@latest', 'new', name],
+    postInstall: false // Angular CLI already installs dependencies
+  },
+  
+  'react-native': {
+    name: 'React Native (Expo)',
+    description: 'Build native mobile apps with React',
+    command: 'npx',
+    getArgs: (name) => ['create-expo-app', name],
+    postInstall: false // Expo already installs dependencies
+  }
+};
+
+/**
+ * Get project type configuration
+ * @param {string} typeKey - Project type key
+ * @returns {ProjectTypeConfig|null} Configuration object or null if not found
+ */
+function getProjectType(typeKey) {
+  return PROJECT_TYPES[typeKey] || null;
+}
+
+/**
+ * Get all project types as an array
+ * @returns {Array<{key: string, config: ProjectTypeConfig}>}
+ */
+function getAllProjectTypes() {
+  return Object.entries(PROJECT_TYPES).map(([key, config]) => ({
+    key,
+    config
+  }));
+}
+
+/**
+ * Get formatted choices for inquirer prompts
+ * @returns {Array<{name: string, value: string}>}
+ */
+function getProjectTypeChoices() {
+  return Object.entries(PROJECT_TYPES).map(([key, config]) => ({
+    name: `${config.name} (${key})`,
+    value: key,
+    short: config.name
+  }));
+}
+
+/**
+ * Get next steps instructions based on project type
+ * @param {string} typeKey - Project type key
+ * @param {string} projectPath - Full path to the project
+ * @returns {string[]} Array of instruction strings
+ */
+function getNextSteps(typeKey, projectPath) {
+  const steps = [`cd ${projectPath}`];
+  
+  switch (typeKey) {
+    case 'react-vite':
+    case 'react-vite-ts':
+      steps.push('npm run dev');
+      break;
+      
+    case 'nextjs':
+      steps.push('npm run dev');
+      break;
+      
+    case 'angular':
+      steps.push('ng serve');
+      break;
+      
+    case 'react-native':
+      steps.push('npx expo start');
+      break;
+      
+    default:
+      steps.push('npm start');
+  }
+  
+  return steps;
+}
+
+/**
+ * Check if a project type exists
+ * @param {string} typeKey - Project type key to check
+ * @returns {boolean}
+ */
+function isValidProjectType(typeKey) {
+  return typeKey in PROJECT_TYPES;
+}
+
+module.exports = {
+  PROJECT_TYPES,
+  getProjectType,
+  getAllProjectTypes,
+  getProjectTypeChoices,
+  getNextSteps,
+  isValidProjectType
+};

package/src/handlers/ideOpener.js

@@ -0,0 +1,73 @@
+/**
+ * IDE opener handler
+ * Handles opening projects in various IDEs
+ */
+
+const { runCommand } = require('../utils/command');
+const { getIDE, getIDEInstallInstructions } = require('../config/ides');
+const logger = require('../utils/logger');
+
+/**
+ * Open a project in the specified IDE
+ * @param {string} projectPath - Full path to the project
+ * @param {string} ideKey - IDE key (e.g., 'vscode', 'cursor')
+ * @returns {Promise<boolean>} True if opened successfully, false otherwise
+ */
+async function openInIDE(projectPath, ideKey) {
+  // Get IDE configuration
+  const ide = getIDE(ideKey);
+  
+  // Skip if no IDE selected or invalid IDE
+  if (!ide || !ide.command) {
+    return false;
+  }
+
+  try {
+    logger.info(`Opening project in ${ide.name}...`);
+    
+    // Execute IDE command with project path
+    await runCommand(ide.command, [projectPath]);
+    
+    logger.success(`Project opened in ${ide.name}`);
+    return true;
+    
+  } catch (error) {
+    // Handle IDE command failure
+    logger.error(`Could not open ${ide.name}`);
+    logger.warning(`Please ensure ${ide.name} is installed and command-line tools are enabled`);
+    
+    // Provide installation instructions
+    const instructions = getIDEInstallInstructions(ideKey);
+    logger.log(`\n  Setup: ${instructions}`, 'dim');
+    
+    // Provide fallback option
+    logger.log(`  Or manually open: ${projectPath}`, 'yellow');
+    
+    return false;
+  }
+}
+
+/**
+ * Validate if IDE command is available
+ * @param {string} ideKey - IDE key to validate
+ * @returns {Promise<boolean>} True if command is available
+ */
+async function validateIDECommand(ideKey) {
+  const ide = getIDE(ideKey);
+  
+  if (!ide || !ide.command) {
+    return true; // Skip validation for 'skip' option
+  }
+
+  try {
+    const { commandExists } = require('../utils/command');
+    return await commandExists(ide.command);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  openInIDE,
+  validateIDECommand
+};

package/src/handlers/projectCreator.js

@@ -0,0 +1,133 @@
+/**
+ * Project creator handler
+ * Handles the project creation process
+ */
+
+const { runCommand } = require('../utils/command');
+const { 
+  expandHomePath, 
+  ensureDirectory, 
+  pathExists, 
+  getProjectPath 
+} = require('../utils/fileSystem');
+const { getProjectType, getNextSteps } = require('../config/projectTypes');
+const logger = require('../utils/logger');
+
+/**
+ * Create a new project
+ * @param {Object} options - Project creation options
+ * @param {string} options.projectType - Project type key
+ * @param {string} options.projectName - Name of the project
+ * @param {string} options.directory - Directory path where project will be created
+ * @returns {Promise<string>} Full path to the created project
+ * @throws {Error} If project creation fails
+ */
+async function createProject({ projectType, projectName, directory }) {
+  // Get project type configuration
+  const config = getProjectType(projectType);
+  
+  if (!config) {
+    throw new Error(`Invalid project type: ${projectType}`);
+  }
+
+  // Expand home directory and ensure directory exists
+  const expandedDir = expandHomePath(directory);
+  ensureDirectory(expandedDir);
+
+  // Get full project path
+  const fullPath = getProjectPath(expandedDir, projectName);
+
+  // Check if project already exists
+  if (pathExists(fullPath)) {
+    throw new Error('PROJECT_EXISTS');
+  }
+
+  // Display creation start message
+  logger.section('Starting project creation...');
+
+  try {
+    // Execute project creation command in the target directory
+    await runCommand(
+      config.command,
+      config.getArgs(projectName),
+      expandedDir
+    );
+
+    // Run post-install if needed
+    if (config.postInstall) {
+      logger.info('Installing dependencies...');
+      await runCommand('npm', ['install'], fullPath);
+    }
+
+    return fullPath;
+    
+  } catch (error) {
+    // Provide helpful error message
+    throw new Error(`Failed to create project: ${error.message}`);
+  }
+}
+
+/**
+ * Display project creation success message with next steps
+ * @param {string} projectPath - Full path to the created project
+ * @param {string} projectType - Project type key
+ */
+function displaySuccessMessage(projectPath, projectType) {
+  logger.section('✓ Project created successfully!');
+
+  logger.log('Project location:', 'bright');
+  logger.log(`  ${projectPath}`, 'cyan');
+  
+  logger.newLine();
+  logger.log('Next steps:', 'bright');
+  
+  const steps = getNextSteps(projectType, projectPath);
+  steps.forEach(step => {
+    logger.log(`  ${step}`, 'green');
+  });
+  
+  logger.newLine();
+}
+
+/**
+ * Validate project creation parameters
+ * @param {Object} params - Parameters to validate
+ * @param {string} params.projectType - Project type key
+ * @param {string} params.projectName - Project name
+ * @param {string} params.directory - Directory path
+ * @returns {Object} { valid: boolean, error?: string }
+ */
+function validateProjectParams({ projectType, projectName, directory }) {
+  // Validate project type
+  const config = getProjectType(projectType);
+  if (!config) {
+    return {
+      valid: false,
+      error: `Invalid project type: ${projectType}`
+    };
+  }
+
+  // Validate project name
+  if (!projectName || projectName.trim() === '') {
+    return {
+      valid: false,
+      error: 'Project name is required'
+    };
+  }
+
+  // Validate directory
+  if (!directory || directory.trim() === '') {
+    return {
+      valid: false,
+      error: 'Directory is required'
+    };
+  }
+
+  return { valid: true };
+}
+
+module.exports = {
+  createProject,
+  displaySuccessMessage,
+  validateProjectParams
+};

package/src/prompts/questions.js

@@ -0,0 +1,105 @@
+/**
+ * Inquirer prompt definitions
+ * Centralizes all user prompts for consistency
+ */
+
+const { getProjectTypeChoices } = require('../config/projectTypes');
+const { getIDEChoices } = require('../config/ides');
+const { validateProjectName } = require('../utils/fileSystem');
+
+/**
+ * Get project type selection prompt
+ * @returns {Object} Inquirer prompt configuration
+ */
+function getProjectTypePrompt() {
+  return {
+    type: 'list',
+    name: 'projectType',
+    message: 'Select project type:',
+    choices: getProjectTypeChoices(),
+    pageSize: 10
+  };
+}
+
+/**
+ * Get project name input prompt
+ * @returns {Object} Inquirer prompt configuration
+ */
+function getProjectNamePrompt() {
+  return {
+    type: 'input',
+    name: 'projectName',
+    message: 'Enter project name:',
+    validate: (input) => {
+      const result = validateProjectName(input);
+      return result.valid ? true : result.error;
+    },
+    filter: (input) => input.trim() // Remove leading/trailing whitespace
+  };
+}
+
+/**
+ * Get directory path input prompt
+ * @param {string} defaultPath - Default directory path
+ * @returns {Object} Inquirer prompt configuration
+ */
+function getDirectoryPrompt(defaultPath) {
+  return {
+    type: 'input',
+    name: 'directory',
+    message: 'Enter directory path:',
+    default: defaultPath,
+    filter: (input) => input.trim()
+  };
+}
+
+/**
+ * Get IDE selection prompt
+ * @returns {Object} Inquirer prompt configuration
+ */
+function getIDEPrompt() {
+  return {
+    type: 'list',
+    name: 'selectedIDE',
+    message: 'Select IDE to open:',
+    choices: getIDEChoices(),
+    pageSize: 10
+  };
+}
+
+/**
+ * Get overwrite confirmation prompt
+ * @param {string} projectName - Name of the project that already exists
+ * @returns {Object} Inquirer prompt configuration
+ */
+function getOverwritePrompt(projectName) {
+  return {
+    type: 'confirm',
+    name: 'overwrite',
+    message: `Project "${projectName}" already exists. Overwrite?`,
+    default: false
+  };
+}
+
+/**
+ * Get all prompts for project creation flow
+ * @param {string} defaultDirectory - Default directory path
+ * @returns {Array<Object>} Array of prompt configurations
+ */
+function getProjectCreationPrompts(defaultDirectory) {
+  return [
+    getProjectTypePrompt(),
+    getProjectNamePrompt(),
+    getDirectoryPrompt(defaultDirectory),
+    getIDEPrompt()
+  ];
+}
+
+module.exports = {
+  getProjectTypePrompt,
+  getProjectNamePrompt,
+  getDirectoryPrompt,
+  getIDEPrompt,
+  getOverwritePrompt,
+  getProjectCreationPrompts
+};

package/src/utils/command.js

@@ -0,0 +1,64 @@
+/**
+ * Command execution utility
+ * Handles spawning child processes and command execution
+ */
+
+const { spawn } = require('child_process');
+const logger = require('./logger');
+
+/**
+ * Execute a shell command
+ * @param {string} command - Command to execute (e.g., 'npm', 'npx')
+ * @param {string[]} args - Array of command arguments
+ * @param {string} [cwd] - Working directory for command execution
+ * @returns {Promise<void>} Resolves when command completes successfully
+ * @throws {Error} If command exits with non-zero code
+ */
+function runCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    // Log the command being executed for debugging
+    logger.log(`\nExecuting: ${command} ${args.join(' ')}`, 'cyan');
+    
+    // Spawn the process
+    const proc = spawn(command, args, {
+      stdio: 'inherit', // Pipe stdin, stdout, stderr to parent process
+      shell: true,      // Use shell for command execution
+      cwd: cwd || process.cwd() // Use provided cwd or current directory
+    });
+
+    // Handle process completion
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with exit code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+
+    // Handle process errors (e.g., command not found)
+    proc.on('error', (err) => {
+      reject(new Error(`Failed to execute command: ${err.message}`));
+    });
+  });
+}
+
+/**
+ * Check if a command exists in the system PATH
+ * @param {string} command - Command to check
+ * @returns {Promise<boolean>} True if command exists
+ */
+async function commandExists(command) {
+  const checkCmd = process.platform === 'win32' ? 'where' : 'which';
+  
+  try {
+    await runCommand(checkCmd, [command], process.cwd());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  runCommand,
+  commandExists
+};

package/src/utils/fileSystem.js

@@ -0,0 +1,147 @@
+/**
+ * File system utility functions
+ * Handles all file and directory operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const logger = require('./logger');
+
+/**
+ * Expand tilde (~) in path to home directory
+ * @param {string} filePath - Path that may contain ~
+ * @returns {string} Expanded absolute path
+ * @example
+ * expandHomePath('~/Documents') // -> '/Users/username/Documents'
+ */
+function expandHomePath(filePath) {
+  if (filePath.startsWith('~')) {
+    return filePath.replace('~', os.homedir());
+  }
+  return filePath;
+}
+
+/**
+ * Ensure a directory exists, create if it doesn't
+ * @param {string} dirPath - Directory path to ensure
+ * @returns {boolean} True if directory was created, false if already existed
+ */
+function ensureDirectory(dirPath) {
+  const expandedPath = expandHomePath(dirPath);
+  
+  if (!fs.existsSync(expandedPath)) {
+    fs.mkdirSync(expandedPath, { recursive: true });
+    logger.success(`Created directory: ${expandedPath}`);
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if a path exists
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if path exists
+ */
+function pathExists(filePath) {
+  return fs.existsSync(expandHomePath(filePath));
+}
+
+/**
+ * Check if a path is a directory
+ * @param {string} dirPath - Path to check
+ * @returns {boolean} True if path exists and is a directory
+ */
+function isDirectory(dirPath) {
+  try {
+    const stats = fs.statSync(expandHomePath(dirPath));
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the full absolute path
+ * @param {string} dirPath - Directory path
+ * @param {string} projectName - Project name
+ * @returns {string} Full project path
+ */
+function getProjectPath(dirPath, projectName) {
+  const expandedDir = expandHomePath(dirPath);
+  return path.join(expandedDir, projectName);
+}
+
+/**
+ * Validate directory path
+ * @param {string} dirPath - Directory path to validate
+ * @returns {Object} { valid: boolean, error?: string }
+ */
+function validateDirectoryPath(dirPath) {
+  const expandedPath = expandHomePath(dirPath);
+  
+  // Check if path contains invalid characters
+  const invalidChars = /[<>:"|?*]/;
+  if (invalidChars.test(expandedPath)) {
+    return {
+      valid: false,
+      error: 'Path contains invalid characters'
+    };
+  }
+  
+  // Check if parent directory exists (if path doesn't exist)
+  if (!pathExists(expandedPath)) {
+    const parentDir = path.dirname(expandedPath);
+    if (!pathExists(parentDir)) {
+      return {
+        valid: false,
+        error: 'Parent directory does not exist'
+      };
+    }
+  }
+  
+  return { valid: true };
+}
+
+/**
+ * Validate project name
+ * @param {string} projectName - Project name to validate
+ * @returns {Object} { valid: boolean, error?: string }
+ */
+function validateProjectName(projectName) {
+  if (!projectName || !projectName.trim()) {
+    return {
+      valid: false,
+      error: 'Project name cannot be empty'
+    };
+  }
+  
+  // Allow letters, numbers, hyphens, underscores, dots
+  if (!/^[a-zA-Z0-9-_.]+$/.test(projectName)) {
+    return {
+      valid: false,
+      error: 'Project name can only contain letters, numbers, hyphens, underscores, and dots'
+    };
+  }
+  
+  // Don't allow names starting with dots or hyphens
+  if (/^[.-]/.test(projectName)) {
+    return {
+      valid: false,
+      error: 'Project name cannot start with a dot or hyphen'
+    };
+  }
+  
+  return { valid: true };
+}
+
+module.exports = {
+  expandHomePath,
+  ensureDirectory,
+  pathExists,
+  isDirectory,
+  getProjectPath,
+  validateDirectoryPath,
+  validateProjectName
+};

package/src/utils/logger.js

@@ -0,0 +1,110 @@
+/**
+ * Logger utility for colored terminal output
+ * Provides consistent formatting across the application
+ */
+
+// ANSI color codes for terminal styling
+const COLORS = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  
+  // Standard colors
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  
+  // Bright colors
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightCyan: '\x1b[96m'
+};
+
+/**
+ * Main logging function
+ * @param {string} message - Message to log
+ * @param {string} color - Color key from COLORS object
+ */
+function log(message, color = 'reset') {
+  const colorCode = COLORS[color] || COLORS.reset;
+  console.log(`${colorCode}${message}${COLORS.reset}`);
+}
+
+/**
+ * Log success message with green checkmark
+ * @param {string} message - Success message
+ */
+function success(message) {
+  log(`✓ ${message}`, 'green');
+}
+
+/**
+ * Log error message with red X
+ * @param {string} message - Error message
+ */
+function error(message) {
+  log(`✗ ${message}`, 'red');
+}
+
+/**
+ * Log warning message with yellow exclamation
+ * @param {string} message - Warning message
+ */
+function warning(message) {
+  log(`⚠ ${message}`, 'yellow');
+}
+
+/**
+ * Log info message with blue icon
+ * @param {string} message - Info message
+ */
+function info(message) {
+  log(`ℹ ${message}`, 'blue');
+}
+
+/**
+ * Log a horizontal separator line
+ * @param {number} length - Length of separator (default: 50)
+ * @param {string} color - Color of separator
+ */
+function separator(length = 50, color = 'bright') {
+  log('='.repeat(length), color);
+}
+
+/**
+ * Log a section header with separators
+ * @param {string} title - Section title
+ */
+function section(title) {
+  console.log(); // Empty line
+  separator();
+  log(title, 'bright');
+  separator();
+  console.log(); // Empty line
+}
+
+/**
+ * Log an empty line
+ */
+function newLine() {
+  console.log();
+}
+
+module.exports = {
+  log,
+  success,
+  error,
+  warning,
+  info,
+  separator,
+  section,
+  newLine,
+  COLORS
+};