servcraft 0.1.7 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "servcraft",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "A modular, production-ready Node.js backend framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/commands/add-module.ts

@@ -16,6 +16,8 @@ import {
 import { EnvManager } from '../utils/env-manager.js';
 import { TemplateManager } from '../utils/template-manager.js';
 import { InteractivePrompt } from '../utils/interactive-prompt.js';
+import { DryRunManager } from '../utils/dry-run.js';
+import { ErrorTypes, displayError, validateProject } from '../utils/error-handler.js';
 
 // Pre-built modules that can be added
 const AVAILABLE_MODULES = {
@@ -160,10 +162,17 @@ export const addModuleCommand = new Command('add')
   .option('-f, --force', 'Force overwrite existing module')
   .option('-u, --update', 'Update existing module (smart merge)')
   .option('--skip-existing', 'Skip if module already exists')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(
     async (
       moduleName?: string,
-      options?: { list?: boolean; force?: boolean; update?: boolean; skipExisting?: boolean }
+      options?: {
+        list?: boolean;
+        force?: boolean;
+        update?: boolean;
+        skipExisting?: boolean;
+        dryRun?: boolean;
+      }
     ) => {
       if (options?.list || !moduleName) {
         console.log(chalk.bold('\n📦 Available Modules:\n'));
@@ -180,11 +189,24 @@ export const addModuleCommand = new Command('add')
         return;
       }
 
+      // Enable dry-run mode if specified
+      const dryRun = DryRunManager.getInstance();
+      if (options?.dryRun) {
+        dryRun.enable();
+        console.log(chalk.yellow('\n⚠ DRY RUN MODE - No files will be written\n'));
+      }
+
       const module = AVAILABLE_MODULES[moduleName as keyof typeof AVAILABLE_MODULES];
 
       if (!module) {
-        error(`Unknown module: ${moduleName}`);
-        info('Run "servcraft add --list" to see available modules');
+        displayError(ErrorTypes.MODULE_NOT_FOUND(moduleName));
+        return;
+      }
+
+      // Validate project structure
+      const projectError = validateProject();
+      if (projectError) {
+        displayError(projectError);
         return;
       }
 
@@ -319,10 +341,17 @@ export const addModuleCommand = new Command('add')
           }
         }
 
-        console.log('\n📌 Next steps:');
-        info('  1. Configure environment variables in .env (if needed)');
-        info('  2. Register the module in your main app file');
-        info('  3. Run database migrations if needed');
+        if (!options?.dryRun) {
+          console.log('\n📌 Next steps:');
+          info('  1. Configure environment variables in .env (if needed)');
+          info('  2. Register the module in your main app file');
+          info('  3. Run database migrations if needed');
+        }
+
+        // Show dry-run summary if enabled
+        if (options?.dryRun) {
+          dryRun.printSummary();
+        }
       } catch (err) {
         spinner.fail('Failed to add module');
         error(err instanceof Error ? err.message : String(err));

package/src/cli/commands/doctor.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+
+export const doctorCommand = new Command('doctor')
+  .description('Diagnose project configuration and dependencies')
+  .action(async () => {
+    console.log(chalk.bold.cyan('\nServCraft Doctor - Coming soon!\n'));
+  });

package/src/cli/commands/generate.ts

@@ -14,7 +14,26 @@ import {
   info,
   getModulesDir,
 } from '../utils/helpers.js';
+import { DryRunManager } from '../utils/dry-run.js';
+import chalk from 'chalk';
 import { parseFields, type FieldDefinition } from '../utils/field-parser.js';
+import { ErrorTypes, displayError } from '../utils/error-handler.js';
+
+// Helper to enable dry-run mode
+function enableDryRunIfNeeded(options: { dryRun?: boolean }): void {
+  const dryRun = DryRunManager.getInstance();
+  if (options.dryRun) {
+    dryRun.enable();
+    console.log(chalk.yellow('\n⚠ DRY RUN MODE - No files will be written\n'));
+  }
+}
+
+// Helper to show dry-run summary
+function showDryRunSummary(options: { dryRun?: boolean }): void {
+  if (options.dryRun) {
+    DryRunManager.getInstance().printSummary();
+  }
+}
 import { controllerTemplate } from '../templates/controller.js';
 import { serviceTemplate } from '../templates/service.js';
 import { repositoryTemplate } from '../templates/repository.js';
@@ -43,7 +62,9 @@ generateCommand
   .option('--prisma', 'Generate Prisma model suggestion')
   .option('--validator <type>', 'Validator type: zod, joi, yup', 'zod')
   .option('-i, --interactive', 'Interactive mode to define fields')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, fieldsArgs: string[], options) => {
+    enableDryRunIfNeeded(options);
     let fields: FieldDefinition[] = [];
 
     // Parse fields from command line or interactive mode
@@ -161,6 +182,9 @@ generateCommand
         info(`  ${hasFields ? '3' : '4'}. Add the Prisma model to schema.prisma`);
         info(`  ${hasFields ? '4' : '5'}. Run: npm run db:migrate`);
       }
+
+      // Show dry-run summary if enabled
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate module');
       error(err instanceof Error ? err.message : String(err));
@@ -173,7 +197,9 @@ generateCommand
   .alias('c')
   .description('Generate a controller')
   .option('-m, --module <module>', 'Target module name')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, options) => {
+    enableDryRunIfNeeded(options);
     const spinner = ora('Generating controller...').start();
 
     try {
@@ -187,7 +213,7 @@ generateCommand
 
       if (await fileExists(filePath)) {
         spinner.stop();
-        error(`Controller "${kebabName}" already exists`);
+        displayError(ErrorTypes.FILE_ALREADY_EXISTS(`${kebabName}.controller.ts`));
         return;
       }
 
@@ -195,6 +221,7 @@ generateCommand
 
       spinner.succeed(`Controller "${pascalName}Controller" generated!`);
       success(`  src/modules/${moduleName}/${kebabName}.controller.ts`);
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate controller');
       error(err instanceof Error ? err.message : String(err));
@@ -207,7 +234,9 @@ generateCommand
   .alias('s')
   .description('Generate a service')
   .option('-m, --module <module>', 'Target module name')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, options) => {
+    enableDryRunIfNeeded(options);
     const spinner = ora('Generating service...').start();
 
     try {
@@ -229,6 +258,7 @@ generateCommand
 
       spinner.succeed(`Service "${pascalName}Service" generated!`);
       success(`  src/modules/${moduleName}/${kebabName}.service.ts`);
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate service');
       error(err instanceof Error ? err.message : String(err));
@@ -241,7 +271,9 @@ generateCommand
   .alias('r')
   .description('Generate a repository')
   .option('-m, --module <module>', 'Target module name')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, options) => {
+    enableDryRunIfNeeded(options);
     const spinner = ora('Generating repository...').start();
 
     try {
@@ -264,6 +296,7 @@ generateCommand
 
       spinner.succeed(`Repository "${pascalName}Repository" generated!`);
       success(`  src/modules/${moduleName}/${kebabName}.repository.ts`);
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate repository');
       error(err instanceof Error ? err.message : String(err));
@@ -276,7 +309,9 @@ generateCommand
   .alias('t')
   .description('Generate types/interfaces')
   .option('-m, --module <module>', 'Target module name')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, options) => {
+    enableDryRunIfNeeded(options);
     const spinner = ora('Generating types...').start();
 
     try {
@@ -297,6 +332,7 @@ generateCommand
 
       spinner.succeed(`Types for "${pascalName}" generated!`);
       success(`  src/modules/${moduleName}/${kebabName}.types.ts`);
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate types');
       error(err instanceof Error ? err.message : String(err));
@@ -309,7 +345,9 @@ generateCommand
   .alias('v')
   .description('Generate validation schemas')
   .option('-m, --module <module>', 'Target module name')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, options) => {
+    enableDryRunIfNeeded(options);
     const spinner = ora('Generating schemas...').start();
 
     try {
@@ -331,6 +369,7 @@ generateCommand
 
       spinner.succeed(`Schemas for "${pascalName}" generated!`);
       success(`  src/modules/${moduleName}/${kebabName}.schemas.ts`);
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate schemas');
       error(err instanceof Error ? err.message : String(err));
@@ -342,7 +381,9 @@ generateCommand
   .command('routes <name>')
   .description('Generate routes')
   .option('-m, --module <module>', 'Target module name')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(async (name: string, options) => {
+    enableDryRunIfNeeded(options);
     const spinner = ora('Generating routes...').start();
 
     try {
@@ -365,6 +406,7 @@ generateCommand
 
       spinner.succeed(`Routes for "${pascalName}" generated!`);
       success(`  src/modules/${moduleName}/${kebabName}.routes.ts`);
+      showDryRunSummary(options);
     } catch (err) {
       spinner.fail('Failed to generate routes');
       error(err instanceof Error ? err.message : String(err));

package/src/cli/commands/init.ts

@@ -6,6 +6,7 @@ import inquirer from 'inquirer';
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { ensureDir, writeFile, error, warn } from '../utils/helpers.js';
+import { DryRunManager } from '../utils/dry-run.js';
 
 interface InitOptions {
   name: string;
@@ -27,6 +28,7 @@ export const initCommand = new Command('init')
   .option('--esm', 'Use ES Modules (import/export) - default')
   .option('--cjs, --commonjs', 'Use CommonJS (require/module.exports)')
   .option('--db <database>', 'Database type (postgresql, mysql, sqlite, mongodb, none)')
+  .option('--dry-run', 'Preview changes without writing files')
   .action(
     async (
       name?: string,
@@ -37,8 +39,16 @@ export const initCommand = new Command('init')
         esm?: boolean;
         commonjs?: boolean;
         db?: string;
+        dryRun?: boolean;
       }
     ) => {
+      // Enable dry-run mode if specified
+      const dryRun = DryRunManager.getInstance();
+      if (cmdOptions?.dryRun) {
+        dryRun.enable();
+        console.log(chalk.yellow('\n⚠ DRY RUN MODE - No files will be written\n'));
+      }
+
       console.log(
         chalk.blue(`
 ╔═══════════════════════════════════════════╗
@@ -274,19 +284,23 @@ export const initCommand = new Command('init')
 
         spinner.succeed('Project files generated!');
 
-        // Install dependencies
-        const installSpinner = ora('Installing dependencies...').start();
-
-        try {
-          execSync('npm install', { cwd: projectDir, stdio: 'pipe' });
-          installSpinner.succeed('Dependencies installed!');
-        } catch {
-          installSpinner.warn('Failed to install dependencies automatically');
-          warn('  Run "npm install" manually in the project directory');
+        // Install dependencies (skip in dry-run mode)
+        if (!cmdOptions?.dryRun) {
+          const installSpinner = ora('Installing dependencies...').start();
+
+          try {
+            execSync('npm install', { cwd: projectDir, stdio: 'pipe' });
+            installSpinner.succeed('Dependencies installed!');
+          } catch {
+            installSpinner.warn('Failed to install dependencies automatically');
+            warn('  Run "npm install" manually in the project directory');
+          }
         }
 
         // Print success message
-        console.log('\n' + chalk.green('✨ Project created successfully!'));
+        if (!cmdOptions?.dryRun) {
+          console.log('\n' + chalk.green('✨ Project created successfully!'));
+        }
         console.log('\n' + chalk.bold('📁 Project structure:'));
         console.log(`
   ${options.name}/
@@ -317,6 +331,11 @@ export const initCommand = new Command('init')
   ${chalk.yellow('servcraft generate service <name>')}    Generate a service
   ${chalk.yellow('servcraft add auth')}                   Add authentication module
 `);
+
+        // Show dry-run summary if enabled
+        if (cmdOptions?.dryRun) {
+          dryRun.printSummary();
+        }
       } catch (err) {
         spinner.fail('Failed to create project');
         error(err instanceof Error ? err.message : String(err));

package/src/cli/commands/list.ts

@@ -0,0 +1,274 @@
+/* eslint-disable no-console */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import { getProjectRoot, getModulesDir } from '../utils/helpers.js';
+
+// Pre-built modules that can be added
+const AVAILABLE_MODULES: Record<string, { name: string; description: string; category: string }> = {
+  // Core
+  auth: {
+    name: 'Authentication',
+    description: 'JWT authentication with access/refresh tokens',
+    category: 'Core',
+  },
+  users: {
+    name: 'User Management',
+    description: 'User CRUD with RBAC (roles & permissions)',
+    category: 'Core',
+  },
+  email: {
+    name: 'Email Service',
+    description: 'SMTP email with templates (Handlebars)',
+    category: 'Core',
+  },
+
+  // Security
+  mfa: {
+    name: 'MFA/TOTP',
+    description: 'Two-factor authentication with QR codes',
+    category: 'Security',
+  },
+  oauth: {
+    name: 'OAuth',
+    description: 'Social login (Google, GitHub, Facebook, Twitter, Apple)',
+    category: 'Security',
+  },
+  'rate-limit': {
+    name: 'Rate Limiting',
+    description: 'Advanced rate limiting with multiple algorithms',
+    category: 'Security',
+  },
+
+  // Data & Storage
+  cache: {
+    name: 'Redis Cache',
+    description: 'Redis caching with TTL & invalidation',
+    category: 'Data & Storage',
+  },
+  upload: {
+    name: 'File Upload',
+    description: 'File upload with local/S3/Cloudinary storage',
+    category: 'Data & Storage',
+  },
+  search: {
+    name: 'Search',
+    description: 'Full-text search with Elasticsearch/Meilisearch',
+    category: 'Data & Storage',
+  },
+
+  // Communication
+  notification: {
+    name: 'Notifications',
+    description: 'Email, SMS, Push notifications',
+    category: 'Communication',
+  },
+  webhook: {
+    name: 'Webhooks',
+    description: 'Outgoing webhooks with HMAC signatures & retry',
+    category: 'Communication',
+  },
+  websocket: {
+    name: 'WebSockets',
+    description: 'Real-time communication with Socket.io',
+    category: 'Communication',
+  },
+
+  // Background Processing
+  queue: {
+    name: 'Queue/Jobs',
+    description: 'Background jobs with Bull/BullMQ & cron scheduling',
+    category: 'Background Processing',
+  },
+  'media-processing': {
+    name: 'Media Processing',
+    description: 'Image/video processing with FFmpeg',
+    category: 'Background Processing',
+  },
+
+  // Monitoring & Analytics
+  audit: {
+    name: 'Audit Logs',
+    description: 'Activity logging and audit trail',
+    category: 'Monitoring & Analytics',
+  },
+  analytics: {
+    name: 'Analytics/Metrics',
+    description: 'Prometheus metrics & event tracking',
+    category: 'Monitoring & Analytics',
+  },
+
+  // Internationalization
+  i18n: {
+    name: 'i18n/Localization',
+    description: 'Multi-language support with 7+ locales',
+    category: 'Internationalization',
+  },
+
+  // API Management
+  'feature-flag': {
+    name: 'Feature Flags',
+    description: 'A/B testing & progressive rollout',
+    category: 'API Management',
+  },
+  'api-versioning': {
+    name: 'API Versioning',
+    description: 'Multiple API versions support',
+    category: 'API Management',
+  },
+
+  // Payments
+  payment: {
+    name: 'Payments',
+    description: 'Payment processing (Stripe, PayPal, Mobile Money)',
+    category: 'Payments',
+  },
+};
+
+async function getInstalledModules(): Promise<string[]> {
+  try {
+    const modulesDir = getModulesDir();
+    const entries = await fs.readdir(modulesDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+function isServercraftProject(): boolean {
+  try {
+    getProjectRoot();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const listCommand = new Command('list')
+  .alias('ls')
+  .description('List available and installed modules')
+  .option('-a, --available', 'Show only available modules')
+  .option('-i, --installed', 'Show only installed modules')
+  .option('-c, --category <category>', 'Filter by category')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (options: {
+      available?: boolean;
+      installed?: boolean;
+      category?: string;
+      json?: boolean;
+    }) => {
+      const installedModules = await getInstalledModules();
+      const isProject = isServercraftProject();
+
+      if (options.json) {
+        const output: Record<string, unknown> = {
+          available: Object.entries(AVAILABLE_MODULES).map(([key, mod]) => ({
+            id: key,
+            ...mod,
+            installed: installedModules.includes(key),
+          })),
+        };
+
+        if (isProject) {
+          output.installed = installedModules;
+        }
+
+        console.log(JSON.stringify(output, null, 2));
+        return;
+      }
+
+      // Group modules by category
+      const byCategory: Record<
+        string,
+        Array<{ id: string; name: string; description: string; installed: boolean }>
+      > = {};
+
+      for (const [key, mod] of Object.entries(AVAILABLE_MODULES)) {
+        if (options.category && mod.category.toLowerCase() !== options.category.toLowerCase()) {
+          continue;
+        }
+
+        if (!byCategory[mod.category]) {
+          byCategory[mod.category] = [];
+        }
+
+        byCategory[mod.category].push({
+          id: key,
+          name: mod.name,
+          description: mod.description,
+          installed: installedModules.includes(key),
+        });
+      }
+
+      // Show installed modules only
+      if (options.installed) {
+        if (!isProject) {
+          console.log(chalk.yellow('\n⚠ Not in a Servcraft project directory\n'));
+          return;
+        }
+
+        console.log(chalk.bold('\n📦 Installed Modules:\n'));
+
+        if (installedModules.length === 0) {
+          console.log(chalk.gray('  No modules installed yet.\n'));
+          console.log(`  Run ${chalk.cyan('servcraft add <module>')} to add a module.\n`);
+          return;
+        }
+
+        for (const modId of installedModules) {
+          const mod = AVAILABLE_MODULES[modId];
+          if (mod) {
+            console.log(`  ${chalk.green('✓')} ${chalk.cyan(modId.padEnd(18))} ${mod.name}`);
+          } else {
+            console.log(
+              `  ${chalk.green('✓')} ${chalk.cyan(modId.padEnd(18))} ${chalk.gray('(custom module)')}`
+            );
+          }
+        }
+
+        console.log(`\n  Total: ${chalk.bold(installedModules.length)} module(s) installed\n`);
+        return;
+      }
+
+      // Show available modules (default or --available)
+      console.log(chalk.bold('\n📦 Available Modules\n'));
+
+      if (isProject) {
+        console.log(
+          chalk.gray(`  ${chalk.green('✓')} = installed    ${chalk.dim('○')} = not installed\n`)
+        );
+      }
+
+      for (const [category, modules] of Object.entries(byCategory)) {
+        console.log(chalk.bold.blue(`  ${category}`));
+        console.log(chalk.gray('  ' + '─'.repeat(40)));
+
+        for (const mod of modules) {
+          const status = isProject ? (mod.installed ? chalk.green('✓') : chalk.dim('○')) : ' ';
+          const nameColor = mod.installed ? chalk.green : chalk.cyan;
+          console.log(`  ${status} ${nameColor(mod.id.padEnd(18))} ${mod.name}`);
+          console.log(`    ${chalk.gray(mod.description)}`);
+        }
+        console.log();
+      }
+
+      // Summary
+      const totalAvailable = Object.keys(AVAILABLE_MODULES).length;
+      const totalInstalled = installedModules.filter((m) => AVAILABLE_MODULES[m]).length;
+
+      console.log(chalk.gray('─'.repeat(50)));
+      console.log(
+        `  ${chalk.bold(totalAvailable)} modules available` +
+          (isProject ? ` | ${chalk.green.bold(totalInstalled)} installed` : '')
+      );
+      console.log();
+
+      // Usage hints
+      console.log(chalk.bold('  Usage:'));
+      console.log(`    ${chalk.yellow('servcraft add <module>')}      Add a module`);
+      console.log(`    ${chalk.yellow('servcraft list --installed')}  Show installed only`);
+      console.log(`    ${chalk.yellow('servcraft list --category Security')}  Filter by category`);
+      console.log();
+    }
+  );