use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::domain::ControlStateDir;
pub const ONBOARDING_STATE_FILE: &str = "onboarding.json";
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct OnboardingState {
#[serde(default)]
pub last_shown_version: Option<String>,
}
impl OnboardingState {
pub fn load(path: &Path) -> Self {
match std::fs::read_to_string(path) {
Ok(text) => serde_json::from_str(&text).unwrap_or_default(),
Err(_) => Self::default(),
}
}
pub fn save(&self, path: &Path) -> std::io::Result<()> {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
let json = serde_json::to_string_pretty(self).map_err(std::io::Error::other)?;
std::fs::write(path, json)
}
pub fn should_show(&self, current_version: &str) -> bool {
self.last_shown_version.as_deref() != Some(current_version)
}
}
pub trait OnboardingSink {
fn line(&mut self, text: &str);
fn offer_open(&mut self, url: &str) -> bool;
}
pub struct StderrSink;
impl OnboardingSink for StderrSink {
fn line(&mut self, text: &str) {
eprintln!("{text}");
}
fn offer_open(&mut self, url: &str) -> bool {
eprintln!(" Open it in your browser: {url}");
false
}
}
pub fn state_path(control_state_dir: &ControlStateDir) -> PathBuf {
crate::paths::control_state_path(control_state_dir, ONBOARDING_STATE_FILE)
}
pub fn maybe_show_banner(
state_path: &Path,
current_version: &str,
attach_url: &str,
sink: &mut impl OnboardingSink,
) -> bool {
maybe_show_banner_with_aap(state_path, current_version, attach_url, None, sink)
}
pub fn maybe_show_banner_with_aap(
state_path: &Path,
current_version: &str,
attach_url: &str,
aap: Option<&AapBanner>,
sink: &mut impl OnboardingSink,
) -> bool {
let state = OnboardingState::load(state_path);
if !state.should_show(current_version) {
return false;
}
render_banner(current_version, attach_url, aap, sink);
let next = OnboardingState {
last_shown_version: Some(current_version.to_string()),
};
if let Err(e) = next.save(state_path) {
sink.line(&format!(" (note: could not record onboarding state: {e})"));
}
true
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AapBanner {
pub admin_url: String,
pub embed_path_dep: String,
}
fn render_banner(
version: &str,
attach_url: &str,
aap: Option<&AapBanner>,
sink: &mut impl OnboardingSink,
) {
sink.line("");
sink.line(&format!("SymForge {version} is ready."));
sink.line(&format!(
" Attach an MCP client to this server: {attach_url}"
));
sink.line(" Auto-configure your harnesses: symforge init --scan");
if let Some(aap) = aap {
sink.line(&format!(
" AAP detected. Operator panel: {}",
aap.admin_url
));
sink.line(&format!(" AAP embed dependency: {}", aap.embed_path_dep));
}
sink.offer_open(attach_url);
sink.line("");
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(Default)]
struct RecordingSink {
lines: Vec<String>,
offered: Vec<String>,
}
impl OnboardingSink for RecordingSink {
fn line(&mut self, text: &str) {
self.lines.push(text.to_string());
}
fn offer_open(&mut self, url: &str) -> bool {
self.offered.push(url.to_string());
false
}
}
#[test]
fn should_show_when_never_shown() {
let s = OnboardingState::default();
assert!(s.should_show("1.0.0"));
}
#[test]
fn should_not_show_for_same_version() {
let s = OnboardingState {
last_shown_version: Some("1.0.0".to_string()),
};
assert!(!s.should_show("1.0.0"));
assert!(s.should_show("1.0.1"));
}
#[test]
fn banner_shows_once_then_suppressed() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("onboarding.json");
let mut sink = RecordingSink::default();
assert!(maybe_show_banner(&path, "1.0.0", "http://x/mcp", &mut sink));
assert!(sink.offered.iter().any(|u| u == "http://x/mcp"));
let mut sink2 = RecordingSink::default();
assert!(!maybe_show_banner(
&path,
"1.0.0",
"http://x/mcp",
&mut sink2
));
assert!(sink2.lines.is_empty());
}
#[test]
fn banner_resurfaces_on_version_change() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("onboarding.json");
let mut sink = RecordingSink::default();
assert!(maybe_show_banner(&path, "1.0.0", "http://x/mcp", &mut sink));
let mut sink2 = RecordingSink::default();
assert!(maybe_show_banner(
&path,
"1.1.0",
"http://x/mcp",
&mut sink2
));
}
#[test]
fn aap_banner_mentions_admin_and_embed_path_when_detected() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("onboarding.json");
let aap = AapBanner {
admin_url: "http://127.0.0.1:8787/admin".to_string(),
embed_path_dep: "symforge = { path = \"../symforge\", features = [\"embed\"] }"
.to_string(),
};
let mut sink = RecordingSink::default();
assert!(maybe_show_banner_with_aap(
&path,
"1.0.0",
"http://x/mcp",
Some(&aap),
&mut sink
));
let text = sink.lines.join("\n");
assert!(
text.contains("/admin"),
"AAP banner must mention the operator /admin panel: {text}"
);
assert!(
text.contains("path = \"../symforge\"") && text.contains("features = [\"embed\"]"),
"AAP banner must mention the embed path dependency: {text}"
);
}
#[test]
fn banner_without_aap_omits_admin_and_embed_path() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("onboarding.json");
let mut sink = RecordingSink::default();
assert!(maybe_show_banner_with_aap(
&path,
"1.0.0",
"http://x/mcp",
None,
&mut sink
));
let text = sink.lines.join("\n");
assert!(
!text.contains("/admin"),
"non-AAP banner must NOT mention /admin: {text}"
);
assert!(
!text.contains("embed"),
"non-AAP banner must NOT mention the embed path: {text}"
);
}
}