use std::io::{BufRead, Write};
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::time::Duration;
use anyhow::Context;
use clap::{Args, ValueEnum};
use serde::{Deserialize, Serialize};
use crate::cli::admin::{
ADMIN_SERVE_START_DEADLINE, FOREGROUND_SERVE_NOTICE, ServerSessionDescriptor,
operator_server_reachable, start_operator_server,
};
use crate::cli::browser::{BrowserOpener, OsBrowserOpener};
use crate::cli::harness::{AttachEntry, HarnessId, HarnessRegistry, HarnessState};
use crate::cli::harness_apply::{self, ApplyOutcome, PlannedAction};
use crate::cli::operator_profile::{AuthPosture, OperatorSetupProfile};
use crate::server::serve::DEFAULT_LISTEN;
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum, Serialize, Deserialize)]
pub enum InstallationType {
#[value(name = "in-harness")]
#[serde(rename = "in-harness")]
InHarness,
#[serde(rename = "server")]
Server,
#[serde(rename = "both")]
Both,
}
#[derive(Args, Debug, Clone)]
pub struct SetupCliArgs {
#[arg(long)]
pub non_interactive: bool,
#[arg(long, value_enum)]
pub installation_type: Option<InstallationType>,
#[arg(long)]
pub port: Option<u16>,
#[arg(long, value_delimiter = ',')]
pub harnesses: Vec<String>,
#[arg(long)]
pub yes: bool,
}
pub trait SetupSink {
fn status(&mut self, line: &str);
fn ask_choice(&mut self, q: &str, opts: &[&str]) -> usize;
fn confirm(&mut self, action_plan: &str) -> bool;
}
pub struct StderrSetupSink;
impl SetupSink for StderrSetupSink {
fn status(&mut self, line: &str) {
eprintln!("{line}");
}
fn ask_choice(&mut self, q: &str, opts: &[&str]) -> usize {
eprintln!("{q}");
for (i, opt) in opts.iter().enumerate() {
eprintln!(" {}) {opt}", i + 1);
}
eprint!("> ");
let _ = std::io::stderr().flush();
let line = read_stdin_line();
match line.trim().parse::<usize>() {
Ok(n) if (1..=opts.len()).contains(&n) => n - 1,
_ => 0,
}
}
fn confirm(&mut self, action_plan: &str) -> bool {
eprintln!("{action_plan}");
eprint!("Proceed? [y/N] ");
let _ = std::io::stderr().flush();
let line = read_stdin_line();
matches!(line.trim().to_ascii_lowercase().as_str(), "y" | "yes")
}
}
fn read_stdin_line() -> String {
let mut line = String::new();
let stdin = std::io::stdin();
let _ = stdin.lock().read_line(&mut line);
line
}
#[derive(Debug, Default)]
pub struct ScriptedSetupSink {
choices: std::collections::VecDeque<usize>,
confirm_answer: bool,
pub statuses: Vec<String>,
pub questions: Vec<String>,
pub confirmations: Vec<String>,
}
impl ScriptedSetupSink {
pub fn new(choices: impl IntoIterator<Item = usize>, confirm_answer: bool) -> Self {
Self {
choices: choices.into_iter().collect(),
confirm_answer,
statuses: Vec::new(),
questions: Vec::new(),
confirmations: Vec::new(),
}
}
}
impl SetupSink for ScriptedSetupSink {
fn status(&mut self, line: &str) {
self.statuses.push(line.to_string());
}
fn ask_choice(&mut self, q: &str, opts: &[&str]) -> usize {
self.questions.push(format!("{q} [{}]", opts.join(", ")));
self.choices.pop_front().unwrap_or(0)
}
fn confirm(&mut self, action_plan: &str) -> bool {
self.confirmations.push(action_plan.to_string());
self.confirm_answer
}
}
#[derive(Debug, Clone)]
pub struct SetupContext {
pub home: std::path::PathBuf,
pub working_dir: std::path::PathBuf,
}
impl SetupContext {
pub fn from_env() -> anyhow::Result<Self> {
let home = dirs::home_dir().context("cannot determine home directory")?;
let working_dir =
std::env::current_dir().context("cannot determine current working directory")?;
Ok(Self { home, working_dir })
}
pub fn project_base(&self) -> std::path::PathBuf {
self.working_dir.clone()
}
pub fn registry(&self) -> HarnessRegistry {
HarnessRegistry::known_with(&self.home, &self.working_dir)
}
}
#[derive(Debug)]
pub struct WizardOutcome {
pub installation_type: InstallationType,
pub session: Option<ServerSessionDescriptor>,
pub reused_server: bool,
pub harness_outcomes: Vec<ApplyOutcome>,
pub browser_outcome: Option<crate::cli::browser::BrowserOpenOutcome>,
pub profile: OperatorSetupProfile,
pub cancelled: bool,
}
pub fn run(args: SetupCliArgs) -> anyhow::Result<()> {
let ctx = SetupContext::from_env()?;
if args.non_interactive {
let mut sink = ScriptedSetupSink::new([], args.yes);
let browser = crate::cli::browser::NoopBrowserOpener::default();
run_wizard(args, &ctx, &mut sink, &browser)?;
} else {
let mut sink = StderrSetupSink;
let browser = OsBrowserOpener;
let outcome = run_wizard(args, &ctx, &mut sink, &browser)?;
serve_foreground_if_wizard_started(&outcome, block_until_ctrl_c)?;
}
Ok(())
}
fn serve_foreground_if_wizard_started(
outcome: &WizardOutcome,
wait_for_shutdown: impl FnOnce(&ServerSessionDescriptor) -> anyhow::Result<()>,
) -> anyhow::Result<()> {
if outcome.reused_server {
return Ok(());
}
let Some(session) = outcome.session.as_ref() else {
return Ok(());
};
eprintln!("{FOREGROUND_SERVE_NOTICE}");
wait_for_shutdown(session)
}
fn block_until_ctrl_c(_session: &ServerSessionDescriptor) -> anyhow::Result<()> {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()?;
runtime.block_on(tokio::signal::ctrl_c())?;
Ok(())
}
pub fn run_wizard<S: SetupSink + ?Sized, B: BrowserOpener + ?Sized>(
args: SetupCliArgs,
ctx: &SetupContext,
sink: &mut S,
browser: &B,
) -> anyhow::Result<WizardOutcome> {
let registry = ctx.registry();
let project_base = ctx.project_base();
let existing_profile = OperatorSetupProfile::load(&project_base);
let suggested_port = suggest_free_port(args.port)?;
sink.status(&format!(
"SymForge setup — OS: {} — suggested port: {suggested_port}",
std::env::consts::OS
));
for status in scan_harness_summary(®istry, None) {
sink.status(&status);
}
let remembered = existing_profile.as_ref().map(|p| p.port);
let mut remembered_reachable: Option<SocketAddr> = None;
if let Some(port) = remembered {
let addr = loopback_addr(port);
if operator_server_reachable(addr, Duration::from_millis(500)) {
remembered_reachable = Some(addr);
sink.status(&format!(
"Operator server already reachable on {addr} (profile port {port}) — will reuse"
));
}
}
let installation_type = resolve_installation_type(&args, sink)?;
let selected_ids = resolve_harness_ids(&args, ®istry);
let bind_port = args.port.unwrap_or(suggested_port);
let bind_addr = loopback_addr(bind_port);
let needs_server = matches!(
installation_type,
InstallationType::Server | InstallationType::Both
);
let needs_harness_http = installation_type == InstallationType::Both;
let action_plan = build_action_plan(
installation_type,
&selected_ids,
bind_addr,
needs_server,
needs_harness_http,
);
if !args.yes && !sink.confirm(&action_plan) {
sink.status("Setup cancelled — no changes made.");
let profile = OperatorSetupProfile::new(
installation_type,
bind_port,
AuthPosture::LoopbackNoKey,
&selected_ids,
now_epoch_ms(),
);
return Ok(WizardOutcome {
installation_type,
session: None,
reused_server: false,
harness_outcomes: Vec::new(),
browser_outcome: None,
profile,
cancelled: true,
});
}
if args.yes {
sink.status(&action_plan);
}
if installation_type == InstallationType::InHarness {
sink.status(
"In-harness (stdio) mode: configure local MCP clients with `symforge init` per client.",
);
}
let mut session: Option<ServerSessionDescriptor> = None;
let mut reused_server = false;
if needs_server {
if let Some(addr) = remembered_reachable {
session = Some(ServerSessionDescriptor::for_addr(addr, true));
reused_server = true;
sink.status(&format!("Reusing running operator server on {addr}"));
}
if session.is_none() {
sink.status(&format!("Starting operator server on {bind_addr}…"));
session = Some(start_operator_server(
Some(bind_addr),
None,
None,
ADMIN_SERVE_START_DEADLINE,
)?);
}
let desc = session.as_ref().expect("session started or reused");
sink.status(&format!("Dashboard: {}", desc.dashboard_url));
sink.status(&format!("Attach: {}", desc.attach_url));
}
let mut harness_outcomes = Vec::new();
if needs_harness_http {
let desc = session
.as_ref()
.context("internal error: harness HTTP attach requires a running operator server")?;
let attach_entry = AttachEntry::new(desc.attach_url.clone(), None);
let subset = registry_subset(®istry, &selected_ids);
let plan = harness_apply::plan(&subset, &attach_entry);
sink.status("Applying harness attach entries (restorable backups)…");
for change in &plan.changes {
let label = match &change.action {
PlannedAction::Add => "add",
PlannedAction::Refresh => "refresh",
PlannedAction::Skip(reason) => {
sink.status(&format!(" [skip] {} ({reason})", change.id.display_name()));
continue;
}
PlannedAction::Error(reason) => {
sink.status(&format!(
" [error] {} ({reason})",
change.id.display_name()
));
continue;
}
};
sink.status(&format!(
" [{label}] {} -> {}",
change.id.display_name(),
change.config_path.display()
));
}
harness_outcomes = harness_apply::apply(&plan);
for outcome in &harness_outcomes {
match outcome {
ApplyOutcome::Wrote {
id,
config_path,
backup,
} => {
let backup_note = backup
.as_ref()
.map(|b| format!(" (backup: {})", b.backup.display()))
.unwrap_or_default();
sink.status(&format!(
" [written] {} -> {}{backup_note}",
id.display_name(),
config_path.display()
));
}
ApplyOutcome::Skipped { id, reason } => {
sink.status(&format!(" [skipped] {} ({reason})", id.display_name()));
}
ApplyOutcome::Failed { id, reason } => {
sink.status(&format!(" [failed] {} ({reason})", id.display_name()));
}
}
}
}
let bound_port = session
.as_ref()
.map(|s| s.bound_addr.port())
.unwrap_or(bind_port);
let profile = OperatorSetupProfile::new(
installation_type,
bound_port,
AuthPosture::LoopbackNoKey,
&selected_ids,
now_epoch_ms(),
);
profile
.save(&project_base)
.context("could not persist operator setup profile")?;
let mut browser_outcome = None;
if let Some(desc) = &session {
let outcome = browser.open_url(&desc.dashboard_url);
sink.status(&format!(
"Browser: {outcome:?} — open {}",
desc.dashboard_url
));
browser_outcome = Some(outcome);
}
sink.status("Setup complete.");
Ok(WizardOutcome {
installation_type,
session,
reused_server,
harness_outcomes,
browser_outcome,
profile,
cancelled: false,
})
}
fn now_epoch_ms() -> i64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_millis() as i64
}
fn loopback_addr(port: u16) -> SocketAddr {
SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port)
}
fn suggest_free_port(preferred: Option<u16>) -> anyhow::Result<u16> {
let preferred_addr = preferred
.map(loopback_addr)
.or_else(|| DEFAULT_LISTEN.parse().ok());
let addr = crate::cli::admin::select_free_addr_std(preferred_addr)
.map_err(|e| anyhow::anyhow!("could not find a free operator-server port: {e}"))?;
Ok(addr.port())
}
fn scan_harness_summary(registry: &HarnessRegistry, attach: Option<&AttachEntry>) -> Vec<String> {
let entry = attach
.cloned()
.unwrap_or_else(|| AttachEntry::new("", None));
registry
.scan(&entry)
.into_iter()
.map(|s| {
format!(
" {} — {} ({})",
s.id.display_name(),
format_harness_state(&s.state),
s.config_path.display()
)
})
.collect()
}
fn format_harness_state(state: &HarnessState) -> &'static str {
match state {
HarnessState::NotInstalled => "not installed",
HarnessState::Absent => "not configured",
HarnessState::PresentCurrent => "configured (current)",
HarnessState::PresentStale => "configured (stale)",
HarnessState::Malformed(_) => "unreadable",
}
}
fn resolve_installation_type<S: SetupSink + ?Sized>(
args: &SetupCliArgs,
sink: &mut S,
) -> anyhow::Result<InstallationType> {
if let Some(t) = args.installation_type {
return Ok(t);
}
if args.non_interactive {
return Ok(InstallationType::Both);
}
let idx = sink.ask_choice(
"Installation type?",
&[
"in-harness only (stdio via symforge init)",
"operator server + dashboard",
"both (server + harness HTTP attach)",
],
);
Ok(match idx {
0 => InstallationType::InHarness,
1 => InstallationType::Server,
_ => InstallationType::Both,
})
}
fn resolve_harness_ids(args: &SetupCliArgs, registry: &HarnessRegistry) -> Vec<HarnessId> {
if !args.harnesses.is_empty() {
return args
.harnesses
.iter()
.filter_map(|slug| harness_id_from_slug(slug))
.collect();
}
let entry = AttachEntry::new("", None);
registry
.scan(&entry)
.into_iter()
.filter(|s| !matches!(s.state, HarnessState::NotInstalled))
.map(|s| s.id)
.collect()
}
fn harness_id_from_slug(slug: &str) -> Option<HarnessId> {
let slug = slug.trim().to_ascii_lowercase();
[
HarnessId::ClaudeCode,
HarnessId::ClaudeDesktop,
HarnessId::Codex,
HarnessId::Gemini,
HarnessId::KiloCode,
HarnessId::Cursor,
]
.into_iter()
.find(|id| id.slug() == slug)
}
fn registry_subset(registry: &HarnessRegistry, ids: &[HarnessId]) -> HarnessRegistry {
let targets = registry
.targets()
.iter()
.filter(|t| ids.contains(&t.id))
.cloned()
.collect();
HarnessRegistry::from_targets(targets)
}
fn build_action_plan(
installation_type: InstallationType,
harnesses: &[HarnessId],
bind_addr: SocketAddr,
needs_server: bool,
needs_harness_http: bool,
) -> String {
let mut lines = vec![format!(
"Planned actions ({}):",
installation_type_label(installation_type)
)];
if needs_server {
lines.push(format!(" • start operator server on {bind_addr}"));
}
if needs_harness_http {
for id in harnesses {
lines.push(format!(
" • configure {} HTTP attach (backup + write)",
id.display_name()
));
}
}
if installation_type == InstallationType::InHarness {
lines.push(" • no server; use `symforge init` for stdio MCP clients".to_string());
}
lines.join("\n")
}
fn installation_type_label(t: InstallationType) -> &'static str {
match t {
InstallationType::InHarness => "in-harness",
InstallationType::Server => "server",
InstallationType::Both => "both",
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn scripted_sink_returns_scripted_answers_and_records_prompts() {
let mut sink = ScriptedSetupSink::new([1, 0], true);
sink.status("scanning harnesses");
let first = sink.ask_choice("install type?", &["in-harness", "server", "both"]);
let second = sink.ask_choice("which harness?", &["claude", "codex"]);
let proceed = sink.confirm("will configure: claude");
assert_eq!(first, 1, "first ask_choice pops the first scripted answer");
assert_eq!(second, 0, "second ask_choice pops the next scripted answer");
assert!(proceed, "confirm returns the scripted bool");
assert_eq!(sink.statuses, vec!["scanning harnesses"]);
assert_eq!(sink.questions.len(), 2);
assert!(sink.questions[0].contains("install type?"));
assert!(sink.questions[0].contains("in-harness, server, both"));
assert_eq!(sink.confirmations, vec!["will configure: claude"]);
}
#[test]
fn scripted_sink_defaults_to_first_when_script_exhausted() {
let mut sink = ScriptedSetupSink::new([], false);
assert_eq!(sink.ask_choice("pick", &["a", "b"]), 0);
assert!(!sink.confirm("plan"));
}
#[test]
fn installation_type_serde_uses_contract_strings() {
assert_eq!(
serde_json::to_string(&InstallationType::InHarness).unwrap(),
"\"in-harness\""
);
assert_eq!(
serde_json::to_string(&InstallationType::Both).unwrap(),
"\"both\""
);
let parsed: InstallationType = serde_json::from_str("\"server\"").unwrap();
assert_eq!(parsed, InstallationType::Server);
}
#[test]
fn non_interactive_setup_configures_fixture_and_persists_profile() {
use crate::cli::admin::operator_server_reachable;
use crate::cli::browser::NoopBrowserOpener;
use crate::cli::harness::{HarnessFormat, HarnessTarget, SYMFORGE_SERVER_NAME};
use crate::cli::harness_apply::{PlannedAction, plan};
let home = tempfile::tempdir().expect("temp home");
let project = tempfile::tempdir().expect("temp project");
let cfg = home.path().join(".claude.json");
std::fs::write(&cfg, "{}\n").expect("fixture harness config");
let ctx = SetupContext {
home: home.path().to_path_buf(),
working_dir: project.path().to_path_buf(),
};
let mut sink = ScriptedSetupSink::new([], true);
let browser = NoopBrowserOpener::default();
let outcome = run_wizard(
SetupCliArgs {
non_interactive: true,
installation_type: Some(InstallationType::Both),
port: None,
harnesses: vec!["claude".into()],
yes: true,
},
&ctx,
&mut sink,
&browser,
)
.expect("setup should succeed");
assert!(!outcome.cancelled);
assert_eq!(outcome.installation_type, InstallationType::Both);
assert!(
sink.statuses.iter().any(|l| l.contains("Claude Code")),
"scan must list harnesses: {:?}",
sink.statuses
);
let profile = OperatorSetupProfile::load(project.path()).expect("profile persisted");
assert_eq!(profile.installation_type, InstallationType::Both);
assert!(profile.port > 0);
assert_eq!(profile.harnesses, vec!["claude"]);
let after = std::fs::read_to_string(&cfg).expect("config exists");
assert!(after.contains(SYMFORGE_SERVER_NAME));
let session = outcome.session.as_ref().expect("server started");
assert!(session.reachable);
let attach_url = session.attach_url.clone();
assert!(attach_url.contains("/mcp"));
assert!(
operator_server_reachable(session.bound_addr, Duration::from_millis(500)),
"server must be reachable on reported port"
);
assert_eq!(browser.opened_urls().len(), 1);
let entry = AttachEntry::new(attach_url, None);
let reg = HarnessRegistry::from_targets(vec![HarnessTarget {
id: HarnessId::ClaudeCode,
config_path: cfg,
format: HarnessFormat::Json,
}]);
let p2 = plan(®, &entry);
assert!(matches!(p2.changes[0].action, PlannedAction::Skip(_)));
}
#[test]
fn non_interactive_decline_writes_nothing_and_is_not_an_error() {
use crate::cli::browser::NoopBrowserOpener;
let home = tempfile::tempdir().expect("temp home");
let project = tempfile::tempdir().expect("temp project");
let cfg = home.path().join(".claude.json");
let original = "{\n \"mcpServers\": {}\n}\n";
std::fs::write(&cfg, original).expect("fixture");
let ctx = SetupContext {
home: home.path().to_path_buf(),
working_dir: project.path().to_path_buf(),
};
let mut sink = ScriptedSetupSink::new([], false);
let browser = NoopBrowserOpener::default();
let outcome = run_wizard(
SetupCliArgs {
non_interactive: true,
installation_type: Some(InstallationType::Both),
port: None,
harnesses: vec!["claude".into()],
yes: false,
},
&ctx,
&mut sink,
&browser,
)
.expect("a decline is a clean no-op, not an error");
assert!(outcome.cancelled);
assert!(outcome.session.is_none());
assert!(outcome.harness_outcomes.is_empty());
assert_eq!(std::fs::read_to_string(&cfg).unwrap(), original);
assert!(OperatorSetupProfile::load(project.path()).is_none());
assert_eq!(sink.confirmations.len(), 1);
}
#[test]
fn setup_holds_foreground_after_fresh_start_until_shutdown() {
use crate::cli::admin::operator_server_reachable;
use crate::cli::browser::NoopBrowserOpener;
let home = tempfile::tempdir().expect("temp home");
let project = tempfile::tempdir().expect("temp project");
let ctx = SetupContext {
home: home.path().to_path_buf(),
working_dir: project.path().to_path_buf(),
};
let mut sink = ScriptedSetupSink::new([], true);
let browser = NoopBrowserOpener::default();
let outcome = run_wizard(
SetupCliArgs {
non_interactive: true,
installation_type: Some(InstallationType::Server),
port: None,
harnesses: vec![],
yes: true,
},
&ctx,
&mut sink,
&browser,
)
.expect("server-mode setup should start a server when none runs");
assert!(
!outcome.reused_server,
"no server ran; the wizard must start one"
);
assert!(
outcome.session.is_some(),
"a fresh start yields a live session"
);
let waited = std::cell::Cell::new(false);
serve_foreground_if_wizard_started(&outcome, |session| {
waited.set(true);
assert!(
operator_server_reachable(session.bound_addr, Duration::from_millis(500)),
"freshly-started server must be reachable while setup holds the foreground"
);
std::thread::sleep(Duration::from_millis(300));
assert!(
operator_server_reachable(session.bound_addr, Duration::from_millis(500)),
"the started server must STAY reachable (D21: it must not die after start)"
);
Ok(())
})
.expect("foreground wait returns cleanly on shutdown");
assert!(
waited.get(),
"a freshly-started server must hold the foreground (D21 fix); pre-fix `run` returned immediately"
);
assert!(
FOREGROUND_SERVE_NOTICE.contains("Ctrl-C"),
"the foreground notice must tell the operator how to stop it"
);
}
#[test]
fn setup_does_not_hold_foreground_when_reusing() {
use crate::cli::browser::NoopBrowserOpener;
let preferred = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
let running =
start_operator_server(Some(preferred), None, None, ADMIN_SERVE_START_DEADLINE)
.expect("operator server should come up");
let home = tempfile::tempdir().expect("temp home");
let project = tempfile::tempdir().expect("temp project");
OperatorSetupProfile::new(
InstallationType::Server,
running.bound_addr.port(),
AuthPosture::LoopbackNoKey,
&[],
1,
)
.save(project.path())
.expect("persist profile");
let ctx = SetupContext {
home: home.path().to_path_buf(),
working_dir: project.path().to_path_buf(),
};
let mut sink = ScriptedSetupSink::new([], true);
let browser = NoopBrowserOpener::default();
let outcome = run_wizard(
SetupCliArgs {
non_interactive: true,
installation_type: Some(InstallationType::Server),
port: None,
harnesses: vec![],
yes: true,
},
&ctx,
&mut sink,
&browser,
)
.expect("server-mode setup should reuse the running server");
assert!(
outcome.reused_server,
"must reuse the already-running server"
);
let waited = std::cell::Cell::new(false);
serve_foreground_if_wizard_started(&outcome, |_| {
waited.set(true);
Ok(())
})
.expect("reuse path returns cleanly");
assert!(
!waited.get(),
"the reuse path must not hold the foreground (another process owns the server)"
);
}
}