1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
//! `symforge serve` CLI subcommand — operator server flags.
//!
//! Defines the clap arg surface for `serve` and converts it into the
//! transport-agnostic [`crate::server::serve::ServeArgs`]. The async entrypoint
//! ([`crate::server::serve::run`]) is driven from `main.rs` on a multi-thread
//! tokio runtime (mirroring `run_daemon` / `run_mcp_server`).
use clap::Args;
use crate::server::serve::{DEFAULT_LISTEN, ServeArgs};
/// Flags for `symforge serve` (see `contracts/cli-serve.md`).
#[derive(Args, Debug, Clone)]
pub struct ServeCliArgs {
/// Bind address `HOST:PORT` (default `127.0.0.1:8787`; `PORT=0` → OS-assigned).
///
/// Omitting `--listen` selects the default and enables the US1 free-port
/// fallback: if `127.0.0.1:8787` is occupied, serve binds an OS-assigned
/// free port instead of failing. Passing `--listen` explicitly honors the
/// address exactly — an occupied port fails loudly (no substitution).
#[arg(long)]
pub listen: Option<String>,
/// Single static Bearer key (inline). Prefer `--api-key-env` for secrecy.
#[arg(long)]
pub api_key: Option<String>,
/// Name of an environment variable holding the Bearer key.
#[arg(long)]
pub api_key_env: Option<String>,
/// Tool allow-list for this server: comma-separated tool or group names
/// (`read`, `edit`, `knowledge`, `impact`, `service`). Same as `SYMFORGE_TOOLS`,
/// which it overrides.
#[arg(long, value_parser = clap::builder::NonEmptyStringValueParser::new())]
pub tools: Option<String>,
}
impl ServeCliArgs {
/// Convert CLI flags into the transport-agnostic [`ServeArgs`].
///
/// An explicit `--listen` sets `explicit_listen = true` (honor exactly, fail
/// loudly if occupied); omitting it uses [`DEFAULT_LISTEN`] with the US1
/// free-port fallback (`explicit_listen = false`).
pub fn into_serve_args(self) -> ServeArgs {
let explicit_listen = self.listen.is_some();
ServeArgs {
listen: self.listen.unwrap_or_else(|| DEFAULT_LISTEN.to_string()),
explicit_listen,
api_key: self.api_key,
api_key_env: self.api_key_env,
bound_addr_tx: None,
// The operator CLI always discovers the workspace from its CWD.
workspace_root: None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn into_serve_args_carries_flags() {
let cli = ServeCliArgs {
listen: Some("0.0.0.0:9000".to_string()),
api_key: Some("k".to_string()),
api_key_env: None,
tools: None,
};
let args = cli.into_serve_args();
assert_eq!(args.listen, "0.0.0.0:9000");
assert!(
args.explicit_listen,
"an explicit --listen is honored exactly"
);
assert_eq!(args.api_key.as_deref(), Some("k"));
assert_eq!(args.api_key_env, None);
}
#[test]
fn serve_tools_flag_parses_and_rejects_an_empty_value() {
use clap::Parser;
let cli = crate::cli::Cli::try_parse_from(["symforge", "serve", "--tools", "read,status"])
.expect("--tools parses");
match cli.command {
Some(crate::cli::Commands::Serve(args)) => {
assert_eq!(args.tools.as_deref(), Some("read,status"));
}
_ => panic!("expected the serve subcommand"),
}
assert!(crate::cli::Cli::try_parse_from(["symforge", "serve", "--tools", ""]).is_err());
}
#[test]
fn into_serve_args_defaults_listen_without_explicit_flag() {
let cli = ServeCliArgs {
listen: None,
api_key: None,
api_key_env: None,
tools: None,
};
let args = cli.into_serve_args();
assert_eq!(args.listen, DEFAULT_LISTEN);
assert!(
!args.explicit_listen,
"omitting --listen enables the US1 free-port fallback"
);
}
}