1use std::io::Write as _;
12use std::path::PathBuf;
13
14pub const RC_MARKER: &str = "# added by `firstpass onboard`";
17
18#[derive(Debug, Clone, PartialEq, Eq)]
21pub struct Environment {
22 pub shell: String,
24 pub proxy_running: bool,
26 pub already_routed: bool,
28 pub has_api_key: bool,
30 pub has_claude_cli: bool,
32 pub bind: String,
34}
35
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum Provider {
41 Anthropic,
43 OpenAi,
45 Google,
47 Local,
49}
50
51impl Provider {
52 pub const ALL: [Self; 4] = [Self::Anthropic, Self::OpenAi, Self::Google, Self::Local];
54
55 #[must_use]
57 pub const fn id(self) -> &'static str {
58 match self {
59 Self::Anthropic => "anthropic",
60 Self::OpenAi => "openai",
61 Self::Google => "google",
62 Self::Local => "local",
63 }
64 }
65
66 #[must_use]
68 pub const fn blurb(self) -> &'static str {
69 match self {
70 Self::Anthropic => "Claude — haiku opens, sonnet catches (built in)",
71 Self::OpenAi => "GPT — 4.1-mini opens, 5.5 catches (built in)",
72 Self::Google => "Gemini — flash opens, pro catches (needs GEMINI_API_KEY)",
73 Self::Local => "Ollama on localhost, escalating to Claude sonnet",
74 }
75 }
76
77 #[must_use]
80 pub const fn ladder(self) -> [&'static str; 2] {
81 match self {
82 Self::Anthropic => ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"],
83 Self::OpenAi => ["openai/gpt-4.1-mini", "openai/gpt-5.5"],
84 Self::Google => ["google/gemini-3.5-flash-lite", "google/gemini-3.6-flash"],
88 Self::Local => ["ollama/qwen2.5-coder:7b", "anthropic/claude-sonnet-5"],
89 }
90 }
91
92 #[must_use]
95 pub const fn judge_model(self) -> &'static str {
96 match self {
97 Self::Anthropic | Self::Local => "anthropic/claude-opus-4-8",
98 Self::OpenAi | Self::Google => "anthropic/claude-haiku-4-5",
99 }
100 }
101
102 #[must_use]
104 pub const fn provider_block(self) -> Option<&'static str> {
105 match self {
106 Self::Anthropic | Self::OpenAi => None,
107 Self::Google => Some(
108 "[[provider]] # only anthropic + openai are built in\n\
109 id = \"google\"\n\
110 dialect = \"gemini\"\n\
111 base_url = \"https://generativelanguage.googleapis.com\"\n\
112 api_key_env = \"GEMINI_API_KEY\"\n",
113 ),
114 Self::Local => Some(
115 "[[provider]] # local rung; escalates to a frontier model\n\
116 id = \"ollama\"\n\
117 dialect = \"openai\"\n\
118 base_url = \"http://localhost:11434\" # keyless\n\
119 \n\
120 [[price]] # you host it, so the tokens really are free —\n\
121 model = \"ollama/qwen2.5-coder:7b\" # but the receipt has to SAY so,\n\
122 input_per_mtok = 0.0 # rather than infer $0.00 from a missing price\n\
123 output_per_mtok = 0.0\n",
124 ),
125 }
126 }
127}
128
129#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132pub enum Shape {
133 Json,
135 Code,
137 Prose,
139 Mixed,
141}
142
143impl Shape {
144 pub const ALL: [Self; 4] = [Self::Json, Self::Code, Self::Prose, Self::Mixed];
146
147 #[must_use]
149 pub const fn id(self) -> &'static str {
150 match self {
151 Self::Json => "json",
152 Self::Code => "code",
153 Self::Prose => "prose",
154 Self::Mixed => "mixed",
155 }
156 }
157
158 #[must_use]
160 pub const fn blurb(self) -> &'static str {
161 match self {
162 Self::Json => "JSON / API responses — schema gate, cheapest proof there is",
163 Self::Code => "Code — your own test suite is the gate",
164 Self::Prose => "Prose — an LLM judge grades it (maker != checker)",
165 Self::Mixed => "Mixed — k-sample self-consistency scores agreement",
166 }
167 }
168
169 #[must_use]
172 pub const fn gates(self) -> [&'static str; 2] {
173 match self {
174 Self::Json => ["json-valid", "extract-shape"],
175 Self::Code => ["json-valid", "unit-tests"],
176 Self::Prose => ["non-empty", "judge"],
177 Self::Mixed => ["non-empty", "uncertainty"],
178 }
179 }
180
181 #[must_use]
183 pub fn gate_block(self, provider: Provider) -> String {
184 match self {
185 Self::Json => "[[gate]]\n\
186 id = \"extract-shape\"\n\
187 schema = { type = \"object\", required = [\"id\", \"total\"] }\n\
188 on_abstain = \"fail_closed\"\n"
189 .to_owned(),
190 Self::Code => {
200 "[[gate]]\n\
201 # A working gate. `run-tests.py` implements the stdin/stdout contract: it pulls\n\
202 # the code out of the model's reply, runs your command, and reports the pass\n\
203 # FRACTION as the score (a graded score is what the conformal bound calibrates\n\
204 # on; a bare pass/fail gives it only two operating points).\n\
205 # Swap the command after `--` for yours:\n\
206 # jest: \"--write\", \"solution.js\", \"--\", \"npx\", \"jest\", \"--silent\"\n\
207 # cargo: \"--write\", \"src/lib.rs\", \"--\", \"cargo\", \"test\", \"--quiet\"\n\
208 # Add \"--copy\", \"tests/\" to bring your test files into the run directory, and\n\
209 # \"--docker\", \"python:3.12-alpine\" to run untrusted code with no network.\n\
210 id = \"unit-tests\"\n\
211 cmd = [\"python3\", \"scripts/gates/run-tests.py\",\n\
212 \"--write\", \"solution.py\", \"--copy\", \"tests/\",\n\
213 \"--\", \"python3\", \"-m\", \"pytest\", \"-q\"]\n"
214 .to_owned()
215 }
216 Self::Prose => format!(
217 "[[gate]] # judge sits OUTSIDE the ladder: maker != checker\n\
218 id = \"judge\"\n\
219 judge = {{ model = \"{}\", threshold = 0.7, rubric = \"The response fully and \
220 correctly resolves the request, with no errors.\" }}\n",
221 provider.judge_model()
222 ),
223 Self::Mixed => format!(
224 "[[gate]] # k samples; agreement becomes the score\n\
225 id = \"uncertainty\"\n\
226 consistency = {{ model = \"{}\", k = 3, threshold = 0.6 }}\n",
227 provider.ladder()[0]
228 ),
229 }
230 }
231}
232
233#[derive(Debug, Clone, Copy, PartialEq, Eq)]
236pub struct LadderChoice {
237 pub provider: Provider,
239 pub shape: Shape,
241 pub mode: firstpass_core::Mode,
243}
244
245impl Default for LadderChoice {
246 fn default() -> Self {
249 Self {
250 provider: Provider::Anthropic,
251 shape: Shape::Json,
252 mode: firstpass_core::Mode::Observe,
253 }
254 }
255}
256
257#[must_use]
262pub fn render_config(choice: &LadderChoice) -> String {
263 let enforce = choice.mode == firstpass_core::Mode::Enforce;
264 let mode = if enforce { "enforce" } else { "observe" };
265 let quoted = |xs: [&str; 2]| -> String { format!("\"{}\", \"{}\"", xs[0], xs[1]) };
266 let mut out = format!(
267 "# firstpass.toml — written by `firstpass onboard`. Re-run onboard to regenerate.\n\
268 # FIRSTPASS_MODE={mode} FIRSTPASS_CONFIG=./firstpass.toml firstpass up\n\n"
269 );
270 if let Some(block) = choice.provider.provider_block() {
271 out.push_str(block);
272 out.push('\n');
273 }
274 out.push_str(&format!(
275 "[[route]] # routes match top to bottom; first match wins\n\
276 match = {{}} # everything\n\
277 mode = \"{mode}\"\n\
278 ladder = [{}]\n\
279 gates = [{}]\n\n",
280 quoted(choice.provider.ladder()),
281 quoted(choice.shape.gates()),
282 ));
283 out.push_str(&choice.shape.gate_block(choice.provider));
284 if enforce {
285 out.push_str(
286 "\n[escalation]\nmax_rungs_per_request = 2 # one rung up, never a runaway\n",
287 );
288 } else {
289 out.push_str(
290 "\n# observe: every request is forwarded unchanged and a receipt is written off\n\
291 # the hot path. Nothing routes differently until mode = \"enforce\".\n",
292 );
293 }
294 out
295}
296
297#[must_use]
305pub fn presets_js() -> String {
306 use firstpass_core::Mode;
307 let mut out = String::from(
308 "// GENERATED by `cargo test -p firstpass-proxy presets` — do not edit by hand.\n\
309 // Source of truth: crates/firstpass-proxy/src/onboard.rs (render_config).\n\
310 // Regenerate: FIRSTPASS_WRITE_PRESETS=1 cargo test -p firstpass-proxy presets\n\
311 window.FP_LADDER_PRESETS = {\n",
312 );
313 for provider in Provider::ALL {
314 out.push_str(&format!(" {:?}: {{\n", provider.id()));
315 for shape in Shape::ALL {
316 out.push_str(&format!(" {:?}: {{\n", shape.id()));
317 for (mode, key) in [(Mode::Observe, "observe"), (Mode::Enforce, "enforce")] {
318 let toml = render_config(&LadderChoice {
319 provider,
320 shape,
321 mode,
322 });
323 out.push_str(&format!(" {key:?}: {},\n", js_string(&toml)));
324 }
325 out.push_str(" },\n");
326 }
327 out.push_str(" },\n");
328 }
329 out.push_str("};\n");
330 out
331}
332
333fn js_string(s: &str) -> String {
336 let mut out = String::with_capacity(s.len() + 16);
337 out.push('"');
338 for c in s.chars() {
339 match c {
340 '"' => out.push_str("\\\""),
341 '\\' => out.push_str("\\\\"),
342 '\n' => out.push_str("\\n"),
343 '\r' => {}
344 c => out.push(c),
345 }
346 }
347 out.push('"');
348 out
349}
350
351#[derive(Debug, Clone, PartialEq, Eq)]
353pub enum Step {
354 WriteConfig {
356 path: PathBuf,
358 toml: String,
360 },
361 StartProxy {
363 config: Option<PathBuf>,
366 },
367 WireShell {
369 rc: PathBuf,
371 line: String,
373 },
374 SuggestClaudeMcp,
377 Verify,
379 AlreadyDone(&'static str),
381}
382
383pub fn detect(
386 env: impl Fn(&str) -> Option<String>,
387 on_path: impl Fn(&str) -> bool,
388 healthz: impl Fn() -> bool,
389) -> Environment {
390 let bind = env("FIRSTPASS_BIND").unwrap_or_else(|| "127.0.0.1:8080".to_owned());
391 let base_url = format!("http://{bind}");
392 let shell = env("SHELL")
393 .and_then(|s| s.rsplit('/').next().map(str::to_owned))
394 .unwrap_or_else(|| "sh".to_owned());
395 Environment {
396 shell,
397 proxy_running: healthz(),
398 already_routed: env("ANTHROPIC_BASE_URL").is_some_and(|v| v == base_url),
399 has_api_key: env("ANTHROPIC_API_KEY").is_some(),
400 has_claude_cli: on_path("claude"),
401 bind,
402 }
403}
404
405#[must_use]
408pub fn shell_wiring(shell: &str, home: &std::path::Path, bind: &str) -> (PathBuf, String) {
409 let url = format!("http://{bind}");
410 match shell {
411 "fish" => (
412 home.join(".config/fish/config.fish"),
413 format!("set -gx ANTHROPIC_BASE_URL {url} {RC_MARKER}"),
414 ),
415 "bash" => (
416 home.join(".bashrc"),
417 format!("export ANTHROPIC_BASE_URL={url} {RC_MARKER}"),
418 ),
419 "zsh" => (
421 home.join(".zshrc"),
422 format!("export ANTHROPIC_BASE_URL={url} {RC_MARKER}"),
423 ),
424 _ => (
425 home.join(".profile"),
426 format!("export ANTHROPIC_BASE_URL={url} {RC_MARKER}"),
427 ),
428 }
429}
430
431#[derive(Debug, Clone)]
434pub struct ConfigPlan {
435 pub path: PathBuf,
437 pub choice: LadderChoice,
439}
440
441#[must_use]
446pub fn plan(
447 env: &Environment,
448 home: &std::path::Path,
449 rc_already_wired: bool,
450 config: Option<&ConfigPlan>,
451) -> Vec<Step> {
452 let mut steps = Vec::new();
453 if let Some(c) = config {
454 steps.push(Step::WriteConfig {
455 path: c.path.clone(),
456 toml: render_config(&c.choice),
457 });
458 }
459 if env.proxy_running {
460 steps.push(Step::AlreadyDone("proxy already answering /healthz"));
461 } else {
462 steps.push(Step::StartProxy {
463 config: config.map(|c| c.path.clone()),
464 });
465 }
466 if env.already_routed || rc_already_wired {
467 steps.push(Step::AlreadyDone("ANTHROPIC_BASE_URL already wired"));
468 } else {
469 let (rc, line) = shell_wiring(&env.shell, home, &env.bind);
470 steps.push(Step::WireShell { rc, line });
471 }
472 if env.has_claude_cli {
473 steps.push(Step::SuggestClaudeMcp);
474 }
475 steps.push(Step::Verify);
476 steps
477}
478
479#[must_use]
481pub fn render(env: &Environment, steps: &[Step], apply: bool) -> String {
482 let mut out = String::new();
483 out.push_str(&format!(
484 "detected: shell={} · proxy_running={} · routed={} · api_key={} · claude_cli={}\n\n",
485 env.shell, env.proxy_running, env.already_routed, env.has_api_key, env.has_claude_cli
486 ));
487 for (i, s) in steps.iter().enumerate() {
488 let n = i + 1;
489 match s {
490 Step::WriteConfig { path, toml } => {
491 out.push_str(&format!("{n}. write {} —\n", path.display()));
492 for line in toml.lines() {
493 out.push_str(&format!(" {line}\n"));
494 }
495 }
496 Step::StartProxy { config } => {
497 out.push_str(&format!(
498 "{n}. start the proxy — `firstpass up` (observe mode: watches, changes nothing), log → firstpass-proxy.log\n"
499 ));
500 if let Some(c) = config {
501 out.push_str(&format!(
502 " with FIRSTPASS_CONFIG={} — the proxy has no default config path\n",
503 c.display()
504 ));
505 }
506 }
507 Step::WireShell { rc, line } => out.push_str(&format!(
508 "{n}. route your agents — append to {}:\n {line}\n",
509 rc.display()
510 )),
511 Step::SuggestClaudeMcp => out.push_str(&format!(
512 "{n}. (optional) let Claude Code query receipts as tools:\n claude mcp add firstpass -- firstpass mcp\n"
513 )),
514 Step::Verify => out.push_str(&format!(
515 "{n}. verify — probe /healthz and /v1/capabilities, report what's routed\n"
516 )),
517 Step::AlreadyDone(why) => out.push_str(&format!("{n}. ✓ {why}\n")),
518 }
519 }
520 if !env.has_api_key {
521 out.push_str(
522 "\nnote: ANTHROPIC_API_KEY is not set — observe mode passes your agent's own key \
523 through (BYOK), so this only matters for enforce mode.\n",
524 );
525 }
526 if !apply {
527 out.push_str(
528 "\ndry run — nothing changed. Re-run with `firstpass onboard --apply` to execute.\n",
529 );
530 }
531 out
532}
533
534pub fn execute(env: &Environment, steps: &[Step]) -> Result<String, std::io::Error> {
540 let mut out = String::new();
541 for s in steps {
542 match s {
543 Step::WriteConfig { path, toml } => {
544 if path.exists() {
547 out.push_str(&format!(
548 "✓ {} already present — left untouched\n",
549 path.display()
550 ));
551 } else {
552 std::fs::write(path, toml)?;
553 out.push_str(&format!("✓ wrote {}\n", path.display()));
554 }
555 }
556 Step::StartProxy { config } => {
557 let log = std::fs::File::create("firstpass-proxy.log")?;
558 let exe = std::env::current_exe()?;
559 let mut cmd = std::process::Command::new(exe);
560 cmd.arg("up");
561 if let Some(c) = config {
562 cmd.env("FIRSTPASS_CONFIG", c);
565 }
566 let child = cmd
567 .stdin(std::process::Stdio::null())
568 .stdout(std::process::Stdio::from(log.try_clone()?))
569 .stderr(std::process::Stdio::from(log))
570 .spawn();
571 match child {
572 Ok(c) => {
573 let _ = std::fs::write("firstpass-proxy.pid", c.id().to_string());
575 out.push_str(&format!(
576 "✓ proxy started (pid {}, observe mode) — log: firstpass-proxy.log\n",
577 c.id()
578 ));
579 }
580 Err(e) => out.push_str(&format!("✗ could not start proxy: {e}\n")),
581 }
582 }
583 Step::WireShell { rc, line } => {
584 if let Some(parent) = rc.parent() {
585 std::fs::create_dir_all(parent)?;
586 }
587 let mut f = std::fs::OpenOptions::new()
588 .create(true)
589 .append(true)
590 .open(rc)?;
591 writeln!(f, "{line}")?;
592 out.push_str(&format!(
593 "✓ wired {} — takes effect in new shells; for this one:\n {}\n",
594 rc.display(),
595 line.trim_end_matches(RC_MARKER).trim_end()
596 ));
597 }
598 Step::SuggestClaudeMcp => {
599 out.push_str("→ optional: claude mcp add firstpass -- firstpass mcp\n");
600 }
601 Step::Verify => {
602 let url = format!("http://{}/healthz", env.bind);
603 let ok = wait_healthz(&url, std::time::Duration::from_secs(6));
604 if ok {
605 out.push_str(&format!(
606 "✓ verified — proxy healthy at http://{} · capabilities: http://{}/v1/capabilities\n",
607 env.bind, env.bind
608 ));
609 } else {
610 out.push_str(&format!(
611 "✗ proxy not answering http://{} after 6s — check firstpass-proxy.log\n",
612 env.bind
613 ));
614 }
615 }
616 Step::AlreadyDone(why) => out.push_str(&format!("✓ {why}\n")),
617 }
618 }
619 out.push_str("\noffboard any time: unset ANTHROPIC_BASE_URL (and remove the marked rc line)\n");
620 Ok(out)
621}
622
623#[must_use]
634pub fn healthz_is_firstpass(status_ok: bool, body: &str) -> bool {
635 if !status_ok {
636 return false;
637 }
638 serde_json::from_str::<serde_json::Value>(body)
639 .ok()
640 .and_then(|v| {
641 v.get("service")
642 .and_then(serde_json::Value::as_str)
643 .map(|s| s == "firstpass")
644 })
645 .unwrap_or(false)
646}
647
648fn get_healthz(addr: &str) -> Option<(bool, String)> {
654 let mut s = std::net::TcpStream::connect(addr).ok()?;
655 let _ = s.set_read_timeout(Some(std::time::Duration::from_millis(500)));
656 let req = format!("GET /healthz HTTP/1.1\r\nHost: {addr}\r\nConnection: close\r\n\r\n");
657 s.write_all(req.as_bytes()).ok()?;
658 use std::io::Read as _;
659 let mut raw = Vec::new();
660 let _ = s.take(64 * 1024).read_to_end(&mut raw);
662 let text = String::from_utf8_lossy(&raw).into_owned();
663 let status_ok = text.lines().next().is_some_and(|l| l.contains(" 200"));
664 let body = text
665 .split_once("\r\n\r\n")
666 .map_or("", |(_, b)| b)
667 .to_owned();
668 Some((status_ok, body))
669}
670
671#[must_use]
676pub fn firstpass_listening(addr: &str) -> bool {
677 get_healthz(addr).is_some_and(|(ok, body)| healthz_is_firstpass(ok, &body))
678}
679
680fn wait_healthz(url: &str, deadline: std::time::Duration) -> bool {
682 let Some(addr) = url
683 .strip_prefix("http://")
684 .and_then(|r| r.split('/').next())
685 .map(str::to_owned)
686 else {
687 return false;
688 };
689 let start = std::time::Instant::now();
690 while start.elapsed() < deadline {
691 if firstpass_listening(&addr) {
692 return true;
693 }
694 std::thread::sleep(std::time::Duration::from_millis(200));
695 }
696 false
697}
698
699#[must_use]
701pub fn rc_wired(rc: &std::path::Path) -> bool {
702 std::fs::read_to_string(rc).is_ok_and(|s| s.contains(RC_MARKER))
703}
704
705pub fn offboard_rc(rc: &std::path::Path) -> Result<bool, std::io::Error> {
711 let Ok(content) = std::fs::read_to_string(rc) else {
712 return Ok(false); };
714 if !content.contains(RC_MARKER) {
715 return Ok(false);
716 }
717 let kept: Vec<&str> = content.lines().filter(|l| !l.contains(RC_MARKER)).collect();
718 std::fs::write(rc, kept.join("\n") + "\n")?;
719 Ok(true)
720}
721
722pub fn offboard(home: &std::path::Path) -> Result<String, std::io::Error> {
729 let mut out = String::new();
730 for rc in [
731 home.join(".zshrc"),
732 home.join(".bashrc"),
733 home.join(".profile"),
734 home.join(".config/fish/config.fish"),
735 ] {
736 if offboard_rc(&rc)? {
737 out.push_str(&format!("✓ removed firstpass line from {}\n", rc.display()));
738 }
739 }
740 if let Ok(pid) = std::fs::read_to_string("firstpass-proxy.pid") {
742 let pid = pid.trim().to_owned();
743 #[cfg(unix)]
744 {
745 let killed = std::process::Command::new("kill")
746 .arg(&pid)
747 .status()
748 .is_ok_and(|s| s.success());
749 if killed {
750 out.push_str(&format!("✓ stopped proxy (pid {pid})\n"));
751 } else {
752 out.push_str(&format!(
753 "→ proxy pid {pid} not running (already stopped)\n"
754 ));
755 }
756 }
757 let _ = std::fs::remove_file("firstpass-proxy.pid");
758 }
759 if out.is_empty() {
760 out.push_str("nothing to offboard — no marked rc lines, no pidfile.\n");
761 }
762 out.push_str("for this shell: unset ANTHROPIC_BASE_URL\n");
763 Ok(out)
764}
765
766#[cfg(test)]
767mod tests {
768 #![allow(clippy::unwrap_used)]
769 use super::*;
770
771 fn env_of<'a>(pairs: &'a [(&'a str, &'a str)]) -> impl Fn(&str) -> Option<String> + 'a {
772 move |k| {
773 pairs
774 .iter()
775 .find(|(a, _)| *a == k)
776 .map(|(_, v)| (*v).to_owned())
777 }
778 }
779
780 #[test]
781 fn detect_reads_shell_routing_and_tools() {
782 let e = detect(
783 env_of(&[
784 ("SHELL", "/bin/zsh"),
785 ("ANTHROPIC_BASE_URL", "http://127.0.0.1:8080"),
786 ("ANTHROPIC_API_KEY", "sk-x"),
787 ]),
788 |bin| bin == "claude",
789 || true,
790 );
791 assert_eq!(e.shell, "zsh");
792 assert!(e.proxy_running && e.already_routed && e.has_api_key && e.has_claude_cli);
793 assert_eq!(e.bind, "127.0.0.1:8080");
794 }
795
796 #[test]
797 fn detect_respects_custom_bind_and_mismatched_base_url() {
798 let e = detect(
799 env_of(&[
800 ("FIRSTPASS_BIND", "127.0.0.1:9999"),
801 ("ANTHROPIC_BASE_URL", "http://127.0.0.1:8080"), ]),
803 |_| false,
804 || false,
805 );
806 assert_eq!(e.bind, "127.0.0.1:9999");
807 assert!(
808 !e.already_routed,
809 "routed to a different port is not routed"
810 );
811 }
812
813 #[test]
814 fn shell_wiring_speaks_each_dialect() {
815 let home = std::path::Path::new("/home/u");
816 let (rc, line) = shell_wiring("fish", home, "127.0.0.1:8080");
817 assert!(rc.ends_with(".config/fish/config.fish"));
818 assert!(line.starts_with("set -gx ANTHROPIC_BASE_URL http://127.0.0.1:8080"));
819
820 let (rc, line) = shell_wiring("zsh", home, "127.0.0.1:8080");
821 assert!(rc.ends_with(".zshrc"));
822 assert!(line.starts_with("export ANTHROPIC_BASE_URL="));
823
824 let (rc, _) = shell_wiring("dash", home, "127.0.0.1:8080");
825 assert!(
826 rc.ends_with(".profile"),
827 "unknown shells fall back to .profile"
828 );
829 }
830
831 #[test]
832 fn plan_covers_fresh_machine_and_is_idempotent_when_done() {
833 let home = std::path::Path::new("/home/u");
834 let fresh = Environment {
835 shell: "zsh".into(),
836 proxy_running: false,
837 already_routed: false,
838 has_api_key: false,
839 has_claude_cli: true,
840 bind: "127.0.0.1:8080".into(),
841 };
842 let steps = plan(&fresh, home, false, None);
843 assert!(matches!(steps[0], Step::StartProxy { .. }));
844 assert!(matches!(steps[1], Step::WireShell { .. }));
845 assert!(matches!(steps[2], Step::SuggestClaudeMcp));
846 assert!(matches!(steps.last(), Some(Step::Verify)));
847
848 let done = Environment {
850 proxy_running: true,
851 already_routed: true,
852 has_claude_cli: false,
853 ..fresh
854 };
855 let steps = plan(&done, home, true, None);
856 assert!(
857 steps
858 .iter()
859 .all(|s| matches!(s, Step::AlreadyDone(_) | Step::Verify))
860 );
861 }
862
863 #[test]
864 fn render_dry_run_says_nothing_changed_and_flags_missing_key() {
865 let home = std::path::Path::new("/home/u");
866 let e = Environment {
867 shell: "bash".into(),
868 proxy_running: false,
869 already_routed: false,
870 has_api_key: false,
871 has_claude_cli: false,
872 bind: "127.0.0.1:8080".into(),
873 };
874 let text = render(&e, &plan(&e, home, false, None), false);
875 assert!(text.contains("dry run — nothing changed"));
876 assert!(text.contains("ANTHROPIC_API_KEY is not set"));
877 assert!(text.contains(".bashrc"));
878 }
879
880 #[test]
881 fn rc_wired_detects_the_marker_and_execute_appends_it_once() {
882 let dir = std::env::temp_dir().join(format!("fp-onboard-{}", uuid::Uuid::now_v7()));
883 std::fs::create_dir_all(&dir).unwrap();
884 let rc = dir.join(".zshrc");
885 assert!(!rc_wired(&rc), "missing file is not wired");
886
887 let e = Environment {
888 shell: "zsh".into(),
889 proxy_running: true, already_routed: false,
891 has_api_key: true,
892 has_claude_cli: false,
893 bind: "127.0.0.1:1".into(), };
895 let (rc_path, line) = shell_wiring("zsh", &dir, &e.bind);
896 let steps = vec![Step::WireShell {
897 rc: rc_path.clone(),
898 line,
899 }];
900 let report = execute(&e, &steps).unwrap();
901 assert!(report.contains("✓ wired"));
902 assert!(rc_wired(&rc_path), "marker written");
903 let steps = plan(&e, &dir, rc_wired(&rc_path), None);
905 assert!(!steps.iter().any(|s| matches!(s, Step::WireShell { .. })));
906
907 let _ = std::fs::remove_dir_all(&dir);
908 }
909
910 #[test]
911 fn offboard_removes_only_the_marked_line_and_is_idempotent() {
912 let dir = std::env::temp_dir().join(format!("fp-offboard-{}", uuid::Uuid::now_v7()));
913 std::fs::create_dir_all(&dir).unwrap();
914 let rc = dir.join(".zshrc");
915 std::fs::write(
916 &rc,
917 format!("alias ll='ls -l'\nexport ANTHROPIC_BASE_URL=http://127.0.0.1:8080 {RC_MARKER}\nexport EDITOR=vim\n"),
918 )
919 .unwrap();
920
921 assert!(offboard_rc(&rc).unwrap(), "marked line removed");
922 let after = std::fs::read_to_string(&rc).unwrap();
923 assert!(!after.contains(RC_MARKER));
924 assert!(
925 after.contains("alias ll") && after.contains("EDITOR=vim"),
926 "user lines untouched"
927 );
928 assert!(!offboard_rc(&rc).unwrap(), "second offboard is a no-op");
929
930 std::fs::write(&rc, format!("x {RC_MARKER}\n")).unwrap();
932 let report = offboard(&dir).unwrap();
933 assert!(report.contains("removed firstpass line"));
934 assert!(report.contains("unset ANTHROPIC_BASE_URL"));
935
936 let _ = std::fs::remove_dir_all(&dir);
937 }
938
939 #[test]
943 fn every_generated_config_parses_and_resolves() {
944 use firstpass_core::Mode;
945 let mut n = 0;
946 for provider in Provider::ALL {
947 for shape in Shape::ALL {
948 for mode in [Mode::Observe, Mode::Enforce] {
949 n += 1;
950 let choice = LadderChoice {
951 provider,
952 shape,
953 mode,
954 };
955 let toml = render_config(&choice);
956 let cfg = firstpass_core::Config::parse(&toml).unwrap_or_else(|e| {
957 panic!(
958 "{}/{}/{mode:?} did not parse: {e}\n{toml}",
959 provider.id(),
960 shape.id()
961 )
962 });
963 let route = &cfg.routes[0];
964 assert_eq!(
965 route.mode, mode,
966 "route mode is what actually gates enforcement"
967 );
968 assert_eq!(
969 route.ladder.len(),
970 2,
971 "a ladder needs somewhere to escalate to"
972 );
973
974 for g in &route.gates {
976 let builtin = g == "non-empty" || g == "json-valid";
977 assert!(
978 builtin || cfg.gate_defs.iter().any(|d| &d.id == g),
979 "{}/{}: gate {g:?} is neither built in nor declared",
980 provider.id(),
981 shape.id()
982 );
983 }
984 for rung in &route.ladder {
986 let pid = rung.split('/').next().unwrap();
987 let builtin = pid == "anthropic" || pid == "openai";
988 assert!(
989 builtin || cfg.providers.iter().any(|d| d.id == pid),
990 "{}/{}: provider {pid:?} is neither built in nor declared",
991 provider.id(),
992 shape.id()
993 );
994 }
995 if let Some(j) = cfg.gate_defs.iter().find_map(|d| d.judge.as_ref()) {
997 assert!(
998 !route.ladder.contains(&j.model),
999 "{}: judge {} is on its own ladder",
1000 provider.id(),
1001 j.model
1002 );
1003 }
1004 assert_eq!(
1006 toml.contains("[escalation]"),
1007 mode == Mode::Enforce,
1008 "escalation block should track enforce only"
1009 );
1010 }
1011 }
1012 }
1013 assert_eq!(n, 32, "4 providers x 4 shapes x 2 modes");
1014 }
1015
1016 #[test]
1019 fn planned_config_is_written_before_the_proxy_starts_and_is_handed_to_it() {
1020 let home = std::path::Path::new("/home/u");
1021 let env = Environment {
1022 shell: "zsh".into(),
1023 proxy_running: false,
1024 already_routed: false,
1025 has_api_key: true,
1026 has_claude_cli: false,
1027 bind: "127.0.0.1:8080".into(),
1028 };
1029 let cfg = ConfigPlan {
1030 path: PathBuf::from("firstpass.toml"),
1031 choice: LadderChoice::default(),
1032 };
1033 let steps = plan(&env, home, false, Some(&cfg));
1034 assert!(
1035 matches!(&steps[0], Step::WriteConfig { path, .. } if path == &cfg.path),
1036 "config is written first, before anything reads it"
1037 );
1038 assert!(
1039 matches!(&steps[1], Step::StartProxy { config: Some(p) } if p == &cfg.path),
1040 "the spawned proxy is handed the config explicitly"
1041 );
1042
1043 let steps = plan(&env, home, false, None);
1045 assert!(matches!(steps[0], Step::StartProxy { config: None }));
1046 assert!(!steps.iter().any(|s| matches!(s, Step::WriteConfig { .. })));
1047 }
1048
1049 #[test]
1051 fn write_config_refuses_to_overwrite_an_existing_file() {
1052 let dir = std::env::temp_dir().join(format!("fp-cfg-{}", uuid::Uuid::now_v7()));
1053 std::fs::create_dir_all(&dir).unwrap();
1054 let path = dir.join("firstpass.toml");
1055 std::fs::write(&path, "# hand-tuned, do not touch\n").unwrap();
1056 let env = Environment {
1057 shell: "zsh".into(),
1058 proxy_running: true, already_routed: true,
1060 has_api_key: true,
1061 has_claude_cli: false,
1062 bind: "127.0.0.1:1".into(),
1063 };
1064 let steps = vec![Step::WriteConfig {
1065 path: path.clone(),
1066 toml: render_config(&LadderChoice::default()),
1067 }];
1068 let report = execute(&env, &steps).unwrap();
1069 assert!(report.contains("already present"));
1070 assert_eq!(
1071 std::fs::read_to_string(&path).unwrap(),
1072 "# hand-tuned, do not touch\n",
1073 "existing config survived untouched"
1074 );
1075 let _ = std::fs::remove_dir_all(&dir);
1076 }
1077
1078 #[test]
1081 fn dry_run_shows_the_config_it_would_write() {
1082 let home = std::path::Path::new("/home/u");
1083 let env = Environment {
1084 shell: "bash".into(),
1085 proxy_running: false,
1086 already_routed: false,
1087 has_api_key: true,
1088 has_claude_cli: false,
1089 bind: "127.0.0.1:8080".into(),
1090 };
1091 let cfg = ConfigPlan {
1092 path: PathBuf::from("firstpass.toml"),
1093 choice: LadderChoice {
1094 provider: Provider::Local,
1095 shape: Shape::Code,
1096 mode: firstpass_core::Mode::Enforce,
1097 },
1098 };
1099 let text = render(&env, &plan(&env, home, false, Some(&cfg)), false);
1100 assert!(text.contains("write firstpass.toml"));
1101 assert!(text.contains("ollama"), "provider block is shown");
1102 assert!(text.contains("unit-tests"), "gate block is shown");
1103 assert!(
1104 text.contains("FIRSTPASS_CONFIG="),
1105 "explains how the proxy finds it"
1106 );
1107 assert!(text.contains("dry run — nothing changed"));
1108 }
1109
1110 #[test]
1114 fn docs_presets_are_current() {
1115 let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
1116 .join("../../docs/assets/ladder-presets.js");
1117 let generated = presets_js();
1118
1119 if std::env::var("FIRSTPASS_WRITE_PRESETS").is_ok() {
1121 std::fs::write(&path, &generated).expect("write presets");
1122 return;
1123 }
1124
1125 let committed = std::fs::read_to_string(&path).unwrap_or_else(|e| {
1126 panic!(
1127 "{}: {e}\nregenerate with:\n \
1128 FIRSTPASS_WRITE_PRESETS=1 cargo test -p firstpass-proxy presets",
1129 path.display()
1130 )
1131 });
1132 assert_eq!(
1133 committed.replace("\r\n", "\n"),
1134 generated,
1135 "docs/assets/ladder-presets.js is stale — the docs builder and `firstpass onboard` \
1136 would emit different config.\nregenerate with:\n \
1137 FIRSTPASS_WRITE_PRESETS=1 cargo test -p firstpass-proxy presets"
1138 );
1139 }
1140
1141 #[test]
1144 fn every_docs_preset_parses() {
1145 let js = presets_js();
1146 let mut n = 0;
1147 for raw in js.split("\": \"").skip(1) {
1148 let lit = &raw[..raw.find("\",\n").unwrap_or(raw.len())];
1149 let toml = lit
1150 .replace("\\n", "\n")
1151 .replace("\\\"", "\"")
1152 .replace("\\\\", "\\");
1153 if !toml.contains("[[route]]") {
1154 continue;
1155 }
1156 n += 1;
1157 firstpass_core::Config::parse(&toml)
1158 .unwrap_or_else(|e| panic!("preset #{n} does not parse: {e}\n{toml}"));
1159 }
1160 assert_eq!(n, 32, "expected all 32 presets to be checked, saw {n}");
1161 }
1162
1163 #[test]
1172 fn a_foreign_listener_answering_healthz_is_not_accepted_as_the_proxy() {
1173 let foreign = r#"{"status":"ok","llmMode":"api","rlsEnforce":false,"appPoolActive":false}"#;
1175 assert!(
1176 !healthz_is_firstpass(true, foreign),
1177 "a 200 from a stranger must not read as Firstpass"
1178 );
1179
1180 let ours = r#"{"status":"ok","service":"firstpass","version":"0.6.0"}"#;
1182 assert!(
1183 healthz_is_firstpass(true, ours),
1184 "the real proxy must still be recognised"
1185 );
1186
1187 assert!(!healthz_is_firstpass(false, ours));
1189 assert!(!healthz_is_firstpass(true, "not json at all"));
1190 assert!(!healthz_is_firstpass(true, r#"{"status":"ok"}"#));
1192 }
1193}