@fyresmith/hive-server 1.0.1-3

package/cli/main.js

@@ -0,0 +1,730 @@
+import { existsSync } from 'fs';
+import { access } from 'fs/promises';
+import { constants as fsConstants } from 'fs';
+import process from 'process';
+import { Command, CommanderError } from 'commander';
+import prompts from 'prompts';
+import {
+  DEFAULT_ENV_FILE,
+  DEFAULT_CLOUDFLARED_CERT,
+  DEFAULT_CLOUDFLARED_CONFIG,
+  DEFAULT_TUNNEL_NAME,
+  EXIT,
+  HIVE_CONFIG_FILE,
+  LEGACY_ENV_FILE,
+} from './constants.js';
+import { CliError } from './errors.js';
+import { section, info, success, warn, fail } from './output.js';
+import { loadHiveConfig, updateHiveConfig } from './config.js';
+import {
+  inferDomainFromRedirect,
+  loadEnvFile,
+  normalizeEnv,
+  promptForEnv,
+  redactEnv,
+  validateEnvValues,
+  writeEnvFile,
+} from './env-file.js';
+import { isPortAvailable, pathExists, validateDomain } from './checks.js';
+import { run } from './exec.js';
+import {
+  cloudflaredServiceStatus,
+  installCloudflaredService,
+  runTunnelForeground,
+  setupTunnel,
+  tunnelStatus,
+  getCloudflaredPath,
+} from './tunnel.js';
+import {
+  getServiceDefaults,
+  getHiveServiceStatus,
+  installHiveService,
+  restartHiveService,
+  startHiveService,
+  stopHiveService,
+  streamHiveServiceLogs,
+  uninstallHiveService,
+} from './service.js';
+import { startHiveServer } from '../index.js';
+
+function parseInteger(value, key) {
+  const parsed = parseInt(String(value ?? '').trim(), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new CliError(`${key} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function requiredOrFallback(value, fallback) {
+  const trimmed = String(value ?? '').trim();
+  return trimmed || fallback;
+}
+
+async function promptConfirm(message, yes = false, initial = true) {
+  if (yes) return true;
+  const answer = await prompts({
+    type: 'confirm',
+    name: 'ok',
+    message,
+    initial,
+  });
+  return Boolean(answer.ok);
+}
+
+async function resolveContext(options = {}) {
+  const config = await loadHiveConfig();
+  const envFile = options.envFile || config.envFile || DEFAULT_ENV_FILE;
+  return { config, envFile };
+}
+
+function resolveServiceConfig(config) {
+  const defaults = getServiceDefaults();
+  return {
+    servicePlatform: config.servicePlatform || defaults.servicePlatform,
+    serviceName: config.serviceName || defaults.serviceName,
+  };
+}
+
+async function loadValidatedEnv(envFile, { requireFile = true } = {}) {
+  if (requireFile && !existsSync(envFile)) {
+    throw new CliError(`Env file not found: ${envFile}. Run: hive env init`, EXIT.FAIL);
+  }
+  const raw = await loadEnvFile(envFile);
+  const env = normalizeEnv(raw);
+  const issues = validateEnvValues(env);
+  return { env, issues };
+}
+
+async function setRedirectUriForDomain({ envFile, env, domain, yes = false }) {
+  const expected = `https://${domain}/auth/callback`;
+  if (env.DISCORD_REDIRECT_URI === expected) return env;
+
+  const shouldUpdate = await promptConfirm(
+    `Set DISCORD_REDIRECT_URI to ${expected}?`,
+    yes,
+    true
+  );
+
+  if (!shouldUpdate) return env;
+
+  const next = { ...env, DISCORD_REDIRECT_URI: expected };
+  await writeEnvFile(envFile, next);
+  success(`Updated DISCORD_REDIRECT_URI -> ${expected}`);
+  return next;
+}
+
+async function runDoctorChecks({ envFile, includeCloudflared = true }) {
+  section('Hive Doctor');
+
+  let prereqFailures = 0;
+  let failures = 0;
+
+  const major = parseInt(process.versions.node.split('.')[0], 10);
+  if (major >= 18) {
+    success(`Node version OK (${process.versions.node})`);
+  } else {
+    fail(`Node >= 18 is required (current: ${process.versions.node})`);
+    prereqFailures += 1;
+  }
+
+  if (includeCloudflared) {
+    const cloudflaredPath = getCloudflaredPath();
+    if (!cloudflaredPath) {
+      fail('cloudflared is not installed or not on PATH');
+      prereqFailures += 1;
+    } else {
+      const versionOutput = await run('cloudflared', ['--version']).catch(() => ({ stdout: '' }));
+      success(`cloudflared found (${cloudflaredPath}) ${versionOutput.stdout.trim()}`);
+    }
+  }
+
+  if (!existsSync(envFile)) {
+    fail(`Env file missing: ${envFile}`);
+    failures += 1;
+  } else {
+    success(`Env file found: ${envFile}`);
+    const { env, issues } = await loadValidatedEnv(envFile, { requireFile: true });
+    if (issues.length > 0) {
+      for (const issue of issues) fail(issue);
+      failures += issues.length;
+    } else {
+      success('Env values look valid');
+    }
+
+    if (env.VAULT_PATH) {
+      const vaultExists = await pathExists(env.VAULT_PATH);
+      if (!vaultExists) {
+        fail(`VAULT_PATH does not exist: ${env.VAULT_PATH}`);
+        failures += 1;
+      } else {
+        try {
+          await access(env.VAULT_PATH, fsConstants.R_OK | fsConstants.W_OK);
+          success(`VAULT_PATH is readable/writable: ${env.VAULT_PATH}`);
+        } catch {
+          fail(`VAULT_PATH is not readable/writable: ${env.VAULT_PATH}`);
+          failures += 1;
+        }
+      }
+    }
+
+    const port = parseInt(env.PORT, 10);
+    const yjsPort = parseInt(env.YJS_PORT, 10);
+    if (Number.isInteger(port) && port > 0) {
+      const portFree = await isPortAvailable(port);
+      if (portFree) info(`PORT ${port} is available`);
+      else warn(`PORT ${port} is in use`);
+    }
+    if (Number.isInteger(yjsPort) && yjsPort > 0) {
+      const yjsFree = await isPortAvailable(yjsPort);
+      if (yjsFree) info(`YJS_PORT ${yjsPort} is available`);
+      else warn(`YJS_PORT ${yjsPort} is in use`);
+    }
+
+    if (Number.isInteger(port) && port > 0) {
+      const health = await fetch(`http://127.0.0.1:${port}/health`)
+        .then((res) => ({ ok: res.ok, status: res.status }))
+        .catch(() => null);
+      if (health?.ok) {
+        success(`Health endpoint reachable on :${port}`);
+      } else if (health) {
+        warn(`Health endpoint returned HTTP ${health.status}`);
+      } else {
+        info(`Health endpoint not reachable on :${port} (server may not be running)`);
+      }
+    }
+  }
+
+  if (prereqFailures > 0) {
+    throw new CliError('Doctor found missing prerequisites', EXIT.PREREQ);
+  }
+  if (failures > 0) {
+    throw new CliError('Doctor found configuration issues', EXIT.FAIL);
+  }
+
+  success('Doctor checks passed');
+}
+
+async function runSetupWizard(options) {
+  const yes = Boolean(options.yes);
+
+  section('Hive Setup');
+
+  const { config, envFile } = await resolveContext(options);
+  let nextConfig = { ...config, envFile };
+  let importedLegacy = false;
+
+  if (!existsSync(HIVE_CONFIG_FILE) && existsSync(LEGACY_ENV_FILE)) {
+    const shouldImportLegacy = await promptConfirm(
+      `Import existing legacy env from ${LEGACY_ENV_FILE}?`,
+      yes,
+      true
+    );
+    if (shouldImportLegacy) {
+      const legacyValues = await loadEnvFile(LEGACY_ENV_FILE);
+      await writeEnvFile(envFile, legacyValues);
+      importedLegacy = true;
+      success(`Imported legacy env into ${envFile}`);
+    }
+  }
+
+  const envExists = existsSync(envFile);
+  let envValues;
+  if (!envExists || importedLegacy) {
+    info(`Initializing env file at ${envFile}`);
+    const existing = await loadEnvFile(envFile);
+    envValues = await promptForEnv({ envFile, existing, yes });
+  } else {
+    const edit = await promptConfirm('Env file exists. Edit it now?', yes, false);
+    if (edit) {
+      const existing = await loadEnvFile(envFile);
+      envValues = await promptForEnv({ envFile, existing, yes });
+    } else {
+      envValues = normalizeEnv(await loadEnvFile(envFile));
+    }
+  }
+
+  const envIssues = validateEnvValues(envValues);
+  if (envIssues.length > 0) {
+    for (const issue of envIssues) fail(issue);
+    throw new CliError('Env configuration is invalid', EXIT.FAIL);
+  }
+
+  let domain = requiredOrFallback(
+    options.domain,
+    inferDomainFromRedirect(envValues.DISCORD_REDIRECT_URI) || nextConfig.domain
+  );
+
+  if (!yes) {
+    const response = await prompts({
+      type: 'text',
+      name: 'domain',
+      message: 'Public domain for Hive server',
+      initial: domain,
+    });
+    if (response.domain !== undefined) {
+      domain = String(response.domain).trim();
+    }
+  }
+
+  if (!validateDomain(domain)) {
+    throw new CliError(`Invalid domain: ${domain}`);
+  }
+
+  envValues = await setRedirectUriForDomain({ envFile, env: envValues, domain, yes });
+
+  const shouldSetupTunnel = await promptConfirm('Configure Cloudflare Tunnel now?', yes, true);
+  if (shouldSetupTunnel) {
+    const port = parseInteger(envValues.PORT, 'PORT');
+    const yjsPort = parseInteger(envValues.YJS_PORT, 'YJS_PORT');
+    const tunnelName = requiredOrFallback(options.tunnelName, nextConfig.tunnelName || DEFAULT_TUNNEL_NAME);
+    const cloudflaredConfigFile = requiredOrFallback(
+      options.cloudflaredConfigFile,
+      nextConfig.cloudflaredConfigFile || DEFAULT_CLOUDFLARED_CONFIG
+    );
+    const tunnelService = await promptConfirm('Install cloudflared as a service?', yes, true);
+
+    const tunnelResult = await setupTunnel({
+      tunnelName,
+      domain,
+      configFile: cloudflaredConfigFile,
+      certPath: DEFAULT_CLOUDFLARED_CERT,
+      port,
+      yjsPort,
+      yes,
+      installService: tunnelService,
+    });
+
+    nextConfig = {
+      ...nextConfig,
+      domain,
+      tunnelName,
+      tunnelId: tunnelResult.tunnelId,
+      tunnelCredentialsFile: tunnelResult.credentialsFile,
+      cloudflaredConfigFile: tunnelResult.configFile,
+    };
+  }
+
+  const shouldInstallService = await promptConfirm('Install Hive server as an OS service?', yes, true);
+  if (shouldInstallService) {
+    const serviceInfo = await installHiveService({ envFile, yes });
+    nextConfig = {
+      ...nextConfig,
+      servicePlatform: serviceInfo.servicePlatform,
+      serviceName: serviceInfo.serviceName,
+    };
+    success(`Installed service ${serviceInfo.serviceName}`);
+  }
+
+  await updateHiveConfig(nextConfig);
+  success(`Saved config: ${HIVE_CONFIG_FILE}`);
+
+  await runDoctorChecks({ envFile, includeCloudflared: shouldSetupTunnel });
+}
+
+function registerEnvCommands(program) {
+  const env = program.command('env').description('Manage Hive .env configuration');
+
+  env
+    .command('init')
+    .description('Create or update env file from prompts')
+    .option('--env-file <path>', 'env file path')
+    .option('--yes', 'accept defaults where possible', false)
+    .action(async (options) => {
+      section('Env Init');
+      const { config, envFile } = await resolveContext(options);
+      const existing = await loadEnvFile(envFile);
+      const values = await promptForEnv({ envFile, existing, yes: options.yes });
+      const issues = validateEnvValues(values);
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Env file has validation issues', EXIT.FAIL);
+      }
+
+      const domain = inferDomainFromRedirect(values.DISCORD_REDIRECT_URI) || config.domain;
+      await updateHiveConfig({ envFile, domain });
+      success(`Env file ready at ${envFile}`);
+    });
+
+  env
+    .command('edit')
+    .description('Edit env values interactively')
+    .option('--env-file <path>', 'env file path')
+    .option('--yes', 'accept defaults where possible', false)
+    .action(async (options) => {
+      section('Env Edit');
+      const { envFile } = await resolveContext(options);
+      if (!existsSync(envFile)) {
+        throw new CliError(`Env file not found: ${envFile}. Run: hive env init`, EXIT.FAIL);
+      }
+      const existing = await loadEnvFile(envFile);
+      const values = await promptForEnv({ envFile, existing, yes: options.yes });
+      const issues = validateEnvValues(values);
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Env file has validation issues', EXIT.FAIL);
+      }
+      success(`Env file updated: ${envFile}`);
+    });
+
+  env
+    .command('check')
+    .description('Validate env file')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      section('Env Check');
+      const { envFile } = await resolveContext(options);
+      const { issues } = await loadValidatedEnv(envFile, { requireFile: true });
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Env validation failed', EXIT.FAIL);
+      }
+      success('Env validation passed');
+    });
+
+  env
+    .command('print')
+    .description('Print redacted env values')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { envFile } = await resolveContext(options);
+      const values = normalizeEnv(await loadEnvFile(envFile));
+      const redacted = redactEnv(values);
+      section(`Env (${envFile})`);
+      for (const [key, value] of Object.entries(redacted)) {
+        console.log(`${key}=${value}`);
+      }
+    });
+}
+
+function registerTunnelCommands(program) {
+  const tunnel = program.command('tunnel').description('Manage Cloudflare tunnel');
+
+  tunnel
+    .command('setup')
+    .description('Run full tunnel lifecycle setup')
+    .option('--env-file <path>', 'env file path')
+    .option('--domain <domain>', 'public domain')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .option('--cloudflared-config-file <path>', 'cloudflared config file')
+    .option('--install-service', 'install cloudflared service', false)
+    .option('--yes', 'non-interactive mode', false)
+    .action(async (options) => {
+      section('Tunnel Setup');
+      const { config, envFile } = await resolveContext(options);
+      const { env, issues } = await loadValidatedEnv(envFile, { requireFile: true });
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Fix env file first (hive env check)', EXIT.FAIL);
+      }
+
+      const domain = requiredOrFallback(
+        options.domain,
+        inferDomainFromRedirect(env.DISCORD_REDIRECT_URI) || config.domain
+      );
+      if (!validateDomain(domain)) {
+        throw new CliError(`Invalid domain: ${domain}`);
+      }
+
+      const tunnelName = requiredOrFallback(options.tunnelName, config.tunnelName || DEFAULT_TUNNEL_NAME);
+      const cloudflaredConfigFile = requiredOrFallback(
+        options.cloudflaredConfigFile,
+        config.cloudflaredConfigFile || DEFAULT_CLOUDFLARED_CONFIG
+      );
+
+      const tunnelResult = await setupTunnel({
+        tunnelName,
+        domain,
+        configFile: cloudflaredConfigFile,
+        certPath: DEFAULT_CLOUDFLARED_CERT,
+        port: parseInteger(env.PORT, 'PORT'),
+        yjsPort: parseInteger(env.YJS_PORT, 'YJS_PORT'),
+        yes: Boolean(options.yes),
+        installService: Boolean(options.installService),
+      });
+
+      const nextEnv = await setRedirectUriForDomain({
+        envFile,
+        env,
+        domain,
+        yes: Boolean(options.yes),
+      });
+
+      await updateHiveConfig({
+        envFile,
+        domain,
+        tunnelName,
+        tunnelId: tunnelResult.tunnelId,
+        tunnelCredentialsFile: tunnelResult.credentialsFile,
+        cloudflaredConfigFile: cloudflaredConfigFile,
+      });
+
+      if (nextEnv.DISCORD_REDIRECT_URI !== env.DISCORD_REDIRECT_URI) {
+        success('Redirect URI synced for tunnel domain');
+      }
+      success('Tunnel setup complete');
+    });
+
+  tunnel
+    .command('status')
+    .description('Show tunnel status and config')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .option('--cloudflared-config-file <path>', 'cloudflared config path')
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const tunnelName = requiredOrFallback(options.tunnelName, config.tunnelName || DEFAULT_TUNNEL_NAME);
+      const cloudflaredConfigFile = requiredOrFallback(
+        options.cloudflaredConfigFile,
+        config.cloudflaredConfigFile || DEFAULT_CLOUDFLARED_CONFIG
+      );
+      const status = await tunnelStatus({ tunnelName, configFile: cloudflaredConfigFile });
+      section('Tunnel Status');
+      console.log(`Name: ${tunnelName}`);
+      console.log(`Tunnel ID: ${status.tunnel?.id || '(not found)'}`);
+      console.log(`Config file: ${status.configFile} ${status.configExists ? '' : '(missing)'}`);
+      if (config.domain) {
+        console.log(`Domain: ${config.domain}`);
+      }
+      const svc = await cloudflaredServiceStatus().catch(() => false);
+      console.log(`cloudflared service: ${svc ? 'active' : 'inactive or unknown'}`);
+    });
+
+  tunnel
+    .command('run')
+    .description('Run tunnel in foreground')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const tunnelName = requiredOrFallback(options.tunnelName, config.tunnelName || DEFAULT_TUNNEL_NAME);
+      await runTunnelForeground({ tunnelName });
+    });
+
+  tunnel
+    .command('service-install')
+    .description('Install cloudflared as a system service')
+    .action(async () => {
+      section('Tunnel Service Install');
+      await installCloudflaredService();
+      success('cloudflared service installed');
+    });
+
+  tunnel
+    .command('service-status')
+    .description('Show cloudflared service status')
+    .action(async () => {
+      const active = await cloudflaredServiceStatus();
+      section('Tunnel Service Status');
+      console.log(active ? 'active' : 'inactive');
+      if (process.platform === 'darwin') {
+        const listing = await run('launchctl', ['list']).catch(() => ({ stdout: '' }));
+        const row = listing.stdout
+          .split('\n')
+          .find((line) => line.toLowerCase().includes('cloudflared'));
+        if (row) {
+          console.log('');
+          console.log(row.trim());
+        }
+      } else if (process.platform === 'linux') {
+        const status = await run('sudo', ['systemctl', 'status', 'cloudflared', '--no-pager', '--lines', '20'])
+          .catch(() => ({ stdout: '' }));
+        if (status.stdout) {
+          console.log('');
+          console.log(status.stdout);
+        }
+      }
+    });
+}
+
+function registerServiceCommands(program) {
+  const service = program.command('service').description('Manage Hive OS service');
+
+  service
+    .command('install')
+    .description('Install Hive as launchd/systemd service')
+    .option('--env-file <path>', 'env file path')
+    .option('--yes', 'non-interactive mode', false)
+    .action(async (options) => {
+      const { config, envFile } = await resolveContext(options);
+      const infoOut = await installHiveService({
+        envFile,
+        yes: Boolean(options.yes),
+        serviceName: config.serviceName,
+      });
+      await updateHiveConfig({
+        envFile,
+        servicePlatform: infoOut.servicePlatform,
+        serviceName: infoOut.serviceName,
+      });
+      success(`Service installed: ${infoOut.serviceName}`);
+    });
+
+  service
+    .command('start')
+    .description('Start Hive service')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await startHiveService(svc);
+      success('Hive service started');
+    });
+
+  service
+    .command('stop')
+    .description('Stop Hive service')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await stopHiveService(svc);
+      success('Hive service stopped');
+    });
+
+  service
+    .command('restart')
+    .description('Restart Hive service')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await restartHiveService(svc);
+      success('Hive service restarted');
+    });
+
+  service
+    .command('status')
+    .description('Show Hive service status')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      const status = await getHiveServiceStatus(svc);
+      section('Hive Service Status');
+      console.log(`Service: ${svc.serviceName} (${svc.servicePlatform})`);
+      console.log(`Active: ${status.active ? 'yes' : 'no'}`);
+      if (status.detail) {
+        console.log('');
+        console.log(status.detail);
+      }
+    });
+
+  service
+    .command('logs')
+    .description('Stream service logs')
+    .option('-n, --lines <n>', 'lines to show', '80')
+    .option('--no-follow', 'do not follow logs')
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      const lines = parseInteger(options.lines, 'lines');
+      await streamHiveServiceLogs({
+        ...svc,
+        follow: Boolean(options.follow),
+        lines,
+      });
+    });
+
+  service
+    .command('uninstall')
+    .description('Uninstall Hive service')
+    .option('--yes', 'skip confirmation', false)
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await uninstallHiveService({
+        ...svc,
+        yes: Boolean(options.yes),
+      });
+      success(`Service removed: ${svc.serviceName}`);
+    });
+}
+
+function registerRootCommands(program) {
+  program
+    .command('setup')
+    .description('Run guided setup for env, tunnel, and service')
+    .option('--env-file <path>', 'env file path')
+    .option('--domain <domain>', 'public domain')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .option('--cloudflared-config-file <path>', 'cloudflared config file')
+    .option('--yes', 'non-interactive mode', false)
+    .action(runSetupWizard);
+
+  program
+    .command('doctor')
+    .description('Run prerequisite and configuration checks')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { envFile } = await resolveContext(options);
+      await runDoctorChecks({ envFile, includeCloudflared: true });
+    });
+
+  program
+    .command('run')
+    .description('Start Hive server immediately')
+    .option('--env-file <path>', 'env file path')
+    .option('--quiet', 'reduce startup logs', false)
+    .action(async (options) => {
+      const { envFile } = await resolveContext(options);
+      if (!existsSync(envFile)) {
+        throw new CliError(`Env file not found: ${envFile}. Run: hive env init`, EXIT.FAIL);
+      }
+      await startHiveServer({ envFile, quiet: Boolean(options.quiet) });
+      info(`Hive server started using env: ${envFile}`);
+    });
+
+  program
+    .command('status')
+    .description('Quick status summary (service + tunnel + doctor-lite)')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { config, envFile } = await resolveContext(options);
+      section('Hive Status');
+      console.log(`Config: ${HIVE_CONFIG_FILE}`);
+      console.log(`Env: ${envFile} ${existsSync(envFile) ? '' : '(missing)'}`);
+      if (config.domain) console.log(`Domain: ${config.domain}`);
+      if (config.tunnelName) console.log(`Tunnel: ${config.tunnelName}`);
+
+      const svc = resolveServiceConfig(config);
+      const serviceStatus = await getHiveServiceStatus(svc).catch(() => ({ active: false, detail: 'not installed' }));
+      console.log(`Service ${svc.serviceName}: ${serviceStatus.active ? 'active' : 'inactive'}`);
+
+      const tunnelSvc = await cloudflaredServiceStatus().catch(() => false);
+      console.log(`cloudflared service: ${tunnelSvc ? 'active' : 'inactive or unknown'}`);
+    });
+}
+
+export async function runCli(argv = process.argv) {
+  const program = new Command();
+
+  program
+    .name('hive')
+    .description('Hive server operations CLI')
+    .showHelpAfterError()
+    .version('1.0.0');
+
+  registerRootCommands(program);
+  registerEnvCommands(program);
+  registerTunnelCommands(program);
+  registerServiceCommands(program);
+
+  program.exitOverride();
+
+  try {
+    await program.parseAsync(argv);
+    return EXIT.OK;
+  } catch (err) {
+    if (err instanceof CommanderError) {
+      if (err.code === 'commander.helpDisplayed') return EXIT.OK;
+      throw new CliError(err.message, err.exitCode ?? EXIT.FAIL);
+    }
+    throw err;
+  }
+}
+
+export async function runCliOrExit(argv = process.argv) {
+  try {
+    const code = await runCli(argv);
+    process.exit(code);
+  } catch (err) {
+    const exitCode = err instanceof CliError ? err.exitCode : EXIT.FAIL;
+    const message = err instanceof Error ? err.message : String(err);
+    fail(message);
+    process.exit(exitCode);
+  }
+}