@zintrust/core 2.3.1 → 2.4.1

package/bin/zintrust-main.ts

@@ -0,0 +1,482 @@
+/**
+ * ZinTrust CLI - Main Entry Point (hashbang-free)
+ *
+ * This module contains the CLI implementation without a hashbang so that it can
+ * be imported by other bin shortcuts (zin/z/zt) without parse errors.
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+type ProjectLocalCliTarget = {
+  binPath: string;
+  packageRoot: string;
+};
+
+type LoggerLike = {
+  warn: (message: string, details?: unknown) => void;
+  debug: (message: string, details?: unknown) => void;
+  error: (message: string, details?: unknown) => void;
+};
+
+const CLI_HANDOFF_ENV_KEY = 'ZINTRUST_CLI_HANDOFF';
+const require = createRequire(import.meta.url);
+
+const loadLogger = async (): Promise<LoggerLike | undefined> => {
+  try {
+    const { Logger } = await import('@config/logger');
+    return Logger;
+  } catch {
+    return undefined;
+  }
+};
+
+const getCurrentPackageRoot = (): string => {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+};
+
+const getRealPath = (targetPath: string): string => {
+  try {
+    return fs.realpathSync(targetPath);
+  } catch {
+    return path.resolve(targetPath);
+  }
+};
+
+const isWithinDirectory = (targetPath: string, possibleParentPath: string): boolean => {
+  const normalizedTarget = getRealPath(targetPath);
+  const normalizedParent = getRealPath(possibleParentPath);
+
+  if (normalizedTarget === normalizedParent) return true;
+
+  const relativePath = path.relative(normalizedParent, normalizedTarget);
+  return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+};
+
+const findProjectLocalCliTarget = (cwd: string): ProjectLocalCliTarget | undefined => {
+  let currentDir = path.resolve(cwd);
+
+  while (true) {
+    const packageRoot = path.join(currentDir, 'node_modules', '@zintrust', 'core');
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    const binCandidates = [
+      path.join(packageRoot, 'bin', 'zin.js'),
+      path.join(packageRoot, 'bin', 'zin.mjs'),
+      path.join(packageRoot, 'bin', 'zin.cjs'),
+      path.join(packageRoot, 'bin', 'zin.ts'),
+    ];
+
+    if (fs.existsSync(packageJsonPath)) {
+      const binPath = binCandidates.find((candidate) => fs.existsSync(candidate));
+      if (binPath !== undefined) {
+        return { binPath, packageRoot };
+      }
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return undefined;
+    currentDir = parentDir;
+  }
+};
+
+const resolveProjectLocalCliHandoff = (
+  cwd: string,
+  currentPackageRoot: string,
+  env: NodeJS.ProcessEnv = process.env
+): ProjectLocalCliTarget | undefined => {
+  if (env[CLI_HANDOFF_ENV_KEY] === '1') return undefined;
+
+  if (isWithinDirectory(cwd, currentPackageRoot)) return undefined;
+
+  const target = findProjectLocalCliTarget(cwd);
+  if (target === undefined) return undefined;
+
+  if (getRealPath(target.packageRoot) === getRealPath(currentPackageRoot)) {
+    return undefined;
+  }
+
+  return target;
+};
+
+const getHandoffExitCode = (exitCode: number | null, signal: NodeJS.Signals | null): number => {
+  if (typeof exitCode === 'number') return exitCode;
+  if (signal === 'SIGINT' || signal === 'SIGTERM') return 0;
+  return 1;
+};
+
+const waitForChildTermination = async (
+  child: ReturnType<typeof spawn>
+): Promise<{ exitCode: number | null; signal: NodeJS.Signals | null }> => {
+  return await new Promise<{ exitCode: number | null; signal: NodeJS.Signals | null }>(
+    (resolve, reject) => {
+      let settled = false;
+
+      const finish = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
+        if (settled) return;
+        settled = true;
+        child.off?.('exit', onExit);
+        child.off?.('close', onClose);
+        resolve({ exitCode, signal });
+      };
+
+      const onExit = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
+        finish(exitCode, signal);
+      };
+
+      const onClose = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
+        finish(exitCode, signal);
+      };
+
+      child.once('error', reject);
+      child.once('exit', onExit);
+      child.once('close', onClose);
+    }
+  );
+};
+
+const handoffToProjectLocalCli = async (
+  target: ProjectLocalCliTarget,
+  rawArgs: string[]
+): Promise<never> => {
+  const childArgs = target.binPath.endsWith('.ts')
+    ? ['--import', require.resolve('tsx'), target.binPath, ...rawArgs]
+    : [target.binPath, ...rawArgs];
+
+  const child = spawn(process.execPath, childArgs, {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      [CLI_HANDOFF_ENV_KEY]: '1',
+    },
+  });
+
+  const forwardSignals = !process.stdin.isTTY;
+  const forwardSignal = (signal: NodeJS.Signals): void => {
+    if (!forwardSignals) return;
+
+    try {
+      child.kill(signal);
+    } catch {
+      // best-effort forwarding during CLI handoff
+    }
+  };
+
+  const onSigint = (): void => forwardSignal('SIGINT');
+  const onSigterm = (): void => forwardSignal('SIGTERM');
+
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+
+  try {
+    const result = await waitForChildTermination(child);
+
+    process.exit(getHandoffExitCode(result.exitCode, result.signal));
+  } finally {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+  }
+};
+
+const maybeHandoffToProjectLocalCli = async (rawArgs: string[]): Promise<boolean> => {
+  const localCliTarget = resolveProjectLocalCliHandoff(process.cwd(), getCurrentPackageRoot());
+  if (localCliTarget === undefined) return false;
+
+  await handoffToProjectLocalCli(localCliTarget, rawArgs);
+  return true;
+};
+
+const loadPackageVersionFast = (): string => {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packagePath = path.join(here, '../package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8')) as { version?: string };
+    return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+};
+
+const stripLeadingScriptArg = (rawArgs: string[]): string[] => {
+  if (rawArgs.length === 0) return rawArgs;
+  const first = rawArgs[0];
+  const looksLikeScript =
+    typeof first === 'string' && (first.endsWith('.ts') || first.endsWith('.js'));
+  return looksLikeScript ? rawArgs.slice(1) : rawArgs;
+};
+
+const getArgsFromProcess = (): { rawArgs: string[]; args: string[] } => {
+  const rawArgs = process.argv.slice(2);
+  return { rawArgs, args: stripLeadingScriptArg(rawArgs) };
+};
+
+const isVersionRequest = (args: string[]): boolean => {
+  return args.includes('-v') || args.includes('--version');
+};
+
+const maybePrintVersionAndExit = (args: string[]): boolean => {
+  if (!isVersionRequest(args)) return false;
+
+  printFancyVersion(loadPackageVersionFast());
+  return true;
+};
+
+const printFancyVersion = (version: string): void => {
+  const framework = 'ZinTrust Framework';
+  const bannerWidth = 46;
+  const env = (process.env['NODE_ENV'] ?? 'development').toString();
+  const db = (process.env['DB_CONNECTION'] ?? 'sqlite').toString();
+
+  // Keep this dependency-free and fast; version flags should return instantly.
+  // (No logger, no config boot, no CLI registration.)
+
+  console.log('┌' + '─'.repeat(bannerWidth) + '┐');
+
+  console.log(`│ Framework: ${framework.padEnd(bannerWidth - 11)}│`);
+
+  console.log(`│ Version:   ${version.padEnd(bannerWidth - 11)}│`);
+
+  console.log(`│ Env:       ${env.padEnd(bannerWidth - 11)}│`);
+
+  console.log(`│ Database:  ${db.padEnd(bannerWidth - 11)}│`);
+
+  console.log('└' + '─'.repeat(bannerWidth) + '┘');
+
+  console.log();
+};
+
+const shouldDebugArgs = (rawArgs: string[]): boolean => {
+  return process.env['ZINTRUST_CLI_DEBUG_ARGS'] === '1' && rawArgs.includes('--verbose');
+};
+
+const normalizeProxyTargetArgs = (args: string[]): string[] => {
+  if (args.length < 2 || args[0] !== 'proxy') return args;
+
+  const target = args[1];
+  if (!target || target.startsWith('-') || target.includes(':')) return args;
+
+  const normalized = target.trim().toLowerCase();
+  const aliases: Record<string, string> = {
+    redis: 'redis',
+    red: 'red',
+    smtp: 'smtp',
+    mysql: 'mysql',
+    postgres: 'postgres',
+    mongodb: 'mongodb',
+    sqlserver: 'sqlserver',
+  };
+
+  const mappedTarget = aliases[normalized];
+  if (!mappedTarget) return args;
+
+  return [`proxy:${mappedTarget}`, ...args.slice(2)];
+};
+
+const normalizeRedisRpcStartArgs = (args: string[]): string[] => {
+  if (args.length < 2) return args;
+  const command = args[0]?.trim().toLowerCase();
+  const target = args[1]?.trim().toLowerCase();
+  if ((command === 'start' || command === 's') && target === 'redis-rpc') {
+    return ['redis-rpc', ...args.slice(2)];
+  }
+  return args;
+};
+
+const getPrimaryCommand = (args: string[]): string | undefined => {
+  for (const arg of args) {
+    const normalized = arg.trim().toLowerCase();
+    if (normalized === '' || normalized.startsWith('-')) continue;
+    return normalized;
+  }
+
+  return undefined;
+};
+
+const shouldDeferPluginAutoImportWarnings = (args: string[]): boolean => {
+  const command = getPrimaryCommand(args);
+  return command === 'start' || command === 's';
+};
+
+const logPluginAutoImportFailure = async (
+  args: string[],
+  scope: 'Official' | 'Project',
+  details?: string
+): Promise<void> => {
+  const logger = await loadLogger();
+  if (logger === undefined) return;
+
+  if (shouldDeferPluginAutoImportWarnings(args)) {
+    logger.debug(`${scope} plugin auto-import advisory deferred to runtime bootstrap`, {
+      details,
+    });
+    return;
+  }
+
+  logger.warn(`${scope} plugin auto-imports failed:`, details);
+};
+
+const handleCliFatal = async (error: unknown, context: string): Promise<never> => {
+  try {
+    const logger = await loadLogger();
+    logger?.error(context, error);
+  } catch {
+    // best-effort logging
+  }
+
+  try {
+    const { ErrorHandler } = await import('@cli/ErrorHandler');
+    ErrorHandler.handle(error as Error);
+  } catch {
+    // best-effort error handling
+  }
+
+  process.exit(1);
+};
+
+const maybeRunVersionCheckChild = async (): Promise<boolean> => {
+  if (process.env['ZINTRUST_VERSION_CHECK_CHILD'] !== 'true') {
+    return false;
+  }
+
+  const { VersionChecker } = await import('@cli/services/VersionChecker');
+  await VersionChecker.runVersionCheckInline();
+  return true;
+};
+
+const loadOptionalCliExtensionsForArgs = async (
+  args: string[]
+): Promise<{
+  optionalCliExtensions:
+    | typeof import('@cli/OptionalCliExtensions').OptionalCliExtensions
+    | undefined;
+  optionalCliStatuses: ReadonlyArray<
+    import('@cli/OptionalCliExtensions').OptionalCliExtensionStatus
+  >;
+}> => {
+  let optionalCliExtensions:
+    | typeof import('@cli/OptionalCliExtensions').OptionalCliExtensions
+    | undefined;
+  let optionalCliStatuses: ReadonlyArray<
+    import('@cli/OptionalCliExtensions').OptionalCliExtensionStatus
+  > = [];
+
+  try {
+    ({ OptionalCliExtensions: optionalCliExtensions } = await import('@cli/OptionalCliExtensions'));
+    optionalCliStatuses = await optionalCliExtensions.loadForArgs(args);
+  } catch {
+    // best-effort; missing optional extensions must not block the CLI
+  }
+
+  return {
+    optionalCliExtensions,
+    optionalCliStatuses,
+  };
+};
+
+const runCliInternal = async (): Promise<void> => {
+  if (await maybeRunVersionCheckChild()) {
+    return;
+  }
+
+  const { rawArgs: rawArgs0, args: args0 } = getArgsFromProcess();
+  if (await maybeHandoffToProjectLocalCli(rawArgs0)) {
+    return;
+  }
+
+  // Fast path: print version and exit without bootstrapping the CLI.
+  // This keeps `zin -v` / `zin --version` snappy and avoids any debug output.
+  if (maybePrintVersionAndExit(args0)) {
+    return;
+  }
+
+  const { EnvFileLoader } = await import('@cli/utils/EnvFileLoader');
+  EnvFileLoader.ensureLoaded();
+
+  // Auto-load install-only CLI extension packages that self-register commands.
+  const { optionalCliExtensions, optionalCliStatuses } =
+    await loadOptionalCliExtensionsForArgs(args0);
+
+  const missingOptionalExtension = optionalCliExtensions?.findMissingExtensionForArgs(
+    args0,
+    optionalCliStatuses
+  );
+
+  if (missingOptionalExtension !== undefined) {
+    const { ErrorFactory } = await import('@exceptions/ZintrustError');
+    throw ErrorFactory.createCliError(
+      optionalCliExtensions?.getMissingExtensionMessage(missingOptionalExtension) ??
+        `Missing optional CLI package: ${missingOptionalExtension.packageName}`
+    );
+  }
+
+  // Ensure project-installed adapters/drivers are registered for CLI commands.
+  // (This is driven by src/zintrust.plugins.ts generated by `zin plugin install`.)
+  try {
+    const { PluginAutoImports } = await import('@runtime/PluginAutoImports');
+    const runtimeImportMode = process.env['DOCKER_WORKER'] === 'true' ? 'worker' : 'base';
+    const officialImports = await PluginAutoImports.tryImportRuntimeAutoImports(runtimeImportMode);
+    if (!officialImports.ok) {
+      await logPluginAutoImportFailure(args0, 'Official', officialImports.errorMessage);
+    }
+
+    const projectImports = await PluginAutoImports.tryImportProjectAutoImports();
+    if (!projectImports.ok && projectImports.reason !== 'not-found') {
+      await logPluginAutoImportFailure(args0, 'Project', projectImports.errorMessage);
+    }
+  } catch {
+    // best-effort; CLI should still run even if plugins file is missing
+  }
+
+  const { CLI } = await import('@cli/CLI');
+
+  const cli = CLI.create();
+
+  // When executing via tsx (e.g. `npx tsx bin/zin.ts ...`), the script path can
+  // appear as the first element of `process.argv.slice(2)`. Commander expects
+  // args to start at the command name, so we strip a leading script path if present.
+  const { rawArgs, args } = getArgsFromProcess();
+  if (shouldDebugArgs(rawArgs)) {
+    try {
+      process.stderr.write(`[zintrust-cli] process.argv=${JSON.stringify(process.argv)}\n`);
+      process.stderr.write(`[zintrust-cli] rawArgs=${JSON.stringify(rawArgs)}\n`);
+    } catch {
+      // ignore
+    }
+  }
+  await cli.run(normalizeProxyTargetArgs(normalizeRedisRpcStartArgs(args)));
+};
+
+export async function run(): Promise<void> {
+  try {
+    await runCliInternal();
+  } catch (error) {
+    await handleCliFatal(error, 'CLI execution failed');
+  }
+}
+
+export const CliLauncherInternal = Object.freeze({
+  CLI_HANDOFF_ENV_KEY,
+  findProjectLocalCliTarget,
+  getHandoffExitCode,
+  getCurrentPackageRoot,
+  getRealPath,
+  handoffToProjectLocalCli,
+  isWithinDirectory,
+  maybeHandoffToProjectLocalCli,
+  resolveProjectLocalCliHandoff,
+});
+
+const shouldRunAsMain = (): boolean => {
+  const entryArg = process.argv[1];
+  if (typeof entryArg !== 'string' || entryArg.trim() === '') return false;
+
+  return getRealPath(entryArg) === getRealPath(fileURLToPath(import.meta.url));
+};
+
+if (shouldRunAsMain()) {
+  await run();
+}
+
+export {};

package/bin/zintrust-microservices.ts

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * ZinTrust Microservices CLI
+ * Commands for generating, bundling, and managing microservices
+ */
+
+import { Logger } from '@config/logger';
+import { MicroserviceGenerator } from '@microservices/MicroserviceGenerator';
+import { MicroserviceManager } from '@microservices/MicroserviceManager';
+import { ServiceBundler } from '@microservices/ServiceBundler';
+import { readFileSync } from '@node-singletons/fs';
+import { dirname, join } from '@node-singletons/path';
+import { fileURLToPath } from '@node-singletons/url';
+import { program } from 'commander';
+
+type CliOptions = Record<string, unknown>;
+
+const getStringOption = (options: CliOptions, key: string, fallback: string): string => {
+  const value = options[key];
+  return typeof value === 'string' && value.trim() !== '' ? value : fallback;
+};
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Version
+const packageJsonUnknown: unknown = JSON.parse(
+  readFileSync(join(__dirname, '../package.json'), 'utf-8')
+);
+const packageVersion =
+  typeof packageJsonUnknown === 'object' &&
+  packageJsonUnknown !== null &&
+  'version' in packageJsonUnknown &&
+  typeof (packageJsonUnknown as { version: unknown }).version === 'string'
+    ? (packageJsonUnknown as { version: string }).version
+    : '0.0.0';
+
+program.version(packageVersion);
+
+/**
+ * Generate microservices
+ */
+program
+  .command('generate <domain> <services>')
+  .description('Generate microservices scaffold')
+  .option('--port <port>', 'Base port for services', '3001')
+  .option('--version <version>', 'Service version', '1.0.0')
+  .action(async (domain: string, services: string, options: CliOptions) => {
+    try {
+      const serviceList = services.split(',').map((s) => s.trim());
+      const portRaw = getStringOption(options, 'port', '3001');
+      const version = getStringOption(options, 'version', '1.0.0');
+
+      await MicroserviceGenerator.getInstance().generate({
+        domain,
+        services: serviceList,
+        basePort: Number.parseInt(portRaw, 10),
+        version,
+      });
+
+      Logger.info('Microservices generated successfully');
+    } catch (error) {
+      Logger.error('Error generating microservices:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Bundle services
+ */
+program
+  .command('bundle <domain> <services>')
+  .description('Bundle microservices for deployment')
+  .option('--output <dir>', 'Output directory', 'dist/services')
+  .option('--target-size <mb>', 'Target bundle size in MB', '1')
+  .action(async (domain: string, services: string, options: CliOptions) => {
+    try {
+      const serviceList = services.split(',').map((s) => s.trim());
+      const outputDir = getStringOption(options, 'output', 'dist/services');
+
+      const results = await ServiceBundler.getInstance().bundleAll(domain, serviceList, outputDir);
+
+      const allOptimized = results.every((r: { optimized: boolean }) => r.optimized === true);
+      if (allOptimized === false) {
+        Logger.warn('Some services exceed target size. Consider optimizing bundle.');
+      }
+    } catch (error) {
+      Logger.error('Error bundling microservices:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Create Docker images
+ */
+program
+  .command('docker <domain> <services>')
+  .description('Create Docker images for services')
+  .option('--registry <url>', 'Docker registry URL', 'localhost:5000')
+  .action(async (domain: string, services: string, options: CliOptions) => {
+    try {
+      const serviceList = services.split(',').map((s) => s.trim());
+      const registry = getStringOption(options, 'registry', 'localhost:5000');
+
+      await Promise.all(
+        serviceList.map((service) =>
+          ServiceBundler.getInstance().createServiceImage(service, domain, registry)
+        )
+      );
+
+      Logger.info(
+        `Docker images ready. Build with:\n  docker-compose -f services/${domain}/docker-compose.yml build`
+      );
+    } catch (error) {
+      Logger.error('Error creating Docker images:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Discover services
+ */
+program
+  .command('discover')
+  .description('Discover available microservices')
+  .action(async () => {
+    try {
+      const configs = await MicroserviceManager.discoverServices();
+
+      if (configs.length === 0) {
+        Logger.info('No microservices found in services/ folder');
+        return;
+      }
+
+      Logger.info(`Found ${configs.length} microservice(s):`);
+
+      for (const config of configs) {
+        const version =
+          config.version !== undefined && config.version !== null && config.version !== ''
+            ? config.version
+            : '1.0.0';
+
+        Logger.info(`  • ${config.name} (${config.domain}) - v${version}`);
+
+        if (
+          config.dependencies !== undefined &&
+          config.dependencies !== null &&
+          config.dependencies.length > 0
+        ) {
+          Logger.info(`    Dependencies: ${config.dependencies.join(', ')}`);
+        }
+      }
+    } catch (error) {
+      Logger.error('Error discovering services:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Status of services
+ */
+program
+  .command('status')
+  .description('Check status of running microservices')
+  .action(async () => {
+    try {
+      const manager = MicroserviceManager.getInstance();
+      const summary = manager.getStatusSummary();
+
+      Logger.info(`Microservices Status:\n${JSON.stringify(summary, null, 2)}`);
+    } catch (error) {
+      Logger.error('Error getting microservices status:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Health check
+ */
+program
+  .command('health')
+  .description('Health check all services')
+  .action(async () => {
+    try {
+      const manager = MicroserviceManager.getInstance();
+      const results = await manager.healthCheckAll();
+
+      Logger.info('Health Check Results');
+      for (const [service, healthy] of Object.entries(results)) {
+        Logger.info(`  ${service}: ${healthy ? 'Healthy' : 'Unhealthy'}`);
+      }
+    } catch (error) {
+      Logger.error('Error performing health check:', error);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/bin/zintrust.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env -S node --import tsx
+
+/**
+ * ZinTrust CLI - Main Entry Point
+ *
+ * This bin script is a thin wrapper around the hashbang-free implementation in
+ * bin/zintrust-main.ts. Keeping the implementation hashbang-free allows other
+ * shortcuts (zin/z/zt) to reuse the same launcher behavior.
+ */
+
+import { runCliWrapper } from './launcher';
+
+await runCliWrapper();

package/bin/zt.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S node --import tsx
+
+/**
+ * ZinTrust CLI Shortcut - 'zt'
+ * Mirrors bin/zintrust.ts for convenience
+ */
+
+import { runCliWrapper } from './launcher';
+
+await runCliWrapper();