feat: guard bootstrap against an existing App of Apps and announce the target context

[filipegalo]

Problem

bootstrap ran regardless of whether the cluster had already been bootstrapped, silently overwriting the app-of-apps root Application. It also never named the cluster it was about to modify unless --context was passed explicitly — so a wrong kubectl config use-context was enough to bootstrap the wrong cluster with no warning.

Changes

Two checks run after the Kubernetes client connects but before anything is written, so aborting leaves the cluster untouched.

Existing App of Apps safeguard — Client.GetAppOfApps reads the app-of-apps Application. When one exists, bootstrap reports what it found and stops:

  Existing App of Apps:
    Application:  app-of-apps (namespace argocd)
    Repository:   git@github.com:acme/repo.git
    Revision:     main
    Path:         apps
    Sync/Health:  Synced / Healthy

ERROR cluster already bootstrapped: App of Apps "app-of-apps" exists in namespace argocd on context microk8s
  hint: inspect the existing installation with: cluster-bootstrap-cli info <environment>
  tip: re-run with --force to overwrite the existing App of Apps

--force overwrites it instead, still reporting what was found. A missing ArgoCD CRD is treated as "absent" rather than an error, so first-time bootstraps are unaffected.

Target context countdown — the resolved context is announced with a 10 second grace period:

⚠  Bootstrap will modify the cluster on Kubernetes context: microk8s
    Starting in  7s... press Ctrl+C to abort

Skipped by --yes/-y, and automatically when stdout is not a terminal, so CI is not delayed. The context line still prints in that case.

k8s.ResolveContext resolves the context through client-go rather than shelling out to kubectl, so the Configuration stage and the JSON report now name the real target context even when --context is omitted (previously it printed nothing).

New flags

Flag	Default	Description
--force	false	Bootstrap even if the cluster already has an App of Apps, overwriting it
--yes, -y	false	Skip the countdown. Already skipped when stdout is not a terminal

Drive-by fixes the early abort exposed

• The report rendered zero-valued resource entries, printing Application: (updated) on a run that aborted before touching anything — reading as if the App of Apps had been overwritten. Resource lines are now printed only for resources bootstrap actually reached.
• Runtime errors dumped the full usage text and printed the error twice. SilenceUsage is now set inside runBootstrap (so flag-parse errors still show usage) and SilenceErrors on the root command, since Execute prints errors itself.

⚠️ Behaviour change for existing users

Re-running bootstrap on an already bootstrapped cluster now requires --force. The docs previously advertised bootstrap as "fully idempotent, safe to re-run" — the underlying operations remain idempotent, but the default run now stops first. Any CI that re-runs bootstrap needs --force --yes. Marked as a feat (minor) rather than a breaking change; say the word if you'd rather this land as a major.

Docs updated accordingly: new Safeguards section and flags in docs/cli/bootstrap.md, a troubleshooting entry for the new error, the README idempotency note, and the one place in subfolder-setup.md that told users to re-run bootstrap.

Testing

• go build, go vet, gofmt clean; 288 tests pass
• New unit tests: guard (absent / exists / --force / lookup error), countdown (interactive vs not), GetAppOfApps via a fake dynamic client, and ResolveContext (override, kubeconfig fallback, no current context)
• Verified end-to-end against a live cluster that already had an app-of-apps: bootstrap aborted at the guard with the correct context name and no cluster mutation
• Not exercised: the countdown against a live TTY-attached bootstrap, since reaching it requires --force on a real cluster (installs ArgoCD, overwrites the root Application). The logic is unit-tested and the TTY gate uses the same term.IsTerminal idiom as vault_token.go.
• golangci-lint / gosec not installed locally — left to CI. The one integer conversion carries the same #nosec G115 annotation as the existing one in vault_token.go.

🤖 Generated with Claude Code