kubectl-grove v2: Comprehensive CLI for Grove Cluster Management

[athreesh]

Summary

This PR implements the kubectl-grove CLI with comprehensive commands for managing Grove AI inference workloads on Kubernetes. It includes a complete migration of the CLI to a standalone module and replaces the Bubbletea TUI with the Arborist (tview-based) TUI.

Note: This PR is in Draft mode for prototyping the Grove CLI. See split strategy below if needed for merge.

What's Included

CLI Commands

Command	Description
kubectl grove status	Show PodCliqueSet status with clique/gang information
kubectl grove topology	Visualize pod placement across topology domains (with watch mode)
kubectl grove health	Gang health dashboard with threshold monitoring
kubectl grove metrics	Scrape and display inference metrics from pods
kubectl grove tui	Interactive Arborist TUI for hierarchical resource browsing
kubectl grove diagnostics	Collect diagnostics for troubleshooting

Key Features

• Standalone cli-plugin module: Migrated from operator/cmd/kubectl-grove/ to cli-plugin/
• Arborist TUI: tview-based hierarchical resource viewer replacing Bubbletea
• Watch Mode: Real-time updates for topology and health commands
• Shell Completion: bash, zsh, and fish support
• Namespace Resolution: Uses kubeconfig current namespace as default

---

PR Size Breakdown (~62K lines)

Category	Lines	% of PR	Notes
Test files (*_test.go)	~29K	47%	Comprehensive test coverage
cli-plugin/ (total)	~15K	24%	New CLI module (includes ~7K tests)
operator/ (non-test)	~12K	19%	Operator code changes
docs/	~2.8K	5%	User guide, design docs, API reference
CRD YAML	~1.7K	3%	Generated CRD manifests
go.mod/go.sum	~1.5K	2%	Dependency lockfiles

Key insight: Almost half (~29K) is test code. Actual implementation is ~30K lines.

---

Split Strategy (if needed for merge)

This PR can be split into 2-3 smaller PRs:

PR 1: cli-plugin migration (~15K lines)

• New standalone CLI module at cli-plugin/
• All commands: status, topology, health, metrics, generate, plan, compare
• Arborist TUI
• AIConfigurator integration

PR 2: Operator changes (~12K lines)

• API changes and webhook validation
• Topology constraints
• ClusterTopology CRD

PR 3: Tests & Docs (~32K lines)

• All *_test.go files
• Documentation updates (user guide, design docs)
• Can be reviewed/merged last

---

Review Tips

• Skip generated files: CRDs, go.sum, zz_generated.*
• 74 commits total: Can review by commit for context
• Tests validate behavior: Review implementation first, tests last

---

Example Usage

# Show status for a PodCliqueSet
kubectl grove status my-inference -n production

# Watch topology changes in real-time
kubectl grove topology my-inference --watch

# Generate manifests for a disaggregated deployment
kubectl grove generate \
  --model QWEN3_32B \
  --system h200_sxm \
  --total-gpus 8 \
  --backend sglang \
  --isl 2048 --osl 512 \
  --ttft 200 --tpot 50 \
  --save-dir ./manifests

# Launch interactive TUI
kubectl grove tui -n default

# Enable shell completion
source <(kubectl grove completion bash)

Test plan

• Unit tests for all commands pass (cd cli-plugin && go test ./...)
• Integration tested on Kind cluster with sample PodCliqueSets
• Verified all commands work with real Grove CRDs
• Watch mode tested for topology and health commands
• Arborist TUI navigation tested

Related Issues

Closes #329 (kubectl grove status)
Closes #330 (kubectl grove topology)
Closes #331 (kubectl grove generate)
Closes #332 (kubectl grove plan)
Closes #333 (kubectl grove health)

🤖 Generated with Claude Code

[unmarshall]

@athreesh while this PR is draft can you please use an existing go module cli-plugin to create any kubectl plugin and not include this in the operator go module. I would personally wish to keep operator module separate with a clear semantic purpose. We do not follow a mono-repo concept but use a more modern way for golang based applications by leveraging go modules to allow clear separation of concerns and dependencies.