/**
 * CLI Entry Point
 *
 * Orchestration function (Rule 10.1) - routes commands to handlers
 */

import { log as uiLog } from '@celilo/cli-display';
import {
  COMMANDS,
  type CommandDef,
  EXIT_BLOCKED,
  resolveRemote,
  runRemoteClient,
} from '@celilo/core';
import { CLIServerRequestSchema, parseJsonWithValidation } from '../validation/schemas';
import {
  handleApiAuthorizedKeys,
  handleApiGrant,
  handleApiKeyNew,
  handleApiList,
  handleApiRevoke,
} from './commands/api';
import { handleAptUpgrade } from './commands/apt-upgrade';
import { handleCapabilityInfo } from './commands/capability-info';
import { handleCapabilityList } from './commands/capability-list';
import { handleCommands } from './commands/commands-json';
import { handleCompletion } from './commands/completion';
import { handleConsoleGet, handleConsoleStatus } from './commands/console';
import { handleDnsRegistrations } from './commands/dns';
import {
  handleEventsAck,
  handleEventsDrain,
  handleEventsEmit,
  handleEventsFail,
  handleEventsInstallDaemon,
  handleEventsListFailed,
  handleEventsListPending,
  handleEventsListSubscribers,
  handleEventsListUnanswered,
  handleEventsRepair,
  handleEventsReply,
  handleEventsRespond,
  handleEventsRestartDaemon,
  handleEventsResyncSubscriptions,
  handleEventsRun,
  handleEventsRunHook,
  handleEventsShowDaemon,
  handleEventsStatus,
  handleEventsTail,
  handleEventsUninstallDaemon,
} from './commands/events';
import { handleFirewallInterfaceList } from './commands/firewall-interface-list';
import { handleHookRun } from './commands/hook-run';
import {
  handleIpamIpEdit,
  handleIpamIpListReservations,
  handleIpamIpReserve,
  handleIpamIpUnreserve,
  handleIpamListAllocations,
  handleIpamShow,
  handleIpamVmidListReservations,
  handleIpamVmidReserve,
  handleIpamVmidUnreserve,
} from './commands/ipam';
import { handleMachineAdd } from './commands/machine-add';
import { handleMachineEarmark } from './commands/machine-earmark';
import { handleMachineList } from './commands/machine-list';
import { handleMachineRemove } from './commands/machine-remove';
import { handleMachineStatus } from './commands/machine-status';
import { moduleAudit } from './commands/module-audit';
import { handleModuleBuild } from './commands/module-build';
import { handleModuleChangeset } from './commands/module-changeset';
import { handleModuleCheck } from './commands/module-check';
import {
  handleModuleConfigGet,
  handleModuleConfigSet,
  handleModuleConfigUnset,
} from './commands/module-config';
import { handleModuleDeploy } from './commands/module-deploy';
import { handleModuleGenerate } from './commands/module-generate';
import { handleModuleHealth } from './commands/module-health';
import { handleModuleImport } from './commands/module-import';
import { handleModuleJail } from './commands/module-jail';
import { handleModuleJournal } from './commands/module-journal';
import { handleModuleList } from './commands/module-list';
import { handleModuleLogs } from './commands/module-logs';
import { handleModuleOperations } from './commands/module-operations';
import { handleModulePause, handleModuleUnpause } from './commands/module-pause';
import { handleModulePublish } from './commands/module-publish';
import { handleModuleRemove } from './commands/module-remove';
import { handleModuleSearch } from './commands/module-search';
import { handleModuleShowConfig, handleModuleShowZone } from './commands/module-show';
import { handleModuleStatus } from './commands/module-status';
import { handleModuleTerraformUnlock } from './commands/module-terraform-unlock';
import { handleModuleTypesCheck, handleModuleTypesGenerate } from './commands/module-types';
import { handleModuleUpdate } from './commands/module-update';
import { handleModuleUpgrade } from './commands/module-upgrade';
import { moduleVerify } from './commands/module-verify';
import { handleModuleVersion } from './commands/module-version';
import { handleModuleWhere } from './commands/module-where';
import { handlePackage } from './commands/package';
import { handleProxmoxInstanceList } from './commands/proxmox-instance-list';
import { handleProxmoxInstanceResize } from './commands/proxmox-instance-resize';
import { handleProxmoxNodeList } from './commands/proxmox-node-list';
import { handleSecretList } from './commands/secret-list';
import { handleSecretSet } from './commands/secret-set';
import { handleServiceAddDigitalOcean } from './commands/service-add-digitalocean';
import { handleServiceAddProxmox } from './commands/service-add-proxmox';
import { handleServiceConfigGet } from './commands/service-config-get';
import { handleServiceConfigSet } from './commands/service-config-set';
import { handleServiceList } from './commands/service-list';
import { handleServiceReconfigure } from './commands/service-reconfigure';
import { handleServiceRemove } from './commands/service-remove';
import { handleServiceSetCredentials } from './commands/service-set-credentials';
import { handleServiceVerify } from './commands/service-verify';
import { handleStatus } from './commands/status';
import { handleSubscribersAdd } from './commands/subscribers-add';
import {
  handleSubscribersInstallDaemon,
  handleSubscribersUninstallDaemon,
} from './commands/subscribers-install-daemon';
import { handleSubscribersList } from './commands/subscribers-list';
import { handleSubscribersRemove } from './commands/subscribers-remove';
import { handleSubscribersServe } from './commands/subscribers-serve';
import { handleSubscribersStatus } from './commands/subscribers-status';
import { handleSubscribersTest } from './commands/subscribers-test';
import { handleSystemApplyConfig } from './commands/system-apply-config';
import { handleSystemAudit } from './commands/system-audit';
import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
import { handleSystemDiscoverNetwork } from './commands/system-discover-network';
import { handleSystemDoctor } from './commands/system-doctor';
import { handleSystemEnsureFleetKey } from './commands/system-ensure-fleet-key';
import { handleSystemInit } from './commands/system-init';
import { handleSystemMigrate } from './commands/system-migrate';
import { handleSystemSecretGet } from './commands/system-secret-get';
import { handleSystemSecretSet } from './commands/system-secret-set';
import { handleSystemUpdate } from './commands/system-update';
import { handleSystemVaultPassword } from './commands/system-vault-password';
import { getCompletions } from './completion';
import { parseArguments, validateFlags } from './parser';
import type { CommandResult } from './types';

/**
 * Look up a command definition from the registry and validate flags.
 * Walks the full subcommand chain (e.g., ipam -> ip -> reserve) to find
 * the leaf command where flags are defined.
 * Returns an error CommandResult if unknown flags are found, or null if valid.
 */
function checkFlags(
  command: string,
  subcommand: string | undefined,
  flags: Record<string, string | boolean>,
  args: string[] = [],
): CommandResult | null {
  // Skip validation for help requests
  if (flags.help || flags.h) return null;

  const topDef = COMMANDS.find((c) => c.name === command);
  if (!topDef) return null;

  let commandDef: CommandDef | undefined = subcommand
    ? topDef.subcommands?.find((s) => s.name === subcommand)
    : topDef;
  if (!commandDef) return null;

  // Walk deeper into nested subcommands using args
  // e.g., for "ipam ip reserve", subcommand='ip' and args=['reserve', ...]
  // We need to find the 'reserve' sub-subcommand to get its flags
  for (const arg of args) {
    const deeper: CommandDef | undefined = commandDef?.subcommands?.find((s) => s.name === arg);
    if (!deeper) break;
    commandDef = deeper;
  }

  if (!commandDef) return null;

  const error = validateFlags(flags, commandDef);
  if (error) {
    return { success: false, error };
  }
  return null;
}

/**
 * Display CLI version. Reads the npm package version from this
 * package's manifest at runtime — single source of truth, so
 * `bun publish` bumping the version automatically updates what
 * `celilo --version` reports.
 */
function displayVersion(): CommandResult {
  const pkg = require('../../package.json') as { version: string };
  return { success: true, message: `celilo ${pkg.version}` };
}

/**
 * Display general help message
 */
function displayHelp(): CommandResult {
  const helpText = `
Celilo - Home Lab Orchestration System

Usage:
  celilo <command> [subcommand] [args...] [options]

Commands:
  status                   Show system and module status
  audit                    Top-level alias for 'system audit'
  alerts                   View alerts raised by monitors
  monitor                  Manage what celilo watches (health checks on a schedule)
  person                   Manage people celilo can reach
  route                    Manage how each person is reached (transport + address)
  escalation-policy        Manage who gets paged, and in what order
  events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
  capability               View registered module capabilities
  dns                      View DNS bookkeeping (registrations ledger)
  package                  Create distributable .netapp packages from module source
  module                   Manage modules (import, list, configure, build, generate)
  service                  Manage container services (Proxmox, Digital Ocean)
  storage                  Manage backup storage destinations
  backup                   Create and manage backups
  restore                  Restore a celilo-mgmt backup from a local file (fresh-bootstrap path)
  firewall                 Inspect a firewall's interfaces (classification, on demand)
  machine                  Manage machine pool (bring-your-own-hardware)
  system                   Manage system configuration
  apt-upgrade              Upgrade the deb-installed celilo packages + apply migrations
  ipam                     Manage IP address and VMID allocations and reservations
  proxmox                  Proxmox cluster introspection (proxmox node list)
  publish                  Publish workspace packages to npm and modules to celilo.computer
  registry                 Administer the module registry (append-safe publish-token management)
  token                    Manage contributor identity tokens (idp-issued per-user publish tokens)
  subscribers              Manage build-bus subscribers (cross-machine publish-event delivery)
  api                      Manage remote-API access (principals, grants, authorized_keys)
  completion               Generate shell completion scripts (bash/zsh)
  commands                 Print the CLI command registry as JSON (drives @celilo/mcp)
  console                  Narrow read-only projections for the web console

  help, --help, -h         Show this help message

Run any command on a remote celilo-mgr over SSH:
  celilo --remote <ssh-dest> <command>     (or set CELILO_REMOTE=<ssh-dest>)

For command-specific help:
  celilo package --help
  celilo module --help
  celilo secret --help
  celilo service --help
  celilo machine --help
  celilo system --help
  celilo ipam --help

Enable tab completion:
  # Bash
  celilo completion bash >> ~/.bashrc && source ~/.bashrc
  # Zsh
  celilo completion zsh >> ~/.zshrc && source ~/.zshrc

Examples:
  celilo package ./modules/homebridge
  celilo module import ./modules/homebridge
  celilo module list
  celilo module build caddy
  celilo module secret set homebridge api_key mykey123
  celilo system config set dns.primary 192.168.0.1
  celilo system vault-password
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display package command help
 */
function displayPackageHelp(): CommandResult {
  const helpText = `
Celilo - Module Packaging

Usage:
  celilo package <source-directory> [options]

Description:
  Creates a distributable .netapp package from a module source directory.
  The package includes checksums and a signature for integrity verification.

Options:
  --output <path>    Output path for the package (default: <source-dir>/<module-id>.netapp)

Examples:
  celilo package ./modules/homebridge
  celilo package ./my-module --output /tmp/test.netapp
  celilo package ../custom-module

Related Commands:
  celilo module import <name-or-path>      Import a module (registry name or local path)
  celilo module verify <module-id>         Verify package integrity
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display capability command help
 */
function displayEventsHelp(): CommandResult {
  const helpText = `
Celilo - SQLite Event Bus

Usage:
  celilo events <subcommand> [args...]

Subcommands:
  status                       Print bus health as JSON
  tail [--type T] [--limit N]  Recent events as JSON
  list-subscribers             List persistent bus subscribers
  resync-subscriptions         Rebuild subscribers from deployed modules' manifests (after a restore/migration)
  list-pending [--subscriber]  List pending deliveries
  list-failed [--subscriber]   List failed/abandoned deliveries with a true total
  list-unanswered              List interview questions nobody has answered yet
  drain [--concurrency N]      Process pending deliveries once and return
  run [--poll-ms N]            Run the long-running dispatcher (foreground)
  emit <type> [<payload>]      Emit an event (operator/test path)
  reply <event_id> <value>     Answer one pending interview query by id (config/secret/ensure)
  ack <event_id>               Mark a running delivery succeeded
  fail <event_id> --error MSG  Mark a running delivery failed
  repair                       Crash-recovery sweep without starting the dispatcher
  resume                       Alias for repair (acknowledges halt-on-recovery)
  respond                      Run the terminal responder; answer deploy prompts from another shell
  install-daemon [--system]    Write a systemd/launchd unit for the dispatcher (--system: management-plane scope)
  uninstall-daemon [--system]  Remove the installed supervisor unit
  restart-daemon [--system]    Restart the dispatcher and verify the new process is on current code
  show-daemon [--system]       Print the currently installed unit file

Description:
  The event bus is a SQLite-backed pub/sub layer for celilo modules.
  Modules declare \`subscriptions:\` in their manifests; \`celilo module deploy\`
  emits lifecycle events that subscribers react to.

  See infra/openspec/specs/event-bus/spec.md for the full design.

Examples:
  celilo events run                                      # foreground dispatcher
  celilo events status                                   # is anything stuck?
  celilo events tail --type deploy.completed.lunacycle   # filter by type
  celilo events emit deploy.completed.lunacycle '{}'     # operator-fired event
  celilo events tail --type 'config.required.*'          # see pending deploy questions
  celilo events reply 42 '"example.net"'               # answer query #42 (config)
`;
  return { success: true, message: helpText.trim() };
}

function displaySubscribersHelp(): CommandResult {
  const helpText = `
Celilo - Build-Bus Subscribers

Usage:
  celilo subscribers <subcommand> [args...] [options]

Subcommands:
  list                                 Show registered subscribers (truncated secret fingerprints)
  add <url> --secret <hmac-secret>     Add a subscriber (replaces any with the same URL)
       [--name <label>] [--registry <r>]
       [--tag <t>] [--package-pattern <glob>]
  remove <url>                         Remove a subscriber
  test <url>                           Fire a synthetic event at a subscriber; report delivery
  serve --secret <hmac-secret>         Run the receiver daemon (verifies + emits to local bus)
       [--port <p>] [--no-dispatch]
  install-daemon --secret <s>          Write a supervisor unit for the receiver (celilo#1304:
       [--system] [--port <p>]         nothing else installs it). Runs serve --no-dispatch so the
       [--dispatch] [--print]          standing dispatcher keeps owning hook delivery.
  uninstall-daemon [--system]          Remove the receiver supervisor unit
  status                               Per-subscriber delivery history (success rate, recent failures)
  --help, -h                           Show this help

Description:
  Subscribers receive signed webhooks when 'celilo publish' ships a
  new package version. Each subscriber has a per-target HMAC secret,
  a target URL, and optional match filters (registry, dist-tag,
  package name glob). The publisher signs every event with the
  subscriber's secret; the receiver verifies before reacting.

  This is the static-config first cut of openspec/changes/build-bus-poll-cd/proposal.md — operators
  manage subscribers explicitly. Auto-discovery via the celilo
  registry switchboard is a follow-on.

Examples:
  celilo subscribers add https://lunacycle.lab/build-bus --secret <hex> \\
      --name "lunacycle build box" --registry npm --package-pattern '@celilo/*'
  celilo subscribers list
  celilo subscribers test https://lunacycle.lab/build-bus
  celilo subscribers remove https://lunacycle.lab/build-bus
`;
  return { success: true, message: helpText.trim() };
}

function displayPublishHelp(): CommandResult {
  const helpText = `
Celilo - Publish Workspace Packages and Modules

Usage:
  celilo publish [options]

Options:
  --dry-run               Preflight report only — no publishing, no file changes
  --release-touch         Auto-touch drifted module manifests with a fresh release marker
  --allow-stale           Bypass workspace and module stale-version safeguards
  -y, --yes               Auto-confirm every prompt (doesn't bypass safety gates)
  --alpha                 Publish X.Y.Z-alpha.N to npm @alpha dist-tag
  --track-alpha           Force-pin just-published alphas into bun global (with --alpha)
  --alpha-modules         Also publish module +N revisions in alpha mode (with --alpha)
  --promote <spec>        Graduate a named alpha to its base X.Y.Z (e.g. @celilo/e2e@0.7.14-alpha.3)
  --skip-changesets       Skip the pending-changesets prompt at the top of normal-mode publishes
  --help, -h              Show this help message

Description:
  Publishes @celilo/* workspace packages to npm, bumps consumer dependency pins,
  updates the bun global install, and ships modules to celilo.computer. Runs four
  phases: preflight + workspace publish, consumer pin bump, global install update,
  module registry publish.

  In normal mode, if pending changesets exist under .changeset/ (recorded by
  'bun changeset' during dev), 'celilo publish' applies them via
  'bunx changeset version' before planning. Skipped in alpha + promote modes.

  --alpha mode publishes pre-release versions under the @alpha dist-tag so consumers
  can opt into iteration via 'bun add @celilo/<pkg>@alpha' without disturbing @latest.
  Auto-skips packages whose source hasn't changed since the prior alpha.

  --promote graduates a vetted alpha to its real X.Y.Z and runs all four phases.

Examples:
  celilo publish                                        # Full publish flow
  celilo publish --dry-run                              # Show plan, no side effects
  celilo publish --alpha                                # Ship pre-release alphas
  celilo publish --alpha --track-alpha                  # Alpha + pin into global install
  celilo publish --promote @celilo/e2e@0.7.14-alpha.3   # Graduate alpha to real release
  celilo publish --skip-changesets                      # Publish current versions; ignore .changeset/*.md

Related Commands:
  bun changeset                  Record a pending version bump (read by 'celilo publish')
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

function displayDnsHelp(): CommandResult {
  const helpText = `
Celilo - DNS Bookkeeping

Usage:
  celilo dns <subcommand> [options]

Subcommands:
  registrations           List the DNS registration ledger

Description:
  Every successful dns_registrar.registerHost (e.g. a deploy registering
  its public hostname with namecheap) is recorded in the registration
  ledger. The provider's refresh_registrations hook re-asserts these on
  a timer; REFRESHED shows when that last succeeded.

Options:
  --provider <module-id>  Only show registrations owned by one provider

Examples:
  celilo dns registrations
  celilo dns registrations --provider namecheap
`;
  return { success: true, message: helpText };
}

function displayRegistryHelp(): CommandResult {
  const helpText = `
Celilo - Module Registry Administration

Usage:
  celilo registry <subcommand> [args...]

Subcommands:
  token add <token>            Append a publish token (append-safe; never clobbers others)
  token rm <token>             Remove one publish token, leaving the rest intact
  owner list                   List the module-owner table (who may publish what)
  owner show <module>          Show the owner of one module name
  owner set <module> <sub>     Reassign a module name to a new owner (admin)

Description:
  The celilo-registry module's publish_tokens secret is a newline-separated list
  of bootstrap/admin publish tokens. Editing it with 'module secret set' OVERWRITES
  the whole list, clobbering every other holder. These commands read-modify-write
  the list instead.

  The module-owner table (owner *) gates which module NAMES a verified publisher
  may publish: the first verified publisher of an unclaimed name owns it
  (first-publish-claims); thereafter only that owner or an admin may publish it.
  'owner set' is the admin reassignment. These read the admin token from the local
  publish_tokens list; pass --registry to target a non-default registry.

  Run on the host where celilo-registry is deployed (where the master key lives).

Examples:
  celilo registry token add ci-token-abc123
  celilo registry owner list
  celilo registry owner show homebridge
  celilo registry owner set homebridge alice
`;

  return { success: true, message: helpText.trim() };
}

function displayTokenHelp(): CommandResult {
  const helpText = `
Celilo - Contributor Identity Tokens (idp-issued, per-user)

Usage:
  celilo token <subcommand> [args...]

Subcommands:
  obtain --user <username>    Mint (or return) a per-user API token for publishing
  list   --user <username>    List a user's API tokens (metadata only, no secret)
  revoke <identifier>         Revoke a token by identifier; next publish denied

Options:
  --user <username>           The idp user the token is bound to
  --identifier <id>           Token identifier (default: celilo-publish-<user>)
  --description <text>        Human-readable description (obtain only)

Description:
  Issues per-user API tokens from the idp (authentik) so a module contributor
  authenticates publishes AS THEMSELVES — no admin/shared token on their machine.
  The token is consumed by 'celilo author init'. Shown once at mint; the idp
  stores it hashed and celilo persists nothing.

  Distinct from 'celilo registry token add/rm', which manages the raw bootstrap
  publish_tokens list. Run on the host where the idp is deployed (celilo-mgr).

Examples:
  celilo token obtain --user alice
  celilo token list --user alice
  celilo token revoke celilo-publish-alice
`;

  return { success: true, message: helpText.trim() };
}

function displayCapabilityHelp(): CommandResult {
  const helpText = `
Celilo - Capability Management

Usage:
  celilo capability <subcommand> [args...]

Subcommands:
  list                    List all registered capabilities
  info <name>             Show detailed capability information

Description:
  Capabilities are cross-module data contracts. A module can "provide" a capability
  (e.g., dns_registrar) and other modules can "require" it to access shared data
  and secrets.

  Capabilities are automatically registered when importing modules that declare
  "provides.capabilities" in their manifest.

Examples:
  celilo capability list
  celilo capability info dns_registrar
  celilo capability info public_web
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display module command help
 */
function displayModuleHelp(): CommandResult {
  const helpText = `
Celilo - Module Management

Usage:
  celilo module <subcommand> [args...] [options]

Subcommands:
  import <name-or-path>                Import a module from the registry (bare name) or a local path
    Options:
      --registry <url>                 Use a custom registry (default: https://celilo.computer/registry)
      --target <path>                  Target base directory (default: platform-specific)
      --auto-generate-secrets          Auto-generate all secrets without prompting

  list                                 List all installed modules
    Options:
      --json                           Output the module roster as stable JSON

  status <id>                          Show detailed module status

  where <id>                           Show which host(s) serve a module (host discovery)
    Options:
      --json                           Output host discovery as stable JSON

  logs <id>                            Show deploy logs for a module
    Options:
      --tail <n>                       Show last N lines
      --last                           Show only the most recent deploy run

  journal <id>                         Tail a deployed module's runtime daemon journal on its host (no SSH)
    Options:
      --unit <glob>                    systemd unit or glob (default: <module-id>*)
      --lines <n>                      Lines to return (default 100)
      --since <window>                 Time window, e.g. '30 min ago'
      --grep <text>                    Only lines containing this fixed string
      --json                           Machine-readable JSON output

  operations list|clear                Show or release in-flight module operations (the backup/restore lock)
    Options:
      --all                            With clear: also release operations that still look alive
      --abandoned                      With list: also show abandoned rows (hidden by default)

  remove <id>                          Remove a module and all its data

  pause <id>                           Quiesce a module without uninstalling it (container keeps running)
    Options:
      --cascade                        Also pause every dependent module, consumers first
      --stop-infra                     Also stop the module's container or service
      --reason <text>                  Why the pause was taken, recorded on the module
      --dry-run                        Print the ordered plan and change nothing
      --yes                            Skip the cascade confirmation

  unpause <id>                         Redeploy a paused module, rebinding it to current providers
    Options:
      --cascade                        Also unpause every dependent module, providers first
      --dry-run                        Print the ordered plan and change nothing
      --yes                            Skip the cascade confirmation

  verify <id>                          Verify module integrity (signature + checksums) (legacy alias: 'audit')
    Options:
      --deep                           Deep verification (re-check all files)
      --json                           Machine-readable JSON output

  validate <id>                        Pre-flight check: validate module is ready for deployment

  config set <id> <key> <value>        Set module configuration value
  config get <id> [key]                Get module configuration value(s)
  config unset <id> <key>              Remove an override; follow the manifest again

  secret set <id> <key> <value>        Set encrypted module secret
  secret get <id> <key>                Get a decrypted module secret value
  secret list <id>                     List module secrets

  jail <id> [policy]                   Get or set one module's hook jail policy (auto|off|required)
    Options:
      --clear                          Remove the module's policy; follow the system's hooks.jail_policy again
      --force                          Skip the confirmation when the new policy is weaker than the system's

  show-config <id>                     Show all config including auto-derived values
  show-zone <id>                       Show module's network zone and config

  build <module-id>                    Execute module build scripts (Ansible)

  generate <id>                        Generate infrastructure code for module
    Options:
      --output <path>                  Output directory (default: <module>/generated)

  deploy <module-id>                   Deploy module to infrastructure (auto-generates/builds if needed)
    Options:
      --debug                            Run hooks with visible browser (Playwright)
      --preflight                        Run pre-flight validation only (no deployment)
      --verbose                          Keep all sub-events visible (no collapse-on-success)
      --stop-after-interview             Exit after config+secrets interview (no infra/hooks)
      --keep                             Retain the generated project after a successful deploy (it is deleted by design)

  health [module-id]                    Run health checks (transitions to VERIFIED on success)
    Options:
      --json                             Machine-readable JSON output
      --debug                            Show detailed check output

  run-hook <id> <hook-name> [k=v...]   Run a module hook (e.g., retry on_install after fixing an issue)
    Options:
      --debug                            Run with visible browser (Playwright hooks)

  update                                Sweep registry: auto-apply non-breaking updates, prompt for breaking
  update <path> [path...]               Update module(s) from local path(s) (preserves config/secrets/infra)
    Options:
      --registry <url>                  Use a custom registry (sweep mode only)

  upgrade <id>                         Upgrade a module to its latest registry version (update, posture-gated backup, deploy, verify)
    Options:
      --poll                           Run the CD poll: upgrade every auto_upgrade module with a newer version
      --registry <url>                 Registry URL (defaults to configured registry)

Registry:
  search [query]                       Search the registry for modules
    Options:
      --registry <url>                 Use a custom registry
      --limit <n>                      Max results (default: 25)

  publish <module-dir>...              Build and publish one or more modules to the registry
    Options:
      --token <token>                  Publish token. Falls back to CELILO_PUBLISH_TOKEN env var, then celilo-registry's publish_tokens secret.
      --registry <url>                 Use a custom registry
      --revision <n>                   Force package revision number (default: auto). Not allowed with multiple module dirs.
      --message <text>                 Release note recorded in the .netapp's release.json
      --allow-dirty                    Permit publishing from a dirty git tree
      --allow-stale                    Skip the manifest-vs-src stale-check. Use sparingly.

  changeset <module-dir>               Author a version changeset for a module (.changeset/<name>.md)
    Options:
      --bump <type>                    Version bump type: major, minor or patch (required)
      --message <text>                 Changeset body text
      --name <stem>                    Changeset filename stem (default: auto-generated slug)

  backup <module-id>                   Create a backup of a module's data (invokes its on_backup hook)
    Options:
      --force                          Ignore schedule, back up now
      --now                            Ignore schedule, back up now (alias for --force)
      --storage <id>                   Storage destination ID
      --no-interactive                 Non-interactive mode (for cron)

  check [path]                         Check a module for drift against the framework (default: .)
    Options:
      --no-build                       Skip the TypeScript build check
      --json                           Emit a structured Check[] payload (CI-friendly)
      --strict                         Treat warnings as failures

Examples:
  celilo module import caddy                       # registry (bare name)
  celilo module import namecheap --registry https://my-registry.example.com/registry
  celilo module import ./modules/homebridge        # local directory
  celilo module import homebridge.netapp           # local .netapp file
  celilo module import /abs/path/to/module --target /custom/location
  celilo module search dns
  celilo module publish ./modules/caddy --token mytoken
  celilo module publish ./modules/*                # publish every module in a dir
  celilo module list
  celilo module remove homebridge

  # Swap a capability provider (e.g. a replaced edge router):
  celilo module pause --cascade greenwave --reason "ISP swapped the router"
  celilo module remove greenwave
  celilo module import axon && celilo module deploy axon
  celilo module unpause --cascade axon
  celilo module verify homebridge
  celilo module config set homebridge hostname myhost
  celilo module config set homebridge container_ip "192.168.0.110/24"
  celilo module config get homebridge
  celilo module config get homebridge hostname
  celilo module config set caddy backup_schedule 6h
  celilo module config unset caddy backup_schedule
  celilo module show-config homebridge
  celilo module show-zone homebridge
  celilo module build caddy
  celilo module generate homebridge
  celilo module generate homebridge --output /custom/output
  celilo module deploy homebridge
  celilo module deploy caddy
  celilo module run-hook caddy on_install
  celilo module run-hook namecheap validate_config --debug
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display service command help
 */
function displayServiceHelp(): CommandResult {
  const helpText = `
Celilo - Container Service Management

Usage:
  celilo service <subcommand> [args...] [options]

Subcommands:
  add proxmox           Configure a Proxmox container service
  add digitalocean      Configure a Digital Ocean VPS service
  list                  List all configured container services
    Options:
      --zone <zone>     Filter by network zone
  verify <service-id>   Re-verify a container service connection
  set-credentials <service-id>  Update a provider endpoint or API credential
  reconfigure <service-id>  Re-run configuration interview (change template, storage, etc.)
  remove <id>           Remove a container service
    Options:
      --force           Skip confirmation prompts
  config get <service-id> [key]       Get service configuration
  config set <service-id> <key> <value>  Set service configuration

Description:
  Container services are API-driven infrastructure providers that can automatically
  provision containers/VMs for modules. Celilo prefers container services over
  manually-added machines when selecting infrastructure during module generation.

  Supported providers:
    - Proxmox: LXC containers on home lab hardware
    - Digital Ocean: Cloud VPS instances

Examples:
  # Add container services
  celilo service add proxmox
  celilo service add digitalocean

  # List all services
  celilo service list

  # List services for specific zone
  celilo service list --zone dmz

  # Verify a service connection
  celilo service verify proxmox-home-lab

  # Move a Proxmox endpoint while retaining its existing token
  celilo service set-credentials proxmox-home-lab --api-url https://10.77.20.50:8006

  # Get service configuration
  celilo service config get proxmox-home-lab
  celilo service config get proxmox-home-lab name
  celilo service config get proxmox-home-lab zones

  # Set service configuration
  celilo service config set proxmox-home-lab name "New Service Name"
  celilo service config set proxmox-home-lab zones '["dmz", "app"]'
  celilo service config set proxmox-home-lab providerConfig '{"storage": "local-lvm"}'

  # Remove service
  celilo service remove <service-id>
  celilo service remove <service-id> --force

Related Commands:
  celilo module generate <module-id>    Generate infrastructure code (uses services)
  celilo module deploy <module-id>      Deploy module to infrastructure
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display backup command help
 */
function displayBackupHelp(): CommandResult {
  const helpText = `
Celilo - Backup Management

Usage:
  celilo backup <subcommand> [args...] [options]

Subcommands:
  create [module-id]       (DEPRECATED) Create a backup. Use 'celilo module backup' instead.
    Options:
      --force              Ignore schedule, back up now
      --storage <id>       Use specific storage destination
      --no-interactive     Non-interactive mode (for cron)

  sweep                    Back up every module whose declared schedule is due
                           (run by the event bus on timer.tick.1h, not by hand)

  list [module-id]         List available backups
    Options:
      --limit <n>          Number of backups to show (default: 20; 5000 with --json)
      --json               Emit the listing as JSON with EXACT timestamps.
                           The human output buckets ages past six days into
                           "last week", so it cannot be parsed back into days.
      --since <days>       Only attempts from the last N days

  restore <backup-id>      Restore from a backup
    Options:
      --yes                Skip confirmation prompt

  delete <backup-id>       Delete a specific backup
    Options:
      --force              Skip confirmation prompt

  prune [module-id]        Remove old backups per retention policies
    Options:
      --dry-run            Show what would be deleted without deleting

  name <backup-id> [name]  Get or set a human-readable name on a backup
    Options:
      --clear              Remove the name

  import <file> <module>   Import a local file as a module backup
    Options:
      --name <name>        Human-readable name for the backup
      --schema-version <v> Schema version metadata
      --storage <id>       Use specific storage destination
      --yes                Skip confirmation prompt

  pull                      Download another box's backup artifact from a storage destination
    Options:
      --storage <name>     Storage destination name
      --module <id>        Module ID whose backup to pull (default: system state)
      --output <path>      Local path to write the artifact

Description:
  Backups are encrypted with the master key and uploaded to a configured
  storage destination. System state backups capture the Celilo database.
  Module data backups use on_backup hooks defined in module manifests.

  Any command that accepts a <backup-id> also accepts a backup name.
  Use "celilo backup name" to assign human-readable names.

Examples:
  # Create a full backup (system + all due modules) — canonical path:
  celilo module backup

  # Back up a specific module — canonical path:
  celilo module backup authentik --force

  # List recent backups
  celilo backup list
  celilo backup list authentik --limit 5

  # Restore from a backup
  celilo backup restore <backup-id>

  # Name a backup
  celilo backup name <backup-id> Data from beso before migration
  celilo backup name <backup-id> --clear

  # Prune old backups
  celilo backup prune --dry-run
  celilo backup prune

  # Import a local file as a backup
  celilo backup import ./backups/db.sqlite lunacycle --name "pre-migration"

Related Commands:
  celilo storage add local         Add backup storage destination
  celilo storage list              List storage destinations
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display storage command help
 */
function displayStorageHelp(): CommandResult {
  const helpText = `
Celilo - Backup Storage Management

Usage:
  celilo storage <subcommand> [args...] [options]

Subcommands:
  add local             Add local filesystem storage
  add s3                Add S3-compatible storage (AWS, MinIO, B2, Wasabi, GCS)
  list                  List all configured storage destinations
  verify <storage-id>   Test storage connectivity and permissions
  set-default <id>      Set the default backup storage destination
  set-path <id> <path>  Relocate a local destination to a new directory
    Options:
      --no-migrate      Change the path without moving existing archives
  remove <storage-id>   Remove a storage destination
    Options:
      --force           Skip confirmation prompts

Description:
  Backup storage destinations are where Celilo sends encrypted backup archives.
  You must configure at least one storage destination before creating backups.

Examples:
  # Add local storage
  celilo storage add local

  # List storage destinations
  celilo storage list

  # Verify storage connectivity
  celilo storage verify local-backups

  # Set default destination
  celilo storage set-default local-backups

  # Move a local destination (archives at the old path are moved too;
  # if that path is gone, the change proceeds with nothing to migrate)
  celilo storage set-path local-backups /var/lib/celilo/backups

  # Remove storage
  celilo storage remove local-backups --force

Related Commands:
  celilo module backup <module-id>  Create a backup
  celilo backup list                List available backups
  celilo backup restore <id>        Restore from a backup
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display machine command help
 */
function displayFirewallHelp(): CommandResult {
  console.log(`
celilo firewall — inspect a firewall's interfaces

Usage:
  celilo firewall interface list [<hostname>]

  Shows how celilo classifies every interface on a firewall: the zone it
  matched, the external edge, or ALIEN when nothing accounts for it.

  It reads the interface table LIVE from the box, the same way the next
  converge will, so its answer is the answer the converge will act on. If the
  box cannot be reached, it says so and classifies the interface snapshot
  recorded at machine add instead, labelled as possibly stale.

  With no hostname, every machine celilo classifies as a router is shown.

  An interface celilo cannot attribute is resolved by DECLARING it:
    celilo system config set network.<zone>.subnet <cidr>
`);
  return { success: true, message: 'firewall help' };
}

function displayMachineHelp(): CommandResult {
  const helpText = `
Celilo - Machine Pool Management

Usage:
  celilo machine <subcommand> [args...] [options]

Subcommands:
  add                   Add a machine to the pool with auto-detection
    Interactive mode (prompts for input):
      celilo machine add

    Non-interactive mode:
      celilo machine add --ip <ip> --ssh-user <user> --ssh-key-file <path>
    Options:
      --ip <ip>              Machine IP address
      --ssh-user <user>      SSH username (default: root)
      --ssh-key-file <path>  Path to SSH private key

  list                  List all machines in the pool
    Options:
      --zone <zone>        Filter by network zone

  status <hostname>     Show detailed machine status with live connectivity

  remove <hostname>     Remove a machine from the pool
    Options:
      --force              Skip confirmation prompts

Description:
  The machine pool contains bring-your-own-hardware: existing machines like
  Raspberry Pis, VPS instances, or bare metal servers that you manually add
  to Celilo.

  When adding a machine, Celilo automatically:
    - Tests SSH connectivity
    - Detects hostname, CPU, memory, disk
    - Detects network zone from IP address
    - Encrypts and stores SSH key for Ansible deployments

  Celilo prefers container services over machine pool when selecting
  infrastructure during module generation.

Examples:
  # Add machine interactively
  celilo machine add

  # Add machine non-interactively
  celilo machine add --ip 192.168.1.100 --ssh-user ubuntu --ssh-key-file ~/.ssh/id_ed25519

  # List all machines
  celilo machine list

  # List machines in specific zone
  celilo machine list --zone dmz

  # Show machine status
  celilo machine status pi-01

  # Earmark machine for a module
  celilo machine earmark 10.0.10.10 caddy
  celilo machine earmark pi-01 --clear

  # Remove machine (by hostname or IP)
  celilo machine remove pi-01
  celilo machine remove 10.0.10.10 --force

Related Commands:
  celilo service list              List container services
  celilo module generate <id>      Generate infrastructure code (selects infrastructure)
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display IPAM command help
 */
function displayIpamHelp(): CommandResult {
  const helpText = `
Celilo - IPAM (IP Address Management)

Usage:
  celilo ipam <resource> <action> [args...] [options]

Resources:
  vmid          Manage VMID reservations and allocations
  ip            Manage IP address reservations
  show          Show comprehensive IPAM summary
  list-allocations    List all IPAM allocations (VMIDs and IPs)

VMID Commands:
  celilo ipam vmid reserve <vmid-or-range> --reason <reason>
  celilo ipam vmid unreserve <vmid-or-range>
  celilo ipam vmid list-reservations

IP Commands:
  celilo ipam ip exclude <ip-range> --reason <reason> [--zone <zone>]
  celilo ipam ip include <ip-or-range> [--zone <zone>]
  celilo ipam ip edit <ip> --reason <reason> [--zone <zone>]
  celilo ipam ip list-exclusions

Description:
  IPAM automatically allocates VMIDs and IP addresses during module generation.
  Exclusions prevent IPAM from allocating specific IPs (e.g., DHCP ranges, infrastructure).

  VMIDs start at 2100 and increment sequentially.
  IPs are allocated from zone subnets (network.{zone}.subnet).
  Zone is auto-detected from the IP address unless overridden with --zone.

Examples:
  # Reserve VMID for existing VM
  celilo ipam vmid reserve 2100 --reason "Existing Proxmox VM"
  celilo ipam vmid reserve 2100-2110 --reason "Reserved range"

  # Exclude IPs from IPAM allocation (zone auto-detected from IP)
  celilo ipam ip exclude 10.0.10.1-10.0.10.9 --reason "Infrastructure"
  celilo ipam ip exclude 192.168.0.1-192.168.0.150 --reason "DHCP managed range"

  # Re-label an exclusion in place (no include/exclude dance, no allocation race)
  celilo ipam ip edit 192.168.0.153 --reason "orphaned — safe to include"

  # List allocations and reservations
  celilo ipam list-allocations
  celilo ipam vmid list-reservations
  celilo ipam ip list-reservations

  # Remove reservations
  celilo ipam vmid unreserve 2100
  celilo ipam ip unreserve 10.0.10.1 --zone dmz
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Display system command help
 */
function displaySystemHelp(): CommandResult {
  const helpText = `
Celilo - System Configuration

Usage:
  celilo system <subcommand> [args...]

Subcommands:
  init [--accept-defaults] [key=val...] Initialize system with guided setup or defaults

  apply-config <key=val>... | --from-stdin
                                       Headless config write — designed for module
                                       hooks (no prompts, no guidance, just writes).
                                       Refuses network.* keys: networks are celilo's
                                       to define, not a module's.

  discover-network                     Record the network this box sits on, from its own routing table (idempotent)
  ensure-fleet-key                     Mint celilo's fleet SSH key if absent, record ssh.public_key, print the public half

  config set <key> <value>             Set system-wide configuration value
  config get [key]                     Get system configuration value(s)

  secret set <key> <value>             Set encrypted system-level secret
  secret get [key]                     Get decrypted system secret value(s)

  vault-password                       Get Ansible Vault password for decrypting secrets.yml

  audit [--json]                       Report system-wide drift (no mutations)

  update [--module <id>] [--no-backup] [--allow-destructive] [--dry-run] [--json]
                                       Bring the system to the audit-determined READY state

  migrate                              Apply pending database migrations (idempotent; safe to re-run)

  doctor [--fix]                       Diagnose system prerequisites and @celilo/* version drift

Runbook:
  https://celilo.computer/docs/system-update
  (offline summary in apps/celilo/docs/INDEX.md)

Description:
  System initialization (init) guides you through first-time setup with interactive
  prompts or applies sensible defaults for testing.

  System configuration stores values that are shared across all modules, such as
  DNS servers, network settings, and domain information. These values can be
  referenced in module templates using $system:key.path syntax.

  System secrets store encrypted sensitive values like passwords and tokens.
  Note: Provider-specific credentials (Proxmox, DigitalOcean, etc.) are managed
  via 'celilo service' commands, not system secrets.

Examples:
  # Initialize system (first-time setup)
  celilo system init
  celilo system init --accept-defaults
  celilo system init --accept-defaults primary_domain=example.com dns.primary=1.1.1.1

  # Set DNS configuration
  celilo system config set dns.primary 192.168.0.1
  celilo system config set dns.fallback "8.8.8.8 1.1.1.1"

  # Set network configuration
  celilo system config set network.bridge vmbr0
  celilo system config set network.dmz.subnet 10.0.10.0/24

  # Get specific value
  celilo system config get dns.primary

  # Get all system config
  celilo system config get
  celilo system secret get

  # Get vault password for Ansible
  celilo system vault-password

Using Vault Password:
  # View encrypted Ansible secrets
  ansible-vault view secrets.yml \\
    --vault-password-file=<(celilo system vault-password)

  # Run Ansible playbook with encrypted secrets
  ansible-playbook playbook.yml \\
    --vault-password-file=<(celilo system vault-password)

  # Edit encrypted secrets
  ansible-vault edit secrets.yml \\
    --vault-password-file=<(celilo system vault-password)
`;

  return {
    success: true,
    message: helpText.trim(),
  };
}

/**
 * Route command to appropriate handler
 *
 * @param argv - Command-line arguments
 * @returns Command result
 */
export async function runCli(argv: string[]): Promise<CommandResult> {
  const parsed = parseArguments(argv);

  // Remote API server: the sshd forced-command entry point
  // (`celilo api-serve --principal=<id>`). Not an operator command — kept out
  // of the registry/completion on purpose. Runs a persistent NDJSON protocol
  // loop until stdin closes, then exits the process; never returns here.
  if (parsed.command === 'api-serve') {
    const principal = typeof parsed.flags.principal === 'string' ? parsed.flags.principal : '';
    if (!principal) {
      return {
        success: false,
        error:
          'api-serve requires --principal <name> (normally supplied by the forced command in authorized_keys)',
      };
    }
    const { apiServeMode } = await import('../api/serve');
    await apiServeMode(principal);
    return { success: true, message: '' };
  }

  // Handle --get-completions for shell completion (must be before other processing)
  if (parsed.flags['get-completions']) {
    try {
      // Arguments: celilo --get-completions word1 word2 ... currentIndex
      // The words array and current index are passed as remaining args
      const words = parsed.args.slice(0, -1); // All args except last
      const currentStr = parsed.args[parsed.args.length - 1]; // Last arg is the index
      const current = Number.parseInt(currentStr || '0', 10);

      const suggestions = await getCompletions(words, current);

      // Return suggestions as newline-separated list (for zsh array splitting)
      return {
        success: true,
        message: suggestions.join('\n'),
      };
    } catch (_error) {
      // Silent failure for completion errors
      return { success: true, message: '' };
    }
  }

  // Handle --version / -v / `version` (top-level only — subcommands
  // like `celilo module --version` aren't supported here; they'd
  // reach the per-command help anyway).
  if (
    parsed.flags.version ||
    parsed.flags.v ||
    (parsed.command === 'version' && !parsed.subcommand)
  ) {
    return displayVersion();
  }

  // Handle general help (only if no specific command, or command is 'help')
  if (parsed.command === 'help') {
    return displayHelp();
  }

  // Handle completion command
  if (parsed.command === 'completion') {
    // Completion is a simple command without subcommands
    // If parser treated first arg as subcommand, prepend it to args
    const completionArgs = parsed.subcommand ? [parsed.subcommand, ...parsed.args] : parsed.args;
    return handleCompletion(completionArgs, parsed.flags);
  }

  // Handle status command
  if (parsed.command === 'status') {
    return handleStatus();
  }

  // Handle commands command (serialize the registry; drives @celilo/mcp)
  if (parsed.command === 'commands') {
    return handleCommands(parsed.args, parsed.flags);
  }

  // The web console's narrow reads.
  if (parsed.command === 'console') {
    const flagError = checkFlags('console', parsed.subcommand, parsed.flags, parsed.args);
    if (flagError) return flagError;

    switch (parsed.subcommand) {
      case 'status':
        return handleConsoleStatus(parsed.flags);
      case 'get':
        return handleConsoleGet(parsed.args, parsed.flags);
      default:
        return {
          success: false,
          error: 'Console subcommand required: status | get',
        };
    }
  }

  // Top-level alias: `celilo audit` → `celilo system audit`
  if (parsed.command === 'audit') {
    return handleSystemAudit(parsed.args, parsed.flags);
  }

  if (parsed.command === 'apt-upgrade') {
    return handleAptUpgrade(parsed.args, parsed.flags);
  }

  // Route commands
  if (parsed.command === 'package') {
    // Handle package --help
    if (parsed.flags.help || parsed.flags.h) {
      return displayPackageHelp();
    }

    // Package is a simple command without subcommands
    // If parser treated first arg as subcommand, prepend it to args
    const packageArgs = parsed.subcommand ? [parsed.subcommand, ...parsed.args] : parsed.args;
    return handlePackage(packageArgs, parsed.flags);
  }

  if (parsed.command === 'hook') {
    if (parsed.flags.help || parsed.flags.h) {
      return {
        success: true,
        message: [
          'Hook commands:',
          '',
          '  celilo hook run <module-id> <hook-name> [--debug] [key=value...]',
          '',
          'Options:',
          '  --debug    Run with visible browser (Playwright hooks)',
          '',
          'Examples:',
          '  celilo hook run namecheap validate_config --debug',
          '  celilo hook run namecheap container_created vps_ip=192.0.2.30',
        ].join('\n'),
      };
    }

    if (parsed.subcommand === 'run') {
      return handleHookRun(parsed.args, parsed.flags);
    }

    return {
      success: false,
      error: 'Hook subcommand required\n\nRun "celilo hook --help" for usage',
    };
  }

  if (parsed.command === 'dns') {
    if (parsed.flags.help || parsed.flags.h) {
      return displayDnsHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'DNS subcommand required\n\nRun "celilo dns --help" for usage',
      };
    }

    if (parsed.subcommand === 'registrations') {
      return handleDnsRegistrations(parsed.args, parsed.flags);
    }

    return {
      success: false,
      error: `Unknown dns subcommand: ${parsed.subcommand}\n\nRun "celilo dns --help" for usage`,
    };
  }

  if (parsed.command === 'capability') {
    if (parsed.flags.help || parsed.flags.h) {
      return displayCapabilityHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Capability subcommand required\n\nRun "celilo capability --help" for usage',
      };
    }

    const capFlagError = checkFlags('capability', parsed.subcommand, parsed.flags, parsed.args);
    if (capFlagError) return capFlagError;

    if (parsed.subcommand === 'list') {
      return handleCapabilityList();
    }

    if (parsed.subcommand === 'info') {
      return handleCapabilityInfo(parsed.args);
    }

    return {
      success: false,
      error: `Unknown capability subcommand: ${parsed.subcommand}\n\nRun "celilo capability --help" for usage`,
    };
  }

  if (parsed.command === 'registry') {
    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
      return displayRegistryHelp();
    }

    const registryFlagError = checkFlags('registry', parsed.subcommand, parsed.flags, parsed.args);
    if (registryFlagError) return registryFlagError;

    if (parsed.subcommand === 'token') {
      const action = parsed.args[0];
      const tokenArgs = parsed.args.slice(1);
      const { handleRegistryTokenAdd, handleRegistryTokenRm } = await import(
        './commands/registry-token'
      );
      if (action === 'add') return handleRegistryTokenAdd(tokenArgs);
      if (action === 'rm') return handleRegistryTokenRm(tokenArgs);
      return {
        success: false,
        error:
          'Token action required (add or rm)\n\nUsage:\n  celilo registry token add <token>\n  celilo registry token rm <token>',
      };
    }

    if (parsed.subcommand === 'owner') {
      const action = parsed.args[0];
      const ownerArgs = parsed.args.slice(1);
      const { handleRegistryOwnerList, handleRegistryOwnerShow, handleRegistryOwnerSet } =
        await import('./commands/registry-owner');
      if (action === 'list') return handleRegistryOwnerList(parsed.flags);
      if (action === 'show') return handleRegistryOwnerShow(ownerArgs, parsed.flags);
      if (action === 'set') return handleRegistryOwnerSet(ownerArgs, parsed.flags);
      return {
        success: false,
        error:
          'Owner action required (list, show, or set)\n\nUsage:\n  celilo registry owner list\n  celilo registry owner show <module>\n  celilo registry owner set <module> <owner-sub>',
      };
    }

    return {
      success: false,
      error: `Unknown registry subcommand: ${parsed.subcommand}\n\nRun "celilo registry --help" for usage`,
    };
  }

  if (parsed.command === 'token') {
    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
      return displayTokenHelp();
    }

    const tokenFlagError = checkFlags('token', parsed.subcommand, parsed.flags, parsed.args);
    if (tokenFlagError) return tokenFlagError;

    const { handleTokenObtain, handleTokenList, handleTokenRevoke } = await import(
      './commands/token'
    );
    if (parsed.subcommand === 'obtain') return handleTokenObtain(parsed.args, parsed.flags);
    if (parsed.subcommand === 'list') return handleTokenList(parsed.args, parsed.flags);
    if (parsed.subcommand === 'revoke') return handleTokenRevoke(parsed.args, parsed.flags);

    return {
      success: false,
      error: `Unknown token subcommand: ${parsed.subcommand}\n\nRun "celilo token --help" for usage`,
    };
  }

  if (parsed.command === 'publish') {
    if (parsed.flags.help || parsed.flags.h) {
      return displayPublishHelp();
    }
    const pubFlagError = checkFlags('publish', undefined, parsed.flags, parsed.args);
    if (pubFlagError) return pubFlagError;
    // Slice from `publish` onwards in the raw argv so the publish entry
    // sees the operator's exact flag spelling (`-y` vs `--yes`, etc.).
    // Falling back to args+flags reconstruction would lose short-form
    // flag identity since the parser canonicalises those.
    const publishIdx = process.argv.indexOf('publish');
    const publishArgv = publishIdx >= 0 ? process.argv.slice(publishIdx + 1) : [...parsed.args];
    // Lazy-load the publish command: it's monorepo-only release tooling whose
    // transitive import chain reaches scripts/workspace-graph.ts, which does NOT
    // ship in @celilo/cli's files[]. A static top-level import pulled that into
    // EVERY command's load graph, so `celilo --version` in a consumer install
    // crashed on the unresolvable module (WORKSPACE_PACKAGE_GRAPH.md — the D3
    // failure, deeper than the module-load throw). Loading it only when the
    // operator actually runs `celilo publish` (which only happens in the
    // monorepo) keeps every other command free of the dependency.
    const { main: runPublish } = await import('./commands/publish');
    await runPublish(publishArgv);
    // runPublish handles its own console output (multi-phase, multi-line);
    // returning an empty success message tells the outer CLI loop to write
    // nothing more and exit 0 cleanly. Any failure inside runPublish
    // calls process.exit() directly and never returns here.
    return { success: true, message: '' };
  }

  if (parsed.command === 'events') {
    if (parsed.flags.help || parsed.flags.h) {
      return displayEventsHelp();
    }
    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Events subcommand required\n\nRun "celilo events --help" for usage',
      };
    }
    const evFlagError = checkFlags('events', parsed.subcommand, parsed.flags, parsed.args);
    if (evFlagError) return evFlagError;

    switch (parsed.subcommand) {
      case 'status':
        return handleEventsStatus();
      case 'tail':
        return handleEventsTail(parsed.args, parsed.flags);
      case 'list-subscribers':
        return handleEventsListSubscribers();
      case 'resync-subscriptions':
        return handleEventsResyncSubscriptions();
      case 'list-pending':
        return handleEventsListPending(parsed.args, parsed.flags);
      case 'list-failed':
        return handleEventsListFailed(parsed.args, parsed.flags);
      case 'list-unanswered':
        return handleEventsListUnanswered(parsed.args, parsed.flags);
      case 'drain':
        return handleEventsDrain(parsed.args, parsed.flags);
      case 'run':
        return handleEventsRun(parsed.args, parsed.flags);
      case 'run-hook':
        return handleEventsRunHook(parsed.args);
      case 'emit':
        return handleEventsEmit(parsed.args, parsed.flags);
      case 'reply':
        return handleEventsReply(parsed.args, parsed.flags);
      case 'ack':
        return handleEventsAck(parsed.args, parsed.flags);
      case 'fail':
        return handleEventsFail(parsed.args, parsed.flags);
      case 'repair':
      case 'resume':
        return handleEventsRepair();
      case 'respond':
        return handleEventsRespond(parsed.args, parsed.flags);
      case 'install-daemon':
        return handleEventsInstallDaemon(parsed.args, parsed.flags);
      case 'uninstall-daemon':
        return handleEventsUninstallDaemon(parsed.args, parsed.flags);
      case 'restart-daemon':
        return handleEventsRestartDaemon(parsed.args, parsed.flags);
      case 'show-daemon':
        return handleEventsShowDaemon(parsed.args, parsed.flags);
      default:
        return {
          success: false,
          error: `Unknown events subcommand: ${parsed.subcommand}\n\nRun "celilo events --help" for usage`,
        };
    }
  }

  if (parsed.command === 'module') {
    // Handle module --help
    if (parsed.flags.help || parsed.flags.h) {
      return displayModuleHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Module subcommand required\n\nRun "celilo module --help" for usage',
      };
    }

    const flagError = checkFlags('module', parsed.subcommand, parsed.flags, parsed.args);
    if (flagError) return flagError;

    switch (parsed.subcommand) {
      case 'import':
        return handleModuleImport(parsed.args, parsed.flags);
      case 'list':
        return handleModuleList(parsed.flags);
      case 'status':
        return handleModuleStatus(parsed.args);
      case 'where':
        return handleModuleWhere(parsed.args, parsed.flags);
      case 'logs':
        return handleModuleLogs(parsed.args, parsed.flags);
      case 'journal':
        return handleModuleJournal(parsed.args, parsed.flags);
      case 'health':
        return handleModuleHealth(parsed.args, parsed.flags);
      case 'operations':
        return handleModuleOperations(parsed.args, parsed.flags);
      case 'pause':
        return handleModulePause(parsed.args, parsed.flags);
      case 'unpause':
        return handleModuleUnpause(parsed.args, parsed.flags);
      case 'remove':
        return handleModuleRemove(parsed.args, parsed.flags);
      case 'update':
        return handleModuleUpdate(parsed.args, parsed.flags);
      case 'upgrade':
        return handleModuleUpgrade(parsed.args, parsed.flags);
      case 'version':
        return handleModuleVersion(parsed.args, parsed.flags);
      case 'changeset':
        return handleModuleChangeset(parsed.args, parsed.flags);
      case 'jail':
        return handleModuleJail(parsed.args, parsed.flags);
      case 'audit':
        return moduleAudit(parsed.args, parsed.flags);
      case 'verify':
        return moduleVerify(parsed.args, parsed.flags);
      case 'config': {
        // Config requires additional subcommand (set/get)
        const configSubcommand = parsed.args[0];
        if (!configSubcommand) {
          return {
            success: false,
            error: 'Config action required (set, get or unset)\n\nRun "celilo help" for usage',
          };
        }
        const configArgs = parsed.args.slice(1);
        if (configSubcommand === 'set') {
          return handleModuleConfigSet(configArgs);
        }
        if (configSubcommand === 'get') {
          return handleModuleConfigGet(configArgs);
        }
        if (configSubcommand === 'unset') {
          return handleModuleConfigUnset(configArgs);
        }
        return {
          success: false,
          error: `Unknown config action: ${configSubcommand}`,
        };
      }
      case 'secret': {
        // Module secret requires additional subcommand (set/list)
        const moduleSecretSubcommand = parsed.args[0];
        if (!moduleSecretSubcommand) {
          return {
            success: false,
            error:
              'Secret action required\n\nUsage:\n  celilo module secret set <module-id> <key> <value>\n  celilo module secret get <module-id> <key>\n  celilo module secret list <module-id>',
          };
        }
        const moduleSecretArgs = parsed.args.slice(1);
        if (moduleSecretSubcommand === 'set') {
          return handleSecretSet(moduleSecretArgs);
        }
        if (moduleSecretSubcommand === 'list') {
          return handleSecretList(moduleSecretArgs);
        }
        if (moduleSecretSubcommand === 'get') {
          const { handleModuleSecretGet } = await import('./commands/module-secret-get');
          return handleModuleSecretGet(moduleSecretArgs);
        }
        return {
          success: false,
          error: `Unknown secret action: ${moduleSecretSubcommand}`,
        };
      }
      case 'types': {
        // Types requires additional subcommand (generate/check)
        const typesSubcommand = parsed.args[0];
        if (!typesSubcommand) {
          return {
            success: false,
            error:
              'Types action required (generate or check)\n\nUsage:\n  celilo module types generate <module-dir>\n  celilo module types check <module-dir>',
          };
        }
        const typesArgs = parsed.args.slice(1);
        if (typesSubcommand === 'generate') {
          return handleModuleTypesGenerate(typesArgs);
        }
        if (typesSubcommand === 'check') {
          return handleModuleTypesCheck(typesArgs);
        }
        return {
          success: false,
          error: `Unknown types action: ${typesSubcommand}\n\nAvailable: generate, check`,
        };
      }
      case 'generate':
        return handleModuleGenerate(parsed.args, parsed.flags);
      case 'build':
        return handleModuleBuild(parsed.args, parsed.flags);
      case 'deploy':
        return handleModuleDeploy(parsed.args, parsed.flags);
      case 'validate':
        // Alias for `module deploy --preflight`
        return handleModuleDeploy(parsed.args, { ...parsed.flags, preflight: true });
      case 'backup': {
        // Canonical create-a-module-backup surface, matching the rest of
        // the module CLI verbs (deploy, health, remove, ...). The legacy
        // `celilo backup create <module>` still works but prints a
        // deprecation banner.
        const { handleBackupCreate } = await import('./commands/backup-create');
        return handleBackupCreate(parsed.args, parsed.flags);
      }
      case 'run-hook':
        return handleHookRun(parsed.args, parsed.flags);
      case 'terraform-unlock':
        return handleModuleTerraformUnlock(parsed.args);
      case 'show-config':
        return handleModuleShowConfig(parsed.args);
      case 'show-zone':
        return handleModuleShowZone(parsed.args);
      case 'search':
        return handleModuleSearch(parsed.args, parsed.flags);
      case 'publish':
        return handleModulePublish(parsed.args, parsed.flags);
      case 'check':
        return handleModuleCheck(parsed.args, parsed.flags);
      default:
        return {
          success: false,
          error: `Unknown module subcommand: ${parsed.subcommand}\n\nRun "celilo help" for usage`,
        };
    }
  }

  if (parsed.command === 'secret') {
    return {
      success: false,
      error:
        'The top-level "secret" command has been moved.\n\nUse:\n  celilo module secret set <module-id> <key> <value>\n  celilo module secret list <module-id>\n  celilo system secret set <key> <value>\n  celilo system secret get <key>',
    };
  }

  if (parsed.command === 'service') {
    // Handle service --help
    if (parsed.flags.help || parsed.flags.h) {
      return displayServiceHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Service subcommand required\n\nRun "celilo service --help" for usage',
      };
    }

    const svcFlagError = checkFlags('service', parsed.subcommand, parsed.flags, parsed.args);
    if (svcFlagError) return svcFlagError;

    if (parsed.subcommand === 'add') {
      // Add requires provider type
      const provider = parsed.args[0];
      if (!provider) {
        return {
          success: false,
          error:
            'Provider type required (proxmox or digitalocean)\n\nRun "celilo service --help" for usage',
        };
      }
      const addArgs = parsed.args.slice(1);
      if (provider === 'proxmox') {
        return handleServiceAddProxmox(addArgs, parsed.flags);
      }
      if (provider === 'digitalocean') {
        return handleServiceAddDigitalOcean(addArgs, parsed.flags);
      }
      return {
        success: false,
        error: `Unknown provider: ${provider}\n\nSupported providers: proxmox, digitalocean`,
      };
    }

    if (parsed.subcommand === 'list') {
      return handleServiceList(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'remove') {
      return handleServiceRemove(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'verify') {
      return handleServiceVerify(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'set-credentials') {
      return handleServiceSetCredentials(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'reconfigure') {
      return handleServiceReconfigure(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'config') {
      const configSubcommand = parsed.args[0];
      if (!configSubcommand) {
        return {
          success: false,
          error: 'Config action required (set or get)\n\nRun "celilo help" for usage',
        };
      }
      const configArgs = parsed.args.slice(1);
      if (configSubcommand === 'set') {
        return handleServiceConfigSet(configArgs);
      }
      if (configSubcommand === 'get') {
        return handleServiceConfigGet(configArgs);
      }
      return {
        success: false,
        error: `Unknown config action: ${configSubcommand}`,
      };
    }

    return {
      success: false,
      error: `Unknown service subcommand: ${parsed.subcommand}\n\nRun "celilo service --help" for usage`,
    };
  }

  if (parsed.command === 'subscribers') {
    if (parsed.flags.help || parsed.flags.h) {
      return displaySubscribersHelp();
    }
    if (!parsed.subcommand) {
      return {
        success: false,
        error:
          'Subscribers subcommand required (list, add, remove, test).\n\nRun "celilo subscribers --help" for usage.',
      };
    }
    const subFlagError = checkFlags('subscribers', parsed.subcommand, parsed.flags, parsed.args);
    if (subFlagError) return subFlagError;

    switch (parsed.subcommand) {
      case 'list':
        return handleSubscribersList();
      case 'add':
        return handleSubscribersAdd(parsed.args, parsed.flags);
      case 'remove':
        return handleSubscribersRemove(parsed.args);
      case 'test':
        return handleSubscribersTest(parsed.args);
      case 'serve':
        return handleSubscribersServe(parsed.args, parsed.flags);
      case 'install-daemon':
        return handleSubscribersInstallDaemon(parsed.args, parsed.flags);
      case 'uninstall-daemon':
        return handleSubscribersUninstallDaemon(parsed.args, parsed.flags);
      case 'status':
        return handleSubscribersStatus();
      default:
        return {
          success: false,
          error: `Unknown subscribers subcommand: ${parsed.subcommand}\n\nRun "celilo subscribers --help" for usage.`,
        };
    }
  }

  if (parsed.command === 'person') {
    const { handlePerson } = await import('./commands/notify-config');
    return handlePerson(parsed.subcommand, parsed.args, parsed.flags);
  }

  if (parsed.command === 'route') {
    const { handleRoute } = await import('./commands/notify-config');
    return handleRoute(parsed.subcommand, parsed.args, parsed.flags);
  }

  if (parsed.command === 'escalation-policy') {
    const { handleEscalationPolicy } = await import('./commands/notify-config');
    return handleEscalationPolicy(parsed.subcommand, parsed.args, parsed.flags);
  }

  if (parsed.command === 'monitor') {
    const { handleMonitor } = await import('./commands/monitor');
    return handleMonitor(parsed.subcommand, parsed.args, parsed.flags);
  }

  if (parsed.command === 'alerts') {
    if (parsed.subcommand === 'ack') {
      const { handleAlertsAck } = await import('./commands/alerts-act');
      return handleAlertsAck(parsed.args, parsed.flags);
    }
    if (parsed.subcommand === 'silence') {
      const { handleAlertsSilence } = await import('./commands/alerts-act');
      return handleAlertsSilence(parsed.args, parsed.flags);
    }
    if (parsed.subcommand === 'resolve') {
      const { handleAlertsResolve } = await import('./commands/alerts-act');
      return handleAlertsResolve(parsed.args);
    }
    if (parsed.subcommand === 'poll') {
      const { handleAlertsPoll } = await import('./commands/alerts-poll');
      return handleAlertsPoll(parsed.flags);
    }
    if (parsed.subcommand === 'sweep') {
      const { handleAlertsSweep } = await import('./commands/alerts-sweep');
      return handleAlertsSweep();
    }
    if (!parsed.subcommand || parsed.subcommand === 'list') {
      const alertsFlagError = checkFlags('alerts', 'list', parsed.flags, parsed.args);
      if (alertsFlagError) return alertsFlagError;
      const { handleAlertsList } = await import('./commands/alerts-list');
      return handleAlertsList(parsed.args, parsed.flags);
    }
    return {
      success: false,
      error: `Unknown alerts subcommand: ${parsed.subcommand}\n\nUse: list, ack, silence, resolve, sweep, poll`,
    };
  }

  if (parsed.command === 'storage') {
    if (parsed.flags.help || parsed.flags.h) {
      return displayStorageHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Storage subcommand required\n\nRun "celilo storage --help" for usage',
      };
    }

    // Skip flag validation for 'add' — flags belong to the sub-subcommand (local/s3)
    if (parsed.subcommand !== 'add') {
      const storageFlagError = checkFlags('storage', parsed.subcommand, parsed.flags, parsed.args);
      if (storageFlagError) return storageFlagError;
    }

    if (parsed.subcommand === 'add') {
      const provider = parsed.args[0];
      if (!provider) {
        return {
          success: false,
          error: 'Provider type required (local or s3)\n\nRun "celilo storage --help" for usage',
        };
      }
      const addArgs = parsed.args.slice(1);
      if (provider === 'local') {
        const { handleStorageAddLocal } = await import('./commands/storage-add-local');
        return handleStorageAddLocal(addArgs, parsed.flags);
      }
      if (provider === 's3') {
        const { handleStorageAddS3 } = await import('./commands/storage-add-s3');
        return handleStorageAddS3(addArgs, parsed.flags);
      }
      return {
        success: false,
        error: `Unknown storage provider: ${provider}\n\nSupported providers: local, s3`,
      };
    }

    if (parsed.subcommand === 'list') {
      const { handleStorageList } = await import('./commands/storage-list');
      return handleStorageList(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'remove') {
      const { handleStorageRemove } = await import('./commands/storage-remove');
      return handleStorageRemove(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'verify') {
      const { handleStorageVerify } = await import('./commands/storage-verify');
      return handleStorageVerify(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'set-default') {
      const { handleStorageSetDefault } = await import('./commands/storage-set-default');
      return handleStorageSetDefault(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'set-path') {
      const { handleStorageSetPath } = await import('./commands/storage-set-path');
      return handleStorageSetPath(parsed.args, parsed.flags);
    }

    return {
      success: false,
      error: `Unknown storage subcommand: ${parsed.subcommand}\n\nRun "celilo storage --help" for usage`,
    };
  }

  if (parsed.command === 'backup') {
    if (parsed.flags.help || parsed.flags.h) {
      return displayBackupHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Backup subcommand required\n\nRun "celilo backup --help" for usage',
      };
    }

    const backupFlagError = checkFlags('backup', parsed.subcommand, parsed.flags, parsed.args);
    if (backupFlagError) return backupFlagError;

    if (parsed.subcommand === 'create') {
      // Legacy surface — `celilo module backup <id>` is the canonical
      // create command now (matches the module-namespaced verbs:
      // deploy, health, remove). Print a one-line deprecation banner
      // and forward to the same handler. Suppress via
      // `CELILO_SUPPRESS_DEPRECATION=1` so tests / cron stay quiet.
      if (process.env.CELILO_SUPPRESS_DEPRECATION !== '1') {
        const target = parsed.args[0]
          ? `celilo module backup ${parsed.args[0]}`
          : 'celilo module backup';
        console.warn(`⚠ "celilo backup create" is deprecated. Use: ${target}`);
      }
      const { handleBackupCreate } = await import('./commands/backup-create');
      return handleBackupCreate(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'sweep') {
      const { handleBackupSweep } = await import('./commands/backup-sweep');
      return handleBackupSweep();
    }

    if (parsed.subcommand === 'list') {
      const { handleBackupList } = await import('./commands/backup-list');
      return handleBackupList(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'restore') {
      const { handleBackupRestore } = await import('./commands/backup-restore');
      return handleBackupRestore(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'prune') {
      const { handleBackupPrune } = await import('./commands/backup-prune');
      return handleBackupPrune(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'delete') {
      const { handleBackupDelete } = await import('./commands/backup-delete');
      return handleBackupDelete(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'name') {
      const { handleBackupName } = await import('./commands/backup-name');
      return handleBackupName(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'import') {
      const { handleBackupImport } = await import('./commands/backup-import');
      return handleBackupImport(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'pull') {
      const { handleBackupPull } = await import('./commands/backup-pull');
      return handleBackupPull(parsed.args, parsed.flags);
    }

    return {
      success: false,
      error: `Unknown backup subcommand: ${parsed.subcommand}\n\nRun "celilo backup --help" for usage`,
    };
  }

  if (parsed.command === 'restore') {
    // Phase 4 of openspec/specs/management-server-backup/spec.md — top-level
    // fresh-bootstrap restore. Distinct from `celilo backup restore
    // <id>` (which restores from a configured storage destination
    // using an existing backup record); this one takes a local file
    // directly so it works before any storage is configured.
    //
    // `restore` has no subcommands but the parser eagerly captures
    // the second positional as `subcommand`. Re-thread it as the
    // first arg so `celilo restore <file>` works alongside
    // `celilo restore --from <file>`.
    const restoreArgs = parsed.subcommand ? [parsed.subcommand, ...parsed.args] : parsed.args;
    const restoreFlagError = checkFlags('restore', undefined, parsed.flags, restoreArgs);
    if (restoreFlagError) return restoreFlagError;

    const { handleRestore } = await import('./commands/restore');
    return handleRestore(restoreArgs, parsed.flags);
  }

  if (parsed.command === 'api') {
    if (parsed.flags.help || parsed.flags.h) {
      return {
        success: true,
        message: [
          'celilo api — manage remote-API access',
          '',
          'Usage:',
          '  celilo api grant <principal> --key <pubkey|path> --can <grant[,grant...]>',
          '  celilo api list',
          '  celilo api revoke <principal>',
          '  celilo api authorized-keys',
          '  celilo api key new <name>',
          '',
          'Grants are command:subcommand (module:deploy), command:* (service:*), or * (all).',
        ].join('\n'),
      };
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'API subcommand required\n\nRun "celilo api --help" for usage',
      };
    }

    const apiFlagError = checkFlags('api', parsed.subcommand, parsed.flags, parsed.args);
    if (apiFlagError) return apiFlagError;

    if (parsed.subcommand === 'grant') {
      return handleApiGrant(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'list') {
      return handleApiList();
    }

    if (parsed.subcommand === 'revoke') {
      return handleApiRevoke(parsed.args);
    }

    if (parsed.subcommand === 'authorized-keys') {
      return handleApiAuthorizedKeys();
    }

    if (parsed.subcommand === 'key') {
      if (parsed.args[0] === 'new') {
        return handleApiKeyNew(parsed.args.slice(1));
      }
      return { success: false, error: 'Usage: celilo api key new <name>' };
    }

    return {
      success: false,
      error: `Unknown api subcommand: ${parsed.subcommand}\n\nRun "celilo api --help" for usage`,
    };
  }

  if (parsed.command === 'firewall') {
    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
      return displayFirewallHelp();
    }
    if (parsed.subcommand === 'interface') {
      // `interface` is a group, not a leaf: `list` is its only verb today.
      // `acknowledge` and `enforce` were both deleted in the design amendments —
      // there is no policy toggle and no per-interface escape hatch.
      const verb = parsed.args[0];
      if (!verb || verb === 'list') {
        return handleFirewallInterfaceList(parsed.args.slice(1), parsed.flags);
      }
      return {
        success: false,
        error: `Unknown firewall interface subcommand: ${verb}\n\nRun "celilo firewall --help" for usage`,
      };
    }
    return {
      success: false,
      error: `Unknown firewall subcommand: ${parsed.subcommand}\n\nRun "celilo firewall --help" for usage`,
    };
  }

  if (parsed.command === 'machine') {
    // Handle machine --help
    if (parsed.flags.help || parsed.flags.h) {
      return displayMachineHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Machine subcommand required\n\nRun "celilo machine --help" for usage',
      };
    }

    const machFlagError = checkFlags('machine', parsed.subcommand, parsed.flags, parsed.args);
    if (machFlagError) return machFlagError;

    if (parsed.subcommand === 'add') {
      return handleMachineAdd(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'list') {
      return handleMachineList(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'status') {
      return handleMachineStatus(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'remove') {
      return handleMachineRemove(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'earmark') {
      return handleMachineEarmark(parsed.args, parsed.flags);
    }

    return {
      success: false,
      error: `Unknown machine subcommand: ${parsed.subcommand}\n\nRun "celilo machine --help" for usage`,
    };
  }

  if (parsed.command === 'system') {
    // Handle system --help
    if (parsed.flags.help || parsed.flags.h) {
      return displaySystemHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'System subcommand required\n\nRun "celilo system --help" for usage',
      };
    }

    const sysFlagError = checkFlags('system', parsed.subcommand, parsed.flags, parsed.args);
    if (sysFlagError) return sysFlagError;

    if (parsed.subcommand === 'init') {
      return handleSystemInit(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'apply-config') {
      return handleSystemApplyConfig(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'discover-network') {
      return handleSystemDiscoverNetwork();
    }

    if (parsed.subcommand === 'ensure-fleet-key') {
      return handleSystemEnsureFleetKey();
    }

    if (parsed.subcommand === 'config') {
      const configSubcommand = parsed.args[0];
      if (!configSubcommand) {
        return {
          success: false,
          error: 'Config action required (set or get)\n\nRun "celilo system --help" for usage',
        };
      }
      const configArgs = parsed.args.slice(1);
      if (configSubcommand === 'set') {
        return await handleSystemConfigSet(configArgs, parsed.flags);
      }
      if (configSubcommand === 'get') {
        return handleSystemConfigGet(configArgs);
      }
      return {
        success: false,
        error: `Unknown config action: ${configSubcommand}`,
      };
    }

    if (parsed.subcommand === 'secret') {
      const secretSubcommand = parsed.args[0];
      if (!secretSubcommand) {
        return {
          success: false,
          error: 'Secret action required (set or get)\n\nRun "celilo system --help" for usage',
        };
      }
      const secretArgs = parsed.args.slice(1);
      if (secretSubcommand === 'set') {
        return handleSystemSecretSet(secretArgs);
      }
      if (secretSubcommand === 'get') {
        return handleSystemSecretGet(secretArgs);
      }
      return {
        success: false,
        error: `Unknown secret action: ${secretSubcommand}`,
      };
    }

    if (parsed.subcommand === 'vault-password') {
      return handleSystemVaultPassword();
    }

    if (parsed.subcommand === 'audit') {
      return handleSystemAudit(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'update') {
      return handleSystemUpdate(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'doctor') {
      return handleSystemDoctor(parsed.args, parsed.flags);
    }

    if (parsed.subcommand === 'migrate') {
      return handleSystemMigrate(parsed.args, parsed.flags);
    }

    return {
      success: false,
      error: `Unknown system subcommand: ${parsed.subcommand}\n\nRun "celilo system --help" for usage`,
    };
  }

  if (parsed.command === 'proxmox') {
    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'Proxmox subcommand required (node)\n\nRun "celilo proxmox --help" for usage',
      };
    }
    if (parsed.subcommand === 'node') {
      const nodeSubcommand = parsed.args[0];
      if (nodeSubcommand === 'list') {
        return handleProxmoxNodeList(parsed.args.slice(1), parsed.flags);
      }
      return {
        success: false,
        error: 'Proxmox node action required (list)\n\nRun "celilo proxmox --help" for usage',
      };
    }
    if (parsed.subcommand === 'vm' || parsed.subcommand === 'ct') {
      const action = parsed.args[0];
      if (action === 'list') {
        return handleProxmoxInstanceList(parsed.subcommand, parsed.args.slice(1));
      }
      if (action === 'resize') {
        return handleProxmoxInstanceResize(parsed.subcommand, parsed.args.slice(1), parsed.flags);
      }
      return {
        success: false,
        error: `Proxmox ${parsed.subcommand} action required (list, resize)\n\nRun "celilo proxmox --help" for usage`,
      };
    }
    return {
      success: false,
      error: `Unknown proxmox subcommand: ${parsed.subcommand}\n\nRun "celilo proxmox --help" for usage`,
    };
  }

  if (parsed.command === 'ipam') {
    // Handle ipam --help
    if (parsed.flags.help || parsed.flags.h) {
      return displayIpamHelp();
    }

    if (!parsed.subcommand) {
      return {
        success: false,
        error: 'IPAM subcommand required\n\nRun "celilo ipam --help" for usage',
      };
    }

    const ipamFlagError = checkFlags('ipam', parsed.subcommand, parsed.flags, parsed.args);
    if (ipamFlagError) return ipamFlagError;

    // Handle show command (comprehensive summary)
    if (parsed.subcommand === 'show') {
      return handleIpamShow(parsed.args, parsed.flags);
    }

    // Handle list-allocations (no additional subcommand)
    if (parsed.subcommand === 'list-allocations') {
      return handleIpamListAllocations(parsed.args, parsed.flags);
    }

    // VMID commands
    if (parsed.subcommand === 'vmid') {
      const vmidSubcommand = parsed.args[0];
      if (!vmidSubcommand) {
        return {
          success: false,
          error:
            'VMID action required (reserve, unreserve, list-reservations)\n\nRun "celilo ipam --help" for usage',
        };
      }
      const vmidArgs = parsed.args.slice(1);
      if (vmidSubcommand === 'reserve') {
        return handleIpamVmidReserve(vmidArgs, parsed.flags);
      }
      if (vmidSubcommand === 'unreserve') {
        return handleIpamVmidUnreserve(vmidArgs, parsed.flags);
      }
      if (vmidSubcommand === 'list-reservations') {
        return handleIpamVmidListReservations(vmidArgs, parsed.flags);
      }
      return {
        success: false,
        error: `Unknown VMID action: ${vmidSubcommand}`,
      };
    }

    // IP commands
    if (parsed.subcommand === 'ip') {
      const ipSubcommand = parsed.args[0];
      if (!ipSubcommand) {
        return {
          success: false,
          error:
            'IP action required (exclude, include, edit, list-exclusions)\n\nRun "celilo ipam --help" for usage',
        };
      }
      const ipArgs = parsed.args.slice(1);
      if (ipSubcommand === 'exclude') {
        return handleIpamIpReserve(ipArgs, parsed.flags);
      }
      if (ipSubcommand === 'include') {
        return handleIpamIpUnreserve(ipArgs, parsed.flags);
      }
      if (ipSubcommand === 'edit') {
        return handleIpamIpEdit(ipArgs, parsed.flags);
      }
      if (ipSubcommand === 'list-exclusions') {
        return handleIpamIpListReservations(ipArgs, parsed.flags);
      }
      return {
        success: false,
        error: `Unknown IP action: ${ipSubcommand}`,
      };
    }

    return {
      success: false,
      error: `Unknown IPAM subcommand: ${parsed.subcommand}\n\nRun "celilo ipam --help" for usage`,
    };
  }

  return {
    success: false,
    error: `Unknown command: ${parsed.command}\n\nRun "celilo help" for usage`,
  };
}

/**
 * Server Mode - Persistent CLI Process
 *
 * Accepts commands via stdin, executes them, and returns results via stdout.
 * Used by test infrastructure for efficient command execution without spawning
 * fresh processes.
 *
 * Protocol:
 * - Input (stdin): JSON lines with `{ command: string, id: number }`
 * - Output (stdout): JSON lines with `{ id: number, success: boolean, message?: string, error?: string, exitCode: number, duration: number }`
 * - Special command "__exit__" terminates server
 * - Special command "__ping__" returns pong (health check)
 */
/**
 * Parse command string respecting quotes
 * Handles: system config set dns.fallback "8.8.8.8 1.1.1.1"
 * Returns: ['system', 'config', 'set', 'dns.fallback', '8.8.8.8 1.1.1.1']
 */
function parseCommand(command: string): string[] {
  const args: string[] = [];
  let current = '';
  let inQuotes = false;
  let quoteChar = '';

  for (let i = 0; i < command.length; i++) {
    const char = command[i];

    if ((char === '"' || char === "'") && !inQuotes) {
      // Start of quoted string
      inQuotes = true;
      quoteChar = char;
    } else if (char === quoteChar && inQuotes) {
      // End of quoted string
      inQuotes = false;
      quoteChar = '';
    } else if (char === ' ' && !inQuotes) {
      // Space outside quotes - word boundary
      if (current) {
        args.push(current);
        current = '';
      }
    } else {
      // Regular character
      current += char;
    }
  }

  // Add final argument
  if (current) {
    args.push(current);
  }

  return args;
}

async function serverMode(): Promise<void> {
  const readline = await import('node:readline');

  // Signal ready
  console.log(JSON.stringify({ type: 'ready', pid: process.pid }));

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    terminal: false,
  });

  // Keep process alive - don't exit when stdin ends
  rl.on('close', () => {
    // Stdin closed - exit gracefully
    process.exit(0);
  });

  for await (const line of rl) {
    try {
      const request = parseJsonWithValidation(line, CLIServerRequestSchema, 'CLI server request');

      // Health check
      if (request.command === '__ping__') {
        console.log(
          JSON.stringify({
            id: request.id,
            success: true,
            message: 'pong',
            exitCode: 0,
            duration: 0,
          }),
        );
        continue;
      }

      // Exit command
      if (request.command === '__exit__') {
        console.log(
          JSON.stringify({
            id: request.id,
            success: true,
            message: 'exiting',
            exitCode: 0,
            duration: 0,
          }),
        );
        process.exit(0);
      }

      // Execute command
      const startTime = Date.now();
      const argv = ['bun', 'celilo', ...parseCommand(request.command)];
      const result = await runCli(argv);
      const duration = Date.now() - startTime;

      // Send response
      console.log(
        JSON.stringify({
          id: request.id,
          success: result.success,
          message: result.success ? result.message : undefined,
          error: !result.success ? result.error : undefined,
          details: !result.success ? result.details : undefined,
          exitCode: result.success ? 0 : 1,
          duration,
        }),
      );
    } catch (error) {
      // Parse or execution error
      console.error(
        JSON.stringify({
          id: -1,
          success: false,
          error: `Server error: ${error}`,
          exitCode: 1,
          duration: 0,
        }),
      );
    }
  }
}

/**
 * Main CLI entry point
 *
 * Executes CLI and handles output/exit codes.
 * If CLI_SERVER_MODE=true, runs in persistent server mode for testing.
 */
export async function main(): Promise<void> {
  // Check for server mode
  if (process.env.CLI_SERVER_MODE === 'true') {
    await serverMode();
    return;
  }

  // Remote execution: `celilo --remote <dest> <cmd>` or CELILO_REMOTE=<dest>.
  // SSH to the remote celilo-mgr and drive its api-serve over the wire.
  const remote = resolveRemote(process.argv);
  if (remote) {
    const outcome = await runRemoteClient(remote.dest, remote.commandArgv);
    if (outcome.status === 'blocked') {
      // Not a failure and not a decline: the command is parked server-side on a
      // question this client couldn't decide, and is still alive.
      process.stderr.write(
        `Command is parked on an unanswered question: ${outcome.question}\n` +
          `  answer it:  celilo events reply ${outcome.eventId} <value>\n` +
          `  it resumes server-side under session ${outcome.sessionId}\n`,
      );
      process.exit(EXIT_BLOCKED);
    }
    process.exit(outcome.exitCode);
  }

  // Normal single-command execution
  try {
    const result = await runCli(process.argv);

    if (result.success) {
      // For completion mode, output raw text without formatting
      if (process.argv.includes('--get-completions') || process.argv.includes('completion')) {
        console.log(result.message);
        process.exit(0);
      }

      // Empty message → command already emitted its own output (e.g. via
      // ProgressDisplay) and doesn't want anything written on top.
      if (!result.message) {
        process.exit(0);
      }

      // A successful command's message IS its result, so it goes to stdout
      // verbatim — no glyph, no `│  ` prefix, no re-wrapping on `\n\n`.
      //
      // `rawOutput` no longer selects a different destination; it is kept
      // because it still records which commands are contractually
      // machine-readable, and because JSON payloads must never acquire a
      // decoration if this branch ever grows one again (celilo#698).
      //
      // The old path split the message on `\n\n` and fed each section to the
      // clack renderer, which prefixed every line. That is what made
      // `line.startsWith('<module-id> ')` over `celilo module list` match
      // nothing — read in celilo#695 as a missing module rather than as a
      // parse failure, at the cost of a full e2e run.
      process.stdout.write(`${result.message}\n`);
      process.exit(0);
    }

    // Diagnostics go to stderr so a caller can separate them from the result.
    uiLog.error(`Error: ${result.error}`);
    if (result.details) {
      console.error('Details:', result.details);
    }
    process.exit(1);
  } catch (error) {
    console.error('Fatal error:', error);
    process.exit(1);
  }
}

// Execute main only when run directly (not when imported by tests)
if (import.meta.main) {
  await main();
}