@zintrust/core 0.4.16 → 0.4.17

package/src/cli/commands/DockerCommand.ts

@@ -0,0 +1,185 @@
+import { generateUuid } from '@/common/utility';
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { DockerPushCommand } from '@cli/commands/DockerPushCommand';
+import { SpawnUtil } from '@cli/utils/spawn';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { existsSync, renameSync } from '@node-singletons/fs';
+import { join } from '@node-singletons/path';
+import type { Command } from 'commander';
+
+type DockerCommandOptions = CommandOptions & {
+  env?: string;
+  wranglerConfig?: string;
+  port?: string;
+};
+
+const resolveDefaultWranglerConfig = (cwd: string): string | undefined => {
+  const candidates = [
+    'wrangler.containers-proxy.jsonc',
+    'wrangler.containers-proxy.json',
+    'wrangler.containers-proxy.toml',
+    'wrangler.jsonc',
+    'wrangler.json',
+    'wrangler.toml',
+  ];
+
+  for (const candidate of candidates) {
+    const full = join(cwd, candidate);
+    if (existsSync(full)) return candidate;
+  }
+
+  return undefined;
+};
+
+const resolvePort = (raw: string | undefined): string | undefined => {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value === '') return undefined;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0 || parsed >= 65536) {
+    throw ErrorFactory.createCliError(`Error: Invalid --port '${value}'. Expected 1-65535.`);
+  }
+  return String(parsed);
+};
+
+const resolveWranglerConfig = (cwd: string, options: DockerCommandOptions): string => {
+  const fromCli = typeof options.wranglerConfig === 'string' ? options.wranglerConfig.trim() : '';
+  if (fromCli.length > 0) {
+    const full = join(cwd, fromCli);
+    if (existsSync(full)) return fromCli;
+    throw ErrorFactory.createCliError(`Wrangler config not found: ${fromCli}`);
+  }
+
+  const fallback = resolveDefaultWranglerConfig(cwd);
+  if (typeof fallback === 'string' && fallback.length > 0) return fallback;
+
+  throw ErrorFactory.createCliError(
+    'Wrangler config not found. Expected wrangler.containers-proxy.jsonc (or wrangler.jsonc/toml).'
+  );
+};
+
+const isContainersProxyConfig = (config: string): boolean => {
+  const base = config.split(/[/\\]/).pop() ?? config;
+  return (
+    base === 'wrangler.containers-proxy.jsonc' ||
+    base === 'wrangler.containers-proxy.json' ||
+    base === 'wrangler.containers-proxy.toml' ||
+    base.startsWith('wrangler.containers-proxy.')
+  );
+};
+
+const withDevVarsForConfig = async <T>(
+  cwd: string,
+  config: string,
+  envName: string,
+  fn: () => Promise<T>
+): Promise<T> => {
+  const nonce = generateUuid();
+  const moved: Array<{ from: string; to: string }> = [];
+  const swappedIn: Array<{ from: string; to: string }> = [];
+
+  const disable = (name: string): void => {
+    const from = join(cwd, name);
+    if (!existsSync(from)) return;
+    const to = join(cwd, `${name}.disabled-by-zin-${nonce}`);
+    renameSync(from, to);
+    moved.push({ from, to });
+  };
+
+  const swapIn = (source: string, target: string): void => {
+    const from = join(cwd, source);
+    if (!existsSync(from)) return;
+
+    const to = join(cwd, target);
+    if (existsSync(to)) return;
+
+    renameSync(from, to);
+    swappedIn.push({ from, to });
+  };
+
+  try {
+    if (isContainersProxyConfig(config)) {
+      // For containers-proxy configs, we want `.dev.vars*` to exist but only for
+      // this run. Users keep the files renamed as `.dev.vars*.containers-proxy`.
+      swapIn('.dev.vars.containers-proxy', '.dev.vars');
+      if (envName !== '') {
+        swapIn(`.dev.vars.${envName}.containers-proxy`, `.dev.vars.${envName}`);
+      }
+      return await fn();
+    }
+
+    // For all other configs, disable `.dev.vars*` so Wrangler relies on `.env*`.
+    disable('.dev.vars');
+    disable('.dev.vars.local');
+    disable('.dev.vars.staging');
+    disable('.dev.vars.staging.local');
+    if (envName !== '') {
+      disable(`.dev.vars.${envName}`);
+      disable(`.dev.vars.${envName}.local`);
+    }
+
+    return await fn();
+  } finally {
+    const restoreSwaps = swappedIn.slice().reverse();
+    for (const item of restoreSwaps) {
+      try {
+        if (existsSync(item.to) && !existsSync(item.from)) renameSync(item.to, item.from);
+      } catch {
+        // noop
+      }
+    }
+
+    const restoreMoved = moved.slice().reverse();
+    for (const item of restoreMoved) {
+      try {
+        if (existsSync(item.to)) renameSync(item.to, item.from);
+      } catch {
+        // noop
+      }
+    }
+  }
+};
+
+const executeDocker = async (options: DockerCommandOptions): Promise<void> => {
+  const cwd = process.cwd();
+  const config = resolveWranglerConfig(cwd, options);
+  const env = typeof options.env === 'string' ? options.env.trim() : '';
+  const port = resolvePort(options.port);
+
+  const args: string[] = ['dev', '--config', config];
+  if (typeof port === 'string' && port.length > 0) args.push('--port', port);
+  if (env.length > 0) args.push('--env', env);
+
+  Logger.info('Starting Wrangler dev (Containers/Docker-backed)...');
+  const exitCode = await withDevVarsForConfig(cwd, config, env, async () => {
+    return SpawnUtil.spawnAndWait({ command: 'wrangler', args, env: process.env });
+  });
+  process.exit(exitCode);
+};
+
+export const DockerCommand = Object.freeze({
+  create(): IBaseCommand {
+    return BaseCommand.create({
+      name: 'docker',
+      aliases: ['dkr', 'dk'],
+      description: 'Run Wrangler dev using a Docker-backed Cloudflare Containers config',
+      addOptions: (command: Command): void => {
+        // `zin docker push` (subcommand) for Docker Hub publishing.
+        // Keep `zin docker` itself as the Wrangler dev command.
+        const pushCommand = DockerPushCommand.create().getCommand();
+        pushCommand.name('push');
+        command.addCommand(pushCommand);
+
+        command.option(
+          '-c, --wrangler-config <path>',
+          'Wrangler config file (defaults if present)'
+        );
+        command.option('-e, --env <name>', 'Wrangler environment name');
+        command.option('-p, --port <number>', 'Port for wrangler dev');
+      },
+      execute: async (options: CommandOptions): Promise<void> =>
+        executeDocker(options as DockerCommandOptions),
+    });
+  },
+});

package/src/cli/commands/DockerComposeCommandUtils.ts

@@ -0,0 +1,36 @@
+import { SpawnUtil } from '@cli/utils/spawn';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { existsSync } from '@node-singletons/fs';
+import { join } from '@node-singletons/path';
+
+export const resolveComposePath = (composeFileName: string, missingMessage: string): string => {
+  const composePath = join(process.cwd(), composeFileName);
+  if (!existsSync(composePath)) {
+    throw ErrorFactory.createCliError(missingMessage);
+  }
+  return composePath;
+};
+
+export const runComposeWithFallback = async (args: string[]): Promise<void> => {
+  try {
+    const exitCode = await SpawnUtil.spawnAndWait({ command: 'docker', args });
+    if (exitCode !== 0) process.exit(exitCode);
+    return;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("'docker' not found")) {
+      throw error;
+    }
+  }
+
+  Logger.warn("'docker' not found. Falling back to 'docker-compose'.");
+  const exitCode = await SpawnUtil.spawnAndWait({
+    command: 'docker-compose',
+    args: args.slice(1),
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+};

package/src/cli/commands/DockerPushCommand.ts

@@ -0,0 +1,143 @@
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { VersionChecker } from '@cli/services/VersionChecker';
+import { SpawnUtil } from '@cli/utils/spawn';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { Command } from 'commander';
+
+type DockerPushOptions = CommandOptions & {
+  tag?: string;
+  platforms?: string;
+  alsoLatest?: boolean;
+  only?: string;
+};
+
+const parsePlatforms = (value: string | undefined): string => {
+  const raw = (value ?? '').trim();
+  if (raw !== '') return raw;
+  return 'linux/amd64,linux/arm64';
+};
+
+const parseTag = (value: string | undefined): string => {
+  const raw = (value ?? '').trim();
+  if (raw === '') {
+    const currentVersion = VersionChecker.getCurrentVersion();
+    return currentVersion === '0.0.0' ? 'latest' : currentVersion;
+  }
+  return raw;
+};
+
+const resolvePublishTags = (tag: string, alsoLatest: boolean | undefined): string[] => {
+  if (tag === 'latest') return ['latest'];
+  if (alsoLatest === false) return [tag];
+  return [tag, 'latest'];
+};
+
+const parseOnly = (value: string | undefined): 'runtime' | 'worker' | 'gateway' | 'both' => {
+  const raw = (value ?? '').trim().toLowerCase();
+  if (raw === 'runtime' || raw === 'worker' || raw === 'gateway') return raw;
+  return 'both';
+};
+
+const runPublishImages = async (options: DockerPushOptions): Promise<void> => {
+  const tag = parseTag(options.tag);
+  const platforms = parsePlatforms(options.platforms);
+  const tags = resolvePublishTags(tag, options.alsoLatest);
+  const only = parseOnly(options.only);
+
+  const runtimeRepo = 'zintrust/zintrust';
+  const workerRepo = 'zintrust/zintrust-worker';
+  const gatewayRepo = 'zintrust/zintrust-proxy-gateway';
+
+  const buildArgsFor = (repo: string, context: string, target?: string): string[] => {
+    const args: string[] = ['buildx', 'build', '--platform', platforms];
+    for (const t of tags) args.push('-t', `${repo}:${t}`);
+    if (typeof target === 'string' && target.trim() !== '') {
+      args.push('--target', target);
+    }
+    args.push('--push', context);
+    return args;
+  };
+
+  Logger.info('Publishing images to Docker Hub via buildx...', {
+    runtime: runtimeRepo,
+    worker: workerRepo,
+    gateway: gatewayRepo,
+    platforms,
+    tags,
+    only,
+  });
+
+  if (only === 'runtime' || only === 'both') {
+    const runtimeExit = await SpawnUtil.spawnAndWait({
+      command: 'docker',
+      args: buildArgsFor(runtimeRepo, '.', 'runtime'),
+      env: process.env,
+    });
+    if (runtimeExit !== 0) {
+      throw ErrorFactory.createCliError(
+        `Failed to publish ${runtimeRepo} (exit code ${runtimeExit})`
+      );
+    }
+  }
+
+  if (only === 'worker' || only === 'both') {
+    const workerExit = await SpawnUtil.spawnAndWait({
+      command: 'docker',
+      args: buildArgsFor(workerRepo, '.', 'worker'),
+      env: process.env,
+    });
+    if (workerExit !== 0) {
+      throw ErrorFactory.createCliError(
+        `Failed to publish ${workerRepo} (exit code ${workerExit})`
+      );
+    }
+  }
+
+  if (only === 'gateway' || only === 'both') {
+    const gatewayExit = await SpawnUtil.spawnAndWait({
+      command: 'docker',
+      args: buildArgsFor(gatewayRepo, './docker/proxy-gateway'),
+      env: process.env,
+    });
+    if (gatewayExit !== 0) {
+      throw ErrorFactory.createCliError(
+        `Failed to publish ${gatewayRepo} (exit code ${gatewayExit})`
+      );
+    }
+  }
+};
+
+export const DockerPushCommand = Object.freeze({
+  create(): IBaseCommand {
+    return BaseCommand.create({
+      name: 'docker:push',
+      aliases: ['docker-push'],
+      description: 'Build and push ZinTrust Docker images to Docker Hub',
+      addOptions: (command: Command): void => {
+        command.option(
+          '--tag <tag>',
+          'Docker image tag to publish. Defaults to current version and also tags :latest'
+        );
+        command.option(
+          '--platforms <list>',
+          'Comma-separated platforms for buildx',
+          'linux/amd64,linux/arm64'
+        );
+        command.option(
+          '--no-also-latest',
+          'When publishing a non-latest --tag, do not also push :latest'
+        );
+        command.option(
+          '--only <target>',
+          'Publish only one image: runtime|worker|gateway|both',
+          'both'
+        );
+      },
+      execute: async (options: DockerPushOptions): Promise<void> => {
+        await runPublishImages(options);
+      },
+    });
+  },
+});

package/src/cli/commands/DoctorArchitectureCommand.ts

@@ -0,0 +1,72 @@
+import type { RuntimeMode } from '@/runtime/detectRuntime';
+import { getRuntimeMode } from '@/runtime/detectRuntime';
+import { BaseCommand, type IBaseCommand } from '@cli/BaseCommand';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+
+export const DoctorArchitectureCommand = Object.freeze({
+  create(): IBaseCommand {
+    return BaseCommand.create({
+      name: 'doctor:architecture',
+      aliases: ['d'],
+      description: 'Validate producer/consumer architecture configuration',
+      async execute(): Promise<void> {
+        Logger.info('🩺 Diagnosing Architecture Configuration...');
+
+        const mode: RuntimeMode = getRuntimeMode();
+        const workerEnabled = Env.getBool('WORKER_ENABLED', true);
+        const dockerWorker = Env.getBool('DOCKER_WORKER', false);
+
+        Logger.info('----------------------------------------');
+        Logger.info(`Runtime Mode:    ${mode}`);
+        Logger.info(`Docker Worker:   ${dockerWorker}`);
+        Logger.info(`Worker Enabled:  ${workerEnabled}`);
+        Logger.info('----------------------------------------');
+
+        const issues: string[] = [];
+
+        // Rule 1: Cloudflare Workers cannot run Consumers
+        if (mode === 'cloudflare-workers' && workerEnabled) {
+          issues.push(
+            '❌ CRITICAL: Cloudflare Workers runtime detected but WORKER_ENABLED=true. Consumers will fail due to connection persistence limits. Set WORKER_ENABLED=false.'
+          );
+        }
+
+        // Rule 2: Containers should generally run Workers (unless dedicated to API)
+        if (mode === 'containers' && !workerEnabled) {
+          issues.push(
+            '⚠️ WARNING: Container runtime detected but WORKER_ENABLED=false. Are these containers for API only? If attempting to process jobs, enable workers.'
+          );
+        }
+
+        // Rule 2b: Dedicated Docker worker containers must keep workers enabled
+        if (mode === 'containers' && dockerWorker && !workerEnabled) {
+          issues.push(
+            '❌ CRITICAL: DOCKER_WORKER=true but WORKER_ENABLED=false. Dedicated worker containers must enable workers or unset DOCKER_WORKER.'
+          );
+        }
+
+        // Rule 3: Proxy requirement for Cloudflare
+        if (mode === 'cloudflare-workers') {
+          const useProxy =
+            Env.getBool('USE_REDIS_PROXY', false) ||
+            Env.getBool('ENABLE_CLOUDFLARE_SOCKETS', false);
+          if (!useProxy) {
+            issues.push(
+              '❌ CRITICAL: Cloudflare runtime requires USE_REDIS_PROXY=true or ENABLE_CLOUDFLARE_SOCKETS=true for Queue producers.'
+            );
+          }
+        }
+
+        if (issues.length > 0) {
+          Logger.error('Found configuration issues:');
+          issues.forEach((issue) => Logger.error(issue));
+          process.exit(1);
+        } else {
+          Logger.info('✅ Architecture configuration looks valid for this runtime.');
+        }
+        await Promise.resolve();
+      },
+    });
+  },
+});

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