create-mobile-arch 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# create-mobile-arch
+
+A production-ready CLI tool to generate Flutter project architectures with best practices baked in.
+
+## 🚀 Quick Start
+
+Create a new Flutter project with a single command:
+
+```bash
+npx create-mobile-arch my_app
+```
+
+## ✨ Features
+
+- 🏗️ **Multiple Architecture Patterns**: Clean Architecture & Feature-First
+- 📦 **State Management**: Riverpod or Bloc
+- 🔌 **Backend Integration**: Firebase or REST API
+- 📁 **Well-Structured**: Production-ready folder organization
+- 🎨 **Theme Support**: Light & dark mode out of the box
+- 🧪 **Testing Ready**: Example tests included
+- 📝 **Documentation**: README with architecture details
+
+## 📋 Usage
+
+### Basic Usage
+
+```bash
+npx create-mobile-arch <project-name>
+```
+
+### With Default Configuration
+
+Skip prompts and use default settings:
+
+```bash
+npx create-mobile-arch my_app -y
+```
+
+## 🎯 Interactive Configuration
+
+When you run the CLI, you'll be asked to choose:
+
+1. **Architecture Pattern**
+   - Clean Architecture (Domain-driven with layers)
+   - Feature First (Organized by features)
+
+2. **State Management**
+   - Riverpod (Recommended - compile-safe, testable)
+   - Bloc (Event-driven state management)
+
+3. **Backend Integration**
+   - Firebase (Auth, Firestore, Storage)
+   - REST API (Custom backend with HTTP)
+
+4. **Include Examples**
+   - Sample code and features
+
+## 📂 Generated Project Structure
+
+```
+your_app/
+├── lib/
+│   ├── core/               # Core functionality
+│   │   ├── constants/      # App constants
+│   │   ├── theme/          # Theme configuration
+│   │   └── utils/          # Utility functions
+│   ├── data/               # Data layer
+│   │   ├── datasources/    # API, local storage
+│   │   ├── models/         # Data models
+│   │   └── repositories/   # Repository implementations
+│   ├── domain/             # Business logic
+│   │   ├── entities/       # Business entities
+│   │   ├── repositories/   # Repository interfaces
+│   │   └── usecases/       # Business use cases
+│   ├── presentation/       # UI layer
+│   │   ├── screens/        # App screens
+│   │   ├── widgets/        # Reusable widgets
+│   │   └── providers/      # State management
+│   └── main.dart           # App entry point
+├── test/                   # Unit & widget tests
+├── pubspec.yaml            # Dependencies
+└── README.md               # Project documentation
+```
+
+## 🛠️ Requirements
+
+- **Node.js**: >= 14.0.0
+- **Flutter**: >= 3.0.0 (for running the generated project)
+
+## 📦 What's Included
+
+The generated Flutter project includes:
+
+### Dependencies
+- **flutter_riverpod**: State management
+- **get_it**: Dependency injection
+- **dio**: HTTP client
+- **go_router**: Navigation
+- **hive**: Local storage
+- **equatable**: Value equality
+- **freezed**: Code generation
+
+### Dev Dependencies
+- **build_runner**: Code generation
+- **flutter_lints**: Linting rules
+- **flutter_test**: Testing framework
+
+## 🏃 After Project Generation
+
+Once your project is created:
+
+```bash
+cd my_app
+flutter run
+```
+
+## 📖 Examples
+
+### Create a clean architecture project
+
+```bash
+npx create-mobile-arch awesome_app
+# Then select: Clean Architecture, Riverpod, REST API
+```
+
+### Quick start with defaults
+
+```bash
+npx create-mobile-arch quick_app -y
+```
+
+## 🔧 Development
+
+### Clone & Setup
+
+```bash
+git clone <repository-url>
+cd create-mobile-arch
+npm install
+```
+
+### Test Locally
+
+```bash
+npm test
+# or
+node bin/index.js test_app
+```
+
+### Link for Local Development
+
+```bash
+npm link
+create-mobile-arch my_test_app
+```
+
+## 📜 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📞 Support
+
+If you encounter any issues or have questions:
+- Open an issue on GitHub
+- Check the documentation
+
+## 🙏 Acknowledgments
+
+Inspired by popular project generators like:
+- create-next-app
+- create-vite
+- create-react-app
+
+---
+
+**Built with ❤️ for the Flutter community**

package/bin/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * create-mobile-arch CLI
+ * A production-ready CLI tool to generate Flutter project architectures
+ * 
+ * Usage: npx create-mobile-arch <project-name>
+ */
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+
+const { promptUserChoices, confirmOverwrite, displayConfigSummary } = require('../src/prompts');
+const { generateProject } = require('../src/generator');
+const { validateProjectName, directoryExists, printError } = require('../src/utils');
+
+// Package information
+const packageJson = require('../package.json');
+
+/**
+ * Main CLI function
+ */
+async function main() {
+  // Display banner
+  console.log('\n');
+  console.log(chalk.cyan.bold('╔════════════════════════════════════════╗'));
+  console.log(chalk.cyan.bold('║   ') + chalk.white.bold('Create Mobile Architecture') + chalk.cyan.bold('      ║'));
+  console.log(chalk.cyan.bold('║   ') + chalk.gray('Flutter Project Generator') + chalk.cyan.bold('          ║'));
+  console.log(chalk.cyan.bold('╚════════════════════════════════════════╝'));
+  console.log('\n');
+
+  // Configure CLI
+  program
+    .name('create-mobile-arch')
+    .description('Generate a production-ready Flutter project with Clean Architecture or Feature-First pattern')
+    .version(packageJson.version, '-v, --version', 'Output the current version')
+    .argument('[project-name]', 'Name of your Flutter project')
+    .option('-y, --yes', 'Skip prompts and use default configuration')
+    .helpOption('-h, --help', 'Display help for command')
+    .addHelpText('after', `
+Example:
+  $ npx create-mobile-arch my_app
+  $ npx create-mobile-arch my_awesome_app -y
+
+For more information, visit: https://github.com/yourusername/create-mobile-arch
+    `)
+    .parse(process.argv);
+
+  const args = program.args;
+  const options = program.opts();
+
+  // Get project name from arguments
+  let projectName = args[0];
+
+  // If no project name provided, show error
+  if (!projectName) {
+    printError('Project name is required');
+    console.log(chalk.white('Usage:'), chalk.cyan('npx create-mobile-arch <project-name>'));
+    console.log('\n');
+    console.log(chalk.gray('Example:'), chalk.white('npx create-mobile-arch my_app'));
+    console.log('\n');
+    process.exit(1);
+  }
+
+  // Validate project name
+  const validation = validateProjectName(projectName);
+  if (!validation.valid) {
+    printError(validation.error);
+    console.log(chalk.gray('Examples of valid names:'), chalk.white('my_app, flutter_project, awesome_app_2024'));
+    console.log('\n');
+    process.exit(1);
+  }
+
+  try {
+    // Check if directory already exists
+    const projectPath = path.join(process.cwd(), projectName);
+    const exists = await directoryExists(projectPath);
+
+    if (exists) {
+      // Ask for confirmation to overwrite
+      const shouldOverwrite = await confirmOverwrite(projectName);
+      
+      if (!shouldOverwrite) {
+        console.log('\n');
+        console.log(chalk.yellow('Operation cancelled'));
+        console.log('\n');
+        process.exit(0);
+      }
+      
+      // Remove existing directory
+      const fs = require('fs-extra');
+      await fs.remove(projectPath);
+    }
+
+    // Get user choices (or use defaults if -y flag)
+    let userChoices;
+    
+    if (options.yes) {
+      // Use default configuration
+      userChoices = {
+        architecture: 'clean',
+        stateManagement: 'riverpod',
+        backend: 'rest',
+        includeExamples: true
+      };
+      console.log(chalk.gray('Using default configuration...'));
+    } else {
+      // Prompt user for configuration
+      userChoices = await promptUserChoices();
+    }
+
+    // Display configuration summary
+    displayConfigSummary(projectName, userChoices);
+
+    // Generate the project
+    console.log(chalk.cyan.bold('🚀 Generating your Flutter project...'));
+    console.log('\n');
+    
+    await generateProject(projectName, userChoices);
+
+  } catch (error) {
+    // Handle errors gracefully
+    printError(error.message);
+    
+    if (error.stack && process.env.DEBUG) {
+      console.log(chalk.gray('Stack trace:'));
+      console.log(chalk.gray(error.stack));
+    }
+    
+    console.log(chalk.gray('If this issue persists, please report it at:'));
+    console.log(chalk.cyan('https://github.com/yourusername/create-mobile-arch/issues'));
+    console.log('\n');
+    
+    process.exit(1);
+  }
+}
+
+// Run the CLI
+main().catch(error => {
+  printError('Unexpected error occurred');
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-mobile-arch",
+  "version": "1.0.0",
+  "description": "A production-ready CLI tool to generate Flutter project architectures with Clean Architecture or Feature-First patterns",
+  "main": "bin/index.js",
+  "bin": {
+    "create-mobile-arch": "./bin/index.js"
+  },
+  "scripts": {
+    "test": "node bin/index.js test-app",
+    "prepublishOnly": "echo 'Ready to publish'"
+  },
+  "keywords": [
+    "flutter",
+    "cli",
+    "architecture",
+    "clean-architecture",
+    "feature-first",
+    "riverpod",
+    "bloc",
+    "scaffold",
+    "generator"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.5",
+    "ora": "^5.4.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/create-mobile-arch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/create-mobile-arch/issues"
+  }
+}

package/src/generator.js

@@ -0,0 +1,229 @@
+const fs = require('fs-extra');
+const path = require('path');
+const ora = require('ora');
+const chalk = require('chalk');
+const { exec } = require('child_process');
+const util = require('util');
+
+const {
+  copyAndReplace,
+  toPascalCase,
+  toSnakeCase,
+  isFlutterInstalled,
+  printSuccessMessage,
+  printError
+} = require('./utils');
+
+const execPromise = util.promisify(exec);
+
+/**
+ * Main function to generate a Flutter project
+ * This is where the template copying happens:
+ * - Templates are stored in /templates/flutter-clean directory
+ * - The copyAndReplace utility function recursively copies all files
+ * - During copy, it replaces placeholders like __APP_NAME__ with actual values
+ * 
+ * @param {string} projectName - Name of the project
+ * @param {Object} options - Project configuration options
+ * @returns {Promise<void>}
+ */
+async function generateProject(projectName, options) {
+  const projectPath = path.join(process.cwd(), projectName);
+  let spinner;
+
+  try {
+    // Step 1: Create project directory
+    spinner = ora({
+      text: 'Creating project directory...',
+      color: 'cyan'
+    }).start();
+    
+    await fs.ensureDir(projectPath);
+    spinner.succeed(chalk.green('Project directory created'));
+
+    // Step 2: Determine template path based on architecture choice
+    const templateName = options.architecture === 'clean' ? 'flutter-clean' : 'flutter-clean';
+    const templatePath = path.join(__dirname, '..', 'templates', templateName);
+
+    // Check if template exists
+    const templateExists = await fs.pathExists(templatePath);
+    if (!templateExists) {
+      throw new Error(`Template not found at ${templatePath}`);
+    }
+
+    // Step 3: Copy template files and replace placeholders
+    // THIS IS WHERE TEMPLATE COPYING HAPPENS
+    spinner = ora({
+      text: 'Copying template files...',
+      color: 'cyan'
+    }).start();
+
+    const replacements = {
+      '__APP_NAME__': projectName,
+      '__APP_NAME_PASCAL__': toPascalCase(projectName),
+      '__APP_NAME_SNAKE__': toSnakeCase(projectName),
+      '__STATE_MANAGEMENT__': options.stateManagement,
+      '__BACKEND_TYPE__': options.backend
+    };
+
+    // Copy all files from template directory and replace placeholders
+    await copyAndReplace(templatePath, projectPath, replacements);
+    spinner.succeed(chalk.green('Template files copied'));
+
+    // Step 4: Generate README with configuration details
+    spinner = ora({
+      text: 'Generating project documentation...',
+      color: 'cyan'
+    }).start();
+    
+    await generateReadme(projectPath, projectName, options);
+    spinner.succeed(chalk.green('Documentation generated'));
+
+    // Step 5: Check if Flutter is installed
+    const flutterInstalled = await isFlutterInstalled();
+    
+    if (!flutterInstalled) {
+      spinner = ora().warn(chalk.yellow('Flutter not found. Skipping flutter pub get'));
+      console.log(chalk.yellow('  Please install Flutter and run "flutter pub get" manually'));
+    } else {
+      // Step 6: Run flutter pub get
+      spinner = ora({
+        text: 'Running flutter pub get...',
+        color: 'cyan'
+      }).start();
+
+      try {
+        await execPromise('flutter pub get', {
+          cwd: projectPath,
+          // Set timeout to 2 minutes
+          timeout: 120000
+        });
+        spinner.succeed(chalk.green('Dependencies installed'));
+      } catch (error) {
+        spinner.warn(chalk.yellow('Failed to install dependencies'));
+        console.log(chalk.gray(`  You can run "flutter pub get" manually in the project directory`));
+      }
+    }
+
+    // Step 7: Display success message
+    printSuccessMessage(projectName, projectPath);
+
+  } catch (error) {
+    if (spinner) {
+      spinner.fail(chalk.red('Project generation failed'));
+    }
+    throw error;
+  }
+}
+
+/**
+ * Generates a comprehensive README.md file for the project
+ * @param {string} projectPath - Path to the project directory
+ * @param {string} projectName - Name of the project
+ * @param {Object} options - Project configuration options
+ */
+async function generateReadme(projectPath, projectName, options) {
+  const archName = options.architecture === 'clean' ? 'Clean Architecture' : 'Feature-First Architecture';
+  const stateMgmt = options.stateManagement === 'riverpod' ? 'Riverpod' : 'Bloc';
+  const backend = options.backend === 'firebase' ? 'Firebase' : 'REST API';
+
+  const readmeContent = `# ${toPascalCase(projectName)}
+
+A Flutter project built with **${archName}** pattern.
+
+## 📱 Project Overview
+
+This project was generated using \`create-mobile-arch\` CLI tool.
+
+### Architecture & Tech Stack
+
+- **Architecture Pattern:** ${archName}
+- **State Management:** ${stateMgmt}
+- **Backend Integration:** ${backend}
+
+## 🏗️ Project Structure
+
+\`\`\`
+lib/
+├── core/              # Core functionality (constants, themes, utils)
+├── data/              # Data layer (repositories, data sources, models)
+├── domain/            # Business logic (entities, use cases, interfaces)
+├── presentation/      # UI layer (screens, widgets, ${options.stateManagement})
+└── main.dart          # Application entry point
+\`\`\`
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Flutter SDK (>=3.0.0)
+- Dart SDK (>=3.0.0)
+${options.backend === 'firebase' ? '- Firebase project setup\n' : ''}
+### Installation
+
+1. Get dependencies:
+   \`\`\`bash
+   flutter pub get
+   \`\`\`
+
+2. Run the app:
+   \`\`\`bash
+   flutter run
+   \`\`\`
+
+## 📦 Dependencies
+
+Check \`pubspec.yaml\` for the complete list of dependencies.
+
+### Key Packages
+
+- **${stateMgmt}:** State management
+${options.backend === 'firebase' 
+  ? '- **Firebase Core, Auth, Firestore:** Backend services\n' 
+  : '- **HTTP/Dio:** API communication\n'}
+- **Get It:** Dependency injection
+
+## 🧪 Testing
+
+Run tests:
+\`\`\`bash
+flutter test
+\`\`\`
+
+## 🏛️ Architecture Details
+
+### ${archName}
+
+${options.architecture === 'clean' 
+  ? `This project follows Clean Architecture principles with three main layers:
+
+1. **Presentation Layer:** UI components, state management
+2. **Domain Layer:** Business logic, use cases, entities
+3. **Data Layer:** API calls, local storage, repositories
+
+**Data Flow:** UI → State Management → Use Cases → Repository → Data Source`
+  : `This project follows Feature-First architecture:
+
+- Each feature is self-contained in its own directory
+- Features contain their own models, widgets, and logic
+- Shared code is placed in common/core directories`}
+
+## 📝 License
+
+This project is licensed under the MIT License.
+
+---
+
+Generated with ❤️ by create-mobile-arch
+`;
+
+  await fs.writeFile(
+    path.join(projectPath, 'README.md'),
+    readmeContent,
+    'utf8'
+  );
+}
+
+module.exports = {
+  generateProject
+};