@zintrust/core 0.4.16 → 0.4.17

package/src/cli/CLI.ts

@@ -0,0 +1,351 @@
+/**
+ * CLI - Main CLI Class
+ * Orchestrates all CLI commands using Commander
+ */
+
+import { AddCommand } from '@cli/commands/AddCommand';
+import { BroadcastWorkCommand } from '@cli/commands/BroadcastWorkCommand';
+import { BulletproofKeyGenerateCommand } from '@cli/commands/BulletproofKeyGenerateCommand';
+import { ConfigCommand } from '@cli/commands/ConfigCommand';
+import { ContainerProxiesCommand } from '@cli/commands/ContainerProxiesCommand';
+import { ContainerWorkersCommand } from '@cli/commands/ContainerWorkersCommand';
+import {
+  AddMigrationCommand,
+  CreateCommand,
+  CreateMigrationCommand,
+} from '@cli/commands/CreateCommand';
+import { D1LearnCommand } from '@cli/commands/D1LearnCommand';
+import { D1MigrateCommand } from '@cli/commands/D1MigrateCommand';
+import { DbSeedCommand } from '@cli/commands/DbSeedCommand';
+import { DebugCommand } from '@cli/commands/DebugCommand';
+import { DeployCommand } from '@cli/commands/DeployCommand';
+import { DeployContainerProxiesCommand } from '@cli/commands/DeployContainerProxiesCommand';
+import { DeployContainersProxyCommand } from '@cli/commands/DeployContainersProxyCommand';
+import { DeployContainerWorkersCommand } from '@cli/commands/DeployContainerWorkersCommand';
+import { DockerCommand } from '@cli/commands/DockerCommand';
+import { DockerPushCommand } from '@cli/commands/DockerPushCommand';
+import { DoctorArchitectureCommand } from '@cli/commands/DoctorArchitectureCommand';
+import { FixCommand } from '@cli/commands/FixCommand';
+import { InitContainerCommand } from '@cli/commands/InitContainerCommand';
+import { InitContainersProxyCommand } from '@cli/commands/InitContainersProxyCommand';
+import { InitEcosystemCommand } from '@cli/commands/InitEcosystemCommand';
+import { InitProducerCommand } from '@cli/commands/InitProducerCommand';
+import { InitProxyCommand } from '@cli/commands/InitProxyCommand';
+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 { MongoDBProxyCommand } from '@cli/commands/MongoDBProxyCommand';
+import { MySqlProxyCommand } from '@cli/commands/MySqlProxyCommand';
+import { NewCommand } from '@cli/commands/NewCommand';
+import { NotificationWorkCommand } from '@cli/commands/NotificationWorkCommand';
+import { PluginCommand } from '@cli/commands/PluginCommand';
+import { PostgresProxyCommand } from '@cli/commands/PostgresProxyCommand';
+import { PrepareCommand } from '@cli/commands/PrepareCommand';
+import { ProxyCommand } from '@cli/commands/ProxyCommand';
+import { PublishCommand } from '@cli/commands/PublishCommand';
+import { PutCommand } from '@cli/commands/PutCommand';
+import { QACommand } from '@cli/commands/QACommand';
+import { QueueCommand } from '@cli/commands/QueueCommand';
+import { QueueRecoveryCommand } from '@cli/commands/QueueRecoveryCommand';
+import { RedisProxyCommand } from '@cli/commands/RedisProxyCommand';
+import { ResourceControlCommand } from '@cli/commands/ResourceControlCommand';
+import { RoutesCommand } from '@cli/commands/RoutesCommand';
+import { ScheduleListCommand } from '@cli/commands/ScheduleListCommand';
+import { ScheduleRunCommand } from '@cli/commands/ScheduleRunCommand';
+import { ScheduleStartCommand } from '@cli/commands/ScheduleStartCommand';
+import { SecretsCommand } from '@cli/commands/SecretsCommand';
+import { SimulateCommand } from '@cli/commands/SimulateCommand';
+import { SmtpProxyCommand } from '@cli/commands/SmtpProxyCommand';
+import { SqlServerProxyCommand } from '@cli/commands/SqlServerProxyCommand';
+import { StartCommand } from '@cli/commands/StartCommand';
+import { TemplatesCommand } from '@cli/commands/TemplatesCommand';
+import { UpgradeCommand } from '@cli/commands/UpgradeCommand';
+import { ErrorHandler } from '@cli/ErrorHandler';
+import { OptionalCliCommandRegistry } from '@cli/OptionalCliCommandRegistry';
+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;
+}
+
+type CommandProvider = {
+  getCommand: () => Command;
+};
+
+const isCommandProvider = (command: unknown): command is CommandProvider => {
+  return (
+    typeof command === 'object' &&
+    command !== null &&
+    'getCommand' in command &&
+    typeof (command as { getCommand?: unknown }).getCommand === 'function'
+  );
+};
+
+const buildCommandRegistry = (): Array<Command | CommandProvider> => {
+  return [
+    NewCommand.create(),
+    UpgradeCommand.create(),
+    PrepareCommand,
+    InitContainerCommand.create(),
+    InitContainersProxyCommand.create(),
+    InitProxyCommand.create(),
+    InitProducerCommand.create(),
+    InitEcosystemCommand.create(),
+    DoctorArchitectureCommand.create(),
+    AddCommand.create(),
+    CreateCommand.create(),
+    CreateMigrationCommand.create(),
+    AddMigrationCommand.create(),
+    StartCommand.create(),
+    DockerCommand.create(),
+    DockerPushCommand.create(),
+    QueueCommand.create(),
+    QueueRecoveryCommand.create(),
+    ScheduleListCommand.create(),
+    ScheduleRunCommand.create(),
+    ScheduleStartCommand.create(),
+    BroadcastWorkCommand.create(),
+    NotificationWorkCommand.create(),
+    ResourceControlCommand,
+    MigrateWorkerCommand.create(),
+    MigrateCommand.create(),
+    DbSeedCommand.create(),
+    D1LearnCommand.create(),
+    D1MigrateCommand.create(),
+    DebugCommand.create(),
+    SecretsCommand.create(),
+    ConfigCommand.create(),
+    ContainerWorkersCommand.create(),
+    ContainerProxiesCommand.create(),
+    PluginCommand.create(),
+    PublishCommand.create(),
+    PutCommand.create(),
+    DeployCommand.create(),
+    DeployContainersProxyCommand.create(),
+    DeployContainerWorkersCommand.create(),
+    DeployContainerProxiesCommand.create(),
+    QACommand(),
+    FixCommand.create(),
+    KeyGenerateCommand.create(),
+    BulletproofKeyGenerateCommand.create(),
+    SimulateCommand,
+    TemplatesCommand,
+    MakeMailTemplateCommand.create(),
+    MakeNotificationTemplateCommand.create(),
+    RoutesCommand.create(),
+    JwtDevCommand,
+    ProxyCommand.create(),
+    MySqlProxyCommand.create(),
+    PostgresProxyCommand.create(),
+    MongoDBProxyCommand.create(),
+    SqlServerProxyCommand.create(),
+    RedisProxyCommand.create(),
+    SmtpProxyCommand.create(),
+    ...OptionalCliCommandRegistry.list(),
+  ];
+};
+/**
+ * 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 = buildCommandRegistry();
+
+  for (const command of commands) {
+    if (isCommandProvider(command)) {
+      program.addCommand(command.getCommand());
+    } else {
+      program.addCommand(command);
+    }
+  }
+
+  // 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/OptionalCliCommandRegistry.ts

@@ -0,0 +1,42 @@
+import { isObject } from '@helper/index';
+import type { Command } from 'commander';
+
+export type CliCommandProvider = {
+  getCommand: () => Command;
+  name?: string;
+};
+
+type GlobalWithRegistry = {
+  __zintrust_cli_command_registry__?: Map<string, CliCommandProvider>;
+};
+
+const globalWithRegistry = globalThis as unknown as GlobalWithRegistry;
+const registry =
+  globalWithRegistry.__zintrust_cli_command_registry__ ??
+  (globalWithRegistry.__zintrust_cli_command_registry__ = new Map<string, CliCommandProvider>());
+
+const isCliCommandProvider = (value: unknown): value is CliCommandProvider => {
+  return isObject(value) && typeof value['getCommand'] === 'function';
+};
+
+const normalizeId = (id: string): string => id.trim();
+
+export const OptionalCliCommandRegistry = Object.freeze({
+  register(id: string, provider: CliCommandProvider): void {
+    const normalizedId = normalizeId(id);
+    if (normalizedId === '' || !isCliCommandProvider(provider)) return;
+    registry.set(normalizedId, provider);
+  },
+
+  get(id: string): CliCommandProvider | undefined {
+    return registry.get(normalizeId(id));
+  },
+
+  has(id: string): boolean {
+    return registry.has(normalizeId(id));
+  },
+
+  list(): CliCommandProvider[] {
+    return Array.from(registry.values());
+  },
+});