webspresso 0.0.100 → 0.0.102

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

package/bin/commands/routes.js

@@ -19,10 +19,18 @@ function registerCommand(program) {
     .option('-a, --api', 'Filter to only API endpoints')
     .option('-p, --pages', 'Filter to only SSR page routes')
     .option('-j, --json', 'Output routes as JSON')
+    .option('-m, --manifest', 'Generate or update .webspresso/routes.manifest.json')
     .option('--root <dir>', 'Root directory of the project', process.cwd())
     .action((options) => {
       const rootDir = path.resolve(options.root || process.cwd());
 
+      if (options.manifest) {
+        const { generateRouteManifest } = require('../../src/discovery/route-manifest');
+        const result = generateRouteManifest({ rootDir });
+        console.log(`✅ AOT route manifest written to: ${path.relative(rootDir, result.manifestPath)} (${result.routeCount} routes)`);
+        return;
+      }
+
       const descriptors = scanRoutes({
         rootDir,
         pages: fs.existsSync(path.join(rootDir, 'pages')) ? { dir: 'pages' } : true,

package/bin/commands/run.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * Webspresso CLI - run Command
+ * Executes custom management commands with injected framework context
+ * @module bin/commands/run
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { createCommandRegistry, executeCommand } = require('../../core/commands');
+const { createEventDispatcher } = require('../../core/events');
+const { createMailer } = require('../../core/mail');
+const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
+
+/**
+ * Helper to parse unknown CLI options into a flags object
+ * e.g. ['--dry-run', '--limit', '50', 'arg1'] -> flags: { dryRun: true, limit: 50 }, args: ['arg1']
+ * @param {string[]} rawArgs
+ * @returns {{ flags: Object, args: string[] }}
+ */
+function parseRawArgs(rawArgs = []) {
+  const flags = {};
+  const args = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const item = rawArgs[i];
+    if (item.startsWith('--')) {
+      const withoutDashes = item.slice(2);
+      if (withoutDashes.includes('=')) {
+        const [k, v] = withoutDashes.split('=');
+        flags[camelCase(k)] = parseVal(v);
+      } else {
+        const next = rawArgs[i + 1];
+        if (next && !next.startsWith('-')) {
+          flags[camelCase(withoutDashes)] = parseVal(next);
+          i++;
+        } else {
+          flags[camelCase(withoutDashes)] = true;
+        }
+      }
+    } else if (item.startsWith('-') && item.length === 2) {
+      const flagChar = item.slice(1);
+      const next = rawArgs[i + 1];
+      if (next && !next.startsWith('-')) {
+        flags[flagChar] = parseVal(next);
+        i++;
+      } else {
+        flags[flagChar] = true;
+      }
+    } else {
+      args.push(item);
+    }
+  }
+
+  return { flags, args };
+}
+
+function camelCase(str) {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function parseVal(val) {
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  if (val === 'null') return null;
+  if (!Number.isNaN(Number(val)) && val.trim() !== '') return Number(val);
+  return val;
+}
+
+function registerCommand(program) {
+  program
+    .command('run [commandName] [args...]')
+    .alias('command:run')
+    .description('Run a custom management command from commands/ with injected framework context')
+    .option('-d, --dir <path>', 'Custom commands directory (default: ./commands)')
+    .option('-c, --config <path>', 'Path to database config file (optional)')
+    .option('-E, --env <environment>', 'Environment name (default: development)')
+    .allowUnknownOption(true)
+    .action(async (commandName, rawArgs = [], options = {}) => {
+      const rootDir = process.cwd();
+      const commandsDir = options.dir
+        ? path.resolve(rootDir, options.dir)
+        : path.resolve(rootDir, 'commands');
+
+      const registry = createCommandRegistry({ commandsDir });
+      const available = registry.list();
+
+      if (!commandName) {
+        if (available.length === 0) {
+          console.log(`\n⚠️  No custom commands found in "${path.relative(rootDir, commandsDir) || 'commands/'}".`);
+          console.log('   Create your first custom command with:');
+          console.log('   npx webspresso make:command <name>\n');
+          return;
+        }
+
+        console.log(`\n⚡ Available Custom Management Commands (${available.length}):\n`);
+        const maxLen = Math.max(...available.map((c) => c.name.length), 10);
+        for (const cmd of available) {
+          console.log(`  webspresso run ${cmd.name.padEnd(maxLen + 2)} ${cmd.description ? `# ${cmd.description}` : ''}`);
+        }
+        console.log('');
+        return;
+      }
+
+      if (!registry.has(commandName)) {
+        console.error(`\n❌ Error: Command "${commandName}" not found in ${path.relative(rootDir, commandsDir) || 'commands/'}.`);
+        if (available.length > 0) {
+          console.log(`   Available commands: ${registry.names().join(', ')}\n`);
+        } else {
+          console.log('   Use `npx webspresso make:command <name>` to create it.\n');
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      const cmdDef = registry.get(commandName);
+      const { flags, args } = parseRawArgs(rawArgs);
+
+      // Boot Context
+      let knexInstance = null;
+      let db = null;
+      let services = null;
+      const events = createEventDispatcher();
+      const mailer = createMailer({ backend: 'console' });
+
+      // 1. Database
+      try {
+        const dbInfo = resolveDbConfigIfExists(options.config);
+        if (dbInfo) {
+          knexInstance = await createDbInstance(dbInfo.config, options.env);
+          const { createDatabase } = require('../../core/orm');
+          db = createDatabase({ knex: knexInstance });
+        }
+      } catch (err) {
+        console.warn('⚠️  Could not initialize database for command:', err.message);
+      }
+
+      // 2. Services
+      try {
+        const servicesDir = path.resolve(rootDir, 'services');
+        if (fs.existsSync(servicesDir)) {
+          const { createServiceRegistry } = require('../../src/services');
+          services = createServiceRegistry({ servicesDir, isDev: true });
+        }
+      } catch (err) {
+        console.warn('⚠️  Could not initialize service registry for command:', err.message);
+      }
+
+      // 3. Queue
+      let queue = null;
+      try {
+        const { createQueueDispatcher } = require('../../core/queue');
+        queue = createQueueDispatcher({ db: knexInstance });
+      } catch (_) {
+        queue = {
+          dispatch: async () => {},
+        };
+      }
+
+      console.log(`\n🚀 [webspresso run] Executing "${commandName}"...`);
+      const executionResult = await executeCommand(cmdDef, {
+        args,
+        flags,
+        db,
+        queue,
+        services,
+        mailer,
+        events,
+        logger: console,
+      });
+
+      // Cleanup
+      if (knexInstance && typeof knexInstance.destroy === 'function') {
+        try {
+          await knexInstance.destroy();
+        } catch (_) {}
+      }
+
+      if (executionResult.success) {
+        console.log(`\n✨ Command "${commandName}" completed successfully in ${executionResult.durationMs}ms.\n`);
+      } else {
+        console.error(`\n❌ Command "${commandName}" failed after ${executionResult.durationMs}ms:`);
+        if (executionResult.error) {
+          console.error(executionResult.error.stack || executionResult.error.message);
+        }
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+  parseRawArgs,
+};