webspresso 0.0.100 → 0.0.101

package/bin/commands/db-makemigrations.js

@@ -0,0 +1,83 @@
+/**
+ * DB MakeMigrations Command (Django-inspired)
+ * Auto-detect model schema changes against live database and generate migrations
+ */
+
+const path = require('path');
+const { loadDbConfig, createDbInstance } = require('../utils/db');
+const { makeMigrations } = require('../../core/orm/migrations/diff');
+
+function registerCommand(program) {
+  program
+    .command('db:makemigrations')
+    .alias('makemigrations')
+    .description('Auto-detect model changes against live database and generate migration files')
+    .option('-c, --config <path>', 'Path to database config file (webspresso.db.js or knexfile.js)')
+    .option('-m, --models <path>', 'Models directory (overrides config.models)')
+    .option('--migrations <path>', 'Migrations directory (overrides config.migrations.directory)')
+    .option('-n, --name <name>', 'Custom migration name override')
+    .option('--include-drops', 'Generate dropColumn operations for columns removed from models')
+    .option('--dry-run', 'Preview migrations that would be created without writing files')
+    .action(async (options) => {
+      let knex = null;
+      try {
+        const { config, path: configPath } = loadDbConfig(options.config);
+        console.log(`\n📦 Using config: ${configPath}\n`);
+
+        knex = await createDbInstance(config);
+
+        const modelsDir = options.models || config.models || './models';
+        const migrationDir = path.resolve(
+          process.cwd(),
+          options.migrations || config.migrations?.directory || './migrations'
+        );
+
+        console.log(`🔍 Inspecting database and comparing with models in ${modelsDir}...`);
+
+        const result = await makeMigrations({
+          knex,
+          modelsDir,
+          migrationDir,
+          dryRun: Boolean(options.dryRun),
+          includeDrops: Boolean(options.includeDrops),
+          name: options.name || null,
+        });
+
+        if (!result.hasChanges) {
+          console.log('\n✨ No changes detected in models. Database schema is up to date.\n');
+          return;
+        }
+
+        const verb = options.dryRun ? 'Would generate' : 'Generated';
+        console.log(`\n✅ ${verb} ${result.created.length} migration(s):\n`);
+
+        for (const change of result.created) {
+          console.log(`   📄 ${change.file}`);
+          console.log(`      Model: ${change.model} (table: ${change.table})`);
+          console.log(`      Type:  ${change.type}`);
+          if (change.addedColumns?.length > 0) {
+            console.log(`      + Added column(s): ${change.addedColumns.join(', ')}`);
+          }
+          if (change.removedColumns?.length > 0) {
+            console.log(`      - Dropped column(s): ${change.removedColumns.join(', ')}`);
+          }
+          console.log();
+        }
+
+        if (options.dryRun) {
+          console.log('💡 Dry-run mode: No files were written to disk.\n');
+        } else {
+          console.log('📝 Next step: Run "webspresso db:migrate" to apply the changes.\n');
+        }
+      } catch (err) {
+        console.error('\n❌ Migration generation failed:', err.message);
+        process.exit(1);
+      } finally {
+        if (knex) {
+          await knex.destroy().catch(() => {});
+        }
+      }
+    });
+}
+
+module.exports = { registerCommand };

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,
+};

package/bin/commands/make-mail.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * Webspresso CLI - make:mail Command
+ * Scaffolds a declarative Mailable class in emails/<name>.js
+ * @module bin/commands/make-mail
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function generateMailContent(rawName) {
+  const baseName = rawName.replace(/email$/i, '').replace(/mail$/i, '').trim();
+  const cleanBase = baseName.charAt(0).toUpperCase() + baseName.slice(1);
+  const className = `${cleanBase}Email`;
+  const tplName = cleanBase.toLowerCase();
+
+  return `'use strict';
+
+const { Mailable } = require('webspresso');
+
+/**
+ * Mailable: ${className}
+ * Send via: req.mailer.send(new ${className}(user))
+ */
+class ${className} extends Mailable {
+  constructor(recipient, data = {}) {
+    super();
+    this.recipient = recipient;
+    this.data = data;
+  }
+
+  /**
+   * Build email definition
+   */
+  build() {
+    const toAddress = typeof this.recipient === 'string' ? this.recipient : this.recipient?.email;
+    const toName = typeof this.recipient === 'object' ? this.recipient?.name : undefined;
+
+    this.to(toAddress, toName)
+      .subject('Hello from Webspresso')
+      .view('${tplName}', this.data);
+  }
+}
+
+module.exports = {
+  ${className},
+};
+`;
+}
+
+function registerCommand(program) {
+  program
+    .command('make:mail <name>')
+    .alias('mail:make')
+    .alias('make:mailable')
+    .description('Scaffold a declarative Mailable class in emails/<name>.js')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
+    .action((nameArg, options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+      const emailsDir = path.join(rootDir, 'emails');
+
+      if (!fs.existsSync(emailsDir)) {
+        fs.mkdirSync(emailsDir, { recursive: true });
+      }
+
+      const rawName = String(nameArg || '').trim();
+      if (!rawName) {
+        console.error('❌ Mailable name is required.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const cleanName = rawName.replace(/\.js$/, '');
+      const fileName = cleanName.endsWith('Email') ? cleanName : `${cleanName}Email`;
+      const targetFilePath = path.join(emailsDir, `${fileName}.js`);
+
+      if (fs.existsSync(targetFilePath)) {
+        console.error(`❌ Mailable file already exists: ${path.relative(rootDir, targetFilePath)}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const content = generateMailContent(cleanName);
+      fs.writeFileSync(targetFilePath, content, 'utf-8');
+      console.log(`\n✅ Created Mailable class: ${path.relative(rootDir, targetFilePath)}\n`);
+    });
+}
+
+module.exports = {
+  registerCommand,
+  generateMailContent,
+};

package/bin/commands/make-policy.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Webspresso CLI - make:policy Command
+ * Scaffolds an authorization policy in policies/<name>.policy.js
+ * @module bin/commands/make-policy
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function generatePolicyContent(policyName) {
+  const modelName = policyName.replace(/policy$/i, '').trim();
+  const cleanName = modelName.charAt(0).toUpperCase() + modelName.slice(1);
+
+  return `'use strict';
+
+/**
+ * Authorization Policy: ${cleanName}
+ * Invoked via req.bouncer.authorize('${cleanName.toLowerCase()}.update', record)
+ * or {% if fsy.can('${cleanName.toLowerCase()}.update', record) %}
+ */
+module.exports = {
+  name: '${cleanName.toLowerCase()}',
+
+  /**
+   * Determine whether the user can view any records
+   */
+  async viewAny(user) {
+    return true;
+  },
+
+  /**
+   * Determine whether the user can view the specific record
+   */
+  async view(user, record) {
+    return true;
+  },
+
+  /**
+   * Determine whether the user can create records
+   */
+  async create(user) {
+    return Boolean(user);
+  },
+
+  /**
+   * Determine whether the user can update the record
+   */
+  async update(user, record) {
+    if (!user) return false;
+    if (user.isAdmin || user.role === 'admin') return true;
+    return record && (record.userId === user.id || record.user_id === user.id);
+  },
+
+  /**
+   * Determine whether the user can delete the record
+   */
+  async delete(user, record) {
+    if (!user) return false;
+    return Boolean(user.isAdmin || user.role === 'admin');
+  },
+};
+`;
+}
+
+function registerCommand(program) {
+  program
+    .command('make:policy <name>')
+    .alias('policy:make')
+    .description('Scaffold an authorization policy in policies/<name>.policy.js')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
+    .action((nameArg, options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+      const policiesDir = path.join(rootDir, 'policies');
+
+      if (!fs.existsSync(policiesDir)) {
+        fs.mkdirSync(policiesDir, { recursive: true });
+      }
+
+      const rawName = String(nameArg || '').trim();
+      if (!rawName) {
+        console.error('❌ Policy name is required.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const policyBase = rawName.replace(/\.policy(\.js)?$/, '').replace(/\.js$/, '');
+      const targetFilePath = path.join(policiesDir, `${policyBase}.policy.js`);
+
+      if (fs.existsSync(targetFilePath)) {
+        console.error(`❌ Policy file already exists: ${path.relative(rootDir, targetFilePath)}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const content = generatePolicyContent(policyBase);
+      fs.writeFileSync(targetFilePath, content, 'utf-8');
+      console.log(`\n✅ Created authorization policy: ${path.relative(rootDir, targetFilePath)}\n`);
+    });
+}
+
+module.exports = {
+  registerCommand,
+  generatePolicyContent,
+};