kctl-tui/PLAN.md

PLAN.md — Implementation Roadmap

This document tracks how kctl-tui is being built, phase by phase, and what is still open. For the full requirements, see SPEC.md.

Phase 0 — Repository setup (done)

• Go module (github.com/skoelle/kctl-tui), .gitignore, MIT LICENSE.
• GitHub Actions workflow: go vet + go test on every push/PR, plus a cross-platform build matrix (linux/darwin/windows x amd64/arm64) that attaches binaries to GitHub Releases on version tags.
• install.sh for Linux/macOS/WSL, downloading the latest release asset, with clear diagnostics if no release exists yet or the GitHub API is unreachable.
• README.md, config.example.yaml.

Phase 1 — Core logic + navigation (done)

• internal/kctl: pure, unit-tested logic — template resolution (ResolveTemplate), namespace/label filtering (DistinctLabelValues, NamespacesForLabelValue), and secret diffing (DiffSecretValues, AnyMismatch).
• internal/config: YAML config loading with template-based context and secret name resolution (ContextTemplate, SecretNameTemplate, K8sSecretNameTemplate), with safe defaults when no config file exists yet.
• internal/kubeexec: thin wrappers around kubectl/aws CLI calls (namespaces, deployments, rollout restart/status, fetching AWS secrets by template-resolved ID, reading all fields of a Kubernetes secret, ExternalSecret annotation, AWS auth check).
• cmd/kctl-tui "full" mode: Bubble Tea navigation for context -> team -> namespace, with Esc correctly popping back one level at a time, defaults pre-selected from the currently active context/namespace.
• On confirming a namespace, "full" mode launches the 3-pane tmux session (control pane + two k9s panes, even-vertical layout, remain-on-exit so a crashing control pane stays visible) via tea.ExecProcess and resumes at the namespace screen once the session ends.
• cmd/kctl-tui "panel" mode: - Redeploy: pick a deployment from a list, confirm, then rollout restart + rollout status. - Secrets: AWS auth check with interactive SSO login fallback, then automatically resolve the AWS secret ID (from secret_name_template) and Kubernetes secret name (from k8s_secret_name_template), fetch both, diff every field in one table (key / AWS value / Kubernetes value / match status). If any field differs, offer a single force-sync request for the whole secret (one ExternalSecret annotation). - Esc closes the whole tmux session (tmux kill-session).

Phase 2 — Hardening (done)

• Handle non-JSON AWS secrets and Kubernetes secrets with binary (non-UTF8) values more gracefully in the diff table.
• Add integration-style tests against a local kind/k3d cluster in CI for the kubeexec wrappers currently excluded from automated testing. (Deferred — superseded by client-go in v0.3.0)
• Input validation for the free-text steps in "panel" mode.
• Graceful handling when tmux, k9s, or aws are not installed.
• Structured logging / --verbose flag for troubleshooting failed kubectl/aws calls.
• Paginate/scroll the secrets diff table for secrets with many fields.

Phase 3 — Windows-native support (done)

• Windows support via psmux.
• install.ps1 — PowerShell install script for Windows.
• Updated README and SPEC with Windows + psmux setup instructions.

Phase 4 — Nice-to-haves (done for v0.2.0)

• --version flag — prints version, set via -ldflags at build time.
• Config validation command (kctl-tui config check) — validates required fields and shows a resolved context example.
• kctl-tui doctor — health check for tools, config, and connectivity.
• --help flag with full usage documentation.
• CHANGELOG.md, CONTRIBUTING.md, GitHub Issue/PR templates.

---

Bugfix Sprint — between v0.2.0 and v0.3.0

• Dead code cmd/kctl-tui/main.go:47-49 — empty if len(filtered) == 0 block with comment. Remove.

• Redundant logic internal/kctl/diff.go:60-63 — if lb || rb { match = l == r } is identical to the line above. Either dead or misunderstood.

• Diff-scroll is a no-op cmd/kctl-tui/panel.go:398-413 — renderDiffTable is always called with visibleHeight=0, so end = len(entries) is always true. j/k/arrows only change the offset text but the table is always fully rendered. The CHANGELOG promises "Diff table scroll support" but the feature is incomplete.

• README duplicate README.md:98-102 — "This downloads the latest release binary..." appears twice (once "to your PATH", once "to /usr/local/bin"). Edit leftover.

• go mod tidy in CI build.yml — mutates go.sum during the build instead of enforcing a tidy check. If someone forgets to tidy, it's silently fixed instead of blocking the PR.

• Bubbles filter disabled full.go:53, panel.go:87 — workaround for the stuck-filter bug (commit 7db58b6). Users can no longer type-to-filter. Worth restoring with a proper fix later.

• Kleinkram:

  • fmt.Errorf("%s", msg) → errors.New(msg) in kubeexec.go:41
  • helpers.go is a pointless 1:1 passthrough to the kctl package
  • IsBinary also marks UTF-8 special chars (>0x7F) as "binary"

• SECURITY.md — fehlt, besonders wichtig für ein Tool mit Secret-Workflows.

• dependabot.yml — automatische Dependency-Updates.

• Checksummen für Release-Assets — CI erzeugt Binaries aber keine .sha256-Dateien; für curl | bash-Install wichtig.

• Makefile / justfile — Build/Test/Vet-Komfort.

• golangci-lint — go vet allein ist dünn; optional aber empfohlen.

• PLAN.md aufräumen — erledigte Phasen als „Done" markieren, offene Items konsolidieren.

---

Roadmap

v0.3.0 — client-go integration

Replace kubectl shell-outs with direct API calls via client-go.

• Add internal/kubeclient package using client-go for: - Context/namespace/label queries (faster than kubectl JSON parsing) - Deployment list and rollout restart/status - Secret fetch (AWS Secrets Manager via SDK, K8s secrets via API) - ExternalSecret annotation update
• Keep internal/kubeexec as fallback for operations not yet covered by client-go
• Remove kind/k3d integration test plan (client-go has its own test coverage)
• Add unit tests with fake.Clientset for the new package

v1.0 — Stable release

Production-ready with package manager support and documentation.

• Homebrew tap (skoelle/homebrew-tap) with kctl-tui formula
• Scoop manifest (skoelle/scoop-bucket) for Windows
• Full test coverage for internal/kubeclient
• Documentation: architecture diagram, config reference, troubleshooting
• Semantic versioning policy documented
• Deprecation policy for config schema changes

Notes for contributors

• Keep any real organization-specific context names, namespace names, label keys, or secret names out of the repository. Use the generic placeholders already established in SPEC.md and config.example.yaml.
• Pure/testable logic belongs in internal/kctl and internal/config; anything that shells out to kubectl/aws/tmux belongs in internal/kubeexec or directly in cmd/kctl-tui, and should stay thin enough that it does not need its own test suite.