feat(desktop): add --port and --hostname CLI arguments for sidecar configuration

packages/desktop/src-tauri/src/lib.rs

@@ -65,6 +65,22 @@ struct ServerState {
     child: Arc<Mutex<Option<CommandChild>>>,
 }
 
+pub struct CliOptions {
+    pub port: Option<u32>,
+    pub hostname: Option<String>,
+    pub warnings: Vec<String>,
+}
+
+impl Default for CliOptions {
+    fn default() -> Self {
+        Self {
+            port: None,
+            hostname: None,
+            warnings: Vec::new(),
+        }
+    }
+}
+
 /// Resolves with sidecar credentials as soon as the sidecar is spawned (before health check).
 struct SidecarReady(futures::future::Shared<oneshot::Receiver<ServerReadyData>>);
 
@@ -300,6 +316,10 @@ fn wsl_path(path: String, mode: Option<WslPathMode>) -> Result<String, String> {
 
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
+    run_with_options(CliOptions::default())
+}
+
+pub fn run_with_options(options: CliOptions) {
     let builder = make_specta_builder();
 
     #[cfg(debug_assertions)] // <- Only export on non-release builds
@@ -311,7 +331,16 @@ pub fn run() {
         .output();
 
     let mut builder = tauri::Builder::default()
-        .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| {
+        .plugin(tauri_plugin_single_instance::init(|app, args, _cwd| {
+            let has_cli_overrides = args
+                .iter()
+                .any(|a| a.starts_with("--port") || a.starts_with("--hostname"));
+            if has_cli_overrides {
+                tracing::info!(
+                    "Secondary instance launched with --port/--hostname overrides; \
+                     these are ignored since the primary instance is already running"
+                );
+            }
             // Focus existing window when another instance is launched
             if let Some(window) = app.get_webview_window(MainWindow::LABEL) {
                 let _ = window.set_focus();
@@ -349,7 +378,7 @@ pub fn run() {
             handle.manage(logging::init(&log_dir));
 
             builder.mount_events(&handle);
-            tauri::async_runtime::spawn(initialize(handle));
+            tauri::async_runtime::spawn(initialize(handle, options));
 
             Ok(())
         });
@@ -415,17 +444,21 @@ fn test_export_types() {
 #[derive(tauri_specta::Event, serde::Deserialize, specta::Type)]
 struct LoadingWindowComplete;
 
-async fn initialize(app: AppHandle) {
+async fn initialize(app: AppHandle, options: CliOptions) {
     tracing::info!("Initializing app");
 
+    for warning in &options.warnings {
+        tracing::warn!("{warning}");
+    }
+
     let (init_tx, init_rx) = watch::channel(InitStep::ServerWaiting);
 
     setup_app(&app, init_rx);
     spawn_cli_sync_task(app.clone());
 
     // Spawn sidecar immediately - credentials are known before health check
-    let port = get_sidecar_port();
-    let hostname = "127.0.0.1";
+    let port = options.port.unwrap_or_else(get_sidecar_port);
+    let hostname = options.hostname.as_deref().unwrap_or("127.0.0.1");
     let url = format!("http://{hostname}:{port}");
     let password = uuid::Uuid::new_v4().to_string();
 

packages/desktop/src-tauri/src/main.rs

@@ -39,6 +39,59 @@ fn configure_display_backend() -> Option<String> {
     Some(decision.note)
 }
 
+fn parse_cli_args_from(args: &[String]) -> opencode_lib::CliOptions {
+    let mut options = opencode_lib::CliOptions::default();
+    let mut i = 1;
+    while i < args.len() {
+        if args[i] == "--port" {
+            if let Some(v) = args.get(i + 1) {
+                if let Ok(p) = v.parse::<u32>() {
+                    if p > 0 && p <= 65535 {
+                        options.port = Some(p);
+                        i += 2;
+                        continue;
+                    }
+                }
+            }
+            options
+                .warnings
+                .push("invalid --port value, using random port".to_string());
+            i += 1;
+        } else if let Some(v) = args[i].strip_prefix("--port=") {
+            if let Ok(p) = v.parse::<u32>() {
+                if p > 0 && p <= 65535 {
+                    options.port = Some(p);
+                } else {
+                    options
+                        .warnings
+                        .push(format!("invalid --port value '{v}', using random port"));
+                }
+            } else {
+                options
+                    .warnings
+                    .push(format!("invalid --port value '{v}', using random port"));
+            }
+            i += 1;
+        } else if args[i] == "--hostname" {
+            if let Some(v) = args.get(i + 1) {
+                options.hostname = Some(v.clone());
+                i += 2;
+            } else {
+                options
+                    .warnings
+                    .push("--hostname requires a value".to_string());
+                i += 1;
+            }
+        } else if let Some(v) = args[i].strip_prefix("--hostname=") {
+            options.hostname = Some(v.to_string());
+            i += 1;
+        } else {
+            i += 1;
+        }
+    }
+    options
+}
+
 fn main() {
     // Ensure loopback connections are never sent through proxy settings.
     // Some VPNs/proxies set HTTP_PROXY/HTTPS_PROXY/ALL_PROXY without excluding localhost.
@@ -74,5 +127,132 @@ fn main() {
         }
     }
 
-    opencode_lib::run()
+    let options = parse_cli_args_from(&std::env::args().collect::<Vec<_>>());
+    opencode_lib::run_with_options(options)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(args: &[&str]) -> Vec<String> {
+        args.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn port_flag_space_separated() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port", "4096"]));
+        assert_eq!(opts.port, Some(4096));
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn port_flag_equals_syntax() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port=8080"]));
+        assert_eq!(opts.port, Some(8080));
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn port_flag_not_specified() {
+        let opts = parse_cli_args_from(&args(&["opencode"]));
+        assert_eq!(opts.port, None);
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn port_flag_zero_rejected() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port", "0"]));
+        assert_eq!(opts.port, None);
+        assert_eq!(opts.warnings.len(), 1);
+        assert!(opts.warnings[0].contains("--port"));
+    }
+
+    #[test]
+    fn port_flag_out_of_range() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port=70000"]));
+        assert_eq!(opts.port, None);
+        assert_eq!(opts.warnings.len(), 1);
+    }
+
+    #[test]
+    fn port_flag_non_numeric() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port", "abc"]));
+        assert_eq!(opts.port, None);
+        assert_eq!(opts.warnings.len(), 1);
+    }
+
+    #[test]
+    fn port_flag_missing_value() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port"]));
+        assert_eq!(opts.port, None);
+        assert_eq!(opts.warnings.len(), 1);
+    }
+
+    #[test]
+    fn port_flag_boundary_values() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port", "1"]));
+        assert_eq!(opts.port, Some(1));
+        let opts = parse_cli_args_from(&args(&["opencode", "--port=65535"]));
+        assert_eq!(opts.port, Some(65535));
+    }
+
+    #[test]
+    fn hostname_flag_space_separated() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--hostname", "0.0.0.0"]));
+        assert_eq!(opts.hostname.as_deref(), Some("0.0.0.0"));
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn hostname_flag_equals_syntax() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--hostname=192.168.1.1"]));
+        assert_eq!(opts.hostname.as_deref(), Some("192.168.1.1"));
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn hostname_flag_missing_value() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--hostname"]));
+        assert_eq!(opts.hostname, None);
+        assert_eq!(opts.warnings.len(), 1);
+        assert!(opts.warnings[0].contains("--hostname"));
+    }
+
+    #[test]
+    fn both_port_and_hostname() {
+        let opts = parse_cli_args_from(&args(&[
+            "opencode", "--port", "4096", "--hostname", "0.0.0.0",
+        ]));
+        assert_eq!(opts.port, Some(4096));
+        assert_eq!(opts.hostname.as_deref(), Some("0.0.0.0"));
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn unknown_flags_ignored() {
+        let opts = parse_cli_args_from(&args(&[
+            "opencode", "--unknown", "value", "--port", "3000",
+        ]));
+        assert_eq!(opts.port, Some(3000));
+        assert!(opts.warnings.is_empty());
+    }
+
+    #[test]
+    fn invalid_port_with_valid_hostname() {
+        let opts = parse_cli_args_from(&args(&[
+            "opencode", "--port", "abc", "--hostname", "0.0.0.0",
+        ]));
+        assert_eq!(opts.port, None);
+        assert_eq!(opts.hostname.as_deref(), Some("0.0.0.0"));
+        assert_eq!(opts.warnings.len(), 1);
+    }
+
+    #[test]
+    fn port_equals_invalid_numeric() {
+        let opts = parse_cli_args_from(&args(&["opencode", "--port=99999"]));
+        assert_eq!(opts.port, None);
+        assert_eq!(opts.warnings.len(), 1);
+        assert!(opts.warnings[0].contains("99999"));
+    }
 }