servcraft 0.1.6 → 0.2.0

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();
+    }
+  );

package/src/cli/commands/remove.ts

@@ -0,0 +1,102 @@
+/* eslint-disable no-console */
+import { Command } from 'commander';
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import inquirer from 'inquirer';
+import { getModulesDir, success, error, info } from '../utils/helpers.js';
+import { ServCraftError, displayError, validateProject } from '../utils/error-handler.js';
+
+export const removeCommand = new Command('remove')
+  .alias('rm')
+  .description('Remove an installed module from your project')
+  .argument('<module>', 'Module to remove')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .option('--keep-env', 'Keep environment variables')
+  .action(async (moduleName: string, options?: { yes?: boolean; keepEnv?: boolean }) => {
+    // Validate project
+    const projectError = validateProject();
+    if (projectError) {
+      displayError(projectError);
+      return;
+    }
+
+    console.log(chalk.bold.cyan('\n🗑️  ServCraft Module Removal\n'));
+
+    const moduleDir = path.join(getModulesDir(), moduleName);
+
+    try {
+      // Check if module exists
+      const exists = await fs
+        .access(moduleDir)
+        .then(() => true)
+        .catch(() => false);
+
+      if (!exists) {
+        displayError(
+          new ServCraftError(`Module "${moduleName}" is not installed`, [
+            `Run ${chalk.cyan('servcraft list --installed')} to see installed modules`,
+            `Check the spelling of the module name`,
+          ])
+        );
+        return;
+      }
+
+      // Get list of files
+      const files = await fs.readdir(moduleDir);
+      const fileCount = files.length;
+
+      // Confirm removal
+      if (!options?.yes) {
+        console.log(chalk.yellow(`⚠  This will remove the "${moduleName}" module:`));
+        console.log(chalk.gray(`   Directory: ${moduleDir}`));
+        console.log(chalk.gray(`   Files: ${fileCount} file(s)`));
+        console.log();
+
+        const { confirm } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'confirm',
+            message: 'Are you sure you want to remove this module?',
+            default: false,
+          },
+        ]);
+
+        if (!confirm) {
+          console.log(chalk.yellow('\n✖ Removal cancelled\n'));
+          return;
+        }
+      }
+
+      const spinner = ora('Removing module...').start();
+
+      // Remove module directory
+      await fs.rm(moduleDir, { recursive: true, force: true });
+
+      spinner.succeed(`Module "${moduleName}" removed successfully!`);
+
+      // Show what was removed
+      console.log('\n' + chalk.bold('✓ Removed:'));
+      success(`  src/modules/${moduleName}/ (${fileCount} files)`);
+
+      // Instructions for cleanup
+      if (!options?.keepEnv) {
+        console.log('\n' + chalk.bold('📌 Manual cleanup needed:'));
+        info('  1. Remove environment variables related to this module from .env');
+        info('  2. Remove module imports from your main app file');
+        info('  3. Remove related database migrations if any');
+        info('  4. Update your routes if they reference this module');
+      } else {
+        console.log('\n' + chalk.bold('📌 Manual cleanup needed:'));
+        info('  1. Environment variables were kept (--keep-env flag)');
+        info('  2. Remove module imports from your main app file');
+        info('  3. Update your routes if they reference this module');
+      }
+
+      console.log();
+    } catch (err) {
+      error(err instanceof Error ? err.message : String(err));
+      console.log();
+    }
+  });

package/src/cli/index.ts

@@ -5,6 +5,10 @@ import { initCommand } from './commands/init.js';
 import { generateCommand } from './commands/generate.js';
 import { addModuleCommand } from './commands/add-module.js';
 import { dbCommand } from './commands/db.js';
+import { docsCommand } from './commands/docs.js';
+import { listCommand } from './commands/list.js';
+import { removeCommand } from './commands/remove.js';
+import { doctorCommand } from './commands/doctor.js';
 
 const program = new Command();
 
@@ -25,4 +29,16 @@ program.addCommand(addModuleCommand);
 // Database commands
 program.addCommand(dbCommand);
 
+// Documentation commands
+program.addCommand(docsCommand);
+
+// List modules
+program.addCommand(listCommand);
+
+// Remove module
+program.addCommand(removeCommand);
+
+// Diagnose project
+program.addCommand(doctorCommand);
+
 program.parse();

package/src/cli/utils/dry-run.ts

@@ -0,0 +1,155 @@
+/* eslint-disable no-console */
+import chalk from 'chalk';
+import path from 'path';
+
+export interface FileOperation {
+  type: 'create' | 'modify' | 'delete';
+  path: string;
+  content?: string;
+  size?: number;
+}
+
+export class DryRunManager {
+  private static instance: DryRunManager;
+  private enabled = false;
+  private operations: FileOperation[] = [];
+
+  private constructor() {}
+
+  static getInstance(): DryRunManager {
+    if (!DryRunManager.instance) {
+      DryRunManager.instance = new DryRunManager();
+    }
+    return DryRunManager.instance;
+  }
+
+  enable(): void {
+    this.enabled = true;
+    this.operations = [];
+  }
+
+  disable(): void {
+    this.enabled = false;
+    this.operations = [];
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  addOperation(operation: FileOperation): void {
+    if (this.enabled) {
+      this.operations.push(operation);
+    }
+  }
+
+  getOperations(): FileOperation[] {
+    return [...this.operations];
+  }
+
+  printSummary(): void {
+    if (!this.enabled || this.operations.length === 0) {
+      return;
+    }
+
+    console.log(chalk.bold.yellow('\n📋 Dry Run - Preview of changes:\n'));
+    console.log(chalk.gray('No files will be written. Remove --dry-run to apply changes.\n'));
+
+    const createOps = this.operations.filter((op) => op.type === 'create');
+    const modifyOps = this.operations.filter((op) => op.type === 'modify');
+    const deleteOps = this.operations.filter((op) => op.type === 'delete');
+
+    if (createOps.length > 0) {
+      console.log(chalk.green.bold(`\n✓ Files to be created (${createOps.length}):`));
+      createOps.forEach((op) => {
+        const size = op.content ? `${op.content.length} bytes` : 'unknown size';
+        console.log(`  ${chalk.green('+')} ${chalk.cyan(op.path)} ${chalk.gray(`(${size})`)}`);
+      });
+    }
+
+    if (modifyOps.length > 0) {
+      console.log(chalk.yellow.bold(`\n~ Files to be modified (${modifyOps.length}):`));
+      modifyOps.forEach((op) => {
+        console.log(`  ${chalk.yellow('~')} ${chalk.cyan(op.path)}`);
+      });
+    }
+
+    if (deleteOps.length > 0) {
+      console.log(chalk.red.bold(`\n- Files to be deleted (${deleteOps.length}):`));
+      deleteOps.forEach((op) => {
+        console.log(`  ${chalk.red('-')} ${chalk.cyan(op.path)}`);
+      });
+    }
+
+    console.log(chalk.gray('\n' + '─'.repeat(60)));
+    console.log(
+      chalk.bold(`  Total operations: ${this.operations.length}`) +
+        chalk.gray(
+          ` (${createOps.length} create, ${modifyOps.length} modify, ${deleteOps.length} delete)`
+        )
+    );
+    console.log(chalk.gray('─'.repeat(60)));
+    console.log(chalk.yellow('\n⚠ This was a dry run. No files were created or modified.'));
+    console.log(chalk.gray('  Remove --dry-run to apply these changes.\n'));
+  }
+
+  // Helper to format file path relative to cwd
+  relativePath(filePath: string): string {
+    return path.relative(process.cwd(), filePath);
+  }
+}
+
+// Wrapper functions for file operations
+export async function dryRunWriteFile(
+  filePath: string,
+  content: string,
+  actualWriteFn: (path: string, content: string) => Promise<void>
+): Promise<void> {
+  const dryRun = DryRunManager.getInstance();
+
+  if (dryRun.isEnabled()) {
+    dryRun.addOperation({
+      type: 'create',
+      path: dryRun.relativePath(filePath),
+      content,
+      size: content.length,
+    });
+    return;
+  }
+
+  await actualWriteFn(filePath, content);
+}
+
+export async function dryRunModifyFile(
+  filePath: string,
+  actualModifyFn: (path: string) => Promise<void>
+): Promise<void> {
+  const dryRun = DryRunManager.getInstance();
+
+  if (dryRun.isEnabled()) {
+    dryRun.addOperation({
+      type: 'modify',
+      path: dryRun.relativePath(filePath),
+    });
+    return;
+  }
+
+  await actualModifyFn(filePath);
+}
+
+export async function dryRunDeleteFile(
+  filePath: string,
+  actualDeleteFn: (path: string) => Promise<void>
+): Promise<void> {
+  const dryRun = DryRunManager.getInstance();
+
+  if (dryRun.isEnabled()) {
+    dryRun.addOperation({
+      type: 'delete',
+      path: dryRun.relativePath(filePath),
+    });
+    return;
+  }
+
+  await actualDeleteFn(filePath);
+}