webspresso 0.0.99 → 0.0.101

package/bin/commands/deploy-check.js

@@ -0,0 +1,339 @@
+/**
+ * Deploy Check Command (Production Preflight Verification)
+ * Validates environment, secrets, container hardening, database migrations, and health checks
+ * @module bin/commands/deploy-check
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
+
+/**
+ * Known weak secret patterns that should never be used in production
+ */
+const WEAK_SECRET_PATTERNS = [
+  /change-me/i,
+  /your-secret/i,
+  /super-secret/i,
+  /secret-key/i,
+  /webspresso-secret/i,
+  /123456/,
+  /password/i,
+  /^secret$/i,
+  /^default$/i,
+  /^test$/i,
+];
+
+/**
+ * Load .env file into key-value map without modifying process.env
+ * @param {string} envPath
+ * @returns {Record<string, string>}
+ */
+function parseEnvFile(envPath) {
+  if (!fs.existsSync(envPath)) return {};
+  const content = fs.readFileSync(envPath, 'utf8');
+  const result = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx > 0) {
+      const key = trimmed.slice(0, eqIdx).trim();
+      let val = trimmed.slice(eqIdx + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      result[key] = val;
+    }
+  }
+  return result;
+}
+
+/**
+ * Run production preflight checks
+ * @param {Object} options
+ * @param {string} [options.cwd=process.cwd()]
+ * @param {string} [options.env='production']
+ * @returns {Promise<{ passed: boolean, errors: Array<{ check: string, message: string }>, warnings: Array<{ check: string, message: string }>, successes: Array<{ check: string, message: string }> }>}
+ */
+async function runDeployCheck(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const targetEnv = options.env || 'production';
+
+  const successes = [];
+  const warnings = [];
+  const errors = [];
+
+  const addPass = (check, message) => successes.push({ check, message });
+  const addWarn = (check, message) => warnings.push({ check, message });
+  const addError = (check, message) => errors.push({ check, message });
+
+  // Load environment variables from process.env and local .env files
+  const localEnv = {
+    ...parseEnvFile(path.join(cwd, '.env')),
+    ...parseEnvFile(path.join(cwd, `.env.${targetEnv}`)),
+    ...process.env,
+  };
+
+  // ----------------------------------------------------
+  // 1. Project & Server Basics
+  // ----------------------------------------------------
+  const pkgPath = path.join(cwd, 'package.json');
+  let pkg = {};
+  if (!fs.existsSync(pkgPath)) {
+    addError('package.json', 'package.json not found in current directory');
+  } else {
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      addPass('package.json', `Readable (${pkg.name || 'unnamed'})`);
+    } catch (e) {
+      addError('package.json', `Invalid JSON: ${e.message}`);
+    }
+  }
+
+  const serverPath = path.join(cwd, 'server.js');
+  let serverCode = '';
+  if (fs.existsSync(serverPath)) {
+    serverCode = fs.readFileSync(serverPath, 'utf8');
+    addPass('server.js', 'server.js entrypoint found');
+  } else {
+    addError('server.js', 'server.js not found (required for production runtime)');
+  }
+
+  // ----------------------------------------------------
+  // 2. Production Secrets & Cryptography
+  // ----------------------------------------------------
+  const sessionSecret = localEnv.SESSION_SECRET || localEnv.AUTH_SESSION_SECRET || localEnv.APP_KEY || '';
+  if (!sessionSecret) {
+    addError('SESSION_SECRET', 'SESSION_SECRET or APP_KEY environment variable is not set');
+  } else if (sessionSecret.length < 32) {
+    addError('SESSION_SECRET', `SESSION_SECRET is only ${sessionSecret.length} chars (must be >= 32 chars in production)`);
+  } else if (WEAK_SECRET_PATTERNS.some((p) => p.test(sessionSecret))) {
+    addError('SESSION_SECRET', 'SESSION_SECRET appears to use a default or easily guessable placeholder');
+  } else {
+    addPass('SESSION_SECRET', 'Sufficiently strong cryptographic secret configured (>= 32 chars)');
+  }
+
+  const jwtSecret = localEnv.JWT_SECRET || '';
+  if (jwtSecret) {
+    if (jwtSecret.length < 32) {
+      addWarn('JWT_SECRET', `JWT_SECRET is only ${jwtSecret.length} chars (recommend >= 32 chars)`);
+    } else if (WEAK_SECRET_PATTERNS.some((p) => p.test(jwtSecret))) {
+      addError('JWT_SECRET', 'JWT_SECRET uses an insecure default placeholder');
+    } else {
+      addPass('JWT_SECRET', 'Strong JWT secret configured (>= 32 chars)');
+    }
+  }
+
+  // ----------------------------------------------------
+  // 3. Git & File Security (.gitignore / .dockerignore)
+  // ----------------------------------------------------
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const gitignore = fs.readFileSync(gitignorePath, 'utf8');
+    if (!gitignore.includes('.env')) {
+      addError('.gitignore', '.env is not ignored in .gitignore (risk of leaking secrets to git)');
+    } else {
+      addPass('.gitignore', '.env files properly excluded from version control');
+    }
+
+    if (gitignore.includes('.sqlite') || gitignore.includes('*.db')) {
+      addPass('.gitignore', 'Local database files (*.sqlite, *.db) excluded from git');
+    }
+  } else {
+    addWarn('.gitignore', '.gitignore file not found');
+  }
+
+  const dockerignorePath = path.join(cwd, '.dockerignore');
+  if (fs.existsSync(dockerignorePath)) {
+    const dignore = fs.readFileSync(dockerignorePath, 'utf8');
+    if (!dignore.includes('node_modules') || !dignore.includes('.env')) {
+      addWarn('.dockerignore', '.dockerignore should explicitly exclude node_modules and .env');
+    } else {
+      addPass('.dockerignore', 'node_modules and .env excluded from Docker build context');
+    }
+  } else {
+    addWarn('.dockerignore', '.dockerignore not found (recommend running: npx webspresso add:docker)');
+  }
+
+  // ----------------------------------------------------
+  // 4. Docker & Container Hardening
+  // ----------------------------------------------------
+  const dockerfilePath = path.join(cwd, 'Dockerfile');
+  if (fs.existsSync(dockerfilePath)) {
+    const dockerfile = fs.readFileSync(dockerfilePath, 'utf8');
+
+    if (/USER\s+(?!root\b)\w+/i.test(dockerfile)) {
+      addPass('Dockerfile User', 'Container executes as non-root unprivileged user');
+    } else {
+      addWarn('Dockerfile User', 'Container does not appear to switch to a non-root USER (security risk)');
+    }
+
+    if (/HEALTHCHECK/i.test(dockerfile)) {
+      addPass('Dockerfile Healthcheck', 'Container HEALTHCHECK instruction configured');
+    } else {
+      addWarn('Dockerfile Healthcheck', 'No HEALTHCHECK instruction found in Dockerfile');
+    }
+
+    if (/FROM.*AS\s+\w+/i.test(dockerfile)) {
+      addPass('Dockerfile Multi-Stage', 'Multi-stage Docker build configured');
+    } else {
+      addWarn('Dockerfile Multi-Stage', 'Single-stage Dockerfile detected (multi-stage recommended for smaller image size)');
+    }
+  } else {
+    addWarn('Dockerfile', 'Dockerfile not found (run `npx webspresso add:docker` to generate)');
+  }
+
+  // ----------------------------------------------------
+  // 5. Database & Migrations
+  // ----------------------------------------------------
+  const migrationsDir = path.join(cwd, 'migrations');
+  if (fs.existsSync(migrationsDir)) {
+    const files = fs.readdirSync(migrationsDir).filter((f) => f.endsWith('.js') || f.endsWith('.ts'));
+    addPass('Migrations', `Found ${files.length} migration file(s) in migrations/`);
+
+    // Try verifying migration status if db config exists
+    const dbConfig = resolveDbConfigIfExists(cwd, targetEnv);
+    if (dbConfig) {
+      try {
+        const db = createDbInstance(dbConfig);
+        const status = await db.knex.migrate.status();
+        if (status > 0) {
+          addWarn('Pending Migrations', `There are ${status} pending database migration(s) to run (run: npx webspresso db:migrate)`);
+        } else if (status === 0) {
+          addPass('Pending Migrations', 'All database migrations are applied up to date');
+        }
+        await db.knex.destroy();
+      } catch (err) {
+        addWarn('Database Connectivity', `Could not check migration status: ${err.message}`);
+      }
+    }
+  } else {
+    addPass('Migrations', 'No migrations directory (skipping migration status check)');
+  }
+
+  // ----------------------------------------------------
+  // 6. Server Optimizations (Compression & Graceful Shutdown)
+  // ----------------------------------------------------
+  if (serverCode) {
+    if (serverCode.includes('compression: true') || serverCode.includes('compression:')) {
+      addPass('HTTP Compression', 'Response compression (Brotli/Gzip) enabled');
+    } else {
+      addWarn('HTTP Compression', 'Response compression not explicitly enabled in createApp({ server: { compression: true } })');
+    }
+
+    if (serverCode.includes('shutdown:') || serverCode.includes('ShutdownManager')) {
+      addPass('Graceful Shutdown', 'Graceful shutdown handling configured');
+    } else {
+      addPass('Graceful Shutdown', 'Default SIGTERM graceful shutdown active');
+    }
+
+    if (serverCode.includes('healthCheckPlugin') || serverCode.includes('/health') || serverCode.includes('/healthz')) {
+      addPass('Health Check Endpoint', 'Health check route configured');
+    } else {
+      addWarn('Health Check Endpoint', 'No /health or /healthz route found (recommend healthCheckPlugin or health endpoint for orchestrators)');
+    }
+  }
+
+  // ----------------------------------------------------
+  // 7. Client Assets & Build Scripts
+  // ----------------------------------------------------
+  if (pkg.scripts && (pkg.scripts['build:css'] || pkg.scripts['build:js'] || pkg.scripts['build'])) {
+    const publicDir = path.join(cwd, 'public');
+    if (fs.existsSync(publicDir)) {
+      addPass('Asset Build', 'Build scripts and public/ directory found');
+    } else {
+      addWarn('Asset Build', 'Build script defined in package.json but public/ directory is missing');
+    }
+  }
+
+  const passed = errors.length === 0;
+
+  return {
+    passed,
+    successes,
+    warnings,
+    errors,
+  };
+}
+
+/**
+ * Register command with Commander
+ * @param {import('commander').Command} program
+ */
+function registerCommand(program) {
+  program
+    .command('deploy:check')
+    .alias('check:deploy')
+    .description('Run production preflight check (secrets, container hardening, database, and optimizations)')
+    .option('-e, --env <environment>', 'Target environment to evaluate (default: production)', 'production')
+    .option('--strict', 'Fail with exit code 1 if any warnings are detected', false)
+    .option('--json', 'Output preflight results as JSON', false)
+    .action(async (...actionArgs) => {
+      const cmd = actionArgs[actionArgs.length - 1];
+      const options = (cmd && typeof cmd.opts === 'function')
+        ? cmd.opts()
+        : (actionArgs.find((a) => a && typeof a === 'object') || {});
+
+      const result = await runDeployCheck({
+        cwd: process.cwd(),
+        env: options.env || 'production',
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.passed || (options.strict && result.warnings.length > 0)) {
+          process.exit(1);
+        }
+        return;
+      }
+
+      console.log('\n🚀 Webspresso Production Deployment Preflight');
+      console.log('=============================================\n');
+
+      if (result.successes.length > 0) {
+        console.log('Passed Checks:');
+        for (const item of result.successes) {
+          console.log(`  ✅ [${item.check}] ${item.message}`);
+        }
+        console.log('');
+      }
+
+      if (result.warnings.length > 0) {
+        console.log('Warnings:');
+        for (const item of result.warnings) {
+          console.log(`  ⚠️  [${item.check}] ${item.message}`);
+        }
+        console.log('');
+      }
+
+      if (result.errors.length > 0) {
+        console.log('Errors (Must be resolved before production deployment):');
+        for (const item of result.errors) {
+          console.log(`  ❌ [${item.check}] ${item.message}`);
+        }
+        console.log('');
+      }
+
+      console.log('---------------------------------------------');
+      console.log(`Summary: ${result.successes.length} passed, ${result.warnings.length} warning(s), ${result.errors.length} error(s).\n`);
+
+      const hasFailed = !result.passed || (options.strict && result.warnings.length > 0);
+
+      if (hasFailed) {
+        console.error('❌ Deployment preflight checks FAILED.');
+        process.exit(1);
+      } else {
+        console.log('✅ Deployment preflight checks PASSED! Your application is ready for production.\n');
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+  runDeployCheck,
+  parseEnvFile,
+  WEAK_SECRET_PATTERNS,
+};

package/bin/commands/list.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Webspresso CLI - list Command
+ * Lists all built-in and custom project commands with descriptions
+ * @module bin/commands/list
+ */
+
+const path = require('path');
+const { createCommandRegistry } = require('../../core/commands');
+
+function registerCommand(program) {
+  program
+    .command('list')
+    .alias('commands')
+    .description('List all available Webspresso and custom project management commands')
+    .option('-d, --dir <path>', 'Custom commands directory (default: ./commands)')
+    .action((options) => {
+      const rootDir = process.cwd();
+      const commandsDir = options.dir
+        ? path.resolve(rootDir, options.dir)
+        : path.resolve(rootDir, 'commands');
+
+      const customRegistry = createCommandRegistry({ commandsDir });
+      const customCommands = customRegistry.list();
+
+      console.log('');
+      console.log('☕ Webspresso CLI - Command Palette');
+      console.log('===================================');
+
+      const sections = [
+        {
+          title: '🚀 Scaffolding & Code Generation',
+          commands: [
+            ['make:model <name>', 'Scaffold a new ORM model definition in models/'],
+            ['make:job <name>', 'Scaffold a background queue job worker in jobs/'],
+            ['make:policy <name>', 'Scaffold an authorization policy in policies/'],
+            ['make:factory <name>', 'Scaffold a test/seeder model factory in factories/'],
+            ['make:event <name>', 'Scaffold an event listener in listeners/'],
+            ['make:mail <name>', 'Scaffold a declarative Mailable class in emails/'],
+            ['make:command <name>', 'Scaffold a custom management command in commands/'],
+            ['page <path>', 'Scaffold a new file-based SSR page'],
+            ['api <path>', 'Scaffold a new file-based API route'],
+          ],
+        },
+        {
+          title: '💾 Database & Migrations',
+          commands: [
+            ['db:migrate', 'Run all pending Knex migrations'],
+            ['db:makemigrations', 'Auto-diff model schemas against database and generate migration'],
+            ['db:rollback', 'Rollback the last batch of migrations'],
+            ['db:status', 'Show database connection and migration status'],
+            ['db:scaffold', 'Generate initial create table migrations from models/'],
+            ['db:make <name>', 'Create an empty Knex migration file'],
+            ['seed', 'Run database seeders'],
+          ],
+        },
+        {
+          title: '🛠️ Server & Developer Experience',
+          commands: [
+            ['dev', 'Start local development server with hot-reload'],
+            ['start', 'Start production HTTP server'],
+            ['build', 'Build client assets and precompile templates'],
+            ['routes', 'Inspect all discovered SSR page and API routes'],
+            ['doctor', 'Diagnose project configuration, dependencies, and health'],
+            ['service [name]', 'Run and test services interactively without HTTP server'],
+            ['run <command>', 'Execute a custom management command with full DI context'],
+            ['list', 'Display this command index'],
+          ],
+        },
+      ];
+
+      for (const section of sections) {
+        console.log(`\n${section.title}:`);
+        for (const [cmd, desc] of section.commands) {
+          console.log(`  ${cmd.padEnd(28)} ${desc}`);
+        }
+      }
+
+      if (customCommands.length > 0) {
+        console.log(`\n⚡ Custom Project Commands (${path.relative(rootDir, commandsDir) || 'commands/'}):`);
+        for (const cmd of customCommands) {
+          console.log(`  ${('run ' + cmd.name).padEnd(28)} ${cmd.description || 'Custom management command'}`);
+        }
+      } else {
+        console.log('\n⚡ Custom Project Commands:');
+        console.log('  (None discovered. Create with: npx webspresso make:command <name>)');
+      }
+
+      console.log('\nUse "webspresso <command> --help" for more information about any command.\n');
+    });
+}
+
+module.exports = {
+  registerCommand,
+};

package/bin/commands/make-command.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * Webspresso CLI - make:command Command
+ * Scaffolds a custom management command in commands/<name>.js
+ * @module bin/commands/make-command
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function generateCommandContent(commandName, description = '') {
+  return `'use strict';
+
+const { defineCommand } = require('webspresso');
+
+/**
+ * Custom Management Command: ${commandName}
+ * Run via: npx webspresso run ${commandName}
+ */
+module.exports = defineCommand({
+  name: '${commandName}',
+  description: '${description || `Execute ${commandName} task`}',
+  options: [
+    { flags: '-d, --dry-run', description: 'Run without making persistent changes', defaultValue: false },
+  ],
+  handle: async ({ db, queue, services, mailer, events, logger, args, flags }) => {
+    logger.log('Executing "${commandName}"...');
+    if (flags.dryRun) {
+      logger.log('[Dry Run] No actual changes will be committed.');
+    }
+
+    // Business logic goes here:
+    // e.g. const users = await db.getRepository('User').find({ active: false });
+
+    return { success: true };
+  },
+});
+`;
+}
+
+function registerCommand(program) {
+  program
+    .command('make:command <name>')
+    .alias('command:make')
+    .description('Scaffold a custom management command in commands/<name>.js')
+    .option('-d, --desc <description>', 'Command description', '')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
+    .action((nameArg, options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+      const commandsDir = path.join(rootDir, 'commands');
+
+      if (!fs.existsSync(commandsDir)) {
+        fs.mkdirSync(commandsDir, { recursive: true });
+      }
+
+      const commandName = String(nameArg || '').trim();
+      if (!commandName) {
+        console.error('❌ Command name is required.');
+        process.exitCode = 1;
+        return;
+      }
+
+      // Convert colons or slashes to subdirectories or file path
+      // e.g. "users:prune" -> commands/users/prune.js or commands/users-prune.js
+      const relPath = commandName.includes(':')
+        ? commandName.replace(/:/g, '/') + '.js'
+        : `${commandName}.js`;
+
+      const targetFilePath = path.join(commandsDir, relPath);
+      const targetDir = path.dirname(targetFilePath);
+
+      if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+      }
+
+      if (fs.existsSync(targetFilePath)) {
+        console.error(`❌ Command file already exists: ${path.relative(rootDir, targetFilePath)}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const content = generateCommandContent(commandName, options.desc);
+      fs.writeFileSync(targetFilePath, content, 'utf-8');
+      console.log(`\n✅ Created custom management command: ${path.relative(rootDir, targetFilePath)}`);
+      console.log(`   Execute it with: npx webspresso run ${commandName}\n`);
+    });
+}
+
+module.exports = {
+  registerCommand,
+  generateCommandContent,
+};

package/bin/commands/make-event.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * Webspresso CLI - make:event Command
+ * Scaffolds an event / signal listener in listeners/<name>.js
+ * @module bin/commands/make-event
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function generateEventContent(eventName) {
+  return `'use strict';
+
+/**
+ * Event Listener: ${eventName}
+ * Triggered by: app.events.emit('${eventName}', payload)
+ */
+module.exports = {
+  event: '${eventName}',
+
+  /**
+   * Handle incoming event
+   * @param {Object} payload - Event payload
+   * @param {Object} ctx - Injected context { events, db, queue, mailer, logger }
+   */
+  async handle(payload, ctx = {}) {
+    const { logger, mailer, queue } = ctx;
+    if (logger) {
+      logger.log('[Event:${eventName}] Received event payload:', payload);
+    }
+
+    // Example: Dispatch background job or send notification email
+    // if (queue) await queue.dispatch('notify', payload);
+  },
+};
+`;
+}
+
+function registerCommand(program) {
+  program
+    .command('make:event <name>')
+    .alias('event:make')
+    .description('Scaffold an event listener in listeners/<name>.js')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
+    .action((nameArg, options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+      const listenersDir = path.join(rootDir, 'listeners');
+
+      if (!fs.existsSync(listenersDir)) {
+        fs.mkdirSync(listenersDir, { recursive: true });
+      }
+
+      const rawName = String(nameArg || '').trim();
+      if (!rawName) {
+        console.error('❌ Event name is required.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const eventName = rawName.replace(/\.js$/, '');
+      const fileName = eventName.replace(/:/g, '-');
+      const targetFilePath = path.join(listenersDir, `${fileName}.js`);
+
+      if (fs.existsSync(targetFilePath)) {
+        console.error(`❌ Listener file already exists: ${path.relative(rootDir, targetFilePath)}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const content = generateEventContent(eventName);
+      fs.writeFileSync(targetFilePath, content, 'utf-8');
+      console.log(`\n✅ Created event listener: ${path.relative(rootDir, targetFilePath)} (event: "${eventName}")\n`);
+    });
+}
+
+module.exports = {
+  registerCommand,
+  generateEventContent,
+};

package/bin/commands/make-factory.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * Webspresso CLI - make:factory Command
+ * Scaffolds an ORM model factory in factories/<name>.factory.js
+ * @module bin/commands/make-factory
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function generateFactoryContent(modelName) {
+  const cleanName = modelName.charAt(0).toUpperCase() + modelName.slice(1);
+
+  return `'use strict';
+
+const { defineFactory } = require('webspresso');
+
+/**
+ * Model Factory: ${cleanName}
+ * Used in tests and seeders:
+ *   const ${cleanName.toLowerCase()} = await ${cleanName}Factory.create({ status: 'active' });
+ */
+module.exports = defineFactory('${cleanName}', ({ faker, seq }) => ({
+  title: faker ? faker.lorem.words(3) : \`${cleanName} \${seq}\`,
+  status: 'active',
+  createdAt: new Date(),
+  updatedAt: new Date(),
+}));
+`;
+}
+
+function registerCommand(program) {
+  program
+    .command('make:factory <name>')
+    .alias('factory:make')
+    .description('Scaffold an ORM model factory in factories/<name>.factory.js')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
+    .action((nameArg, options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+      const factoriesDir = path.join(rootDir, 'factories');
+
+      if (!fs.existsSync(factoriesDir)) {
+        fs.mkdirSync(factoriesDir, { recursive: true });
+      }
+
+      const rawName = String(nameArg || '').trim();
+      if (!rawName) {
+        console.error('❌ Model name is required for factory.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const cleanName = rawName.replace(/\.factory(\.js)?$/, '').replace(/\.js$/, '');
+      const targetFilePath = path.join(factoriesDir, `${cleanName.toLowerCase()}.factory.js`);
+
+      if (fs.existsSync(targetFilePath)) {
+        console.error(`❌ Factory file already exists: ${path.relative(rootDir, targetFilePath)}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const content = generateFactoryContent(cleanName);
+      fs.writeFileSync(targetFilePath, content, 'utf-8');
+      console.log(`\n✅ Created model factory: ${path.relative(rootDir, targetFilePath)}\n`);
+    });
+}
+
+module.exports = {
+  registerCommand,
+  generateFactoryContent,
+};