@zintrust/core 0.1.26 → 0.1.28

package/src/cli/commands/D1MigrateCommand.ts

@@ -0,0 +1,98 @@
+/**
+ * D1 Migrate Command
+ * Run Cloudflare D1 migrations using Wrangler
+ */
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { WranglerD1 } from '@cli/d1/WranglerD1';
+import { resolveNpmPath } from '@common/index';
+import { appConfig } from '@config/app';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { Command } from 'commander';
+
+const RESOLVED_VOID: Promise<void> = Promise.resolve();
+
+type ID1MigrateCommand = IBaseCommand & {
+  resolveNpmPath: () => string;
+  getSafeEnv: () => NodeJS.ProcessEnv;
+  runWrangler: (args: string[]) => Promise<string>;
+};
+
+const runWrangler = async (cmd: IBaseCommand, args: string[]): Promise<string> => {
+  // Back-compat entrypoint for tests; we only use this for D1 migrations apply.
+  const dbName = args[3];
+  const mode = args[4];
+  const isLocal = mode === '--local';
+  await RESOLVED_VOID;
+  return WranglerD1.applyMigrations({ cmd, dbName, isLocal });
+};
+
+const executeD1Migrate = async (cmd: IBaseCommand, options: CommandOptions): Promise<void> => {
+  const isLocal = options['local'] === true || options['remote'] !== true;
+  const dbName =
+    typeof options['database'] === 'string' && options['database'].trim() !== ''
+      ? options['database']
+      : 'zintrust_db';
+
+  cmd.info(`Running D1 migrations for ${dbName} (${isLocal ? 'local' : 'remote'})...`);
+
+  await RESOLVED_VOID;
+
+  try {
+    const output = WranglerD1.applyMigrations({ cmd, dbName, isLocal });
+    if (output !== '') cmd.info(output);
+    cmd.info('✓ D1 migrations completed successfully');
+  } catch (error: unknown) {
+    Logger.error('D1 Migration failed', error);
+    ErrorFactory.createCliError('D1 Migration failed', error);
+
+    const err = error as { stdout?: Buffer; stderr?: Buffer };
+    if (err.stdout !== undefined && err.stdout.length > 0) cmd.info(err.stdout.toString());
+    if (err.stderr !== undefined && err.stderr.length > 0)
+      Logger.error('Wrangler stderr', err.stderr.toString());
+
+    if (err.stderr !== undefined && err.stderr.length > 0)
+      ErrorFactory.createCliError('Wrangler stderr', err.stderr.toString());
+
+    throw error;
+  }
+};
+
+/**
+ * D1 Migrate Command
+ * Run Cloudflare D1 migrations using Wrangler
+ */
+
+/**
+ * D1 Migrate Command Factory
+ */
+export const D1MigrateCommand = Object.freeze({
+  /**
+   * Create a new D1 migrate command instance
+   */
+  create(): IBaseCommand {
+    const addOptions = (command: Command): void => {
+      command
+        .option('--local', 'Run against local D1 database (via wrangler dev)')
+        .option('--remote', 'Run against remote D1 database (production)')
+        .option(
+          '--database <name>',
+          'Wrangler D1 database binding name (from wrangler.toml). Defaults to "zintrust_db"'
+        );
+    };
+
+    const cmd = BaseCommand.create<ID1MigrateCommand>({
+      name: 'd1:migrate',
+      description: 'Run Cloudflare D1 migrations',
+      addOptions,
+      execute: async (options: CommandOptions): Promise<void> => executeD1Migrate(cmd, options),
+    });
+
+    cmd.resolveNpmPath = (): string => resolveNpmPath();
+    cmd.getSafeEnv = (): NodeJS.ProcessEnv => appConfig.getSafeEnv();
+    cmd.runWrangler = async (args: string[]): Promise<string> => runWrangler(cmd, args);
+
+    return cmd;
+  },
+});

package/src/cli/commands/DbSeedCommand.ts

@@ -0,0 +1,181 @@
+/**
+ * Db Seed Command
+ * Run database seeders from database/seeders
+ */
+
+import { SeederDiscovery } from '@/seeders/SeederDiscovery';
+import { SeederLoader } from '@/seeders/SeederLoader';
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { confirmProductionRun, mapConnectionToOrmConfig } from '@cli/utils/DatabaseCliUtils';
+import { databaseConfig } from '@config/database';
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { resetDatabase, useDatabase } from '@orm/Database';
+import type { Command } from 'commander';
+
+type ServiceArgs = { service: string | undefined; includeGlobal: boolean };
+
+const addSeedOptions = (command: Command): void => {
+  command
+    .option(
+      '--dir <path>',
+      'Seeders directory (relative to project root)',
+      databaseConfig.seeders.directory
+    )
+    .option('--service <domain/name>', 'Run global + service-local seeders')
+    .option('--only-service <domain/name>', 'Run only service-local seeders')
+    .option('--no-interactive', 'Skip interactive prompts');
+};
+
+const getInteractive = (options: CommandOptions): boolean =>
+  options['interactive'] !== false && Env.CI !== 'true';
+
+const ensureNonD1Driver = (driver: string): void => {
+  if (driver === 'd1' || driver === 'd1-remote') {
+    throw ErrorFactory.createCliError(
+      'This project is configured for D1. Seeding via `zin db:seed` is not supported yet.'
+    );
+  }
+};
+
+const getServiceArgs = (options: CommandOptions): ServiceArgs => {
+  let serviceArg: string | undefined;
+
+  if (typeof options['onlyService'] === 'string') {
+    serviceArg = String(options['onlyService']);
+  } else if (typeof options['service'] === 'string') {
+    serviceArg = String(options['service']);
+  }
+
+  const includeGlobal = typeof options['onlyService'] !== 'string';
+  return { service: serviceArg, includeGlobal };
+};
+
+const parseServiceRef = (raw: string): { domain: string; name: string } => {
+  const trimmed = raw.trim();
+  const parts = trimmed.split('/').filter((p) => p.trim().length > 0);
+  if (parts.length !== 2) {
+    throw ErrorFactory.createCliError(
+      `Invalid service reference: '${raw}'. Expected format: <domain>/<name>`
+    );
+  }
+  return { domain: parts[0], name: parts[1] };
+};
+
+const normalizeSeederNameArg = (raw: string): string => {
+  const trimmed = raw.trim();
+  if (trimmed.endsWith('.ts')) return trimmed.slice(0, -3);
+  if (trimmed.endsWith('.js')) return trimmed.slice(0, -3);
+  return trimmed;
+};
+
+const selectSeederFiles = (files: string[], seederName: string | undefined): string[] => {
+  if (seederName !== undefined) {
+    return files.filter((filePath) => {
+      const base = filePath.split('/').pop() ?? '';
+      const withoutExt = base.replace(/\.(ts|js)$/u, '');
+      return withoutExt === seederName;
+    });
+  }
+
+  const databaseSeeder = files.find((filePath) => {
+    const base = filePath.split('/').pop() ?? '';
+    const withoutExt = base.replace(/\.(ts|js)$/u, '');
+    return withoutExt === 'DatabaseSeeder';
+  });
+
+  if (databaseSeeder !== undefined) return [databaseSeeder];
+  return files;
+};
+
+const executeSeed = async (options: CommandOptions, cmd: IBaseCommand): Promise<void> => {
+  const interactive = getInteractive(options);
+  const okToProceed = await confirmProductionRun({
+    cmd,
+    interactive,
+    message: 'NODE_ENV=production. Continue running seeders?',
+  });
+  if (!okToProceed) return;
+
+  const conn = databaseConfig.getConnection();
+  ensureNonD1Driver(conn.driver);
+
+  const ormConfig = mapConnectionToOrmConfig(conn);
+  const db = useDatabase(ormConfig, 'default');
+
+  const dirOpt =
+    typeof options['dir'] === 'string' ? options['dir'] : databaseConfig.seeders.directory;
+
+  const { service, includeGlobal } = getServiceArgs(options);
+  const projectRoot = process.cwd();
+
+  const globalDir = SeederDiscovery.resolveDir(projectRoot, dirOpt);
+  const globalFiles = includeGlobal ? SeederDiscovery.listSeederFiles(globalDir) : [];
+
+  let serviceFiles: string[] = [];
+  if (service !== undefined) {
+    const { domain, name } = parseServiceRef(service);
+    const serviceRoot = `${projectRoot}/services/${domain}/${name}`;
+    const serviceDir = SeederDiscovery.resolveDir(serviceRoot, dirOpt);
+    serviceFiles = SeederDiscovery.listSeederFiles(serviceDir);
+  }
+
+  const seederArgRaw = Array.isArray(options.args) ? options.args[0] : undefined;
+  const seederName =
+    typeof seederArgRaw === 'string' && seederArgRaw.trim() !== ''
+      ? normalizeSeederNameArg(seederArgRaw)
+      : undefined;
+
+  const selectedGlobal = selectSeederFiles(globalFiles, seederName);
+  const selectedService = selectSeederFiles(serviceFiles, seederName);
+  const selected = [...selectedGlobal, ...selectedService];
+
+  if (seederName !== undefined) {
+    if (selected.length === 0) {
+      throw ErrorFactory.createCliError(
+        `Seeder not found: ${seederName} (dir=${dirOpt}, global=${globalFiles.length}, service=${serviceFiles.length})`
+      );
+    }
+
+    if (selected.length > 1) {
+      throw ErrorFactory.createCliError(
+        `Seeder name is ambiguous: ${seederName} (matches=${selected.length}). Use --only-service or adjust name.`
+      );
+    }
+  }
+
+  if (selected.length === 0) {
+    cmd.info('No seeders found.');
+    return;
+  }
+
+  cmd.info(`Running ${selected.length} seeder(s)...`);
+  await db.connect();
+
+  try {
+    await selected.reduce(async (previous, filePath) => {
+      await previous;
+
+      const loaded = await SeederLoader.load(filePath);
+      cmd.info(`→ ${loaded.name}`);
+      await loaded.run(db);
+      cmd.success(`✓ Seeded: ${loaded.name}`);
+    }, Promise.resolve());
+  } finally {
+    await resetDatabase();
+  }
+};
+
+export const DbSeedCommand = Object.freeze({
+  create(): IBaseCommand {
+    const cmd: IBaseCommand = BaseCommand.create({
+      name: 'db:seed',
+      description: 'Run database seeders',
+      addOptions: addSeedOptions,
+      execute: async (options: CommandOptions): Promise<void> => executeSeed(options, cmd),
+    });
+
+    return cmd;
+  },
+});

package/src/cli/commands/DebugCommand.ts

@@ -0,0 +1,71 @@
+/**
+ * Debug Command
+ * Launch debug mode with profiling and monitoring
+ */
+
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { Dashboard } from '@cli/debug/Dashboard';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { Command } from 'commander';
+
+type DashboardHandle = {
+  start(): void;
+  stop(): void;
+};
+
+type IDebugCommand = IBaseCommand & {
+  dashboard: DashboardHandle | undefined;
+};
+
+const addOptions = (command: Command): void => {
+  command
+    .option('--port <number>', 'Debug server port', '3000')
+    .option('--enable-profiling', 'Enable memory profiling')
+    .option('--enable-tracing', 'Enable request tracing');
+};
+
+const executeDebug = (cmd: IDebugCommand, options: CommandOptions): void => {
+  cmd.info(`Debug command executed with options: ${JSON.stringify(options)}`);
+  try {
+    cmd.dashboard = Dashboard.create() as unknown as DashboardHandle;
+    cmd.dashboard.start();
+
+    process.on('SIGINT', () => {
+      cmd.dashboard?.stop();
+      process.exit(0);
+    });
+  } catch (error) {
+    cmd.dashboard?.stop();
+    throw ErrorFactory.createTryCatchError(`Debug failed: ${(error as Error).message}`, error);
+  }
+};
+
+/**
+ * Debug Command
+ * Launch debug mode with profiling and monitoring
+ */
+
+const create = (): IBaseCommand => {
+  const ext = (options: CommandOptions): void => executeDebug(cmd, options);
+  const cmd = BaseCommand.create<IDebugCommand>({
+    name: 'debug',
+    description: 'Launch debug mode with real-time monitoring dashboard',
+    addOptions,
+    execute: ext,
+  });
+
+  cmd.dashboard = undefined;
+
+  return cmd;
+};
+
+/**
+ * Debug Command Factory
+ */
+export const DebugCommand = Object.freeze({
+  /**
+   * Create a new debug command instance
+   */
+  create,
+});

package/src/cli/commands/FixCommand.ts

@@ -0,0 +1,84 @@
+/**
+ * Fix Command - Automated Code Cleanup
+ * Runs ESLint fix and other automated tools
+ */
+
+import { appConfig } from '@/config';
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { resolveNpmPath } from '@common/index';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { execFileSync } from '@node-singletons/child-process';
+import type { Command } from 'commander';
+
+type IFixCommand = IBaseCommand & {
+  resolveNpmPath: () => string;
+  getSafeEnv: () => NodeJS.ProcessEnv;
+  runNpmExec: (args: string[]) => void;
+};
+
+const runNpmScript = (cmd: IBaseCommand, args: string[]): void => {
+  const npmPath = resolveNpmPath();
+  cmd.debug(`Executing: npm run ${args.join(' ')}`);
+  execFileSync(npmPath, ['run', ...args], {
+    stdio: 'inherit',
+    encoding: 'utf8',
+    env: appConfig.getSafeEnv(),
+  });
+};
+
+const executeFix = (cmd: IBaseCommand, options: CommandOptions): void => {
+  cmd.info('Starting automated code fixes...');
+
+  try {
+    const isDryRun = options['dryRun'] === true;
+
+    cmd.info('Running ESLint fix...');
+    try {
+      runNpmScript(cmd, ['lint', '--', isDryRun ? '--fix-dry-run' : '--fix']);
+    } catch (error) {
+      ErrorFactory.createCliError('ESLint fix failed', error);
+      cmd.warn('ESLint fix encountered some issues, continuing...');
+    }
+
+    cmd.info('Running Prettier format...');
+    try {
+      runNpmScript(cmd, ['format']);
+    } catch (error) {
+      ErrorFactory.createCliError('Prettier format failed', error);
+      cmd.warn('Prettier format encountered some issues.');
+    }
+
+    cmd.success('Code fixes completed successfully!');
+  } catch (error) {
+    ErrorFactory.createCliError('Fix command failed', error);
+    cmd.warn('Some fixes could not be applied automatically.');
+  }
+};
+
+/**
+ * Fix Command Factory
+ */
+export const FixCommand = Object.freeze({
+  /**
+   * Create a new fix command instance
+   */
+  create(): IBaseCommand {
+    const addOptions = (command: Command): void => {
+      command.option('--dry-run', 'Show what would be fixed without applying changes');
+    };
+
+    const cmd = BaseCommand.create<IFixCommand>({
+      name: 'fix',
+      description: 'Run automated code fixes',
+      addOptions,
+      execute: (options: CommandOptions): void => executeFix(cmd, options),
+    });
+
+    cmd.resolveNpmPath = (): string => resolveNpmPath();
+    cmd.getSafeEnv = (): NodeJS.ProcessEnv => appConfig.getSafeEnv();
+    cmd.runNpmExec = (args: string[]): void => runNpmScript(cmd, args);
+
+    return cmd;
+  },
+});

package/src/cli/commands/JwtDevCommand.ts

@@ -0,0 +1,154 @@
+/**
+ * JWT Dev Command
+ * Mint a local development JWT for quick manual API testing.
+ */
+
+import { BaseCommand, type CommandOptions, type IBaseCommand } from '@cli/BaseCommand';
+import { appConfig } from '@config/app';
+import { securityConfig } from '@config/security';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { JwtManager, type IJwtManager, type JwtPayload } from '@security/JwtManager';
+import type { Command } from 'commander';
+
+type JwtDevCommandOptions = CommandOptions & {
+  sub?: string;
+  email?: string;
+  role?: string;
+  expires?: string;
+  json?: boolean;
+  allowProduction?: boolean;
+};
+
+const parseExpiresToSeconds = (value: unknown): number => {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  if (raw === '') return 60 * 60;
+
+  // Allow raw seconds
+  if (/^\d+$/.test(raw)) {
+    const seconds = Number.parseInt(raw, 10);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+      throw ErrorFactory.createCliError(`Invalid --expires '${raw}'. Must be > 0 seconds.`);
+    }
+    return seconds;
+  }
+
+  const match = /^(\d+)([smhd])$/i.exec(raw);
+  if (!match) {
+    throw ErrorFactory.createCliError(
+      `Invalid --expires '${raw}'. Use seconds (e.g. 3600) or a duration like 30m, 1h, 7d.`
+    );
+  }
+
+  const amount = Number.parseInt(match[1] ?? '', 10);
+  const unit = (match[2] ?? '').toLowerCase();
+
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw ErrorFactory.createCliError(`Invalid --expires '${raw}'. Must be > 0.`);
+  }
+
+  const multipliers: Record<string, number> = {
+    s: 1,
+    m: 60,
+    h: 60 * 60,
+    d: 24 * 60 * 60,
+  };
+
+  const multiplier = multipliers[unit];
+  if (multiplier === undefined) {
+    throw ErrorFactory.createCliError(
+      `Invalid --expires '${raw}'. Supported units: s, m, h, d (e.g. 30m, 1h).`
+    );
+  }
+
+  return amount * multiplier;
+};
+
+const assertNotProduction = (allowProduction: unknown): void => {
+  if (!appConfig.isProduction()) return;
+  if (allowProduction === true) return;
+
+  throw ErrorFactory.createCliError(
+    "Refusing to mint a dev JWT in production. Use --allow-production only if you know what you're doing."
+  );
+};
+
+const createJwt = (payload: JwtPayload, expiresInSeconds: number): string => {
+  const algorithm = securityConfig.jwt.algorithm;
+  const secret = securityConfig.jwt.secret;
+
+  const jwt: IJwtManager = JwtManager.create();
+
+  if (algorithm === 'HS256' || algorithm === 'HS512') {
+    jwt.setHmacSecret(secret);
+  } else {
+    throw ErrorFactory.createCliError(
+      `JWT algorithm '${algorithm}' is not supported by zin jwt:dev (HS256/HS512 only).`
+    );
+  }
+
+  return jwt.sign(payload, {
+    algorithm,
+    expiresIn: expiresInSeconds,
+    issuer: securityConfig.jwt.issuer,
+    audience: securityConfig.jwt.audience,
+    subject: typeof payload.sub === 'string' ? payload.sub : undefined,
+    jwtId: jwt.generateJwtId(),
+  });
+};
+
+export const JwtDevCommand: IBaseCommand = Object.freeze(
+  BaseCommand.create({
+    name: 'jwt:dev',
+    description: 'Mint a local development JWT (for manual API testing)',
+    aliases: ['jwt:token', 'jwt:mint'],
+    addOptions: (command: Command) => {
+      command
+        .option('--sub <sub>', 'JWT subject claim (default: 1)', '1')
+        .option('--email <email>', 'Email claim')
+        .option('--role <role>', 'Role claim')
+        .option('--expires <duration>', "Expiry: seconds or 30m/1h/7d (default: '1h')", '1h')
+        .option('--json', 'Output machine-readable JSON')
+        .option('--allow-production', 'Allow running in production (dangerous)');
+    },
+    execute: (options: JwtDevCommandOptions): void => {
+      assertNotProduction(options.allowProduction);
+
+      const expiresInSeconds = parseExpiresToSeconds(options.expires);
+
+      const payload: JwtPayload = {
+        ...(typeof options.sub === 'string' && options.sub.trim() !== ''
+          ? { sub: options.sub.trim() }
+          : {}),
+        ...(typeof options.email === 'string' && options.email.trim() !== ''
+          ? { email: options.email.trim() }
+          : {}),
+        ...(typeof options.role === 'string' && options.role.trim() !== ''
+          ? { role: options.role.trim() }
+          : {}),
+      };
+
+      const token = createJwt(payload, expiresInSeconds);
+
+      /* eslint-disable no-console */
+      if (options.json === true) {
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        console.log(
+          JSON.stringify({
+            token,
+            algorithm: securityConfig.jwt.algorithm,
+            expiresIn: expiresInSeconds,
+            issuedAt: nowSeconds,
+            expiresAt: nowSeconds + expiresInSeconds,
+            payload,
+          })
+        );
+        return;
+      }
+
+      console.log(token);
+      /* eslint-enable no-console */
+    },
+  })
+);
+
+export default JwtDevCommand;

package/src/cli/commands/KeyGenerateCommand.ts

@@ -0,0 +1,86 @@
+/**
+ * Key Generate Command
+ * Generates and sets the application key
+ */
+
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { Logger } from '@config/logger';
+import * as crypto from '@node-singletons/crypto';
+import { fsPromises as fs } from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+import type { Command } from 'commander';
+
+export const KeyGenerateCommand = Object.freeze({
+  create(): IBaseCommand {
+    return BaseCommand.create({
+      name: 'key:generate',
+      description: 'Set the application key',
+      addOptions: (command: Command) => {
+        command.option('--show', 'Display the key instead of modifying files');
+        command.option('--force', 'Force the operation to run when in production');
+      },
+      execute: async (options: CommandOptions) => {
+        const key = generateRandomKey();
+
+        if (options['show'] === true) {
+          Logger.info(`Application key: [${key}]`);
+          return;
+        }
+
+        const envPath = path.resolve(process.cwd(), '.env');
+
+        try {
+          let envContent = '';
+          try {
+            envContent = await fs.readFile(envPath, 'utf-8');
+          } catch (error) {
+            Logger.warn('Could not read .env file, attempting to create from example', { error });
+            // If .env doesn't exist, try to copy .env.example
+            const examplePath = path.resolve(process.cwd(), '.env.example');
+            try {
+              envContent = await fs.readFile(examplePath, 'utf-8');
+              await fs.writeFile(envPath, envContent);
+              Logger.info('.env file created from .env.example');
+            } catch (copyError) {
+              Logger.error('Failed to create .env from example', { error: copyError });
+              Logger.warn(
+                '.env file not found and .env.example not found. Creating new .env file.'
+              );
+            }
+          }
+
+          // Backup existing key if present
+          const appKeyMatch = /^APP_KEY=(.*)$/m.exec(envContent);
+          const currentKey = appKeyMatch?.[1]?.trim();
+
+          if (currentKey !== undefined && currentKey.length > 0) {
+            const oldKey = currentKey;
+
+            if (envContent.includes('APP_KEY_BK=')) {
+              envContent = envContent.replace(/^APP_KEY_BK=.*$/m, `APP_KEY_BK=${oldKey}`);
+            } else {
+              envContent += `\nAPP_KEY_BK=${oldKey}`;
+            }
+          }
+
+          if (envContent.includes('APP_KEY=')) {
+            const regex = /^APP_KEY=.*/m;
+            envContent = envContent.replace(regex, `APP_KEY=${key}`);
+          } else {
+            envContent += `\nAPP_KEY=${key}\n`;
+          }
+
+          await fs.writeFile(envPath, envContent);
+          Logger.info(`Application key set successfully. [${key}]`);
+        } catch (error) {
+          Logger.error('Failed to update .env file', error);
+        }
+      },
+    });
+  },
+});
+
+function generateRandomKey(): string {
+  return 'base64:' + crypto.randomBytes(32).toString('base64');
+}

package/src/cli/commands/LogsCleanupCommand.ts

@@ -0,0 +1,24 @@
+import { BaseCommand, type IBaseCommand } from '@cli/BaseCommand';
+import { cleanLogsOnce } from '@config/logger';
+
+export const LogsCleanupCommand = Object.freeze({
+  create(): IBaseCommand {
+    // Create the command first, then assign the execute implementation so we can
+    // safely reference the instance (`cmd`) from inside the handler.
+    const cmd = BaseCommand.create({
+      name: 'logs:cleanup',
+      description: 'Run a one-off log cleanup based on configured retention',
+      execute: async () => {},
+    });
+
+    cmd.execute = async (_options) => {
+      cmd.info('Running log cleanup...');
+      const deleted = await cleanLogsOnce();
+      cmd.info(`Deleted ${deleted.length} log files`);
+    };
+
+    return cmd;
+  },
+});
+
+export default LogsCleanupCommand;