feat: repo install clarification - source or published version selector

Author: patrickleet

README.md

@@ -147,6 +147,40 @@ How it works:
 - Applies a GitHub `ProviderConfig` named `default` unless `--refresh` is used.
 - Supports overrides for namespace, Secret name, ProviderConfig name, provider name, and provider package.
 
+## Quick Start
+
+```bash
+# Build and load a Crossplane configuration package from an Upbound-format XRD project
+hops config install --path /path/to/project
+
+# Install from a GitHub repo; interactive TTY runs ask whether to build from source
+# or use a published version (non-interactive runs default to source build)
+hops config install --repo hops-ops/helm-certmanager
+
+# Force reload from source (deletes existing ConfigurationRevision(s) first)
+hops config install --repo hops-ops/helm-certmanager --reload
+
+# Apply a pinned remote package version directly (no clone/build)
+hops config install --repo hops-ops/helm-certmanager --version v0.1.0
+
+# Remove a configuration and prune orphaned package dependencies
+hops config uninstall --repo hops-ops/helm-certmanager
+
+# Generate apis/*/configuration.yaml from upbound.yaml for validation
+hops validate generate-configuration --path /path/to/project
+
+# Observe an existing XR into a manifest
+hops xr observe --kind AutoEKSCluster --name pat-local --namespace default --aws-region us-east-2
+
+# Render adoption patches for managed resources under an existing XR
+hops xr adopt --kind AutoEKSCluster --name pat-local --namespace default
+
+# Convert an observed/adopted XR into a managed manifest
+hops xr manage --kind AutoEKSCluster --name pat-local --namespace default
+
+# Render patches that remove Delete from management policies
+hops xr orphan --kind AutoEKSCluster --name pat-local --namespace default
+```
 ## Config packages
 
 `config install` and `config uninstall` operate on the currently connected Kubernetes cluster.
@@ -165,7 +199,8 @@ hops config install
 # Build from an explicit local Upbound-format XRD project path
 hops config install --path /path/to/project
 
-# Build from a cached GitHub repo checkout containing an Upbound-format XRD project
+# Install from a GitHub repo; interactive TTY runs ask whether to build from source
+# or use a published version
 hops config install --repo hops-ops/aws-auto-eks-cluster
 
 # Force a source reload before re-applying
@@ -195,6 +230,8 @@ Notes:
 
 - `--reload` only applies to source installs: `--path` or `--repo` without `--version`.
 - `--skip-dependency-resolution` sets `spec.skipDependencyResolution=true` on the generated `Configuration`.
+- `config install --repo ...` now prompts in interactive terminals to choose between cloning/building from source or applying a published package version. Published-version prompts suggest the latest discovered tag by default and still accept arbitrary tags such as `pr-<gitsha>`.
+- Non-interactive `config install --repo ...` keeps the previous default behavior and builds from source.
 - `config install --repo ... --version ...` skips clone/build and applies the remote package directly.
 - `config uninstall --repo ...` derives the configuration name as `<org>-<repo>`.
 
@@ -225,10 +262,13 @@ Notes:
   - Applies Crossplane `Configuration` resources pointing at `registry.crossplane-system.svc.cluster.local:5000/...`
   - Supports `--skip-dependency-resolution`
 - `config install --repo <org/repo> [--reload]`
-  - Source-build mode intended for a local control plane because it depends on the local registry flow
-  - Uses local repo cache at `~/.hops/local/repo-cache/<org>/<repo>`
-  - Clones on first use, then fetches/pulls on subsequent runs
-  - Runs the same build/load/push/apply flow as `--path`
+  - Interactive terminals prompt for install mode: source build or published version
+  - Published-version installs suggest the latest discovered tag by default and accept custom tags such as `pr-<gitsha>`
+  - Non-interactive runs and `--reload` continue to use the source-build flow
+  - Source-build mode is intended for a local control plane because it depends on the local registry flow
+  - Source builds use local repo cache at `~/.hops/local/repo-cache/<org>/<repo>`
+  - Source builds clone on first use, then fetch/pull on subsequent runs
+  - Source builds run the same build/load/push/apply flow as `--path`
 - `--reload`
   - Forces source-based config install (`--path` or `--repo` without `--version`) to delete existing `ConfigurationRevision` resources and matching `Function`/`FunctionRevision` package resources from the same sources, then re-apply the `Configuration`
   - Useful when re-running a config and you want Crossplane to re-create the current revision from source

src/commands/config/install.rs

@@ -9,7 +9,7 @@ use std::collections::{HashMap, HashSet};
 use std::error::Error;
 use std::fs;
 use std::hash::{Hash, Hasher};
-use std::io::{Cursor, Read, Write};
+use std::io::{self, Cursor, IsTerminal, Read, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
@@ -127,14 +127,26 @@ struct PackageResource {
     spec: Option<PackageSpec>,
 }
 
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum RepoInstallTarget {
+    SourceBuild,
+    PublishedVersion(String),
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum RepoInstallChoice {
+    SourceBuild,
+    PublishedVersion,
+}
+
 pub fn run(args: &ConfigArgs) -> Result<(), Box<dyn Error>> {
     validate_reload_args(args)?;
 
     match (args.repo.as_deref(), args.version.as_deref()) {
         (Some(repo), Some(version)) => {
             apply_repo_version(repo, version, args.skip_dependency_resolution)
         }
-        (Some(repo), None) => run_repo_clone(repo, args.reload, args.skip_dependency_resolution),
+        (Some(repo), None) => run_repo_install(repo, args.reload, args.skip_dependency_resolution),
         (None, _) => run_local_path(
             args.path.as_deref().unwrap_or("."),
             args.reload,
@@ -150,12 +162,25 @@ fn validate_reload_args(args: &ConfigArgs) -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
-fn run_repo_clone(
+fn run_repo_install(
     repo: &str,
     reload: bool,
     skip_dependency_resolution: bool,
 ) -> Result<(), Box<dyn Error>> {
     let spec = parse_repo_spec(repo)?;
+    match resolve_repo_install_target(&spec, reload)? {
+        RepoInstallTarget::SourceBuild => run_repo_clone(&spec, reload, skip_dependency_resolution),
+        RepoInstallTarget::PublishedVersion(version) => {
+            apply_repo_version_spec(&spec, &version, skip_dependency_resolution)
+        }
+    }
+}
+
+fn run_repo_clone(
+    spec: &RepoSpec,
+    reload: bool,
+    skip_dependency_resolution: bool,
+) -> Result<(), Box<dyn Error>> {
     let cache_path = ensure_cached_repo_checkout(&spec)?;
     run_local_path(
         &cache_path.to_string_lossy(),
@@ -164,6 +189,154 @@ fn run_repo_clone(
     )
 }
 
+fn resolve_repo_install_target(
+    spec: &RepoSpec,
+    reload: bool,
+) -> Result<RepoInstallTarget, Box<dyn Error>> {
+    if reload || !interactive_stdio_available() {
+        return Ok(RepoInstallTarget::SourceBuild);
+    }
+
+    match prompt_for_repo_install_choice(spec)? {
+        RepoInstallChoice::SourceBuild => Ok(RepoInstallTarget::SourceBuild),
+        RepoInstallChoice::PublishedVersion => {
+            let suggested = latest_published_version(spec).ok().flatten();
+            let version = prompt_for_published_version(spec, suggested.as_deref())?;
+            Ok(RepoInstallTarget::PublishedVersion(version))
+        }
+    }
+}
+
+fn interactive_stdio_available() -> bool {
+    io::stdin().is_terminal() && io::stdout().is_terminal()
+}
+
+fn prompt_for_repo_install_choice(spec: &RepoSpec) -> Result<RepoInstallChoice, Box<dyn Error>> {
+    let repo_slug = format!("{}/{}", spec.org, spec.repo);
+
+    loop {
+        print!("Install {repo_slug} from source or use a published version? [published/source]: ");
+        io::stdout().flush()?;
+
+        let mut input = String::new();
+        io::stdin().read_line(&mut input)?;
+
+        match parse_repo_install_choice(&input) {
+            Ok(choice) => return Ok(choice),
+            Err(message) => {
+                eprintln!("{message}");
+            }
+        }
+    }
+}
+
+fn prompt_for_published_version(
+    spec: &RepoSpec,
+    default_version: Option<&str>,
+) -> Result<String, Box<dyn Error>> {
+    let repo_slug = format!("{}/{}", spec.org, spec.repo);
+
+    loop {
+        let prompt = match default_version {
+            Some(default) => format!(
+                "Enter published version/tag for {repo_slug} [{default}] (for example `pr-<gitsha>`): "
+            ),
+            None => format!(
+                "Enter published version/tag for {repo_slug} (for example `v0.11.0` or `pr-<gitsha>`): "
+            ),
+        };
+        print!("{prompt}");
+        io::stdout().flush()?;
+
+        let mut input = String::new();
+        io::stdin().read_line(&mut input)?;
+
+        match resolve_published_version_input(&input, default_version) {
+            Some(version) => return Ok(version),
+            None => {
+                eprintln!(
+                    "Published version cannot be empty. Enter a tag like `v0.11.0` or `pr-<gitsha>`."
+                );
+            }
+        }
+    }
+}
+
+fn parse_repo_install_choice(input: &str) -> Result<RepoInstallChoice, String> {
+    match input.trim().to_ascii_lowercase().as_str() {
+        "" | "published" | "publish" | "published version" | "version" | "release" | "p" => {
+            Ok(RepoInstallChoice::PublishedVersion)
+        }
+        "source" | "build" | "clone" | "source build" | "s" => Ok(RepoInstallChoice::SourceBuild),
+        _ => Err("Enter `published` or `source`.".to_string()),
+    }
+}
+
+fn resolve_published_version_input(input: &str, default_version: Option<&str>) -> Option<String> {
+    let trimmed = input.trim();
+    if !trimmed.is_empty() {
+        return Some(trimmed.to_string());
+    }
+
+    default_version
+        .map(str::trim)
+        .filter(|version| !version.is_empty())
+        .map(str::to_string)
+}
+
+fn latest_published_version(spec: &RepoSpec) -> Result<Option<String>, Box<dyn Error>> {
+    let repo_url = format!("https://github.com/{}/{}", spec.org, spec.repo);
+    let output = run_cmd_output(
+        "git",
+        &[
+            "ls-remote",
+            "--sort=-version:refname",
+            "--refs",
+            "--tags",
+            &repo_url,
+        ],
+    )?;
+
+    for line in output.lines() {
+        let Some((_, ref_name)) = line.split_once('\t') else {
+            continue;
+        };
+        let Some(tag) = ref_name.strip_prefix("refs/tags/") else {
+            continue;
+        };
+        let version = tag.trim();
+        if !version.is_empty() {
+            return Ok(Some(version.to_string()));
+        }
+    }
+
+    Ok(None)
+}
+
+fn apply_repo_version_spec(
+    spec: &RepoSpec,
+    version: &str,
+    skip_dependency_resolution: bool,
+) -> Result<(), Box<dyn Error>> {
+    let version = version.trim();
+    if version.is_empty() {
+        return Err("`--version` cannot be empty".into());
+    }
+
+    let package_ref = format!("ghcr.io/{}/{}:{}", spec.org, spec.repo, version);
+    let config_name = format!(
+        "{}-{}",
+        sanitize_name_component(&spec.org),
+        sanitize_name_component(&spec.repo)
+    );
+    apply_configuration(
+        &config_name,
+        &package_ref,
+        skip_dependency_resolution,
+        false,
+    )
+}
+
 fn ensure_cached_repo_checkout(spec: &RepoSpec) -> Result<PathBuf, Box<dyn Error>> {
     let cache_path = repo_cache_path(&spec.org, &spec.repo)?;
     let clone_url = format!("https://github.com/{}/{}", spec.org, spec.repo);
@@ -226,23 +399,7 @@ fn apply_repo_version(
     skip_dependency_resolution: bool,
 ) -> Result<(), Box<dyn Error>> {
     let spec = parse_repo_spec(repo)?;
-    let version = version.trim();
-    if version.is_empty() {
-        return Err("`--version` cannot be empty".into());
-    }
-
-    let package_ref = format!("ghcr.io/{}/{}:{}", spec.org, spec.repo, version);
-    let config_name = format!(
-        "{}-{}",
-        sanitize_name_component(&spec.org),
-        sanitize_name_component(&spec.repo)
-    );
-    apply_configuration(
-        &config_name,
-        &package_ref,
-        skip_dependency_resolution,
-        false,
-    )
+    apply_repo_version_spec(&spec, version, skip_dependency_resolution)
 }
 
 fn parse_repo_spec(repo: &str) -> Result<RepoSpec, Box<dyn Error>> {
@@ -1126,6 +1283,52 @@ spec:
         assert!(parse_repo_spec("hops-ops/helm-certmanager/extra").is_err());
     }
 
+    #[test]
+    fn parse_repo_install_choice_accepts_expected_inputs() {
+        assert_eq!(
+            parse_repo_install_choice("published").unwrap(),
+            RepoInstallChoice::PublishedVersion
+        );
+        assert_eq!(
+            parse_repo_install_choice("release").unwrap(),
+            RepoInstallChoice::PublishedVersion
+        );
+        assert_eq!(
+            parse_repo_install_choice("").unwrap(),
+            RepoInstallChoice::PublishedVersion
+        );
+        assert_eq!(
+            parse_repo_install_choice("source").unwrap(),
+            RepoInstallChoice::SourceBuild
+        );
+        assert_eq!(
+            parse_repo_install_choice("clone").unwrap(),
+            RepoInstallChoice::SourceBuild
+        );
+    }
+
+    #[test]
+    fn parse_repo_install_choice_rejects_unknown_input() {
+        assert!(parse_repo_install_choice("banana").is_err());
+    }
+
+    #[test]
+    fn resolve_published_version_input_prefers_explicit_value() {
+        assert_eq!(
+            resolve_published_version_input("pr-123abc", Some("v0.11.0")).as_deref(),
+            Some("pr-123abc")
+        );
+    }
+
+    #[test]
+    fn resolve_published_version_input_uses_default_for_blank_input() {
+        assert_eq!(
+            resolve_published_version_input("   ", Some("v0.11.0")).as_deref(),
+            Some("v0.11.0")
+        );
+        assert_eq!(resolve_published_version_input("", None), None);
+    }
+
     #[test]
     fn sanitize_name_component_normalizes_for_k8s_names() {
         assert_eq!(sanitize_name_component("Hops_Ops"), "hops-ops");