@celilo/cli 0.1.0

package/src/cli/command-registry.ts

@@ -0,0 +1,742 @@
+/**
+ * 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: '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: 'module',
+    description: 'Manage modules (import, generate, configure)',
+    subcommands: [
+      {
+        name: 'import',
+        description: 'Import module from directory or package',
+        args: [{ name: 'path', description: 'Module path', completion: 'directories' }],
+        flags: [
+          {
+            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: '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 module code while preserving state',
+        args: [
+          {
+            name: 'path',
+            description: 'Path to updated module source',
+            completion: 'directories',
+            variadic: true,
+          },
+        ],
+        flags: [
+          {
+            name: 'skip-verify',
+            description: 'Skip package signature verification',
+            takesValue: false,
+          },
+        ],
+      },
+      {
+        name: 'audit',
+        description: 'Verify module integrity',
+        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: 'no-interactive',
+            description: 'Disable progress animation and stream output directly',
+            takesValue: false,
+          },
+          { name: 'debug', description: 'Enable debug mode', takesValue: false },
+          {
+            name: 'preflight',
+            description: 'Run pre-flight validation only (no deployment)',
+            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: '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: 'token-id', description: 'API token ID', takesValue: true },
+              { name: 'token-secret', description: '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', 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: '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: '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: '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: '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: '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: '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',
+  },
+];