@celilo/cli 0.11.0 → 0.12.0

package/src/cli/command-registry.ts

@@ -1,1488 +0,0 @@
-/**
- * Command Registry - Single Source of Truth
- *
- * Defines the complete CLI command tree with metadata used by:
- * - Zsh completion generator (descriptions, args, flags)
- * - Help text generation (future)
- * - Completion coverage tests
- *
- * When adding a new command:
- * 1. Add it to this registry
- * 2. Add routing in index.ts
- * 3. Run `bun run test:completion` to verify coverage
- */
-
-/**
- * Flag definition for a command
- */
-export interface FlagDef {
-  name: string;
-  description: string;
-  takesValue: boolean;
-  /** Zsh completion hint: "_files", "_directories", or literal values like "dmz app secure" */
-  valueHint?: string;
-}
-
-/**
- * Positional argument definition
- */
-export interface ArgDef {
-  name: string;
-  description: string;
-  /** If true, this arg can be repeated (variadic). Uses * in zsh completions. */
-  variadic?: boolean;
-  /**
-   * Dynamic completion source:
-   * - "module_ids": query modules table
-   * - "service_ids": query container_services table
-   * - "machine_hostnames": query machines table
-   * - "capability_names": query capabilities table
-   * - "config_keys": query manifest for module-specific keys
-   * - "system_config_keys": static list of system config keys
-   * - "system_secret_keys": static list of system secret keys
-   * - "files": zsh _files
-   * - "directories": zsh _directories
-   * - undefined: no completion
-   */
-  completion?: string;
-}
-
-/**
- * Command node in the tree
- */
-export interface CommandDef {
-  name: string;
-  description: string;
-  subcommands?: CommandDef[];
-  args?: ArgDef[];
-  flags?: FlagDef[];
-}
-
-/**
- * Complete CLI command tree
- */
-export const COMMANDS: CommandDef[] = [
-  {
-    name: 'status',
-    description: 'Show system and module status',
-  },
-  {
-    name: 'audit',
-    description: 'Top-level alias for `system audit`',
-    flags: [
-      {
-        name: 'json',
-        description: 'Output a stable JSON schema instead of the human-readable table',
-        takesValue: false,
-      },
-      {
-        name: 'tui',
-        description: 'Force the interactive TUI (default when stdout is a terminal)',
-        takesValue: false,
-      },
-      {
-        name: 'no-tui',
-        description: 'Force the static text report even when stdout is a terminal',
-        takesValue: false,
-      },
-      {
-        name: 'theme',
-        description: 'TUI color theme (dark|light); defaults to dark',
-        takesValue: true,
-      },
-    ],
-  },
-  {
-    name: 'api',
-    description: 'Manage remote-API access (principals, grants, authorized_keys)',
-    subcommands: [
-      {
-        name: 'grant',
-        description: 'Grant or replace API access for a principal',
-        args: [{ name: 'principal', description: 'Principal name (kebab-case)' }],
-        flags: [
-          {
-            name: 'key',
-            description: 'SSH public key, or path to a .pub file',
-            takesValue: true,
-            valueHint: '_files',
-          },
-          {
-            name: 'can',
-            description: 'Comma-separated grants (e.g. module:deploy,service:*)',
-            takesValue: true,
-          },
-        ],
-      },
-      { name: 'list', description: 'List API principals and their grants' },
-      {
-        name: 'revoke',
-        description: 'Revoke API access for a principal',
-        args: [{ name: 'principal', description: 'Principal name' }],
-      },
-      {
-        name: 'authorized-keys',
-        description: "Print the API account's authorized_keys (forced-command lines)",
-      },
-      {
-        name: 'key',
-        description: 'Client-side key management',
-        subcommands: [
-          {
-            name: 'new',
-            description: 'Generate a new API keypair and print enrollment steps',
-            args: [{ name: 'name', description: 'Principal name for the key' }],
-          },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'events',
-    description: 'SQLite event-bus operations (status, tail, run dispatcher, etc.)',
-    subcommands: [
-      { name: 'status', description: 'Print bus health as JSON' },
-      {
-        name: 'tail',
-        description: 'Recent events as JSON',
-        flags: [
-          { name: 'type', description: 'Filter by event type', takesValue: true },
-          { name: 'limit', description: 'Max events to return', takesValue: true },
-        ],
-      },
-      { name: 'list-subscribers', description: 'List persistent bus subscribers' },
-      {
-        name: 'resync-subscriptions',
-        description:
-          "Rebuild subscribers from deployed modules' manifests (after a restore/migration)",
-      },
-      {
-        name: 'list-pending',
-        description: 'List pending deliveries',
-        flags: [
-          {
-            name: 'subscriber',
-            description: 'Restrict to a subscriber by name',
-            takesValue: true,
-          },
-          { name: 'limit', description: 'Max rows to return', takesValue: true },
-        ],
-      },
-      {
-        name: 'drain',
-        description: 'Process pending deliveries once and return',
-        flags: [{ name: 'concurrency', description: 'Max parallel handlers', takesValue: true }],
-      },
-      {
-        name: 'run',
-        description: 'Run the long-running dispatcher in the foreground',
-        flags: [
-          { name: 'poll-ms', description: 'Polling interval in ms', takesValue: true },
-          { name: 'concurrency', description: 'Max parallel handlers', takesValue: true },
-          {
-            name: 'halt-on-recovery',
-            description: 'Refuse to start if a prior crash is detected',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'emit',
-        description: 'Emit an event (operator/test path; bypasses schema)',
-        args: [
-          { name: 'type', description: 'Event type' },
-          { name: 'payload', description: 'Payload as JSON (optional)' },
-        ],
-        flags: [
-          { name: 'dedup-key', description: 'Idempotency key', takesValue: true },
-          { name: 'emitted-by', description: 'Audit tag', takesValue: true },
-        ],
-      },
-      {
-        name: 'reply',
-        description: 'Answer one pending interview query by event id (config/secret/ensure)',
-        args: [
-          { name: 'event_id', description: 'Query event id from `tail`' },
-          { name: 'value', description: "Answer as JSON (e.g. '\"foo\"', '8080', '[\"a\"]')" },
-        ],
-        flags: [
-          {
-            name: 'emitted-by',
-            description: 'Responder identity for the reply audit trail',
-            takesValue: true,
-          },
-        ],
-      },
-      {
-        name: 'ack',
-        description: 'Mark a running delivery succeeded',
-        args: [{ name: 'event_id', description: 'Event id from `tail`' }],
-        flags: [
-          {
-            name: 'subscriber',
-            description: 'Subscriber id (auto-detected when running under the dispatcher)',
-            takesValue: true,
-          },
-        ],
-      },
-      {
-        name: 'fail',
-        description: 'Mark a running delivery failed',
-        args: [{ name: 'event_id', description: 'Event id from `tail`' }],
-        flags: [
-          { name: 'error', description: 'Failure message', takesValue: true },
-          {
-            name: 'no-retry',
-            description: 'Abandon immediately instead of retrying',
-            takesValue: false,
-          },
-          { name: 'subscriber', description: 'Subscriber id', takesValue: true },
-        ],
-      },
-      {
-        name: 'repair',
-        description: 'Run the crash-recovery sweep without starting the dispatcher',
-      },
-      {
-        name: 'resume',
-        description: 'Acknowledge halt-on-recovery (alias for repair)',
-      },
-      {
-        name: 'respond',
-        description: 'Answer config/secret/ensure prompts for a deploy running in another shell',
-        flags: [
-          {
-            name: 'values',
-            description:
-              'JSON file with config/secrets/ensures map; switches to non-interactive mode',
-            takesValue: true,
-            valueHint: '_files',
-          },
-          {
-            name: 'idle-timeout',
-            description: 'Exit when bus is quiet for this duration (e.g. 30s, 2m)',
-            takesValue: true,
-          },
-          {
-            name: 'max-duration',
-            description: 'Hard ceiling on responder runtime (e.g. 10m)',
-            takesValue: true,
-          },
-          {
-            name: 'emittedBy',
-            description: 'Identifier for the emittedBy audit field on replies',
-            takesValue: true,
-          },
-        ],
-      },
-      {
-        name: 'install-daemon',
-        description: 'Write a systemd/launchd unit for the dispatcher',
-        flags: [
-          {
-            name: 'celilo-path',
-            description: 'Override the celilo binary path (default: Bun.which("celilo"))',
-            takesValue: true,
-            valueHint: '_files',
-          },
-          { name: 'poll-ms', description: 'Polling interval in ms', takesValue: true },
-          { name: 'concurrency', description: 'Max parallel handlers', takesValue: true },
-          {
-            name: 'system',
-            description:
-              'System scope: /etc/systemd/system unit or /Library/LaunchDaemons plist, run as the celilo state-dir owner (management-plane shape)',
-            takesValue: false,
-          },
-          {
-            name: 'print',
-            description:
-              'Render the unit to stdout without writing it (used by the celilo-mgmt role)',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'uninstall-daemon',
-        description: 'Remove the installed supervisor unit',
-        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
-      },
-      {
-        name: 'show-daemon',
-        description: 'Print the currently installed unit file',
-        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
-      },
-    ],
-  },
-  {
-    name: 'dns',
-    description: 'View DNS bookkeeping (registrations ledger)',
-    subcommands: [
-      {
-        name: 'registrations',
-        description: 'List the DNS registration ledger',
-        flags: [
-          {
-            name: 'provider',
-            description: 'Only show registrations owned by one provider module',
-            takesValue: true,
-            valueHint: 'module_ids',
-          },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'capability',
-    description: 'View registered module capabilities',
-    subcommands: [
-      {
-        name: 'list',
-        description: 'List all registered capabilities',
-      },
-      {
-        name: 'info',
-        description: 'Show detailed capability information',
-        args: [{ name: 'name', description: 'Capability name', completion: 'capability_names' }],
-      },
-    ],
-  },
-  {
-    name: 'publish',
-    description:
-      'Publish workspace packages to npm, bump consumer pins, refresh global install, and ship modules to celilo.computer',
-    flags: [
-      {
-        name: 'dry-run',
-        description: 'Preflight report only — no publishing, no file changes',
-        takesValue: false,
-      },
-      {
-        name: 'release-touch',
-        description: 'Auto-touch drifted module manifests with a fresh release marker, then exit',
-        takesValue: false,
-      },
-      {
-        name: 'allow-stale',
-        description: 'Bypass workspace and module stale-version safeguards',
-        takesValue: false,
-      },
-      {
-        name: 'yes',
-        description: 'Auto-confirm every prompt (also -y). Does NOT bypass safety gates.',
-        takesValue: false,
-      },
-      {
-        name: 'alpha',
-        description: 'Publish X.Y.Z-alpha.N to npm @alpha dist-tag (consumer-first iteration mode)',
-        takesValue: false,
-      },
-      {
-        name: 'track-alpha',
-        description:
-          'Force-pin just-published alphas into the bun global install (requires --alpha)',
-        takesValue: false,
-      },
-      {
-        name: 'alpha-modules',
-        description:
-          'Also publish module +N revisions in alpha mode (requires --alpha; default skips Phase 4)',
-        takesValue: false,
-      },
-      {
-        name: 'promote',
-        description:
-          'Graduate a named alpha to its base X.Y.Z (e.g. --promote @celilo/e2e@0.7.14-alpha.3)',
-        takesValue: true,
-      },
-      {
-        name: 'skip-changesets',
-        description:
-          'Skip the pending-changesets prompt; publish current package.json versions as-is',
-        takesValue: false,
-      },
-    ],
-  },
-  {
-    name: 'module',
-    description: 'Manage modules (import, generate, configure)',
-    subcommands: [
-      {
-        name: 'import',
-        description:
-          'Import a module from the registry (bare name) or from a local path (./, /, ~, or *.netapp)',
-        args: [
-          {
-            name: 'name-or-path',
-            description: 'Module name (registry) or filesystem path',
-            completion: 'directories',
-          },
-        ],
-        flags: [
-          {
-            name: 'registry',
-            description: 'Registry URL (overrides default celilo.computer)',
-            takesValue: true,
-          },
-          {
-            name: 'target',
-            description: 'Target directory',
-            takesValue: true,
-            valueHint: '_directories',
-          },
-          {
-            name: 'auto-generate-secrets',
-            description: 'Auto-generate capability secrets',
-            takesValue: false,
-          },
-          {
-            name: 'skip-verify',
-            description: 'Skip package signature verification',
-            takesValue: false,
-          },
-          {
-            name: 'accept-aspects',
-            description:
-              'Auto-approve any base-module aspect declared by the imported module (non-interactive contexts; CI; e2e)',
-            takesValue: false,
-          },
-        ],
-      },
-      { name: 'list', description: 'List all installed modules' },
-      {
-        name: 'remove',
-        description: 'Remove a module and its data',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-        flags: [
-          {
-            name: 'force',
-            description: 'Skip confirmation for infrastructure destruction',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'update',
-        description:
-          'Update modules. No args = sweep registry (auto-apply non-breaking, prompt for breaking). With args = update from local path(s).',
-        args: [
-          {
-            name: 'path',
-            description: 'Path to updated module source (omit to sweep registry)',
-            completion: 'directories',
-            variadic: true,
-          },
-        ],
-        flags: [
-          {
-            name: 'skip-verify',
-            description: 'Skip package signature verification',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'upgrade',
-        description:
-          'Upgrade a module to its latest registry version: update → backup (posture-gated) → deploy → verify. No id = the CD poll: upgrade every auto_upgrade module with a newer version.',
-        args: [
-          {
-            name: 'id',
-            description: 'Module ID (omit to poll all auto_upgrade modules)',
-            completion: 'module_ids',
-          },
-        ],
-        flags: [
-          {
-            name: 'registry',
-            description: 'Registry URL (defaults to configured registry)',
-            takesValue: true,
-          },
-        ],
-      },
-      {
-        name: 'verify',
-        description: 'Verify module integrity (signature + checksums)',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        // Deprecation alias for `module verify`. Removed after one
-        // release cycle. See CELILO_UPDATE D11.
-        name: 'audit',
-        description: 'DEPRECATED — use `module verify` instead',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        name: 'config',
-        description: 'Get or set module configuration',
-        subcommands: [
-          {
-            name: 'set',
-            description: 'Set configuration value',
-            args: [
-              { name: 'id', description: 'Module ID', completion: 'module_ids' },
-              { name: 'key', description: 'Config key', completion: 'config_keys' },
-              { name: 'value', description: 'Config value' },
-            ],
-          },
-          {
-            name: 'get',
-            description: 'Get configuration value',
-            args: [
-              { name: 'id', description: 'Module ID', completion: 'module_ids' },
-              { name: 'key', description: 'Config key', completion: 'config_keys' },
-            ],
-          },
-        ],
-      },
-      {
-        name: 'secret',
-        description: 'Manage module secrets',
-        subcommands: [
-          {
-            name: 'set',
-            description: 'Set encrypted secret',
-            args: [
-              { name: 'id', description: 'Module ID', completion: 'module_ids' },
-              { name: 'key', description: 'Secret name' },
-              { name: 'value', description: 'Secret value' },
-            ],
-          },
-          {
-            name: 'list',
-            description: 'List module secrets',
-            args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-          },
-        ],
-      },
-      {
-        name: 'show-config',
-        description: 'Show all configuration including derived values',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        name: 'show-zone',
-        description: 'Show module network zone and config',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        name: 'build',
-        description: 'Execute module build scripts',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        name: 'generate',
-        description: 'Generate infrastructure code',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-        flags: [
-          {
-            name: 'output',
-            description: 'Output directory',
-            takesValue: true,
-            valueHint: '_directories',
-          },
-        ],
-      },
-      {
-        name: 'deploy',
-        description: 'Deploy module to infrastructure',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-        flags: [
-          { name: 'debug', description: 'Enable debug mode', takesValue: false },
-          {
-            name: 'preflight',
-            description: 'Run pre-flight validation only (no deployment)',
-            takesValue: false,
-          },
-          {
-            name: 'verbose',
-            description:
-              'Keep all sub-events visible (no collapse-on-success); useful for debugging slow steps',
-            takesValue: false,
-          },
-          {
-            name: 'stop-after-interview',
-            description:
-              'Exit cleanly after the initial config + secrets interview (no terraform/ansible/hooks). Manual validation of the bus-mediated interview path.',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'validate',
-        description: 'Pre-flight check: validate module is ready for deployment',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        name: 'status',
-        description: 'Show detailed module status',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-      },
-      {
-        name: 'logs',
-        description: 'Show deploy logs for a module',
-        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
-        flags: [
-          { name: 'tail', description: 'Show last N lines', takesValue: true },
-          { name: 'last', description: 'Show only the most recent deploy run', takesValue: false },
-        ],
-      },
-      {
-        name: 'health',
-        description: 'Run health checks on deployed modules',
-        args: [{ name: 'id', description: 'Module ID (optional)', completion: 'module_ids' }],
-        flags: [
-          { name: 'json', description: 'Machine-readable JSON output', takesValue: false },
-          { name: 'debug', description: 'Show detailed check output', takesValue: false },
-        ],
-      },
-      {
-        name: 'run-hook',
-        description: 'Run a module hook (e.g., retry on_install after fixing an issue)',
-        args: [
-          { name: 'id', description: 'Module ID', completion: 'module_ids' },
-          { name: 'hook-name', description: 'Hook name (e.g., on_install, health_check)' },
-        ],
-        flags: [
-          {
-            name: 'debug',
-            description: 'Run with visible browser (Playwright hooks)',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'search',
-        description: 'Search the module registry',
-        args: [{ name: 'query', description: 'Search query (optional)' }],
-        flags: [
-          { name: 'registry', description: 'Registry URL', takesValue: true },
-          { name: 'limit', description: 'Max results', takesValue: true },
-        ],
-      },
-      {
-        name: 'publish',
-        description: 'Build and publish one or more modules to the registry',
-        args: [
-          {
-            name: 'module-dir...',
-            description: 'One or more module directories (shell-glob ./modules/* works)',
-            completion: 'directories',
-          },
-        ],
-        flags: [
-          { name: 'token', description: 'Publish token', takesValue: true },
-          { name: 'registry', description: 'Registry URL', takesValue: true },
-          { name: 'revision', description: 'Package revision number', takesValue: true },
-          {
-            name: 'message',
-            description: 'One-line release note stamped into release.json',
-            takesValue: true,
-          },
-          {
-            name: 'allow-dirty',
-            description: 'Bypass the clean-working-tree check (emergency publish)',
-            takesValue: false,
-          },
-          {
-            name: 'allow-stale',
-            description: 'Skip the manifest-vs-src stale-check (use sparingly)',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'backup',
-        description: "Create a backup of a module's data (invokes its on_backup hook)",
-        args: [
-          {
-            name: 'module-id',
-            description: 'Module ID (optional, backs up all if omitted)',
-            completion: 'module_ids',
-          },
-        ],
-        flags: [
-          { name: 'force', description: 'Ignore schedule, back up now', takesValue: false },
-          {
-            name: 'now',
-            description: 'Ignore schedule, back up now (alias for --force)',
-            takesValue: false,
-          },
-          { name: 'storage', description: 'Storage destination ID', takesValue: true },
-          {
-            name: 'no-interactive',
-            description: 'Non-interactive mode (for cron)',
-            takesValue: false,
-          },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'service',
-    description: 'Manage container services (Proxmox, DigitalOcean)',
-    subcommands: [
-      {
-        name: 'add',
-        description: 'Add a new container service',
-        subcommands: [
-          {
-            name: 'proxmox',
-            description: 'Add Proxmox container service',
-            flags: [
-              { name: 'api-url', description: 'Proxmox API URL', takesValue: true },
-              {
-                name: 'api-token-id',
-                description: 'API token ID (or $PROXMOX_API_TOKEN_ID)',
-                takesValue: true,
-              },
-              {
-                name: 'api-token-secret',
-                description: 'API token secret (or $PROXMOX_API_TOKEN_SECRET)',
-                takesValue: true,
-              },
-              { name: 'node', description: 'Target node', takesValue: true },
-              {
-                name: 'zone',
-                description: 'Network zone',
-                takesValue: true,
-                valueHint: 'dmz app secure internal',
-              },
-              { name: 'name', description: 'Service name', takesValue: true },
-            ],
-          },
-          {
-            name: 'digitalocean',
-            description: 'Add DigitalOcean container service',
-            flags: [
-              {
-                name: 'api-token',
-                description: 'DigitalOcean API token (or $DIGITALOCEAN_API_TOKEN)',
-                takesValue: true,
-              },
-              { name: 'region', description: 'Region', takesValue: true },
-              {
-                name: 'zone',
-                description: 'Network zone',
-                takesValue: true,
-                valueHint: 'dmz app secure external',
-              },
-              { name: 'name', description: 'Service name', takesValue: true },
-            ],
-          },
-        ],
-      },
-      {
-        name: 'list',
-        description: 'List all container services',
-        flags: [
-          {
-            name: 'zone',
-            description: 'Filter by zone',
-            takesValue: true,
-            valueHint: 'dmz app secure internal external',
-          },
-        ],
-      },
-      {
-        name: 'verify',
-        description: 'Re-verify a container service connection',
-        args: [{ name: 'service-id', description: 'Service ID', completion: 'service_ids' }],
-      },
-      {
-        name: 'remove',
-        description: 'Remove a container service',
-        args: [{ name: 'service-id', description: 'Service ID', completion: 'service_ids' }],
-        flags: [{ name: 'force', description: 'Skip confirmation', takesValue: false }],
-      },
-      {
-        name: 'reconfigure',
-        description: 'Re-run configuration interview for a service',
-        args: [{ name: 'service-id', description: 'Service ID', completion: 'service_ids' }],
-      },
-      {
-        name: 'config',
-        description: 'Get or set service configuration',
-        subcommands: [
-          {
-            name: 'get',
-            description: 'Get service configuration',
-            args: [
-              { name: 'service-id', description: 'Service ID', completion: 'service_ids' },
-              { name: 'key', description: 'Config key' },
-            ],
-          },
-          {
-            name: 'set',
-            description: 'Set service configuration',
-            args: [
-              { name: 'service-id', description: 'Service ID', completion: 'service_ids' },
-              { name: 'key', description: 'Config key' },
-              { name: 'value', description: 'Config value' },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'machine',
-    description: 'Manage existing machines (Raspberry Pi, VPS, bare metal)',
-    subcommands: [
-      {
-        name: 'add',
-        description: 'Add an existing machine to the pool',
-        flags: [
-          { name: 'ip', description: 'Machine IP address', takesValue: true },
-          { name: 'ssh-user', description: 'SSH username', takesValue: true },
-          {
-            name: 'ssh-key-file',
-            description: 'SSH private key file',
-            takesValue: true,
-            valueHint: '_files',
-          },
-          {
-            name: 'zone',
-            description: 'Network zone',
-            takesValue: true,
-            valueHint: 'dmz app secure internal external',
-          },
-          { name: 'name', description: 'Machine name', takesValue: true },
-          {
-            name: 'earmark',
-            description: 'Earmark machine for a specific module',
-            takesValue: true,
-          },
-          {
-            name: 'local',
-            description:
-              'This box itself — deploy over Ansible local connection (no SSH/key). Implied by ip 127.0.0.1.',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'list',
-        description: 'List all machines',
-        flags: [
-          {
-            name: 'zone',
-            description: 'Filter by zone',
-            takesValue: true,
-            valueHint: 'dmz app secure internal external',
-          },
-        ],
-      },
-      {
-        name: 'status',
-        description: 'Show machine status and assigned modules',
-        args: [
-          { name: 'hostname', description: 'Machine hostname', completion: 'machine_hostnames' },
-        ],
-      },
-      {
-        name: 'remove',
-        description: 'Remove a machine from the pool',
-        args: [
-          { name: 'hostname', description: 'Machine hostname', completion: 'machine_hostnames' },
-        ],
-        flags: [{ name: 'force', description: 'Skip confirmation', takesValue: false }],
-      },
-      {
-        name: 'earmark',
-        description: 'Earmark a machine for a specific module',
-        args: [
-          {
-            name: 'hostname',
-            description: 'Machine hostname or IP',
-            completion: 'machine_hostnames',
-          },
-          { name: 'module-id', description: 'Module ID to earmark for', completion: 'module_ids' },
-        ],
-        flags: [{ name: 'clear', description: 'Clear the earmark', takesValue: false }],
-      },
-    ],
-  },
-  {
-    name: 'system',
-    description: 'System configuration and initialization',
-    subcommands: [
-      {
-        name: 'init',
-        description: 'Initialize system configuration',
-        flags: [
-          {
-            name: 'accept-defaults',
-            description: 'Use default values without prompting',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'apply-config',
-        description:
-          'Headless write of <key=value> overrides to systemConfig (for hooks / automation; no prompts, no guidance)',
-        args: [
-          {
-            name: 'overrides',
-            description: 'Config overrides as <key=value> positionals',
-            variadic: true,
-          },
-        ],
-        flags: [
-          {
-            name: 'from-stdin',
-            description: 'Read a JSON map of overrides from stdin instead of positional args',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'config',
-        description: 'Get or set system configuration',
-        subcommands: [
-          {
-            name: 'set',
-            description: 'Set configuration value',
-            args: [
-              { name: 'key', description: 'Config key', completion: 'system_config_keys' },
-              { name: 'value', description: 'Config value' },
-            ],
-          },
-          {
-            name: 'get',
-            description: 'Get configuration value',
-            args: [{ name: 'key', description: 'Config key', completion: 'system_config_keys' }],
-          },
-        ],
-      },
-      {
-        name: 'secret',
-        description: 'Get or set system secrets',
-        subcommands: [
-          {
-            name: 'set',
-            description: 'Set secret value',
-            args: [
-              { name: 'key', description: 'Secret key', completion: 'system_secret_keys' },
-              { name: 'value', description: 'Secret value' },
-            ],
-          },
-          {
-            name: 'get',
-            description: 'Get secret value',
-            args: [{ name: 'key', description: 'Secret key', completion: 'system_secret_keys' }],
-          },
-        ],
-      },
-      { name: 'vault-password', description: 'Display Ansible vault password' },
-      {
-        name: 'audit',
-        description: 'Report system-wide drift (no mutations)',
-        flags: [
-          {
-            name: 'json',
-            description: 'Output a stable JSON schema instead of the human-readable table',
-            takesValue: false,
-          },
-          {
-            name: 'tui',
-            description: 'Force the interactive TUI (default when stdout is a terminal)',
-            takesValue: false,
-          },
-          {
-            name: 'no-tui',
-            description: 'Force the static text report even when stdout is a terminal',
-            takesValue: false,
-          },
-          {
-            name: 'theme',
-            description: 'TUI color theme (dark|light); defaults to dark',
-            takesValue: true,
-          },
-        ],
-      },
-      {
-        name: 'update',
-        description: 'Bring the system to the audit-determined READY state',
-        flags: [
-          {
-            name: 'module',
-            description: 'Restrict the run to a single module',
-            takesValue: true,
-          },
-          {
-            name: 'dry-run',
-            description: 'Print the plan without executing',
-            takesValue: false,
-          },
-          {
-            name: 'no-backup',
-            description: 'Skip pre-update backups (requires explicit acknowledgement)',
-            takesValue: false,
-          },
-          {
-            name: 'allow-destructive',
-            description: 'Allow destructive terraform plans through',
-            takesValue: false,
-          },
-          {
-            name: 'json',
-            description: 'Output a stable JSON schema instead of the human-readable summary',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'migrate',
-        description: 'Apply pending database migrations (idempotent; safe to re-run)',
-      },
-      {
-        name: 'doctor',
-        description:
-          'Diagnose system prerequisites, @celilo/* version drift, and (on a management plane) fleet-runtime drift',
-        flags: [
-          {
-            name: 'fix',
-            description:
-              'Repair the auto-fixable findings: `bun link` drifted @celilo/* packages and resync bus subscribers',
-            takesValue: false,
-          },
-          {
-            name: 'fleet',
-            description:
-              'Force the fleet-runtime section (dispatcher, subscribers, capability chains) even without a celilo DB',
-            takesValue: false,
-          },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'package',
-    description: 'Create module packages (.netapp files)',
-    args: [
-      {
-        name: 'source-directory',
-        description: 'Module source directory',
-        completion: 'directories',
-      },
-    ],
-    flags: [
-      { name: 'output', description: 'Output file path', takesValue: true, valueHint: '_files' },
-    ],
-  },
-  {
-    name: 'ipam',
-    description: 'IP address management (allocate, reserve, release)',
-    subcommands: [
-      { name: 'show', description: 'Show comprehensive IPAM summary' },
-      { name: 'list-allocations', description: 'Show all module IPAM allocations' },
-      {
-        name: 'vmid',
-        description: 'Manage VMID reservations',
-        subcommands: [
-          {
-            name: 'reserve',
-            description: 'Reserve VMID or range',
-            args: [
-              { name: 'vmid-or-range', description: 'VMID or range (e.g., 2100 or 2100-2110)' },
-            ],
-            flags: [{ name: 'reason', description: 'Reservation reason', takesValue: true }],
-          },
-          {
-            name: 'unreserve',
-            description: 'Unreserve VMID or range',
-            args: [{ name: 'vmid-or-range', description: 'VMID or range' }],
-          },
-          { name: 'list-reservations', description: 'List all VMID reservations' },
-        ],
-      },
-      {
-        name: 'ip',
-        description: 'Manage IP address exclusions',
-        subcommands: [
-          {
-            name: 'exclude',
-            description: 'Exclude IP address or range from IPAM allocation',
-            args: [{ name: 'ip-or-range', description: 'IP or range' }],
-            flags: [
-              {
-                name: 'zone',
-                description: 'Network zone (auto-detected from IP)',
-                takesValue: true,
-                valueHint: 'internal dmz app secure',
-              },
-              { name: 'reason', description: 'Exclusion reason', takesValue: true },
-            ],
-          },
-          {
-            name: 'include',
-            description: 'Remove IP exclusion (allow IPAM to allocate again)',
-            args: [{ name: 'ip-or-range', description: 'IP or range' }],
-            flags: [
-              {
-                name: 'zone',
-                description: 'Network zone (auto-detected from IP)',
-                takesValue: true,
-                valueHint: 'internal dmz app secure',
-              },
-            ],
-          },
-          { name: 'list-exclusions', description: 'List all IP exclusions' },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'proxmox',
-    description: 'Proxmox cluster introspection (nodes, capacity, instance sizing)',
-    subcommands: [
-      {
-        name: 'node',
-        description: 'Proxmox node operations',
-        subcommands: [
-          {
-            name: 'list',
-            description: 'List cluster nodes with live capacity (RAM/CPU/disk)',
-            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
-          },
-        ],
-      },
-      {
-        name: 'vm',
-        description: 'celilo-provisioned VM sizing',
-        subcommands: [
-          {
-            name: 'list',
-            description: 'List celilo VMs with desired vs actual size',
-            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
-          },
-          {
-            name: 'resize',
-            description: 'Resize a celilo VM (canonical size + reconcile)',
-            args: [{ name: 'name', description: 'Instance name (module/hostname)' }],
-            flags: [
-              { name: 'memory', description: 'New RAM in MB', takesValue: true },
-              { name: 'cpu', description: 'New vCPU count', takesValue: true },
-              { name: 'force', description: 'Override the node capacity check', takesValue: false },
-              {
-                name: 'allow-reboot',
-                description: 'Approve the stop/start a resize needs',
-                takesValue: false,
-              },
-              { name: 'skip-backup', description: 'Skip the pre-resize backup', takesValue: false },
-              {
-                name: 'yes',
-                description: 'Auto-approve reboot + backup (headless)',
-                takesValue: false,
-              },
-            ],
-          },
-        ],
-      },
-      {
-        name: 'ct',
-        description: 'celilo-provisioned container (LXC) sizing',
-        subcommands: [
-          {
-            name: 'list',
-            description: 'List celilo containers with desired vs actual size',
-            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
-          },
-          {
-            name: 'resize',
-            description: 'Resize a celilo container (canonical size + reconcile)',
-            args: [{ name: 'name', description: 'Instance name (module/hostname)' }],
-            flags: [
-              { name: 'memory', description: 'New RAM in MB', takesValue: true },
-              { name: 'cpu', description: 'New vCPU count', takesValue: true },
-              { name: 'force', description: 'Override the node capacity check', takesValue: false },
-              {
-                name: 'allow-reboot',
-                description: 'Approve the stop/start a resize needs',
-                takesValue: false,
-              },
-              { name: 'skip-backup', description: 'Skip the pre-resize backup', takesValue: false },
-              {
-                name: 'yes',
-                description: 'Auto-approve reboot + backup (headless)',
-                takesValue: false,
-              },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'subscribers',
-    description: 'Manage build-bus subscribers (cross-machine publish-event delivery)',
-    subcommands: [
-      {
-        name: 'list',
-        description: 'Show registered build-bus subscribers',
-      },
-      {
-        name: 'add',
-        description: 'Add a build-bus subscriber',
-        args: [{ name: 'url', description: 'Subscriber webhook URL (https://...)' }],
-        flags: [
-          { name: 'secret', description: 'Per-subscriber HMAC secret', takesValue: true },
-          { name: 'name', description: 'Human-readable label', takesValue: true },
-          {
-            name: 'registry',
-            description:
-              'Filter: deliver only events from this registry (e.g. npm, celilo-registry)',
-            takesValue: true,
-          },
-          {
-            name: 'tag',
-            description: 'Filter: deliver only events with this dist-tag (e.g. latest, alpha)',
-            takesValue: true,
-          },
-          {
-            name: 'package-pattern',
-            description:
-              'Filter: deliver only events whose package name matches this glob (e.g. @celilo/*)',
-            takesValue: true,
-          },
-        ],
-      },
-      {
-        name: 'remove',
-        description: 'Remove a subscriber by URL',
-        args: [{ name: 'url', description: 'Subscriber webhook URL to remove' }],
-      },
-      {
-        name: 'test',
-        description: 'Fire a synthetic event at a subscriber and report the delivery outcome',
-        args: [{ name: 'url', description: 'Subscriber webhook URL to test' }],
-      },
-      {
-        name: 'serve',
-        description:
-          'Run the build-bus HTTP receiver daemon (verifies signed webhooks, emits to local bus, dispatches module hooks)',
-        flags: [
-          { name: 'port', description: 'TCP port to listen on (default 8123)', takesValue: true },
-          {
-            name: 'secret',
-            description: 'Shared HMAC secret incoming webhooks must sign with',
-            takesValue: true,
-          },
-          {
-            name: 'no-dispatch',
-            description: 'Skip the in-process hook dispatcher (receiver-only mode)',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'status',
-        description:
-          'Per-subscriber delivery history (success rate, last delivery, recent failures)',
-      },
-    ],
-  },
-  {
-    name: 'storage',
-    description: 'Manage backup storage destinations',
-    subcommands: [
-      {
-        name: 'add',
-        description: 'Add a backup storage destination',
-        subcommands: [
-          {
-            name: 'local',
-            description: 'Add local filesystem storage',
-            flags: [
-              { name: 'path', description: 'Storage directory path', takesValue: true },
-              { name: 'name', description: 'Storage name', takesValue: true },
-            ],
-          },
-          {
-            name: 's3',
-            description: 'Add S3-compatible storage',
-            flags: [
-              { name: 'bucket', description: 'S3 bucket name', takesValue: true },
-              { name: 'region', description: 'AWS region', takesValue: true },
-              {
-                name: 'endpoint',
-                description: 'Custom endpoint URL (MinIO, B2)',
-                takesValue: true,
-              },
-              { name: 'name', description: 'Storage name', takesValue: true },
-              {
-                name: 'access-key-id',
-                description: 'S3 access key ID (non-interactive)',
-                takesValue: true,
-              },
-              {
-                name: 'secret-access-key',
-                description: 'S3 secret access key (non-interactive)',
-                takesValue: true,
-              },
-            ],
-          },
-        ],
-      },
-      { name: 'list', description: 'List configured storage destinations' },
-      {
-        name: 'remove',
-        description: 'Remove a storage destination',
-        args: [{ name: 'storage-id', description: 'Storage ID', completion: 'storage_ids' }],
-        flags: [{ name: 'force', description: 'Skip confirmation', takesValue: false }],
-      },
-      {
-        name: 'verify',
-        description: 'Verify storage destination connectivity',
-        args: [{ name: 'storage-id', description: 'Storage ID', completion: 'storage_ids' }],
-      },
-      {
-        name: 'set-default',
-        description: 'Set the default storage destination',
-        args: [{ name: 'storage-id', description: 'Storage ID', completion: 'storage_ids' }],
-      },
-    ],
-  },
-  {
-    name: 'backup',
-    description: 'Create and manage backups',
-    subcommands: [
-      {
-        name: 'create',
-        description: 'Create a backup',
-        args: [
-          {
-            name: 'module-id',
-            description: 'Module ID (optional, backs up all if omitted)',
-            completion: 'module_ids',
-          },
-        ],
-        flags: [
-          { name: 'force', description: 'Ignore schedule, back up now', takesValue: false },
-          {
-            name: 'now',
-            description: 'Ignore schedule, back up now (alias for --force)',
-            takesValue: false,
-          },
-          { name: 'storage', description: 'Storage destination ID', takesValue: true },
-          {
-            name: 'no-interactive',
-            description: 'Non-interactive mode (for cron)',
-            takesValue: false,
-          },
-        ],
-      },
-      {
-        name: 'list',
-        description: 'List available backups',
-        args: [
-          {
-            name: 'module-id',
-            description: 'Filter by module ID',
-            completion: 'module_ids',
-          },
-        ],
-        flags: [{ name: 'limit', description: 'Number of backups to show', takesValue: true }],
-      },
-      {
-        name: 'restore',
-        description: 'Restore from a backup',
-        args: [{ name: 'backup-id', description: 'Backup ID', completion: 'backup_ids' }],
-        flags: [{ name: 'yes', description: 'Skip confirmation', takesValue: false }],
-      },
-      {
-        name: 'delete',
-        description: 'Delete a specific backup',
-        args: [{ name: 'backup-id', description: 'Backup ID', completion: 'backup_ids' }],
-        flags: [{ name: 'force', description: 'Skip confirmation', takesValue: false }],
-      },
-      {
-        name: 'name',
-        description: 'Get or set a human-readable name on a backup',
-        args: [
-          { name: 'backup-id', description: 'Backup ID', completion: 'backup_ids' },
-          { name: 'name', description: 'Name to assign (all remaining text)' },
-        ],
-        flags: [{ name: 'clear', description: 'Remove the name', takesValue: false }],
-      },
-      {
-        name: 'prune',
-        description: 'Remove old backups according to retention policies',
-        args: [
-          {
-            name: 'module-id',
-            description: 'Module ID (optional)',
-            completion: 'module_ids',
-          },
-        ],
-        flags: [{ name: 'dry-run', description: 'Show what would be deleted', takesValue: false }],
-      },
-      {
-        name: 'import',
-        description: 'Import a local file as a module backup',
-        args: [
-          { name: 'file-path', description: 'Path to the file to import' },
-          {
-            name: 'module-id',
-            description: 'Module ID to associate the backup with',
-            completion: 'module_ids',
-          },
-        ],
-        flags: [
-          { name: 'name', description: 'Human-readable name for the backup', takesValue: true },
-          {
-            name: 'schema-version',
-            description: 'Schema version metadata',
-            takesValue: true,
-          },
-          { name: 'storage', description: 'Storage destination ID', takesValue: true },
-          { name: 'yes', description: 'Skip confirmation', takesValue: false },
-        ],
-      },
-      {
-        name: 'pull',
-        description: "Download another box's backup artifact from a storage destination",
-        flags: [
-          { name: 'storage', description: 'Storage destination name', takesValue: true },
-          {
-            name: 'module',
-            description: 'Module ID whose backup to pull (default: system state)',
-            takesValue: true,
-          },
-          { name: 'output', description: 'Local path to write the artifact', takesValue: true },
-        ],
-      },
-    ],
-  },
-  {
-    name: 'restore',
-    description: 'Restore a celilo-mgmt backup from a local artifact file (fresh-bootstrap path)',
-    args: [
-      {
-        name: 'artifact-path',
-        description: 'Path to the .backup file (also accepted via --from)',
-      },
-    ],
-    flags: [
-      { name: 'from', description: 'Path to the .backup file', takesValue: true },
-      {
-        name: 'force',
-        description: 'Override non-destructive pre-flight (clobbers existing state)',
-        takesValue: false,
-      },
-    ],
-  },
-  {
-    name: 'completion',
-    description: 'Generate shell completion scripts',
-    subcommands: [
-      { name: 'bash', description: 'Generate bash completion script' },
-      { name: 'zsh', description: 'Generate zsh completion script' },
-    ],
-  },
-  {
-    name: 'help',
-    description: 'Show help information',
-  },
-];