Add --karate-version flag and fix project config filename

- Add --karate-version flag to `karate setup` for explicit JAR version
  selection without writing karate-cli.json (used by VS Code extension)
- Fix project config filename from karate.json to karate-cli.json
  (consistent naming at both global and project levels)
- Smart JAR check: when --karate-version is specified, only skip download
  if that exact version exists (not just any JAR)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ptrthomas

docs/spec.md

@@ -191,7 +191,7 @@ karate --cp /path/to/a.jar --cp /path/to/b.jar run features/
 ### **F. Config Management**
 
 * Global: `~/.karate/karate-cli.json`
-* Project: `./.karate/karate.json`
+* Project: `./.karate/karate-cli.json`
 * CLI precedence: command flag → project config → global config → defaults
 
 * `karate config`:
@@ -282,7 +282,7 @@ Runtime Commands (JAR-delegated):
 ### **setup**
 
 ```
-karate setup [--all] [--item <name>] [--force] [--java-version <ver>]
+karate setup [--all] [--item <name>] [--force] [--karate-version <ver>] [--java-version <ver>]
 ```
 
 Interactive first-run wizard. Downloads JRE and Karate JAR, offers PATH setup.
@@ -291,15 +291,17 @@ Interactive first-run wizard. Downloads JRE and Karate JAR, offers PATH setup.
 * `--all` — Install all components (JAR + JRE) non-interactively
 * `--item <name>` — Install specific item: jar, jre
 * `--force` — Force download even if components already installed
+* `--karate-version <ver>` — Specific Karate JAR version to install (e.g., 1.5.2, 2.0.0)
 * `--java-version <ver>` — Specific Java major version (default: 21)
 
 **Examples:**
 ```
-karate setup                    # Interactive wizard
-karate setup --all              # Install everything non-interactively
-karate setup --item jar         # JAR only (use system JRE)
-karate setup --item jre         # JRE only
-karate setup --item jar --force # Force re-download JAR
+karate setup                                        # Interactive wizard
+karate setup --all                                  # Install everything non-interactively
+karate setup --item jar                             # JAR only (use system JRE)
+karate setup --item jre                             # JRE only
+karate setup --item jar --force                     # Force re-download JAR
+karate setup --item jar --karate-version 2.0.0      # Install specific Karate version
 ```
 
 ---
@@ -328,7 +330,7 @@ Manage configuration files.
 
 **Flags:**
 * `--global` — Edit `~/.karate/karate-cli.json`
-* `--local` — Edit `./.karate/karate.json` (creates if needed)
+* `--local` — Edit `./.karate/karate-cli.json` (creates if needed)
 * `--show` — Print resolved (merged) config as JSON
 
 ---
@@ -461,16 +463,16 @@ This allows:
 ```
 my-project/
 └── .karate/
-    └── karate.json               # Project-specific config overrides
+    └── karate-cli.json            # Project-specific config overrides
 ```
 
-Note: A `.karate` folder with only `karate.json` is treated as config-only, not a karate home.
+Note: A `.karate` folder with only `karate-cli.json` is treated as config-only, not a karate home.
 
 ---
 
 ## **7.4 Configuration Schema**
 
-### **karate-cli.json (Global) / karate.json (Project)**
+### **karate-cli.json (Global and Project)**
 
 ```json
 {

src/cli.rs

@@ -71,6 +71,10 @@ pub struct SetupArgs {
     #[arg(long = "java-version")]
     pub java_version: Option<String>,
 
+    /// Karate JAR version to install (e.g., 1.5.2, 2.0.0)
+    #[arg(long = "karate-version")]
+    pub karate_version: Option<String>,
+
     /// Release channel: stable or beta (overrides config)
     #[arg(long)]
     pub channel: Option<String>,

src/commands/setup.rs

@@ -40,14 +40,15 @@ pub async fn run(args: SetupArgs) -> Result<ExitCode> {
     };
 
     // Non-interactive install of specified items
-    run_setup_items(&items, args.force, args.java_version, args.channel).await
+    run_setup_items(&items, args.force, args.java_version, args.karate_version, args.channel).await
 }
 
 /// Non-interactive setup of specified items.
 async fn run_setup_items(
     items: &HashSet<String>,
     force: bool,
     java_version: Option<String>,
+    version_override: Option<String>,
     channel_override: Option<String>,
 ) -> Result<ExitCode> {
     let platform = Platform::detect()?;
@@ -129,14 +130,27 @@ async fn run_setup_items(
             style(format!("[{}/{}]", step, total_steps)).bold().dim()
         );
 
-        let existing_jar = find_karate_jar(&paths.dist);
-        if existing_jar.is_some() && !force {
-            println!("  {} Karate JAR already installed", style("✓").green());
+        // If a specific version is requested, check for that version; otherwise check for any JAR
+        let should_download = if let Some(ref ver) = version_override {
+            let target_jar = paths.dist.join(format!("karate-{}.jar", ver));
+            if target_jar.exists() && !force {
+                println!("  {} Karate {} already installed", style("✓").green(), ver);
+                false
+            } else {
+                true
+            }
         } else {
-            if force && existing_jar.is_some() {
-                println!("  {} Force mode: re-downloading JAR", style("!").yellow());
+            let existing_jar = find_karate_jar(&paths.dist);
+            if existing_jar.is_some() && !force {
+                println!("  {} Karate JAR already installed", style("✓").green());
+                false
+            } else {
+                if force { println!("  {} Force mode: re-downloading JAR", style("!").yellow()); }
+                true
             }
-            download_karate_jar(&paths, channel_override.as_deref()).await?;
+        };
+        if should_download {
+            download_karate_jar(&paths, version_override.as_deref(), channel_override.as_deref()).await?;
         }
         println!();
     }
@@ -208,7 +222,7 @@ async fn run_setup_wizard() -> Result<ExitCode> {
     if existing_jar.is_some() {
         println!("  {} Karate JAR already installed", style("✓").green());
     } else {
-        download_karate_jar(&paths, None).await?;
+        download_karate_jar(&paths, None, None).await?;
     }
 
     println!();
@@ -257,7 +271,7 @@ async fn download_jre(platform: &Platform, paths: &KaratePaths, java_version: u8
 }
 
 /// Download Karate JAR using manifest from karate.sh
-async fn download_karate_jar(paths: &KaratePaths, channel_override: Option<&str>) -> Result<()> {
+async fn download_karate_jar(paths: &KaratePaths, version_override: Option<&str>, channel_override: Option<&str>) -> Result<()> {
     // Load config to get channel and version preferences
     let config = load_merged_config()?;
     let channel = channel_override.unwrap_or(&config.channel);
@@ -273,9 +287,12 @@ async fn download_karate_jar(paths: &KaratePaths, channel_override: Option<&str>
         )
     })?;
 
-    // Determine version: use config if pinned, otherwise get latest from channel
-    let version = if config.karate_version != "latest" {
-        // User pinned a specific version
+    // Determine version: CLI flag → config pin → latest from channel
+    let version = if let Some(v) = version_override {
+        println!("  Requested version: {}", style(v).cyan());
+        v.to_string()
+    } else if config.karate_version != "latest" {
+        // User pinned a specific version in config
         println!(
             "  Using pinned version: {}",
             style(&config.karate_version).cyan()

src/platform.rs

@@ -208,12 +208,12 @@ impl KaratePaths {
         global.join(subdir)
     }
 
-    /// Get the project-local config path (.karate/karate.json in cwd).
+    /// Get the project-local config path (.karate/karate-cli.json in cwd).
     pub fn local_config() -> PathBuf {
         std::env::current_dir()
             .expect("Could not determine current directory")
             .join(".karate")
-            .join("karate.json")
+            .join("karate-cli.json")
     }
 
     /// Ensure all directories exist (creates in resolved locations).