@robinmordasiewicz/f5xc-xcsh 6.23.0

package/README.md

@@ -0,0 +1,206 @@
+# xcsh
+
+F5 Distributed Cloud Shell - A command-line interface for managing F5 Distributed Cloud resources.
+
+## Documentation
+
+Full documentation is available at **[robinmordasiewicz.github.io/f5xc-xcsh](https://robinmordasiewicz.github.io/f5xc-xcsh)**
+
+## Installation
+
+### Homebrew
+
+```bash
+brew tap robinmordasiewicz/tap
+brew install --cask xcsh
+```
+
+### Install Script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/robinmordasiewicz/f5xc-xcsh/main/install.sh | sh
+```
+
+## Usage
+
+### Basic Command Structure
+
+The CLI is organized around **domains** matching F5 Distributed Cloud API structure:
+
+```bash
+xcsh <domain> <operation> <resource-type> [resource-name] [flags]
+```
+
+### Domain-Based Commands
+
+Common domains include:
+
+| Domain | Alias | Purpose |
+|--------|-------|---------|
+| `load_balancer` | `lb` | Load balancing and origin pools |
+| `infrastructure` | `infra` | Core infrastructure resources |
+| `security` | `sec` | WAF, DDoS, bot defense |
+| `networking` | `net` | Network routing and configuration |
+| `observability` | `obs`, `o11y` | Monitoring and observability |
+| `api_security` | `apisec` | API protection and security |
+| `identity` | `iam` | Identity and access management |
+
+### Examples
+
+#### List Resources
+
+```bash
+# List HTTP load balancers in default namespace
+xcsh load_balancer list http_loadbalancer
+
+# Using alias for shorter command
+xcsh lb list http_loadbalancer
+
+# List in specific namespace
+xcsh lb list http_loadbalancer -n production
+```
+
+#### Get a Specific Resource
+
+```bash
+# Get a load balancer configuration
+xcsh load_balancer get http_loadbalancer example-lb
+
+# Get from specific namespace
+xcsh lb get http_loadbalancer example-lb -n production
+```
+
+#### Create a Resource
+
+```bash
+# Create from YAML file
+xcsh load_balancer create http_loadbalancer -i lb-config.yaml
+
+# Create from inline JSON
+xcsh lb create origin_pool --json-data '{"metadata":{"name":"example-pool"},...}'
+```
+
+#### Delete a Resource
+
+```bash
+# Delete with confirmation
+xcsh load_balancer delete http_loadbalancer example-lb
+
+# Delete without confirmation (for scripts)
+xcsh lb delete http_loadbalancer example-lb --yes
+```
+
+#### Apply (Create or Update)
+
+```bash
+# Apply from YAML (creates if not exists, updates if does)
+xcsh load_balancer apply http_loadbalancer -i lb-config.yaml
+```
+
+#### Get Help
+
+```bash
+# Show available domains
+xcsh --help
+
+# Show domain-specific operations
+xcsh load_balancer --help
+
+# Show operation-specific help
+xcsh load_balancer list --help
+
+# Show resource-type help
+xcsh load_balancer list http_loadbalancer --help
+```
+
+## Development & Domain System
+
+### Automated Domain Synchronization
+
+xcsh uses an **automated CI/CD-driven system** to keep domain definitions synchronized with upstream F5 Distributed Cloud API changes. This ensures the CLI always reflects the latest API structure without manual intervention.
+
+#### How It Works
+
+1. **Daily Checks**: GitHub Actions workflow (`sync-upstream-specs.yml`) checks for new upstream spec versions daily at 6 AM UTC
+2. **Automatic Regeneration**: When updates are detected, the system:
+   - Downloads latest enriched API specifications
+   - Regenerates domain and resource registries
+   - Validates code quality and tests pass
+   - Creates a pull request with all changes
+3. **Idempotent Generation**: Code generation is deterministic - running it twice with identical inputs produces byte-for-byte identical output
+4. **CI/CD Validation**: Every commit validates that generated files match upstream specs and are reproducible
+
+#### Domain Registry
+
+The domain registry (`pkg/types/domains_generated.go`) is **automatically generated** from upstream API specifications (``.specs/index.json`). It currently contains **40 domains** organized by functional area:
+
+- **Infrastructure**: cloud_infrastructure, site, site_management, container_services
+- **Security**: waf, bot_and_threat_defense, network_security
+- **Networking**: network, dns, network_connectivity, vpn
+- **Observability**: observability_and_analytics, telemetry_and_insights, statistics
+- **Identity**: identity, user_and_account_management, users
+- **And 24 more...**
+
+#### Manual Domain Configuration
+
+Team-specific domain customization is managed in `.specs/domain_config.yaml`:
+
+```yaml
+# Domain aliases (short command shortcuts)
+aliases:
+  load_balancer: [lb]
+  security: [sec]
+  networking: [net]
+  infrastructure: [infra]
+
+# Deprecated domains with migration guidance
+deprecated_domains:
+  config:
+    maps_to: system
+    reason: "Configuration management merged into system domain"
+    deprecated_since: "v1.0.25"
+
+# Missing metadata requiring upstream attention
+missing_metadata:
+  - domain: api_security
+    missing_field: "is_preview"
+    reason: "Need to mark preview/beta domains"
+```
+
+This file is **version-controlled** and survives automated spec updates, allowing teams to maintain consistent domain aliases across releases.
+
+#### For Developers
+
+To regenerate domain definitions:
+
+```bash
+# Full generation pipeline
+make generate
+
+# Just regenerate domains
+make generate-domains
+
+# Verify idempotency (CI safety check)
+make ci-generate
+```
+
+The generation pipeline:
+
+1. Downloads latest specs via `scripts/download-specs.sh`
+2. Runs `scripts/generate-domains.go` to create domain registry
+3. Runs `scripts/generate-schemas.go` to create resource schemas
+4. Validates against `scripts/validate-specs.go`
+
+#### Upstream Spec Quality
+
+When spec organization issues are detected, the system can automatically report them to the upstream repository. Use the GitHub issue template to report specification problems:
+
+- Missing metadata fields
+- Resource classification issues
+- Domain organization concerns
+
+See `.github/ISSUE_TEMPLATE/upstream-spec-quality.md` for the standardized reporting format.
+
+## License
+
+This project is open source. See the LICENSE file for details.

package/completions/_xcsh

@@ -0,0 +1,219 @@
+#compdef xcsh
+# zsh completion for xcsh
+# Generated by xcsh completion zsh
+
+_xcsh() {
+    local curcontext="$curcontext" state line
+    typeset -A opt_args
+
+    local -a global_opts
+    global_opts=(
+        '(-h --help)'{-h,--help}'[Show help information]'
+        '(-v --version)'{-v,--version}'[Show version number]'
+        '(-i --interactive)'{-i,--interactive}'[Force interactive mode]'
+        '--no-color[Disable color output]'
+        '(-o --output)'{-o,--output}'[Output format]:format:(json yaml table)'
+        '(-ns --namespace)'{-ns,--namespace}'[Namespace]:namespace:_xcsh_namespaces'
+    )
+
+    _arguments -C \
+        "${global_opts[@]}" \
+        '1: :->domain' \
+        '2: :->action' \
+        '*: :->args'
+
+    case $state in
+        (domain)
+            local -a domains builtins
+            domains=(
+            'admin_console_and_ui:Static UI component and console asset management'
+            'api:API discovery, security testing, and credential management'
+            'authentication:Authentication API'
+            'bigip:BigIP appliance management, iRules, and data groups'
+            'billing_and_usage:Subscription billing, payment methods, and usage tracking'
+            'blindfold:Secret encryption and policy-based data protection'
+            'bot_and_threat_defense:Bot detection, threat categorization, and defense management'
+            'cdn:CDN load balancing, caching rules, and content delivery'
+            'ce_management:Customer Edge site lifecycle and network configuration'
+            'certificates:SSL/TLS certificate and trusted CA management'
+            'cloud_infrastructure:Multi-cloud provider connectivity and credential management'
+            'cloudstatus:F5 XC service status and incidents'
+            'completion:Shell completion script generation'
+            'container_services:Edge container workloads and virtual Kubernetes management'
+            'data_and_privacy_security:Sensitive data detection, classification, and privacy...'
+            'data_intelligence:Data Intelligence API'
+            'ddos:DDoS protection and infrastructure security policies'
+            'dns:DNS zone management, load balancing, and record...'
+            'generative_ai:AI-powered features, assistants, and data collection'
+            'login:Authentication and session management'
+            'managed_kubernetes:Kubernetes RBAC, pod security, and container registries'
+            'marketplace:Third-party integrations, add-ons, and extensions'
+            'network:BGP routing, IPsec tunnels, and network connectivity'
+            'network_security:Network firewall, NAT, ACL, and policy-based routing'
+            'nginx_one:NGINX One platform integration and instance management'
+            'object_storage:Object storage for mobile SDK artifacts and integrations'
+            'observability:Synthetic monitoring, health checks, and observability...'
+            'rate_limiting:Traffic rate limiting, policers, and throttling controls'
+            'secops_and_incident_response:Malicious user detection and automated threat mitigation'
+            'service_mesh:Service mesh connectivity, discovery, and NFV management'
+            'shape:Bot defense and threat prevention with Shape Security'
+            'sites:Multi-cloud site deployment and edge infrastructure'
+            'statistics:Flow statistics, alerts, logs, and operational analytics'
+            'subscription:xcsh-specific subscription management commands (overview, quota analysis, validation)'
+            'support:Customer support ticket lifecycle and site diagnostics'
+            'telemetry_and_insights:Telemetry And Insights API'
+            'tenant_and_identity:User settings, notifications, sessions, and identity...'
+            'threat_campaign:Threat Campaign API'
+            'users:User accounts, tokens, and label management'
+            'virtual:HTTP/HTTPS load balancing and traffic management'
+            'vpm_and_node_management:Vpm And Node Management API'
+            'waf:Web application firewall rules and security policies'
+            'apisec:Alias for api'
+            'api-discovery:Alias for api'
+            'authn:Alias for authentication'
+            'oidc:Alias for authentication'
+            'sso:Alias for authentication'
+            'f5-bigip:Alias for bigip'
+            'irule:Alias for bigip'
+            'ltm:Alias for bigip'
+            'bf:Alias for blindfold'
+            'encrypt:Alias for blindfold'
+            'secrets:Alias for blindfold'
+            'cache:Alias for cdn'
+            'content:Alias for cdn'
+            'cert:Alias for certificates'
+            'certs:Alias for certificates'
+            'ssl:Alias for certificates'
+            'tls:Alias for certificates'
+            'cloud:Alias for cloud_infrastructure'
+            'infra:Alias for cloud_infrastructure'
+            'provider:Alias for cloud_infrastructure'
+            'vk8s:Alias for container_services'
+            'containers:Alias for container_services'
+            'workloads:Alias for container_services'
+            'di:Alias for data_intelligence'
+            'intelligence:Alias for data_intelligence'
+            'insights:Alias for data_intelligence'
+            'dos:Alias for ddos'
+            'ddos-protect:Alias for ddos'
+            'dns-zone:Alias for dns'
+            'zones:Alias for dns'
+            'ai:Alias for generative_ai'
+            'genai:Alias for generative_ai'
+            'assistant:Alias for generative_ai'
+            'mk8s:Alias for managed_kubernetes'
+            'appstack:Alias for managed_kubernetes'
+            'k8s-mgmt:Alias for managed_kubernetes'
+            'market:Alias for marketplace'
+            'addons:Alias for marketplace'
+            'extensions:Alias for marketplace'
+            'net:Alias for network'
+            'routing:Alias for network'
+            'bgp:Alias for network'
+            'netsec:Alias for network_security'
+            'nfw:Alias for network_security'
+            'nginx:Alias for nginx_one'
+            'nms:Alias for nginx_one'
+            'nginx-plus:Alias for nginx_one'
+            'storage:Alias for object_storage'
+            's3:Alias for object_storage'
+            'buckets:Alias for object_storage'
+            'obs:Alias for observability'
+            'monitoring:Alias for observability'
+            'synth:Alias for observability'
+            'ratelimit:Alias for rate_limiting'
+            'throttle:Alias for rate_limiting'
+            'policer:Alias for rate_limiting'
+            'mesh:Alias for service_mesh'
+            'svc-mesh:Alias for service_mesh'
+            'shape-sec:Alias for shape'
+            'safeap:Alias for shape'
+            'site:Alias for sites'
+            'deployment:Alias for sites'
+            'stats:Alias for statistics'
+            'metrics:Alias for statistics'
+            'logs:Alias for statistics'
+            'tickets:Alias for support'
+            'help-desk:Alias for support'
+            'telemetry:Alias for telemetry_and_insights'
+            'ti:Alias for telemetry_and_insights'
+            'threats:Alias for threat_campaign'
+            'campaigns:Alias for threat_campaign'
+            'threat-intel:Alias for threat_campaign'
+            'user:Alias for users'
+            'accounts:Alias for users'
+            'iam:Alias for users'
+            'lb:Alias for virtual'
+            'loadbalancer:Alias for virtual'
+            'vhost:Alias for virtual'
+            'vpm:Alias for vpm_and_node_management'
+            'nodes:Alias for vpm_and_node_management'
+            'node-mgmt:Alias for vpm_and_node_management'
+            'firewall:Alias for waf'
+            'appfw:Alias for waf'
+            )
+            builtins=(
+                'help:Show help information'
+                'quit:Exit the shell'
+                'exit:Exit the shell'
+                'clear:Clear the screen'
+                'history:Show command history'
+                'context:Show current navigation context'
+                'ctx:Show current navigation context'
+            )
+            _describe -t domains 'domain' domains
+            _describe -t builtins 'builtin' builtins
+            ;;
+        (action)
+            case ${line[1]} in
+        (login)
+            _values 'command' 'show:Command' 'profile:Subcommand group' 'context:Subcommand group'
+            ;;
+        (cloudstatus)
+            _values 'command' 'status:Command' 'summary:Command' 'components:Command' 'incidents:Command' 'maintenance:Command'
+            ;;
+        (completion)
+            _values 'command' 'bash:Command' 'zsh:Command' 'fish:Command'
+            ;;
+                (help|quit|exit|clear|history|context|ctx)
+                    ;;
+                (*)
+                    local -a actions
+                    actions=(
+            'list:List resources'
+            'get:Get a specific resource'
+            'create:Create a new resource'
+            'delete:Delete a resource'
+            'replace:Replace a resource'
+            'apply:Apply configuration from file'
+            'status:Get resource status'
+            'patch:Patch a resource'
+            'add-labels:Add labels to a resource'
+            'remove-labels:Remove labels from a resource'
+                    )
+                    _describe -t actions 'action' actions
+                    ;;
+            esac
+            ;;
+        (args)
+            local -a action_opts
+            action_opts=(
+                '(-n --name)'{-n,--name}'[Resource name]:name:'
+                '(-ns --namespace)'{-ns,--namespace}'[Namespace]:namespace:_xcsh_namespaces'
+                '(-o --output)'{-o,--output}'[Output format]:format:(json yaml table)'
+                '--limit[Maximum results]:limit:'
+                '--label[Filter by label]:label:'
+                '(-f --file)'{-f,--file}'[Configuration file]:file:_files'
+            )
+            _arguments "${action_opts[@]}"
+            ;;
+    esac
+}
+
+_xcsh_namespaces() {
+    local -a namespaces
+    namespaces=('default' 'system' 'shared')
+    _describe -t namespaces 'namespace' namespaces
+}
+
+_xcsh "$@"

package/completions/xcsh.bash

@@ -0,0 +1,70 @@
+# bash completion for xcsh
+# Generated by xcsh completion bash
+# shellcheck disable=SC2034,SC2207
+
+_xcsh_completions() {
+  local cur prev words cword
+  _init_completion || return
+
+  local commands="admin_console_and_ui api authentication bigip billing_and_usage blindfold bot_and_threat_defense cdn ce_management certificates cloud_infrastructure cloudstatus completion container_services data_and_privacy_security data_intelligence ddos dns generative_ai login managed_kubernetes marketplace network network_security nginx_one object_storage observability rate_limiting secops_and_incident_response service_mesh shape sites statistics subscription support telemetry_and_insights tenant_and_identity threat_campaign users virtual vpm_and_node_management waf apisec api-discovery authn oidc sso f5-bigip irule ltm bf encrypt secrets cache content cert certs ssl tls cloud infra provider vk8s containers workloads di intelligence insights dos ddos-protect dns-zone zones ai genai assistant mk8s appstack k8s-mgmt market addons extensions net routing bgp netsec nfw nginx nms nginx-plus storage s3 buckets obs monitoring synth ratelimit throttle policer mesh svc-mesh shape-sec safeap site deployment stats metrics logs tickets help-desk telemetry ti threats campaigns threat-intel user accounts iam lb loadbalancer vhost vpm nodes node-mgmt firewall appfw help quit exit clear history"
+  local actions="list get create delete replace apply status patch add-labels remove-labels"
+  local builtins="help quit exit clear history context ctx"
+  local global_flags="--help -h --version -v --interactive -i --no-color --output -o --namespace -ns"
+
+  # Handle completion based on position
+  case ${cword} in
+    1)
+      # First word: domains, builtins, or flags
+      if [[ "${cur}" == -* ]]; then
+        COMPREPLY=($(compgen -W "${global_flags}" -- "${cur}"))
+      else
+        COMPREPLY=($(compgen -W "${commands} ${builtins}" -- "${cur}"))
+      fi
+      return 0
+      ;;
+    2)
+      # Second word: actions or subcommands based on first word
+      local domain="${words[1]}"
+      case "${domain}" in
+        login)
+          COMPREPLY=($(compgen -W "show profile context" -- "${cur}"))
+          return 0
+          ;;
+        login/profile)
+          COMPREPLY=($(compgen -W "list show create use delete" -- "${cur}"))
+          return 0
+          ;;
+        login/context)
+          COMPREPLY=($(compgen -W "show set list" -- "${cur}"))
+          return 0
+          ;;
+        cloudstatus)
+          COMPREPLY=($(compgen -W "status summary components incidents maintenance" -- "${cur}"))
+          return 0
+          ;;
+        completion)
+          COMPREPLY=($(compgen -W "bash zsh fish" -- "${cur}"))
+          return 0
+          ;;
+        help | quit | exit | clear | history | context | ctx)
+          return 0
+          ;;
+        *)
+          # API domain - suggest actions
+          COMPREPLY=($(compgen -W "${actions}" -- "${cur}"))
+          return 0
+          ;;
+      esac
+      ;;
+    *)
+      # Third+ word: flags
+      if [[ "${cur}" == -* ]]; then
+        local action_flags="--name -n --namespace -ns --output -o --json --yaml --limit --label"
+        COMPREPLY=($(compgen -W "${action_flags}" -- "${cur}"))
+      fi
+      return 0
+      ;;
+  esac
+}
+
+complete -F _xcsh_completions xcsh