feat: cluster backend abstraction (colima + kind + dory)

[patrickleet]

Summary

hops local now supports three backends behind the same commands:

• colima (unchanged behavior) — VM + dockerd + k3s
• kind — nodes as docker containers on any docker daemon (Docker Desktop, colima's dockerd, dory's dockerd, CI runners)
• dory — A free, open-source native macOS app for Docker & Linux containers, an alternative to OrbStack and Docker Desktop. Universal for Intel and Apple silicon.

How it works

• Global --backend <colima|kind> on hops local; persisted to ~/.hops/local/backend on successful start. Resolution: flag > persisted > existing-cluster detection (colima wins for back-compat) > platform default (macOS colima, else kind).
• HOPS_KUBE_CONTEXT auto-set from the backend (colima / kind-hops) when --context is absent.
• kind create pins the registry NodePort mapping 127.0.0.1:30500 -> 30500; stop/start resume via docker stop/start of the node container; reset recreates the cluster.
• Registry trust on kind: containerd certs.d hosts.toml files alias both pull names (registry.crossplane-system.svc.cluster.local:5000 and localhost:30500, which provider runtime pods use) to the registry Service ClusterIP over HTTP. Written idempotently after the registry deploys; survives node restarts; no containerd restart needed (requires kind >= 0.27, enforced in preflight).
• Sizing flags and resize fail with actionable errors on kind.
• provider install / config install registry wiring flows through the same backend seam (was hardcoded colima ssh hosts sync).

dory gets no native backend (only 6443 published, no CLI, trust wiped on recreate — see task doc); dory users run the kind backend against dory's docker socket. Documented in README.

Commits

1. refactor: extract backend seam, colima-only, no behavior change
2. feat: kind backend + flag/persistence/detection
3. ci+docs: kind smoke workflow + README

Test output

• cargo test: 116 passed (new: resolution order, kind config gen, hosts.toml content, kind version parse, sizing rejection)
• Manual: hops local doctor on a running colima cluster resolves backend to colima via detection and targets context colima; hops local resize --backend kind and start --backend kind --cpus 4 fail with the intended errors.
• End-to-end kind path: the new kind backend smoke workflow in this PR (doctor + dual-name registry round-trip + stop/start resume + destroy).

Implements [[tasks/cluster-backend-abstraction]]

🤖 Generated with Claude Code

https://claude.ai/code/session_011Ei12zcYdwvUoZ3jCbwiWf

Summary by CodeRabbit

• New Features

  • Added support for multiple local cluster backends: Colima, kind, and Dory.
  • Added backend selection, persistence, lifecycle management, resizing where supported, and local registry integration.
  • Added backend-aware configuration and provider installation options.
  • Added end-to-end smoke checks for kind-based local development workflows.

• Documentation

  • Expanded local development guidance, backend selection instructions, prerequisites, and Dory usage examples.

• Bug Fixes

  • Improved registry wiring across backend and Kubernetes context combinations.
  • Added safer uninstall safeguards and persisted backend state handling.

[coderabbitai]

Warning

Review limit reached

@patrickleet, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5d90a04e-7b79-4034-a67d-e3a6db6e19a4

📥 Commits

Reviewing files that changed from the base of the PR and between 4297cd2 and cdf9145.

📒 Files selected for processing (24)

• .github/workflows/on-pr-colima-smoke.yaml
• .github/workflows/on-pr-kind-smoke.yaml
• README.md
• src/commands/auth/bootstrap.rs
• src/commands/config/install.rs
• src/commands/local/backend/colima.rs
• src/commands/local/backend/dory.rs
• src/commands/local/backend/kind.rs
• src/commands/local/backend/mod.rs
• src/commands/local/destroy.rs
• src/commands/local/doctor.rs
• src/commands/local/install.rs
• src/commands/local/mod.rs
• src/commands/local/package_install.rs
• src/commands/local/reset.rs
• src/commands/local/resize.rs
• src/commands/local/start.rs
• src/commands/local/stop.rs
• src/commands/local/uninstall.rs
• src/commands/provider/install.rs
• src/commands/secrets/list.rs
• src/commands/vars/mod.rs
• src/commands/vars/sync.rs
• tests/colima_smoke_workflow.rs

📝 Walkthrough

Walkthrough

Adds a unified local-cluster backend abstraction supporting Colima, kind, and Dory. Lifecycle, registry wiring, installation, context handling, documentation, and backend-specific smoke validation are updated accordingly.

Changes

Local backend abstraction

Layer / File(s)	Summary
Backend contract and selection src/commands/local/backend/mod.rs	Defines backend selection, persistence, lifecycle dispatch, kube-context activation, sizing, and registry-wiring behavior.
Local command delegation src/commands/local/*.rs, src/commands/local/mod.rs	Routes local lifecycle commands through the selected backend and adds uninstall safeguards and backend-aware Helm/Kubernetes context handling.
Colima backend src/commands/local/backend/colima.rs	Adds Colima lifecycle, resizing, Docker registry configuration, VM host synchronization, and tests.
Kind backend src/commands/local/backend/kind.rs	Adds kind cluster lifecycle, version checks, readiness handling, containerd registry aliases, and tests.
Dory backend src/commands/local/backend/dory.rs	Adds Dory k3s lifecycle, persistent registry and port configuration, engine recovery, kubeconfig handling, and tests.
Installation registry wiring src/commands/config/install.rs, src/commands/provider/install.rs	Adds backend selection and centralizes local-registry preparation with context-aware wiring.
Documentation and CI validation README.md, .github/workflows/on-pr-kind-smoke.yaml	Documents colima, kind, and dory usage and adds kind registry round-trip and resume-path smoke checks.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

• hops-ops/hops-cli issue 71 — Adds kind backend validation and registry round-trip smoke coverage related to the issue’s requested backend verification.

Possibly related PRs

• hops-ops/hops-cli#28: The lifecycle delegation replaces the earlier Colima-only local command behavior.
• hops-ops/hops-cli#51: Both changes modify local command dispatch wiring.
• hops-ops/hops-cli#68: The Colima lifecycle and sizing changes are incorporated into the new backend abstraction.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.55% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding a cluster backend abstraction for Colima, Kind, and Dory.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cluster-backend-abstraction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[patrickleet]

Augani/dory#18

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/commands/config/install.rs (1)

178-185: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract prepare_local_registry to a shared module to eliminate duplication.

This function is identical to the one in src/commands/provider/install.rs:141-148. Both call ensure_registry() then delegate to backend::wire_local_registry_for_target. Extracting it to package_install.rs (which both files already import from) or backend/mod.rs would keep the registry-preparation contract in one place and prevent divergence.

♻️ Proposed extraction to `package_install.rs`

In src/commands/local/package_install.rs:

use crate::commands::local::backend::{self, Backend};

pub fn prepare_local_registry(
    backend: Backend,
    backend_flag: Option<Backend>,
    context: Option<&str>,
) -> Result<(), Box<dyn Error>> {
    ensure_registry()?;
    backend::wire_local_registry_for_target(backend, backend_flag, context)
}

Then in both config/install.rs and provider/install.rs, replace the local prepare_local_registry with an import:

-fn prepare_local_registry(
-    backend: Backend,
-    backend_flag: Option<Backend>,
-    context: Option<&str>,
-) -> Result<(), Box<dyn Error>> {
-    ensure_registry()?;
-    backend::wire_local_registry_for_target(backend, backend_flag, context)
-}
+use crate::commands::local::package_install::prepare_local_registry;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/config/install.rs` around lines 178 - 185, Extract the
duplicated prepare_local_registry function from config/install.rs and
provider/install.rs into the shared local package_install module. Make it public
there, preserve its ensure_registry call and
backend::wire_local_registry_for_target delegation, then import and use the
shared function from both install modules and remove their local copies.

src/commands/local/mod.rs (1)

176-186: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consolidate kubectl/helm blocks to reduce duplication.

The helm blocks in run_cmd and run_cmd_output are near-identical to the kubectl blocks, differing only in the context-injection helper. Extracting a shared helper would eliminate the copy-paste and make it easier to add future backends or command wrappers.

♻️ Proposed consolidation for run_cmd

 pub fn run_cmd(program: &str, args: &[&str]) -> Result<(), Box<dyn Error>> {
-    if program == "kubectl" {
-        let full = with_kube_context(args);
-        let refs: Vec<&str> = full.iter().map(|s| s.as_str()).collect();
-        return run_cmd_with_logged_args(program, &refs, &refs);
-    }
-    if program == "helm" {
-        let full = with_helm_kube_context(args);
+    if program == "kubectl" || program == "helm" {
+        let full = if program == "kubectl" {
+            with_kube_context(args)
+        } else {
+            with_helm_kube_context(args)
+        };
         let refs: Vec<&str> = full.iter().map(|s| s.as_str()).collect();
         return run_cmd_with_logged_args(program, &refs, &refs);
     }
     run_cmd_with_logged_args(program, args, args)
 }

♻️ Proposed consolidation for run_cmd_output

 pub fn run_cmd_output(program: &str, args: &[&str]) -> Result<String, Box<dyn Error>> {
-    if program == "kubectl" {
-        let full = with_kube_context(args);
-        log::debug!("Running: {} {}", program, full.join(" "));
-        let output = Command::new(program).args(&full).output()?;
-        if !output.status.success() {
-            let stderr = String::from_utf8_lossy(&output.stderr);
-            return Err(format!("{} exited with {}: {}", program, output.status, stderr).into());
-        }
-        return Ok(String::from_utf8_lossy(&output.stdout).to_string());
-    }
-    if program == "helm" {
-        let full = with_helm_kube_context(args);
+    if program == "kubectl" || program == "helm" {
+        let full = if program == "kubectl" {
+            with_kube_context(args)
+        } else {
+            with_helm_kube_context(args)
+        };
         log::debug!("Running: {} {}", program, full.join(" "));
         let output = Command::new(program).args(&full).output()?;
         if !output.status.success() {
             let stderr = String::from_utf8_lossy(&output.stderr);
             return Err(format!("{} exited with {}: {}", program, output.status, stderr).into());
         }
         return Ok(String::from_utf8_lossy(&output.stdout).to_string());
     }

Also applies to: 198-207

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/local/mod.rs` around lines 176 - 186, Consolidate the duplicated
kubectl/helm handling in run_cmd and run_cmd_output by extracting a shared
helper for context injection and command execution. Have the helper select the
appropriate context-injection function based on the program, while preserving
unchanged behavior for other programs and both logged and output-capturing
execution paths.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/commands/local/mod.rs`:
- Around line 114-116: Update the doc comments for the Install and Reset
variants in the Backend enum to include Dory alongside colima and kind,
accurately documenting all supported local backends while preserving the
existing operation descriptions.

---

Nitpick comments:
In `@src/commands/config/install.rs`:
- Around line 178-185: Extract the duplicated prepare_local_registry function
from config/install.rs and provider/install.rs into the shared local
package_install module. Make it public there, preserve its ensure_registry call
and backend::wire_local_registry_for_target delegation, then import and use the
shared function from both install modules and remove their local copies.

In `@src/commands/local/mod.rs`:
- Around line 176-186: Consolidate the duplicated kubectl/helm handling in
run_cmd and run_cmd_output by extracting a shared helper for context injection
and command execution. Have the helper select the appropriate context-injection
function based on the program, while preserving unchanged behavior for other
programs and both logged and output-capturing execution paths.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e496c838-001d-41dd-ba0b-9e88e832a36b

📥 Commits

Reviewing files that changed from the base of the PR and between a7a3151 and 4297cd2.

📒 Files selected for processing (22)

• .github/workflows/on-pr-kind-smoke.yaml
• README.md
• src/commands/auth/bootstrap.rs
• src/commands/config/install.rs
• src/commands/local/backend/colima.rs
• src/commands/local/backend/dory.rs
• src/commands/local/backend/kind.rs
• src/commands/local/backend/mod.rs
• src/commands/local/destroy.rs
• src/commands/local/doctor.rs
• src/commands/local/install.rs
• src/commands/local/mod.rs
• src/commands/local/package_install.rs
• src/commands/local/reset.rs
• src/commands/local/resize.rs
• src/commands/local/start.rs
• src/commands/local/stop.rs
• src/commands/local/uninstall.rs
• src/commands/provider/install.rs
• src/commands/secrets/list.rs
• src/commands/vars/mod.rs
• src/commands/vars/sync.rs

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Doc comments omit Dory backend.

The Install and Reset variant doc comments mention only "colima or kind" but the Backend enum now includes Dory. Update to reflect all supported backends.

📝 Proposed doc updates

-    /// Install the local cluster backend (colima or kind) via Homebrew
+    /// Install the local cluster backend (colima, kind, or dory)
     Install,
-    /// Reset local Kubernetes state (colima: k8s reset; kind: recreate cluster)
+    /// Reset local Kubernetes state (colima: k8s reset; kind: recreate cluster; dory: recreate cluster)
     Reset,

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	/// Install the local cluster backend (colima or kind) via Homebrew
	Install,
	/// Reset local Colima Kubernetes state
	/// Reset local Kubernetes state (colima: k8s reset; kind: recreate cluster)
	/// Install the local cluster backend (colima, kind, or dory)
	Install,
	/// Reset local Kubernetes state (colima: k8s reset; kind: recreate cluster; dory: recreate cluster)
	Reset,

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/local/mod.rs` around lines 114 - 116, Update the doc comments
for the Install and Reset variants in the Backend enum to include Dory alongside
colima and kind, accurately documenting all supported local backends while
preserving the existing operation descriptions.