@zintrust/core 0.1.27 → 0.1.28

package/src/cli/CLI.ts

@@ -0,0 +1,280 @@
+/**
+ * CLI - Main CLI Class
+ * Orchestrates all CLI commands using Commander
+ */
+
+import { AddCommand } from '@cli/commands/AddCommand';
+import { BroadcastWorkCommand } from '@cli/commands/BroadcastWorkCommand';
+import { ConfigCommand } from '@cli/commands/ConfigCommand';
+import {
+  AddMigrationCommand,
+  CreateCommand,
+  CreateMigrationCommand,
+} from '@cli/commands/CreateCommand';
+import { D1MigrateCommand } from '@cli/commands/D1MigrateCommand';
+import { DbSeedCommand } from '@cli/commands/DbSeedCommand';
+import { DebugCommand } from '@cli/commands/DebugCommand';
+import { FixCommand } from '@cli/commands/FixCommand';
+import { JwtDevCommand } from '@cli/commands/JwtDevCommand';
+import { KeyGenerateCommand } from '@cli/commands/KeyGenerateCommand';
+import { MakeMailTemplateCommand } from '@cli/commands/MakeMailTemplateCommand';
+import { MakeNotificationTemplateCommand } from '@cli/commands/MakeNotificationTemplateCommand';
+import { MigrateCommand } from '@cli/commands/MigrateCommand';
+import { MigrateWorkerCommand } from '@cli/commands/MigrateWorkerCommand';
+import { NewCommand } from '@cli/commands/NewCommand';
+import { NotificationWorkCommand } from '@cli/commands/NotificationWorkCommand';
+import { PluginCommand } from '@cli/commands/PluginCommand';
+import { PrepareCommand } from '@cli/commands/PrepareCommand';
+import { PublishCommand } from '@cli/commands/PublishCommand';
+import { QACommand } from '@cli/commands/QACommand';
+import { QueueCommand } from '@cli/commands/QueueCommand';
+import { ResourceControlCommand } from '@cli/commands/ResourceControlCommand';
+import { RoutesCommand } from '@cli/commands/RoutesCommand';
+import { SecretsCommand } from '@cli/commands/SecretsCommand';
+import { SimulateCommand } from '@cli/commands/SimulateCommand';
+import { StartCommand } from '@cli/commands/StartCommand';
+import { TemplatesCommand } from '@cli/commands/TemplatesCommand';
+import { UpgradeCommand } from '@cli/commands/UpgradeCommand';
+import { WorkerCommands } from '@cli/commands/WorkerCommands';
+import { ErrorHandler } from '@cli/ErrorHandler';
+import { VersionChecker } from '@cli/services/VersionChecker';
+import { esmDirname } from '@common/index';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { readFileSync } from '@node-singletons/fs';
+import { join } from '@node-singletons/path';
+import { Command } from 'commander';
+
+const __dirname = esmDirname(import.meta.url);
+
+export interface ICLI {
+  run(args: string[]): Promise<void>;
+  getProgram(): Command;
+}
+/**
+ * Load version from package.json
+ */
+const loadVersion = (): string => {
+  try {
+    const packagePath = join(__dirname, '../../package.json');
+    const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8')) as {
+      version?: string;
+    };
+    return typeof packageJson.version === 'string' ? packageJson.version : '1.0.0';
+  } catch (error) {
+    ErrorFactory.createCliError('Failed to load version from package.json', error);
+    // Use default version if package.json not found
+    return '1.0.0';
+  }
+};
+
+/**
+ * Setup program metadata
+ */
+const setupProgram = (program: Command, version: string): void => {
+  program
+    .name('zintrust')
+    .description('ZinTrust Framework CLI - Build production-grade TypeScript APIs')
+    .version(version, '-v, --version', 'Output version number')
+    .helpOption('-h, --help', 'Display help for command')
+    .usage('[command] [options]');
+
+  // Global error handling
+  program.exitOverride();
+};
+
+/**
+ * Register all available commands
+ */
+const registerCommands = (program: Command): void => {
+  const commands = [
+    NewCommand.create(),
+    UpgradeCommand.create(),
+    PrepareCommand,
+    AddCommand.create(),
+    CreateCommand.create(),
+    CreateMigrationCommand.create(),
+    AddMigrationCommand.create(),
+    StartCommand.create(),
+    QueueCommand.create(),
+    BroadcastWorkCommand.create(),
+    NotificationWorkCommand.create(),
+    ResourceControlCommand,
+    MigrateWorkerCommand.create(),
+    MigrateCommand.create(),
+    DbSeedCommand.create(),
+    D1MigrateCommand.create(),
+    DebugCommand.create(),
+    SecretsCommand.create(),
+    ConfigCommand.create(),
+    PluginCommand.create(),
+    PublishCommand.create(),
+    QACommand(),
+    FixCommand.create(),
+    KeyGenerateCommand.create(),
+    SimulateCommand,
+    TemplatesCommand,
+    MakeMailTemplateCommand.create(),
+    MakeNotificationTemplateCommand.create(),
+    RoutesCommand.create(),
+    JwtDevCommand,
+    // Worker management commands
+    WorkerCommands.createWorkerListCommand(),
+    WorkerCommands.createWorkerStatusCommand(),
+    WorkerCommands.createWorkerStartCommand(),
+    WorkerCommands.createWorkerStopCommand(),
+    WorkerCommands.createWorkerRestartCommand(),
+    WorkerCommands.createWorkerSummaryCommand(),
+  ];
+
+  for (const command of commands) {
+    program.addCommand(command.getCommand());
+  }
+
+  // Help command
+  program
+    .command('help [command]')
+    .description('Display help for a command')
+    .action((commandName: string) => {
+      if (commandName) {
+        const cmd = program.commands.find((c) => c.name() === commandName);
+        if (cmd) {
+          cmd.help();
+        } else {
+          Logger.error(`Unknown command: ${commandName}`);
+          program.help();
+        }
+      } else {
+        program.help();
+      }
+    });
+};
+
+/**
+ * Check if error is a commander error that can be safely ignored
+ */
+const isIgnorableCommanderError = (error: unknown): boolean => {
+  if (
+    error instanceof Error &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    error.code.startsWith('commander.')
+  ) {
+    const commanderError = error as unknown as Error & { exitCode: number };
+    return typeof commanderError.exitCode === 'number' && commanderError.exitCode === 0;
+  }
+  return false;
+};
+
+/**
+ * Get exit code from error
+ */
+const getExitCode = (error: unknown): number => {
+  if (
+    error instanceof Error &&
+    'exitCode' in error &&
+    typeof (error as unknown as { exitCode: unknown }).exitCode === 'number'
+  ) {
+    return (error as unknown as { exitCode: number }).exitCode;
+  }
+  return 1;
+};
+
+/**
+ * Handle CLI execution error
+ */
+const handleExecutionError = (error: unknown, version: string, log: boolean = true): void => {
+  if (isIgnorableCommanderError(error)) {
+    return;
+  }
+
+  if (error === version) {
+    return;
+  }
+
+  const exitCode = getExitCode(error);
+
+  if (error instanceof Error) {
+    ErrorHandler.handle(error, undefined, log);
+  }
+
+  // Check for commander-specific errors that need special handling
+  if (
+    error instanceof Error &&
+    'code' in error &&
+    typeof (error as Error & { code: unknown }).code === 'string' &&
+    (error as Error & { code: string }).code.startsWith('commander.')
+  ) {
+    ErrorFactory.createCliError('CLI execution failed', error);
+    process.exit(exitCode);
+    return;
+  }
+
+  throw ErrorFactory.createCliError('Unhandled CLI execution error', error);
+};
+
+/**
+ * Run CLI with arguments
+ */
+const runCLI = async (program: Command, version: string, args: string[]): Promise<void> => {
+  try {
+    // If version is requested, let Commander print it (no banner, fast/clean output).
+    if (args.includes('-v') || args.includes('--version')) {
+      await program.parseAsync(['node', 'zintrust', ...args]);
+      return;
+    }
+
+    // Always show banner for normal commands
+    ErrorHandler.banner(version);
+
+    // Run version check in background (non-blocking)
+    VersionChecker.runVersionCheck().catch((error: unknown) => {
+      // Version check should never crash the CLI
+      Logger.debug('Version check encountered an error', error);
+    });
+
+    // Show help if no arguments provided
+    if (args.length === 0) {
+      program.help();
+      return;
+    }
+
+    // Convert global aliases to subcommand format
+    // e.g., `zin -sim my-app` -> `zin simulate my-app`
+    let processedArgs = args;
+    if (args[0] === '-sim' || args[0] === '--sim') {
+      processedArgs = ['simulate', ...args.slice(1)];
+    }
+
+    await program.parseAsync(['node', 'zintrust', ...processedArgs]);
+  } catch (error) {
+    // Handle all errors with proper logging and exit logic
+    handleExecutionError(error, version, false);
+  }
+};
+
+/**
+ * CLI - Main CLI Class
+ * Orchestrates all CLI commands using Commander
+ *
+ * Notes:
+ * - `CLI.create()` is the preferred API (used by current bin scripts/tests).
+ * - `new CLI()` remains supported for backward compatibility with older bin scripts.
+ */
+export const CLI = Object.freeze({
+  create(): ICLI {
+    const program = new Command();
+    const version = loadVersion();
+
+    setupProgram(program, version);
+    registerCommands(program);
+
+    const run = async (args: string[]): Promise<void> => runCLI(program, version, args);
+    const getProgram = (): Command => program;
+
+    return Object.freeze({
+      run,
+      getProgram,
+    });
+  },
+});

package/src/cli/ErrorHandler.ts

@@ -0,0 +1,130 @@
+/**
+ * Error Handler - CLI Error Formatting & Exit Codes
+ * Provides consistent error formatting and proper Unix exit codes
+ * Sealed namespace with immutable error handling methods
+ */
+
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import chalk from 'chalk';
+
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  RUNTIME_ERROR: 1,
+  USAGE_ERROR: 2,
+} as const;
+
+/**
+ * Format and display error
+ * Exit codes: 0 (success), 1 (runtime error), 2 (usage error)
+ */
+const handleError = (
+  error: Error | string,
+  exitCode: number = EXIT_CODES.RUNTIME_ERROR,
+  log: boolean = true
+): void => {
+  const message = typeof error === 'string' ? error : error.message;
+
+  if (log) {
+    Logger.error(message);
+  }
+  process.exit(exitCode);
+};
+
+/**
+ * Display usage error with help hint
+ */
+const usageError = (message: string, command?: string): void => {
+  const helpText = `Run: zin ${command} --help`;
+  const hint = command !== undefined && command !== '' ? `\n${chalk.gray(helpText)}` : '';
+
+  Logger.error(`${message}${hint}`);
+
+  process.exit(EXIT_CODES.USAGE_ERROR);
+};
+
+/**
+ * Display info message
+ */
+const displayInfo = (message: string): void => {
+  const formatted = `${chalk.blue('[i]')} ${message}`;
+  Logger.info(formatted);
+};
+
+/**
+ * Display framework banner
+ */
+const displayBanner = (version: string): void => {
+  /* eslint-disable no-console */
+  const framework = 'ZinTrust Framework';
+  const bannerWidth = 46;
+  const env = Env.NODE_ENV ?? 'development';
+  const db = Env.DB_CONNECTION ?? 'sqlite';
+
+  const border = chalk.cyanBright;
+  const label = chalk.bold.white;
+  const frameworkValue = chalk.bold.cyanBright;
+  const versionValue = chalk.bold.greenBright;
+  const envValue = chalk.bold.yellowBright;
+  const dbValue = chalk.bold.magentaBright;
+
+  console.log(border('┌' + '─'.repeat(bannerWidth) + '┐'));
+  console.log(
+    `${border('│')} ${label('Framework: ')}${frameworkValue(
+      framework.padEnd(bannerWidth - 12)
+    )} ${border('│')}`
+  );
+  console.log(
+    `${border('│')} ${label('Version:   ')}${versionValue(
+      version.padEnd(bannerWidth - 12)
+    )} ${border('│')}`
+  );
+  console.log(
+    `${border('│')} ${label('Env:       ')}${envValue(env.padEnd(bannerWidth - 12))} ${border('│')}`
+  );
+  console.log(
+    `${border('│')} ${label('Database:  ')}${dbValue(db.padEnd(bannerWidth - 12))} ${border('│')}`
+  );
+  console.log(border('└' + '─'.repeat(bannerWidth) + '┘'));
+  console.log();
+  /* eslint-enable no-console */
+};
+
+/**
+ * Display success message
+ */
+const displaySuccess = (message: string): void => {
+  const formatted = `${chalk.green('[✓]')} ${message}`;
+  Logger.info(formatted);
+};
+
+/**
+ * Display warning message
+ */
+const displayWarning = (message: string): void => {
+  const formatted = `${chalk.yellow('[!]')} ${message}`;
+  Logger.warn(formatted);
+};
+
+/**
+ * Display debug message (only if verbose)
+ */
+const displayDebug = (message: string, verbose: boolean = false): void => {
+  if (verbose) {
+    const formatted = `${chalk.gray('[DEBUG]')} ${message}`;
+    Logger.debug(formatted);
+  }
+};
+
+/**
+ * ErrorHandler namespace - sealed for immutability
+ */
+export const ErrorHandler = Object.freeze({
+  handle: handleError,
+  usageError,
+  info: displayInfo,
+  success: displaySuccess,
+  warn: displayWarning,
+  debug: displayDebug,
+  banner: displayBanner,
+});

package/src/cli/PromptHelper.ts

@@ -0,0 +1,203 @@
+/**
+ * Prompt Helper - Interactive CLI Prompts
+ * Provides reusable prompt utilities using inquirer
+ */
+
+import inquirer from 'inquirer';
+
+export interface PromptOptions {
+  interactive?: boolean;
+  defaults?: Record<string, unknown>;
+}
+
+/**
+ * Prompt Helper Factory
+ * Sealed namespace for immutability
+ */
+export const PromptHelper = Object.freeze({
+  /**
+   * Generic prompt method for custom questions
+   */
+  async prompt(questions: unknown): Promise<Record<string, unknown>> {
+    return (inquirer as { prompt: (q: unknown) => Promise<Record<string, unknown>> }).prompt(
+      questions
+    );
+  },
+
+  /**
+   * Ask for project name
+   */
+  async projectName(defaultName?: string, interactive: boolean = true): Promise<string> {
+    if (!interactive && defaultName !== undefined && defaultName !== '') {
+      return defaultName;
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'projectName',
+        message: 'Project name:',
+        default: defaultName ?? 'my-zintrust-app',
+        validate: (input: string): string | boolean => {
+          if (!input.trim()) return 'Project name cannot be empty';
+          if (!/^[a-z\d\-_]+$/i.test(input))
+            return 'Project name can only contain letters, numbers, hyphens, and underscores';
+          return true;
+        },
+      },
+    ]);
+
+    return answer.projectName;
+  },
+
+  /**
+   * Ask for database type
+   */
+  async databaseType(
+    defaultDb: string = 'postgresql',
+    interactive: boolean = true
+  ): Promise<string> {
+    if (!interactive) {
+      return defaultDb;
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'database',
+        message: 'Select database:',
+        choices: [
+          { name: 'PostgreSQL — Production-ready relational DB', value: 'postgresql' },
+          { name: 'MySQL — Production-ready relational DB', value: 'mysql' },
+          { name: 'SQLite — Local dev (file-based)', value: 'sqlite' },
+          { name: 'd1-proxy — Cloudflare D1 via HTTPS proxy', value: 'd1-remote' },
+        ],
+        default: defaultDb,
+      },
+    ]);
+
+    return answer.database;
+  },
+
+  /**
+   * Ask for port number
+   */
+  async port(defaultPort: number = 7777, interactive: boolean = true): Promise<number> {
+    if (!interactive) {
+      return defaultPort;
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'number',
+        name: 'port',
+        message: 'Server port:',
+        default: defaultPort,
+        validate: (input: number): string | boolean => {
+          if (input < 1 || input > 65535) return 'Port must be between 1 and 65535';
+          return true;
+        },
+      },
+    ]);
+
+    return answer.port;
+  },
+
+  /**
+   * Ask for feature selection
+   */
+  async selectFeatures(
+    availableFeatures: string[] = ['auth', 'payments', 'notifications'],
+    interactive: boolean = true
+  ): Promise<string[]> {
+    if (!interactive) {
+      return availableFeatures.slice(0, 1);
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'features',
+        message: 'Select features to include:',
+        choices: availableFeatures,
+        default: [],
+      },
+    ]);
+
+    return answer.features;
+  },
+
+  /**
+   * Confirm action
+   */
+  async confirm(
+    message: string,
+    defaultConfirm: boolean = true,
+    interactive: boolean = true
+  ): Promise<boolean> {
+    if (!interactive) {
+      return defaultConfirm;
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmed',
+        message,
+        default: defaultConfirm,
+      },
+    ]);
+
+    return answer.confirmed;
+  },
+
+  /**
+   * Choose from list
+   */
+  async chooseFrom(
+    message: string,
+    choices: string[],
+    defaultChoice: string = choices[0],
+    interactive: boolean = true
+  ): Promise<string> {
+    if (!interactive) {
+      return defaultChoice;
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'choice',
+        message,
+        choices,
+        default: defaultChoice,
+      },
+    ]);
+
+    return answer.choice;
+  },
+
+  /**
+   * Get text input
+   */
+  async textInput(
+    message: string,
+    defaultValue: string = '',
+    interactive: boolean = true
+  ): Promise<string> {
+    if (!interactive) {
+      return defaultValue;
+    }
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'input',
+        message,
+        default: defaultValue,
+      },
+    ]);
+
+    return answer.input;
+  },
+});