feat(ampup): add token resolution, rate limiter, and --jobs CLI flag

ampup/src/commands/init.rs

@@ -98,6 +98,7 @@ pub async fn run(
             None,
             None,
             None,
+            None,
         )
         .await?;
     } else {

ampup/src/commands/install.rs

@@ -5,7 +5,7 @@ use crate::{
     github::GitHubClient,
     install::Installer,
     platform::{Architecture, Platform},
-    ui,
+    token, ui,
     version_manager::VersionManager,
 };
 
@@ -16,9 +16,16 @@ pub async fn run(
     version: Option<String>,
     arch_override: Option<String>,
     platform_override: Option<String>,
+    jobs: Option<usize>,
 ) -> Result<()> {
     let config = Config::new(install_dir)?;
-    let github = GitHubClient::new(repo, github_token)?;
+    // Will be passed to DownloadManager for bounded-concurrent downloads
+    let _max_concurrent = jobs.unwrap_or(4);
+
+    // Resolve token with fallback chain: explicit → gh auth token → unauthenticated
+    let resolved_token = token::resolve_github_token(github_token);
+
+    let github = GitHubClient::new(repo, resolved_token)?;
     let version_manager = VersionManager::new(config);
 
     // Determine version to install

ampup/src/github.rs

@@ -1,8 +1,12 @@
+use std::sync::Arc;
+
 use anyhow::{Context, Result};
 use futures::StreamExt;
 use indicatif::{ProgressBar, ProgressStyle};
 use serde::Deserialize;
 
+use crate::rate_limiter::GitHubRateLimiter;
+
 const AMPUP_API_URL: &str = "https://ampup.sh/api";
 const GITHUB_API_URL: &str = "https://api.github.com";
 
@@ -37,6 +41,10 @@ pub enum GitHubError {
         url: String,
         body: String,
     },
+    RateLimited {
+        retry_after_secs: u64,
+        has_token: bool,
+    },
 }
 
 impl std::fmt::Display for GitHubError {
@@ -144,6 +152,18 @@ impl std::fmt::Display for GitHubError {
                     writeln!(f, "  Response: {}", body)?;
                 }
             }
+            Self::RateLimited {
+                retry_after_secs,
+                has_token,
+            } => {
+                writeln!(f, "GitHub API rate limit exceeded")?;
+                writeln!(f, "  Retry after: {} seconds", retry_after_secs)?;
+                writeln!(f)?;
+                if !*has_token {
+                    writeln!(f, "  Unauthenticated requests have lower rate limits.")?;
+                    writeln!(f, "  Try: export GITHUB_TOKEN=$(gh auth token)")?;
+                }
+            }
         }
         Ok(())
     }
@@ -166,12 +186,16 @@ struct Asset {
     url: String,
 }
 
+/// Clone is cheap: `reqwest::Client` and `rate_limiter` are both `Arc`-backed.
+/// Needed so `DownloadManager` can move a handle into each spawned download task.
+#[derive(Clone)]
 pub struct GitHubClient {
     client: reqwest::Client,
     repo: String,
     token: Option<String>,
     /// Base URL for API requests (either custom API or GitHub API)
     api: String,
+    rate_limiter: Arc<GitHubRateLimiter>,
 }
 
 impl GitHubClient {
@@ -203,11 +227,14 @@ impl GitHubClient {
             format!("{}/repos/{}/releases", GITHUB_API_URL, repo)
         };
 
+        let rate_limiter = Arc::new(GitHubRateLimiter::new(github_token.is_some()));
+
         Ok(Self {
             client,
             repo,
             token: github_token,
             api,
+            rate_limiter,
         })
     }
 
@@ -227,16 +254,71 @@ impl GitHubClient {
         self.get_release(&format!("tags/{}", version)).await
     }
 
+    /// Wait for any active rate-limit pause, or fail if the wait is too long.
+    async fn check_rate_limit_pause(&self) -> Result<()> {
+        if let Err(duration) = self.rate_limiter.wait_if_paused().await {
+            return Err(GitHubError::RateLimited {
+                retry_after_secs: duration.as_secs(),
+                has_token: self.token.is_some(),
+            }
+            .into());
+        }
+        Ok(())
+    }
+
+    /// Send a request with rate-limit awareness and one retry on 429.
+    async fn send_with_rate_limit(
+        &self,
+        build_request: impl Fn() -> reqwest::RequestBuilder,
+        context_msg: &str,
+    ) -> Result<reqwest::Response> {
+        self.check_rate_limit_pause().await?;
+
+        let response = build_request()
+            .send()
+            .await
+            .with_context(|| context_msg.to_string())?;
+
+        if let Some(retry_after) = self.rate_limiter.update_from_response(&response).await {
+            crate::ui::warn!(
+                "Rate limited by GitHub API, retrying in {} seconds...",
+                retry_after
+            );
+            self.check_rate_limit_pause().await?;
+
+            let response = build_request()
+                .send()
+                .await
+                .with_context(|| context_msg.to_string())?;
+
+            if let Some(retry_after) = self.rate_limiter.update_from_response(&response).await {
+                return Err(GitHubError::RateLimited {
+                    retry_after_secs: retry_after,
+                    has_token: self.token.is_some(),
+                }
+                .into());
+            }
+
+            return Ok(response);
+        }
+
+        // Warn if rate limit is exhausted (preemptive pause applies to next request)
+        if self.rate_limiter.remaining().await == Some(0) {
+            crate::ui::warn!(
+                "GitHub API rate limit exhausted, subsequent requests will be paused until reset"
+            );
+        }
+
+        Ok(response)
+    }
+
     /// Fetch release from GitHub API
     async fn get_release(&self, path: &str) -> Result<Release> {
         let url = format!("{}/{}", self.api, path);
 
         let response = self
-            .client
-            .get(&url)
-            .send()
-            .await
-            .context("Failed to fetch release")?;
+            .send_with_rate_limit(|| self.client.get(&url), "Failed to fetch release")
+            .await?;
 
         if !response.status().is_success() {
             let status = response.status();
@@ -312,12 +394,15 @@ impl GitHubClient {
         );
 
         let response = self
-            .client
-            .get(&url)
-            .header(reqwest::header::ACCEPT, "application/octet-stream")
-            .send()
-            .await
-            .context("Failed to download asset")?;
+            .send_with_rate_limit(
+                || {
+                    self.client
+                        .get(&url)
+                        .header(reqwest::header::ACCEPT, "application/octet-stream")
+                },
+                "Failed to download asset",
+            )
+            .await?;
 
         self.download_with_progress(response, &url, asset_name)
             .await
@@ -326,11 +411,8 @@ impl GitHubClient {
     /// Download asset directly (for public repos)
     async fn download_asset_direct(&self, url: &str, asset_name: &str) -> Result<Vec<u8>> {
         let response = self
-            .client
-            .get(url)
-            .send()
-            .await
-            .context("Failed to download asset")?;
+            .send_with_rate_limit(|| self.client.get(url), "Failed to download asset")
+            .await?;
 
         self.download_with_progress(response, url, asset_name).await
     }

ampup/src/lib.rs

@@ -4,7 +4,9 @@ pub mod config;
 pub mod github;
 pub mod install;
 pub mod platform;
+pub mod rate_limiter;
 pub mod shell;
+pub mod token;
 pub mod updater;
 pub mod version_manager;
 

ampup/src/main.rs

@@ -57,6 +57,10 @@ enum Commands {
         /// Override platform detection (linux, darwin)
         #[arg(long)]
         platform: Option<String>,
+
+        /// Number of concurrent downloads (default: 4)
+        #[arg(short = 'j', long = "jobs")]
+        jobs: Option<usize>,
     },
 
     /// List installed versions
@@ -142,6 +146,10 @@ enum Commands {
         /// Override platform detection (linux, darwin)
         #[arg(long)]
         platform: Option<String>,
+
+        /// Number of concurrent downloads (default: 4)
+        #[arg(short = 'j', long = "jobs")]
+        jobs: Option<usize>,
     },
 
     /// Manage the ampup executable
@@ -198,9 +206,18 @@ async fn run() -> anyhow::Result<()> {
             github_token,
             arch,
             platform,
+            jobs,
         }) => {
-            commands::install::run(install_dir, repo, github_token, version, arch, platform)
-                .await?;
+            commands::install::run(
+                install_dir,
+                repo,
+                github_token,
+                version,
+                arch,
+                platform,
+                jobs,
+            )
+            .await?;
         }
         Some(Commands::List { install_dir }) => {
             commands::list::run(install_dir)?;
@@ -235,9 +252,11 @@ async fn run() -> anyhow::Result<()> {
             github_token,
             arch,
             platform,
+            jobs,
         }) => {
             // Install latest version (same as default behavior)
-            commands::install::run(install_dir, repo, github_token, None, arch, platform).await?;
+            commands::install::run(install_dir, repo, github_token, None, arch, platform, jobs)
+                .await?;
         }
         Some(Commands::SelfCmd { command }) => match command {
             SelfCommands::Update { repo, github_token } => {
@@ -256,6 +275,7 @@ async fn run() -> anyhow::Result<()> {
                 None,
                 None,
                 None,
+                None,
             )
             .await?;
         }