2026-11-08 23:55:00 +01:00
//! The connect screen's "This Mac" tab: where the Codeman on this Mac listens,
//! whether it is installed, its login, and which other Codeman servers of this
//! user run here. The install most people get runs in the app
//! (`gui_install.rs`); the Terminal installs are in `terminal_install.rs`.
2026-11-04 18:02:27 +01:00
use std ::collections ::HashMap ;
use std ::net ::{ Ipv4Addr , SocketAddr , TcpStream };
use std ::path ::{ Path , PathBuf };
use std ::process ::{ Command , Stdio };
use std ::time ::Duration ;
use serde ::Serialize ;
use url ::Url ;
2026-11-06 02:14:58 +01:00
use crate ::gui_install ;
2026-11-04 18:02:27 +01:00
use crate ::local_server ;
use crate ::policy ;
use crate ::probe ::{ self , ProbeOutcome };
2026-11-08 23:55:00 +01:00
use crate ::terminal_install ::LOCAL_SCRIPT_NAME ;
2026-11-04 18:02:27 +01:00
2026-11-06 02:14:58 +01:00
/// Codeman's published installer (a redirect to `install.sh` on master). A test
/// build of an installer change sets `CODEMAN_DESKTOP_INSTALLER_URL` when it is
/// compiled; a shipped app has no way to point this anywhere else, at runtime
/// or otherwise.
pub const INSTALLER_URL : & str = match option_env! ( "CODEMAN_DESKTOP_INSTALLER_URL" ) {
Some ( url ) => url ,
None => "https://getcodeman.com/install" ,
};
/// The branch that test build installs Codeman from (`CODEMAN_BRANCH`).
pub const INSTALL_BRANCH : Option <& str > = option_env! ( "CODEMAN_DESKTOP_INSTALL_BRANCH" );
2026-11-04 18:02:27 +01:00
/// What to paste into a terminal on another machine; the SSH install runs the
/// same thing there.
pub const INSTALL_ONE_LINER : & str = "curl -fsSL https://getcodeman.com/install | bash" ;
/// Codeman's default port, and the first one a fresh install tries.
pub const DEFAULT_PORT : u16 = 3000 ;
2026-11-08 23:57:18 +01:00
/// The username Codeman logs in with when only a password is set
/// (`CODEMAN_USERNAME` unset).
pub const DEFAULT_USERNAME : & str = "admin" ;
2026-11-04 18:02:27 +01:00
/// How many ports above 3000 a fresh install tries when 3000 is taken.
const PORT_SEARCH : u16 = 100 ;
/// The job label both `install.sh` and `codeman service install` use for the
/// default instance (src/config/service-names.ts).
const SERVICE_LABEL : & str = "com.codeman.web" ;
/// The local Codeman's settings, as its LaunchAgent (or LaunchDaemon) runs it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServiceConfig {
pub port : u16 ,
/// `''` or `/codeman`, as Codeman normalizes it (src/config/base-path.ts).
pub base_path : String ,
pub https : bool ,
pub username : Option < String > ,
pub password : Option < String > ,
/// From /Library/LaunchDaemons: a system job, not this user's agent.
pub daemon : bool ,
}
/// Read a launchd job as `plutil -convert json` prints it. The two writers
/// differ: `install.sh` runs a bare `web` and puts the port, base path and
/// password in EnvironmentVariables; `codeman service install` passes
/// `--port`, `--base-url` and `--https` as arguments and keeps no secret in
/// the file. A flag wins over its variable, as in Codeman's CLI (src/cli.ts:
/// the variable is only the flag's default).
pub fn parse_service ( job : & serde_json ::Value ) -> ServiceConfig {
let env = job . get ( "EnvironmentVariables" ). and_then ( | v | v . as_object ());
let var = | key : & str | {
env . and_then ( | e | e . get ( key ))
. and_then ( | v | v . as_str ())
. map ( str ::to_string )
. filter ( | s | ! s . is_empty ())
};
let args : Vec <& str > = job
. get ( "ProgramArguments" )
. and_then ( | v | v . as_array ())
. map ( | a | a . iter (). filter_map ( | v | v . as_str ()). collect ())
. unwrap_or_default ();
// Only what follows the `web` subcommand: node's own flags come before it.
let after_web = args
. iter ()
. position ( | a | * a == "web" )
. map_or ( & [][ .. ], | i | & args [ i + 1 .. ]);
2026-11-06 17:39:12 +01:00
let flags = WebFlags {
port : var ( "CODEMAN_PORT" ),
base : var ( "CODEMAN_BASE_URL" ),
https : false ,
2026-11-04 18:02:27 +01:00
}
2026-11-06 17:39:12 +01:00
. read ( after_web );
2026-11-04 18:02:27 +01:00
ServiceConfig {
2026-11-06 17:39:12 +01:00
port : flags
. port
2026-11-04 18:02:27 +01:00
. and_then ( | p | p . trim (). parse ::< u16 > (). ok ())
. filter ( | p | * p > 0 )
. unwrap_or ( DEFAULT_PORT ),
2026-11-06 17:39:12 +01:00
base_path : normalize_base_path ( flags . base . as_deref (). unwrap_or ( "" )),
https : flags . https ,
2026-11-04 18:02:27 +01:00
username : var ( "CODEMAN_USERNAME" ),
password : var ( "CODEMAN_PASSWORD" ),
daemon : false ,
}
}
2026-11-06 17:39:12 +01:00
/// What Codeman's `web` command takes from the arguments after `web`
/// (src/cli.ts). The fields start as what the environment says, or empty.
#[derive(Debug, Default)]
struct WebFlags {
port : Option < String > ,
base : Option < String > ,
https : bool ,
}
impl WebFlags {
fn read ( mut self , after_web : & [ & str ]) -> Self {
let mut it = after_web . iter ();
while let Some ( arg ) = it . next () {
match * arg {
"-p" | "--port" => self . port = it . next (). map ( | s | s . to_string ()),
"--base-url" => self . base = it . next (). map ( | s | s . to_string ()),
"--https" => self . https = true ,
// Options that take a value: skip it, so it is never read as a flag.
"-H" | "--host" | "--title-hostname" => {
it . next ();
}
other => {
if let Some ( v ) = other . strip_prefix ( "--port=" ) {
self . port = Some ( v . to_string ());
} else if let Some ( v ) = other . strip_prefix ( "--base-url=" ) {
self . base = Some ( v . to_string ());
}
}
}
}
self
}
}
2026-11-04 18:02:27 +01:00
/// Codeman's `normalizeBasePath`, plus its character check: a value Codeman
/// would refuse at startup counts as the root here.
fn normalize_base_path ( input : & str ) -> String {
let mut p = input . trim (). to_string ();
if p . is_empty () || p == "/" {
return String ::new ();
}
if ! p . starts_with ( '/' ) {
p . insert ( 0 , '/' );
}
while p . contains ( "//" ) {
p = p . replace ( "//" , "/" );
}
let p = p . trim_end_matches ( '/' ). to_string ();
let valid = ! p . is_empty ()
&& p . split ( '/' )
. skip ( 1 )
. all ( | seg | ! seg . is_empty () && seg . chars (). all ( | c | c . is_ascii_alphanumeric () || "._~-" . contains ( c )));
if valid {
p
} else {
String ::new ()
}
}
/// Codeman's `parseEnvFile` (src/codeman-credentials.ts): blank lines and `#`
/// comments skipped, an `export ` prefix allowed, one layer of matching quotes
/// stripped, anything else ignored.
pub fn parse_env_file ( text : & str ) -> HashMap < String , String > {
let mut vars = HashMap ::new ();
for raw in text . split ( '\n' ) {
let line = raw . trim ();
if line . is_empty () || line . starts_with ( '#' ) {
continue ;
}
let line = match line . strip_prefix ( "export" ) {
Some ( rest ) if rest . starts_with ( char ::is_whitespace ) => rest . trim_start (),
_ => line ,
};
let Some (( name , value )) = line . split_once ( '=' ) else {
continue ;
};
2026-11-08 23:59:30 +01:00
if ! local_server ::is_env_name ( name ) {
2026-11-04 18:02:27 +01:00
continue ;
}
let mut value = value . trim ();
let quoted =
( value . starts_with ( '"' ) && value . ends_with ( '"' )) || ( value . starts_with ( '\'' ) && value . ends_with ( '\'' ));
if quoted {
// A lone quote reads as empty, as JavaScript's slice(1, -1) does.
value = value . get ( 1 .. value . len () - 1 ). unwrap_or ( "" );
}
vars . insert ( name . to_string (), value . to_string ());
}
vars
}
/// Where the local Codeman answers: its service's port, base path and scheme,
/// else Codeman's defaults. Always 127.0.0.1, which every bind Codeman offers
/// answers on (loopback, all interfaces, and Tailscale serve's target).
pub fn local_url ( service : Option <& ServiceConfig > ) -> Url {
let ( scheme , port , base ) = match service {
Some ( s ) => ( if s . https { "https" } else { "http" }, s . port , s . base_path . as_str ()),
None => ( "http" , DEFAULT_PORT , "" ),
};
Url ::parse ( & format! ( " {scheme} ://127.0.0.1: {port}{base} /" )). expect ( "a valid loopback URL" )
}
/// The login for the Codeman on this Mac, from where it keeps one: its launchd
/// job's environment (which is the server's own), else the data dir's `.env`
/// that Codeman's command-line clients read (src/codeman-credentials.ts).
/// Username and password come from the same place, `admin` by default: the
/// server takes its username from its own environment, so a `.env` username
/// never pairs with the job's password. Only for 127.0.0.1 (the address
/// Codeman binds; `localhost` can be another socket, such as a dev server on
/// `::1`) on the local Codeman's port.
pub fn login_for (
url : & Url ,
service : Option <& ServiceConfig > ,
env_file : & HashMap < String , String > ,
) -> Option < ( String , String ) > {
if url . host () != Some ( url ::Host ::Ipv4 ( Ipv4Addr ::LOCALHOST )) {
return None ;
}
let port = service . map_or ( DEFAULT_PORT , | s | s . port );
if url . port_or_known_default () != Some ( port ) {
return None ;
}
if let Some ( s ) = service {
if let Some ( password ) = & s . password {
2026-11-08 23:57:18 +01:00
let username = s . username . clone (). unwrap_or_else ( || DEFAULT_USERNAME . into ());
2026-11-04 18:02:27 +01:00
return Some (( username , password . clone ()));
}
}
let from_file = | key : & str | env_file . get ( key ). filter ( | v | ! v . is_empty ()). cloned ();
let password = from_file ( "CODEMAN_PASSWORD" ) ? ;
2026-11-08 23:57:18 +01:00
let username = from_file ( "CODEMAN_USERNAME" ). unwrap_or_else ( || DEFAULT_USERNAME . into ());
2026-11-04 18:02:27 +01:00
Some (( username , password ))
}
fn agent_path ( home : & Path ) -> PathBuf {
home . join ( "Library/LaunchAgents" ). join ( format! ( " {SERVICE_LABEL} .plist" ))
}
/// A headless Mac's owner may run Codeman as a system daemon instead.
fn daemon_path () -> PathBuf {
PathBuf ::from ( format! ( "/Library/LaunchDaemons/ {SERVICE_LABEL} .plist" ))
}
/// The local Codeman's launchd job, if there is one this app can read.
pub fn read_service () -> Option < ServiceConfig > {
let home = dirs ::home_dir () ? ;
let agent = agent_path ( & home );
if agent . is_file () {
if let Some ( s ) = read_service_file ( & agent ) {
return Some ( s );
}
}
let daemon = daemon_path ();
if daemon . is_file () {
return read_service_file ( & daemon ). map ( | s | ServiceConfig { daemon : true , .. s });
}
None
}
/// One launchd job file, read with `plutil` (XML or binary plist alike).
fn read_service_file ( path : & Path ) -> Option < ServiceConfig > {
let out = Command ::new ( "/usr/bin/plutil" )
. args ([ "-convert" , "json" , "-o" , "-" ])
. arg ( path )
. stdin ( Stdio ::null ())
. stderr ( Stdio ::null ())
. output ()
. ok () ? ;
if ! out . status . success () {
return None ;
}
let job : serde_json ::Value = serde_json ::from_slice ( & out . stdout ). ok () ? ;
Some ( parse_service ( & job ))
}
fn read_env_file () -> HashMap < String , String > {
dirs ::home_dir ()
. and_then ( | h | std ::fs ::read_to_string ( h . join ( ".codeman/.env" )). ok ())
. map ( | t | parse_env_file ( & t ))
. unwrap_or_default ()
}
/// `login_for` with what is on disk now, and only while one of this user's
/// own Codeman servers holds that port: with Codeman stopped, whatever else
/// listens there (another user's process, say) never gets the password. Runs
/// `plutil`, `ps` and `lsof`, so never on the event loop.
pub fn local_login ( url : & Url ) -> Option < ( String , String ) > {
if url . host () != Some ( url ::Host ::Ipv4 ( Ipv4Addr ::LOCALHOST )) {
return None ;
}
let login = login_for ( url , read_service (). as_ref (), & read_env_file ()) ? ;
let port = url . port_or_known_default () ? ;
let servers = codeman_servers ( & list_processes ());
serves_loopback_port ( & listeners ( & servers ), port ). then_some ( login )
}
/// This user's processes, as `ps` lists them: (pid, command line).
2026-11-06 02:14:58 +01:00
pub fn list_processes () -> Vec < ( u32 , String ) > {
2026-11-04 18:02:27 +01:00
let Ok ( out ) = Command ::new ( "/bin/ps" )
. args ([ "-x" , "-ww" , "-o" , "pid=" , "-o" , "command=" ])
. stdin ( Stdio ::null ())
. stderr ( Stdio ::null ())
. output ()
else {
return Vec ::new ();
};
parse_ps ( & String ::from_utf8_lossy ( & out . stdout ))
}
fn parse_ps ( text : & str ) -> Vec < ( u32 , String ) > {
text . lines ()
. filter_map ( | line | {
let line = line . trim_start ();
let ( pid , command ) = line . split_once ( char ::is_whitespace ) ? ;
Some (( pid . parse (). ok () ? , command . trim (). to_string ()))
})
. collect ()
}
/// Whether a command line is a Codeman server (`codeman web`, the
/// `install.sh` clone's `dist/index.js web`, a source checkout's
/// `src/index.ts web`), not one of its short-lived control commands.
pub fn is_codeman_server ( command : & str ) -> bool {
2026-11-06 17:39:12 +01:00
server_args ( command ). is_some ()
}
2026-11-08 23:59:30 +01:00
/// The last path component of a command-line word.
fn basename ( word : & str ) -> & str {
word . rsplit ( '/' ). next (). unwrap_or ( word )
}
2026-11-06 17:39:12 +01:00
/// What follows `web` on a Codeman server's command line, or None for any
/// other command.
fn server_args ( command : & str ) -> Option < Vec <& str >> {
2026-11-04 18:02:27 +01:00
let words : Vec <& str > = command . split_whitespace (). collect ();
2026-11-06 03:40:53 +01:00
let is_entry = | w : & str | {
2026-11-08 23:59:30 +01:00
let name = basename ( w );
2026-11-04 18:02:27 +01:00
w . ends_with ( "dist/index.js" ) || w . ends_with ( "src/index.ts" ) || name == "codeman" || name == "aicodeman"
2026-11-06 03:40:53 +01:00
};
// Any entry word that `web` follows: an earlier word may only look like
// one (a folder named codeman in `tsx watch --cwd ~/codeman src/index.ts web`).
2026-11-06 17:39:12 +01:00
( 0 .. words . len ())
. find ( |& i | {
is_entry ( words [ i ])
&& words . get ( i + 1 ) == Some ( & "web" )
&& ! words [ i + 1 .. ]. iter (). any ( | w | matches! ( * w , "--stop" | "--status" ))
})
. map ( | i | words [ i + 2 .. ]. to_vec ())
2026-11-04 18:02:27 +01:00
}
/// Whether a command line is an install the app started on this Mac (the
2026-11-06 02:14:58 +01:00
/// Terminal script, the installer it downloaded, or the graphical install), and
/// the port it asked for once the installer runs.
2026-11-04 18:02:27 +01:00
pub fn install_in_progress ( command : & str ) -> Option < Option < u16 >> {
let words : Vec <& str > = command . split_whitespace (). collect ();
2026-11-08 23:59:30 +01:00
let script = format! ( " {LOCAL_SCRIPT_NAME} -" );
2026-11-04 18:02:27 +01:00
if words . iter (). any ( | w | {
2026-11-08 23:59:30 +01:00
let n = basename ( w );
n . starts_with ( & script ) && n . ends_with ( ".command" )
2026-11-04 18:02:27 +01:00
}) {
return Some ( None );
}
2026-11-08 23:59:30 +01:00
if words . iter (). any ( | w | basename ( w ). starts_with ( "codeman-install." )) || gui_install ::Run ::Codeman . matches ( command ) {
2026-11-04 18:02:27 +01:00
let port = words
. iter ()
. position ( | w | * w == "--port" )
. and_then ( | i | words . get ( i + 1 ))
. and_then ( | p | p . parse (). ok ());
return Some ( port );
}
None
}
fn codeman_servers ( procs : & [( u32 , String )]) -> Vec < u32 > {
procs
. iter ()
. filter ( | ( _ , c ) | is_codeman_server ( c ))
. map ( | ( pid , _ ) | * pid )
. collect ()
}
2026-11-06 03:20:01 +01:00
/// The install the app started on this Mac, if one runs, with the port it
/// asked for as soon as one of its processes names it. The Terminal script
/// that wraps the installer names none and is the older process, so the first
/// match alone would report no port for the whole install.
fn running_install ( procs : & [( u32 , String )]) -> Option < Option < u16 >> {
let mut installs = procs . iter (). filter_map ( | ( _ , c ) | install_in_progress ( c )). peekable ();
installs . peek () ? ;
Some ( installs . flatten (). next ())
}
2026-11-04 18:02:27 +01:00
/// A listening TCP socket: its pid, address (`*`, `127.0.0.1`, `[::1]`, a
/// specific IP) and port.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Listener {
pub pid : u32 ,
pub host : String ,
pub port : u16 ,
}
/// What `lsof -F pn` printed: `p<pid>` starts a process, `n<addr>:<port>`
/// names one of its sockets; other fields are ignored.
pub fn parse_lsof ( text : & str ) -> Vec < Listener > {
let mut pid = None ;
let mut found = Vec ::new ();
for line in text . lines () {
if let Some ( p ) = line . strip_prefix ( 'p' ) {
pid = p . parse (). ok ();
} else if let ( Some ( addr ), Some ( pid )) = ( line . strip_prefix ( 'n' ), pid ) {
if let Some (( host , port )) = addr . rsplit_once ( ':' ) {
if let Ok ( port ) = port . parse () {
found . push ( Listener {
pid ,
host : host . to_string (),
port ,
});
}
}
}
}
found
}
/// The TCP ports the given processes listen on.
fn listeners ( pids : & [ u32 ]) -> Vec < Listener > {
if pids . is_empty () {
return Vec ::new ();
}
let list : Vec < String > = pids . iter (). map ( u32 ::to_string ). collect ();
let Ok ( out ) = Command ::new ( "/usr/sbin/lsof" )
. args ([ "-nP" , "-a" , "-iTCP" , "-sTCP:LISTEN" , "-F" , "pn" , "-p" ])
. arg ( list . join ( "," ))
. stdin ( Stdio ::null ())
. stderr ( Stdio ::null ())
. output ()
else {
return Vec ::new ();
};
parse_lsof ( & String ::from_utf8_lossy ( & out . stdout ))
}
/// Whether one of `found` answers 127.0.0.1:`port` (bound to it, or to every
/// interface).
fn serves_loopback_port ( found : & [ Listener ], port : u16 ) -> bool {
found
. iter ()
. any ( | l | l . port == port && matches! ( l . host . as_str (), "*" | "127.0.0.1" | "0.0.0.0" ))
}
2026-11-06 17:39:12 +01:00
/// Where the app can try each of this user's Codeman servers, from their
/// command lines (`procs`) and listening sockets. `default` is the address the
/// app opens by default (local_url); it comes first, then the others by port.
///
/// One address per server and port: 127.0.0.1 when the server listens there
/// or on every interface, `[::1]` when its only loopback socket is the IPv6
/// one, else each address it is bound to. A socket beside a loopback one on
/// the same port is left out (the Docker bridge listener, which serves hook
/// endpoints only). `https` when the command line carries `--https`, and its
/// `--base-url` is the path. `ps` does not show a base path kept in the
/// environment, which is where install.sh's launchd job keeps it, so a server
/// at the default address with no `--base-url` of its own is the default one.
pub fn found_addresses ( procs : & [( u32 , String )], listeners : & [ Listener ], default : & Url ) -> Vec < Url > {
let mut urls : Vec < Url > = Vec ::new ();
for ( pid , command ) in procs {
let Some ( args ) = server_args ( command ) else {
continue ;
};
let flags = WebFlags ::default (). read ( & args );
let scheme = if flags . https { "https" } else { "http" };
let base = flags . base . as_deref (). map ( normalize_base_path );
let own : Vec <& Listener > = listeners . iter (). filter ( | l | l . pid == * pid ). collect ();
for l in & own {
let beside = | hosts : & [ & str ] | own . iter (). any ( | o | o . port == l . port && hosts . contains ( & o . host . as_str ()));
let host = if beside ( & [ "*" , "0.0.0.0" , "[::]" , "127.0.0.1" ]) {
"127.0.0.1"
} else if beside ( & [ "[::1]" ]) {
"[::1]"
} else {
l . host . as_str ()
};
let path = base . as_deref (). unwrap_or ( "" );
let Ok ( mut url ) = Url ::parse ( & format! ( " {scheme} :// {host} : {}{path} /" , l . port )) else {
continue ;
};
if base . is_none () && policy ::same_origin ( & url , default ) {
url = default . clone ();
}
if ! urls . contains ( & url ) {
urls . push ( url );
}
}
}
urls . sort_by_key ( | u | ( u != default , u . port_or_known_default (), u . to_string ()));
urls
}
/// What the This Mac tab says about one found server.
#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase" )]
pub enum FoundState {
/// Codeman answers there: Connect opens it.
Running ,
/// Codeman answers there and wants a login.
NeedsLogin ,
/// It serves HTTPS with a certificate the app refuses (Codeman's own
/// self-signed one, from `codeman web --https`).
Certificate ,
/// Codeman does not answer there.
Unreachable ,
}
/// One of this user's Codeman servers on this Mac, for the This Mac tab's
/// rows.
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase" )]
pub struct FoundServer {
/// Where the app can try it (found_addresses).
pub url : String ,
pub version : Option < String > ,
pub state : FoundState ,
/// It is at the address the app opens by default (local_url).
pub is_default : bool ,
}
/// The row for the server at `url`, from what it answered.
fn found_server ( url : & Url , answer : & ProbeOutcome , default : & Url ) -> FoundServer {
let state = match answer {
ProbeOutcome ::Ok { .. } | ProbeOutcome ::PasswordChangeRequired => FoundState ::Running ,
_ if answers ( answer ) => FoundState ::NeedsLogin ,
// A Codeman started with --https closes a plain http connection.
ProbeOutcome ::TlsUntrusted { .. } | ProbeOutcome ::MaybeHttps => FoundState ::Certificate ,
_ => FoundState ::Unreachable ,
2026-11-04 18:02:27 +01:00
};
2026-11-06 17:39:12 +01:00
FoundServer {
url : url . to_string (),
2026-11-08 23:59:30 +01:00
version : answer . version (),
2026-11-06 17:39:12 +01:00
state ,
is_default : url == default ,
}
}
/// How long a found server gets to answer when the tab only lists it.
const FOUND_TIMEOUT : Duration = Duration ::from_secs ( 2 );
/// Ask the servers at `urls`, all at the same time, so the look takes as long
/// as the slowest answer and no longer. Without a login: the one the app can
/// read belongs to the default address (login_for).
fn ask_found ( urls : & [ Url ], patience : Duration ) -> Vec < ProbeOutcome > {
std ::thread ::scope ( | scope | {
let asking : Vec < _ > = urls
. iter ()
. map ( | url | scope . spawn ( move || probe ::probe_within ( url , None , patience )))
. collect ();
asking
. into_iter ()
. map ( | a | {
a . join (). unwrap_or_else ( | _ | ProbeOutcome ::Failed {
detail : "The check stopped." . into (),
})
})
. collect ()
})
}
/// The address the This Mac tab is about, with its answer: the default one,
/// or, when nothing answers there, the first found server that does (a
/// `codeman web --port 4000` in a terminal, a bind to one network address).
fn shown < 'a > (
default : & 'a Url ,
answer : & 'a ProbeOutcome ,
found : & 'a [( Url , ProbeOutcome )],
) -> ( & 'a Url , & 'a ProbeOutcome ) {
if * answer == ProbeOutcome ::Refused {
if let Some (( url , answer )) = found . iter (). find ( | ( _ , a ) | answers ( a )) {
return ( url , answer );
}
}
( default , answer )
2026-11-04 18:02:27 +01:00
}
/// What the This Mac tab shows.
#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase" )]
pub enum LocalState {
/// Codeman answers, and the app has its login if it needs one.
Running ,
/// Codeman answers but wants a login the app does not have.
NeedsLogin ,
2026-11-06 03:40:53 +01:00
/// A Codeman server of this user runs but listens nowhere yet: it is
/// still starting (the LaunchAgent at login, a restart).
Starting ,
2026-11-06 17:39:12 +01:00
/// A Codeman server of this user runs, but none answers at an address the
/// app can open (HTTPS with Codeman's own certificate, say): see `found`.
2026-11-04 18:02:27 +01:00
RunningElsewhere ,
/// Nothing answers, and Codeman is installed.
Stopped ,
/// Nothing answers, and Codeman is not installed (or, in a quick check,
/// not installed by `install.sh`).
NotInstalled ,
/// Something else happened at that address: see `outcome`.
Other ,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase" )]
pub struct LocalStatus {
/// Where the local Codeman answers, or would.
pub url : String ,
pub state : LocalState ,
pub version : Option < String > ,
/// A launchd job runs Codeman here.
pub service : bool ,
/// That job is a system LaunchDaemon, which only an administrator starts.
pub daemon : bool ,
/// Codeman is on this Mac: it answers or runs, `install.sh` left its
/// files or a launchd job, or (not in a quick check) the login shell
/// finds it.
pub installed : bool ,
/// `install.sh` finished its work (its `.install-complete` marker).
pub install_complete : bool ,
2026-11-06 02:14:58 +01:00
/// An install the app started is still running, and the port it asked
/// for once that is known.
2026-11-04 18:02:27 +01:00
pub install_running : bool ,
pub install_port : Option < u16 > ,
2026-11-06 02:14:58 +01:00
/// That install is the graphical one, not a Terminal window: the page can
/// show it (gui_install::follow), also after the app was quit.
pub install_in_app : bool ,
2026-11-06 13:23:56 +01:00
/// A coding agent is being added the same way. Not an install: it says
/// nothing about Codeman, which may well be running.
pub agent_install_in_app : bool ,
2026-11-06 17:39:12 +01:00
/// Every Codeman server of this user that listens on this Mac, the one at
/// the default address first: the tab offers to connect to each.
pub found : Vec < FoundServer > ,
2026-11-04 18:02:27 +01:00
/// The probe's outcome, for the connect page's explanations.
pub outcome : ProbeOutcome ,
}
2026-11-06 03:40:53 +01:00
/// Whether the probe got an answer from a Codeman server, logged in or not.
fn answers ( outcome : & ProbeOutcome ) -> bool {
matches! (
outcome ,
ProbeOutcome ::Ok { .. }
| ProbeOutcome ::PasswordChangeRequired
| ProbeOutcome ::NeedsLogin
| ProbeOutcome ::BadCredentials
| ProbeOutcome ::RateLimited { .. }
)
}
/// What the This Mac tab shows for what `inspect` found. `server_runs`: one of
/// this user's Codeman server processes exists. `server_listens`: one of them
/// has a listening socket. `installed`: Codeman is on this Mac.
fn local_state ( outcome : & ProbeOutcome , server_runs : bool , server_listens : bool , installed : bool ) -> LocalState {
match outcome {
ProbeOutcome ::Ok { .. } | ProbeOutcome ::PasswordChangeRequired => LocalState ::Running ,
_ if answers ( outcome ) => LocalState ::NeedsLogin ,
ProbeOutcome ::Refused if server_runs && ! server_listens => LocalState ::Starting ,
ProbeOutcome ::Refused if server_runs => LocalState ::RunningElsewhere ,
ProbeOutcome ::Refused if installed => LocalState ::Stopped ,
ProbeOutcome ::Refused => LocalState ::NotInstalled ,
_ => LocalState ::Other ,
}
}
2026-11-04 18:02:27 +01:00
/// How hard `inspect` looks for an installed Codeman when nothing answers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Depth {
/// Files and processes only (while an install runs).
Quick ,
/// Also the login shell (`-l`), as every automatic look does.
Login ,
/// Also the interactive profile (`-i`), on the user's Check again.
Interactive ,
}
/// Look at the Codeman on this Mac.
pub fn inspect ( depth : Depth ) -> LocalStatus {
let home = dirs ::home_dir (). unwrap_or_default ();
let service = read_service ();
2026-11-06 17:39:12 +01:00
let default = local_url ( service . as_ref ());
2026-11-04 18:02:27 +01:00
let procs = list_processes ();
let servers = codeman_servers ( & procs );
2026-11-06 17:39:12 +01:00
let listening = listeners ( & servers );
2026-11-06 03:20:01 +01:00
let install = running_install ( & procs );
2026-11-06 13:23:56 +01:00
let install_in_app = procs . iter (). any ( | ( _ , c ) | gui_install ::Run ::Codeman . matches ( c ));
let agent_install_in_app = procs . iter (). any ( | ( _ , c ) | gui_install ::Run ::Agent . matches ( c ));
2026-11-04 18:02:27 +01:00
// The login goes only to this user's own Codeman on that port.
2026-11-06 17:39:12 +01:00
let auth = if serves_loopback_port ( & listening , default . port_or_known_default (). unwrap_or ( 0 )) {
login_for ( & default , service . as_ref (), & read_env_file ()). map ( | ( u , p ) | policy ::basic_auth_header ( & u , & p ))
2026-11-04 18:02:27 +01:00
} else {
None
};
2026-11-06 17:39:12 +01:00
let answer = probe ::probe ( & default , auth . as_deref ());
2026-11-04 18:02:27 +01:00
2026-11-08 23:59:30 +01:00
// The other addresses this user's Codeman servers listen at, asked once
// each. With nothing at the default address, the first that answers is
// what the tab opens (`shown`), so each gets the probe's usual time;
// otherwise they are only listed, and get less.
2026-11-06 17:39:12 +01:00
let patience = if answer == ProbeOutcome ::Refused {
probe ::TIMEOUT
} else {
FOUND_TIMEOUT
};
let addresses = found_addresses ( & procs , & listening , & default );
let others : Vec < Url > = addresses . iter (). filter ( | u | ** u != default ). cloned (). collect ();
let mut answered : Vec < ( Url , ProbeOutcome ) > = others . iter (). cloned (). zip ( ask_found ( & others , patience )). collect ();
// found_addresses puts the default address first.
if addresses . first () == Some ( & default ) {
answered . insert ( 0 , ( default . clone (), answer . clone ()));
2026-11-04 18:02:27 +01:00
}
2026-11-06 17:39:12 +01:00
let found : Vec < FoundServer > = answered . iter (). map ( | ( u , a ) | found_server ( u , a , & default )). collect ();
// The tab never offers to start a second server on the same sessions: it
// opens the one that answers, or lists where they listen.
let ( url , outcome ) = shown ( & default , & answer , & answered );
let ( url , outcome ) = ( url . clone (), outcome . clone ());
2026-11-04 18:02:27 +01:00
let app = home . join ( ".codeman/app" );
let install_complete = app . join ( ".install-complete" ). is_file ();
// Something else on Codeman's port (a dev server on 3000, say) says
// nothing about whether Codeman is installed, so look either way.
let on_disk = install_complete
|| app . join ( "dist/index.js" ). is_file ()
|| agent_path ( & home ). is_file ()
|| daemon_path (). is_file ();
2026-11-06 03:40:53 +01:00
let installed = answers ( & outcome )
2026-11-04 18:02:27 +01:00
|| ! servers . is_empty ()
|| on_disk
|| match depth {
Depth ::Quick => false ,
Depth ::Login => local_server ::installed ( false ),
Depth ::Interactive => local_server ::installed ( true ),
};
2026-11-06 17:39:12 +01:00
let state = local_state ( & outcome , ! servers . is_empty (), ! listening . is_empty (), installed );
2026-11-08 23:59:30 +01:00
let version = outcome . version ();
2026-11-04 18:02:27 +01:00
LocalStatus {
url : url . to_string (),
state ,
version ,
service : service . is_some (),
daemon : service . as_ref (). is_some_and ( | s | s . daemon ),
installed ,
install_complete ,
install_running : install . is_some (),
install_port : install . flatten (),
2026-11-06 02:14:58 +01:00
install_in_app ,
2026-11-06 13:23:56 +01:00
agent_install_in_app ,
2026-11-06 17:39:12 +01:00
found ,
2026-11-04 18:02:27 +01:00
outcome ,
}
}
/// Why the app will not start a server: one of this user's Codeman servers
/// already runs. A second one on the same data dir and tmux socket would
/// attach to the first one's live sessions (src/config/instance.ts), and
/// `codeman web -d` only notices a server it started itself or one at the
/// same address.
2026-11-06 02:14:58 +01:00
pub fn already_running () -> Option < String > {
2026-11-04 18:02:27 +01:00
let servers = codeman_servers ( & list_processes ());
let pid = servers . first () ? ;
let found = listeners ( & servers );
let at : Vec < String > = found . iter (). map ( | l | format! ( " {} : {} " , l . host , l . port )). collect ();
let where_ = if at . is_empty () {
format! ( "process {pid} " )
} else {
at . join ( ", " )
};
Some ( format! (
"A Codeman server is already running on this Mac ( {where_} ). Starting another one would take over its sessions: connect to it instead, or stop it first."
))
}
2026-11-06 03:20:01 +01:00
/// Whether `url` is where the launchd job `service` answers: its scheme and
/// port on this Mac, under `localhost` as much as 127.0.0.1. The path is left
/// out: a job with a base path answers below `/` too, and a second server on
/// its port would run without the job's settings.
fn served_by ( service : & ServiceConfig , url : & Url ) -> bool {
let at = local_url ( Some ( service ));
policy ::is_loopback ( url ) && url . scheme () == at . scheme () && url . port_or_known_default () == at . port_or_known_default ()
}
2026-11-04 18:02:27 +01:00
/// Start the Codeman on this Mac for `url`. A LaunchAgent that serves that
/// address is started through launchd, so it runs with its own settings
/// (host, password) and stays supervised; anything else gets `codeman web -d`
/// (local_server::start). Never while one of this user's Codeman servers runs.
pub fn start_local ( url : & Url ) -> Result < String , String > {
if let Some ( why ) = already_running () {
return Err ( why );
}
match read_service () {
2026-11-06 03:20:01 +01:00
Some ( s ) if served_by ( & s , url ) => {
2026-11-04 18:02:27 +01:00
if s . daemon {
return Err ( format! (
"A system LaunchDaemon runs Codeman on this Mac; an administrator starts it: sudo launchctl kickstart -k system/ {SERVICE_LABEL} "
));
}
start_launch_agent ( s . port )
}
_ => local_server ::start ( url ),
}
}
/// `launchctl kickstart` the LaunchAgent if launchd has it loaded, else
/// `bootstrap` it, then wait until its port takes connections (a TCP connect,
/// never an HTTP request, which a password-protected server would count as a
/// failed login).
fn start_launch_agent ( port : u16 ) -> Result < String , String > {
let home = dirs ::home_dir (). ok_or ( "No home folder." ) ? ;
let plist = agent_path ( & home );
let uid = Command ::new ( "/usr/bin/id" )
. arg ( "-u" )
. output ()
. ok ()
. and_then ( | o | String ::from_utf8 ( o . stdout ). ok ())
. and_then ( | s | s . trim (). parse ::< u32 > (). ok ())
. ok_or ( "Could not find the user id." ) ? ;
let domain = format! ( "gui/ {uid} " );
let target = format! ( " {domain} / {SERVICE_LABEL} " );
let launchctl = | args : & [ & str ] | {
Command ::new ( "/bin/launchctl" )
. args ( args )
. stdin ( Stdio ::null ())
. stdout ( Stdio ::null ())
. stderr ( Stdio ::piped ())
. output ()
};
let loaded = launchctl ( & [ "print" , & target ]). is_ok_and ( | o | o . status . success ());
let plist_arg = plist . to_string_lossy (). to_string ();
let run = if loaded {
launchctl ( & [ "kickstart" , "-k" , & target ])
} else {
launchctl ( & [ "bootstrap" , & domain , & plist_arg ])
};
match run {
Ok ( o ) if o . status . success () => {}
Ok ( o ) => {
let said = String ::from_utf8_lossy ( & o . stderr ). trim (). to_string ();
return Err ( format! ( "launchd did not start Codeman: {said} " ));
}
Err ( e ) => return Err ( format! ( "Could not run launchctl: {e} " )),
}
let deadline = std ::time ::Instant ::now () + Duration ::from_secs ( 30 );
while std ::time ::Instant ::now () < deadline {
if ! port_free ( port ) {
return Ok ( format! ( "launchd started Codeman ( {SERVICE_LABEL} )." ));
}
2026-11-06 03:40:53 +01:00
std ::thread ::sleep ( Duration ::from_millis ( 100 ));
2026-11-04 18:02:27 +01:00
}
Err ( "launchd started Codeman, but it did not answer within 30 seconds. Its log is /tmp/codeman.log for an install.sh setup." . into ())
}
/// Whether nothing listens on 127.0.0.1:`port`.
fn port_free ( port : u16 ) -> bool {
let addr = SocketAddr ::from (( Ipv4Addr ::LOCALHOST , port ));
match TcpStream ::connect_timeout ( & addr , Duration ::from_millis ( 300 )) {
Ok ( _ ) => false ,
Err ( e ) => e . kind () == std ::io ::ErrorKind ::ConnectionRefused ,
}
}
/// The port a fresh install listens on: 3000 when it is free, else the first
/// free one above it. 3000 is also where most web dev servers run.
pub fn pick_install_port () -> u16 {
pick_port ( port_free )
}
fn pick_port ( free : impl Fn ( u16 ) -> bool ) -> u16 {
( DEFAULT_PORT .. DEFAULT_PORT + PORT_SEARCH )
. find ( | p | free ( * p ))
. unwrap_or ( DEFAULT_PORT )
}
#[cfg(test)]
mod tests {
use super ::* ;
use serde_json ::json ;
fn u ( s : & str ) -> Url {
Url ::parse ( s ). unwrap ()
}
#[test]
fn install_sh_service_reads_from_its_environment () {
let job = json! ({
"Label" : "com.codeman.web" ,
"ProgramArguments" : [ "/opt/homebrew/bin/node" , "/Users/k/.codeman/app/dist/index.js" , "web" ],
"EnvironmentVariables" : {
"PATH" : "/opt/homebrew/bin:/usr/bin" ,
"CODEMAN_HOST" : "0.0.0.0" ,
"CODEMAN_PASSWORD" : "s3cret" ,
"CODEMAN_PORT" : "3001" ,
"CODEMAN_BASE_URL" : "/codeman/"
}
});
let s = parse_service ( & job );
assert_eq! ( s . port , 3001 );
assert_eq! ( s . base_path , "/codeman" );
assert! ( ! s . https );
assert_eq! ( s . password . as_deref (), Some ( "s3cret" ));
assert_eq! ( s . username , None );
assert_eq! ( local_url ( Some ( & s )). as_str (), "http://127.0.0.1:3001/codeman/" );
}
/// The real file shapes through the real plutil: install.sh's template
/// (an XML-escaped password, booleans and an integer plutil must carry
/// into JSON) and `codeman service install`'s.
#[cfg(target_os = "macos" )]
#[test]
fn plutil_reads_both_launch_agent_shapes () {
2026-11-08 23:55:00 +01:00
let dir = std ::env ::temp_dir (). join ( format! ( "codeman-plist-test- {} " , std ::process ::id ()));
2026-11-04 18:02:27 +01:00
std ::fs ::create_dir_all ( & dir ). unwrap ();
let install_sh = r #"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.codeman.web</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/node</string>
<string>/Users/k/.codeman/app/dist/index.js</string>
<string>web</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
<key>HOME</key>
<string>/Users/k</string>
<key>LANG</key>
<string>en_US.UTF-8</string>
<key>CODEMAN_HOST</key>
<string>0.0.0.0</string>
<key>CODEMAN_PASSWORD</key>
<string>p&w<"x'</string>
<key>CODEMAN_PORT</key>
<string>3002</string>
</dict>
<key>WorkingDirectory</key>
<string>/Users/k</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>ThrottleInterval</key>
<integer>10</integer>
<key>StandardOutPath</key>
<string>/tmp/codeman.log</string>
</dict>
</plist>
"# ;
let a = dir . join ( "install-sh.plist" );
std ::fs ::write ( & a , install_sh ). unwrap ();
let s = read_service_file ( & a ). expect ( "plutil read the install.sh agent" );
assert_eq! ( s . port , 3002 );
assert_eq! ( s . password . as_deref (), Some ( "p&w< \" x'" ));
assert_eq! ( local_url ( Some ( & s )). as_str (), "http://127.0.0.1:3002/" );
let service = install_sh
. replace (
"<string>web</string>" ,
"<string>web</string> \n <string>--host</string> \n <string>127.0.0.1</string> \n <string>--port</string> \n <string>4100</string> \n <string>--base-url</string> \n <string>/cm</string>" ,
)
. replace ( "<key>CODEMAN_PASSWORD</key> \n <string>p&w< \" x'</string> \n " , "" );
let b = dir . join ( "service.plist" );
std ::fs ::write ( & b , service ). unwrap ();
let s = read_service_file ( & b ). expect ( "plutil read the service-install agent" );
assert_eq! (
( s . port , s . base_path . as_str (), s . password . as_deref ()),
( 4100 , "/cm" , None )
);
assert! ( read_service_file ( & dir . join ( "missing.plist" )). is_none ());
std ::fs ::write ( dir . join ( "broken.plist" ), "<plist><dict><key>x" ). unwrap ();
assert! ( read_service_file ( & dir . join ( "broken.plist" )). is_none ());
let _ = std ::fs ::remove_dir_all ( & dir );
}
#[test]
fn service_install_reads_its_arguments_and_flags_win () {
let job = json! ({
"ProgramArguments" : [
"/usr/local/bin/node" , "--max-old-space-size=4096" , "/opt/codeman/dist/index.js" ,
"web" , "--host" , "--port" , "--port" , "4100" , "--https" , "--base-url" , "x//y/"
],
"EnvironmentVariables" : { "CODEMAN_PORT" : "3005" , "HOME" : "/Users/k" }
});
let s = parse_service ( & job );
// --host takes "--port" as its value; the real --port follows it.
assert_eq! ( s . port , 4100 );
assert! ( s . https );
assert_eq! ( s . base_path , "/x/y" );
assert_eq! ( s . password , None );
assert_eq! ( local_url ( Some ( & s )). as_str (), "https://127.0.0.1:4100/x/y/" );
let eq = parse_service ( & json! ({ "ProgramArguments" : [ "node" , "i.js" , "web" , "--port=4200" , "--base-url=/a" ] }));
assert_eq! (( eq . port , eq . base_path . as_str ()), ( 4200 , "/a" ));
}
#[test]
fn service_defaults_and_bad_values () {
let s = parse_service ( & json! ({}));
assert_eq! (( s . port , s . base_path . as_str (), s . https ), ( DEFAULT_PORT , "" , false ));
assert_eq! ( local_url ( None ). as_str (), "http://127.0.0.1:3000/" );
let bad = parse_service ( & json! ({
"EnvironmentVariables" : { "CODEMAN_PORT" : "0" , "CODEMAN_BASE_URL" : "/a b" , "CODEMAN_PASSWORD" : "" }
}));
assert_eq! (( bad . port , bad . base_path . as_str ()), ( DEFAULT_PORT , "" ));
assert_eq! ( bad . password , None );
assert_eq! (
parse_service ( & json! ({ "ProgramArguments" : [ "web" , "--port" , "99999" ]})). port ,
DEFAULT_PORT
);
// Before `web` is node's business, not Codeman's.
assert_eq! (
parse_service ( & json! ({ "ProgramArguments" : [ "--port" , "1" , "x.js" , "web" ]})). port ,
DEFAULT_PORT
);
}
#[test]
fn base_path_matches_codeman () {
assert_eq! ( normalize_base_path ( "" ), "" );
assert_eq! ( normalize_base_path ( "/" ), "" );
assert_eq! ( normalize_base_path ( "codeman" ), "/codeman" );
assert_eq! ( normalize_base_path ( "//codeman//" ), "/codeman" );
assert_eq! ( normalize_base_path ( "/a/b.c~_-/" ), "/a/b.c~_-" );
assert_eq! ( normalize_base_path ( "/a?x" ), "" );
assert_eq! ( normalize_base_path ( "/%2e" ), "" );
}
#[test]
fn env_file_like_codeman () {
let vars = parse_env_file (
"# comment \n\n export CODEMAN_PASSWORD= \" pa ss \"\n CODEMAN_USERNAME='kay' \r\n\
BAD-NAME=1 \n exportX=2 \n EMPTY= \n Q= \"\n not an assignment \n " ,
);
assert_eq! ( vars . get ( "CODEMAN_PASSWORD" ). map ( String ::as_str ), Some ( "pa ss" ));
assert_eq! ( vars . get ( "CODEMAN_USERNAME" ). map ( String ::as_str ), Some ( "kay" ));
assert_eq! ( vars . get ( "exportX" ). map ( String ::as_str ), Some ( "2" ));
assert_eq! ( vars . get ( "EMPTY" ). map ( String ::as_str ), Some ( "" ));
assert_eq! ( vars . get ( "Q" ). map ( String ::as_str ), Some ( "" ));
assert! ( ! vars . contains_key ( "BAD-NAME" ));
}
fn service ( port : u16 , user : Option <& str > , pass : Option <& str > ) -> ServiceConfig {
ServiceConfig {
port ,
base_path : String ::new (),
https : false ,
username : user . map ( Into ::into ),
password : pass . map ( Into ::into ),
daemon : false ,
}
}
#[test]
fn local_login_only_for_the_local_codeman () {
let none = HashMap ::new ();
let file : HashMap < String , String > = [( "CODEMAN_PASSWORD" , "fromfile" ), ( "CODEMAN_USERNAME" , "kay" )]
. into_iter ()
. map ( | ( k , v ) | ( k . to_string (), v . to_string ()))
. collect ();
let svc = service ( 3001 , None , Some ( "svc" ));
// The service's password, with the service's username or admin: never
// the file's username, which the server does not read.
assert_eq! (
login_for ( & u ( "http://127.0.0.1:3001/" ), Some ( & svc ), & file ),
Some (( "admin" . into (), "svc" . into ()))
);
assert_eq! (
login_for (
& u ( "http://127.0.0.1:3001/x/" ),
Some ( & service ( 3001 , Some ( "ops" ), Some ( "svc" ))),
& file
),
Some (( "ops" . into (), "svc" . into ()))
);
// No password in the service: the file's pair.
assert_eq! (
login_for ( & u ( "http://127.0.0.1:3001/" ), Some ( & service ( 3001 , None , None )), & file ),
Some (( "kay" . into (), "fromfile" . into ()))
);
// Only 127.0.0.1 itself, on the service's port.
for other in [
"http://localhost:3001/" ,
"http://127.0.0.2:3001/" ,
"http://[::1]:3001/" ,
"http://127.0.0.1:3000/" ,
"http://192.168.1.5:3001/" ,
"https://box.ts.net/" ,
] {
assert_eq! ( login_for ( & u ( other ), Some ( & svc ), & file ), None , "{other}" );
}
assert_eq! ( login_for ( & u ( "http://127.0.0.1:3000/" ), None , & none ), None );
// No service: Codeman's default port.
assert_eq! (
login_for ( & u ( "http://127.0.0.1:3000/" ), None , & file ),
Some (( "kay" . into (), "fromfile" . into ()))
);
}
2026-11-06 03:20:01 +01:00
#[test]
fn a_start_goes_to_the_launchd_job_that_serves_the_address () {
let job = parse_service ( & json! ({
"ProgramArguments" : [ "node" , "i.js" , "web" ],
"EnvironmentVariables" : { "CODEMAN_PORT" : "3001" , "CODEMAN_BASE_URL" : "/codeman" }
}));
// The app's own address for it, and what a user types for the same server.
assert! ( served_by ( & job , & u ( "http://127.0.0.1:3001/codeman/" )));
assert! ( served_by ( & job , & u ( "http://localhost:3001/codeman/" )));
assert! ( served_by ( & job , & u ( "http://LOCALHOST:3001/" )));
// Another port, scheme or machine is not this job's server.
assert! ( ! served_by ( & job , & u ( "http://127.0.0.1:3000/codeman/" )));
assert! ( ! served_by ( & job , & u ( "https://127.0.0.1:3001/codeman/" )));
assert! ( ! served_by ( & job , & u ( "http://192.168.1.5:3001/codeman/" )));
assert! ( ! served_by ( & job , & u ( "http://localhost.example.com:3001/" )));
let https = parse_service ( & json! ({ "ProgramArguments" : [ "node" , "i.js" , "web" , "--https" ] }));
assert! ( served_by ( & https , & u ( "https://localhost:3000/" )));
assert! ( ! served_by ( & https , & u ( "http://localhost:3000/" )));
}
2026-11-06 03:40:53 +01:00
#[test]
fn this_mac_state_for_what_was_found () {
let ok = ProbeOutcome ::Ok {
version : "1.48.0" . into (),
};
// Whatever else is true, a Codeman that answers is what the tab shows.
for ( runs , listens , installed ) in [( false , false , false ), ( true , true , true ), ( true , false , false )] {
assert_eq! ( local_state ( & ok , runs , listens , installed ), LocalState ::Running );
assert_eq! (
local_state ( & ProbeOutcome ::PasswordChangeRequired , runs , listens , installed ),
LocalState ::Running
);
for login in [
ProbeOutcome ::NeedsLogin ,
ProbeOutcome ::BadCredentials ,
ProbeOutcome ::RateLimited {
sent_credentials : false ,
retry_after_secs : None ,
},
] {
assert_eq! ( local_state ( & login , runs , listens , installed ), LocalState ::NeedsLogin );
}
}
// Nothing answers. A server process with no socket yet is starting,
// which comes before "runs somewhere else": the app must not send the
// user to another address for a server that is two seconds from up.
let refused = ProbeOutcome ::Refused ;
assert_eq! ( local_state ( & refused , true , false , true ), LocalState ::Starting );
assert_eq! ( local_state ( & refused , true , false , false ), LocalState ::Starting );
assert_eq! ( local_state ( & refused , true , true , true ), LocalState ::RunningElsewhere );
assert_eq! ( local_state ( & refused , false , false , true ), LocalState ::Stopped );
assert_eq! ( local_state ( & refused , false , false , false ), LocalState ::NotInstalled );
// Something else holds the port, or the look itself failed.
for other in [
ProbeOutcome ::NotCodeman { status : 404 },
ProbeOutcome ::Timeout ,
ProbeOutcome ::MaybeHttps ,
] {
assert_eq! ( local_state ( & other , true , true , true ), LocalState ::Other );
assert_eq! ( local_state ( & other , false , false , false ), LocalState ::Other );
}
assert! ( answers ( & ProbeOutcome ::BadCredentials ) && ! answers ( & refused ));
}
2026-11-04 18:02:27 +01:00
#[test]
fn processes_and_listeners () {
let ps = " 101 /opt/homebrew/bin/node /Users/k/.codeman/app/dist/index.js web \n\
202 node /opt/homebrew/bin/codeman web --port 4000 \n\
303 /usr/local/bin/node --require /x/tsx/preflight.cjs --import file:///x/loader.mjs src/index.ts web \n\
404 node /opt/homebrew/bin/codeman web --stop \n\
505 node /opt/homebrew/bin/codeman attach w1 \n\
606 /bin/zsh -l \n\
707 vim dist/index.js \n\
808 /bin/bash /var/folders/x/T/install-codeman-local-55-0.command \n\
909 bash /var/folders/x/T/codeman-install.Ab12Cd --local --service --port 3001 \n\
1001 /bin/bash /var/folders/x/T/install-codeman-remote-55-1.command \n\
garbage line \n " ;
2026-11-06 03:40:53 +01:00
// A folder named like the command comes before the real entry point.
assert! ( is_codeman_server (
"node /x/tsx/cli.mjs watch --cwd /Users/k/codeman src/index.ts web"
));
assert! ( is_codeman_server (
"node --watch-path /Users/k/codeman /Users/k/codeman/src/index.ts web --port 3001"
));
assert! ( ! is_codeman_server ( "node /Users/k/codeman/scripts/build.mjs web" ));
assert! ( ! is_codeman_server ( "/opt/homebrew/bin/codeman attach web" ));
2026-11-04 18:02:27 +01:00
let procs = parse_ps ( ps );
assert_eq! (
procs [ 0 ],
(
101 ,
"/opt/homebrew/bin/node /Users/k/.codeman/app/dist/index.js web" . to_string ()
)
);
assert_eq! ( codeman_servers ( & procs ), [ 101 , 202 , 303 ]);
let installs : Vec < Option < u16 >> = procs . iter (). filter_map ( | ( _ , c ) | install_in_progress ( c )). collect ();
assert_eq! ( installs , [ None , Some ( 3001 )]);
2026-11-06 03:20:01 +01:00
// The Terminal script comes first and names no port: the installer's wins.
assert_eq! ( running_install ( & procs ), Some ( Some ( 3001 )));
// Before the installer is downloaded, only the script runs.
assert_eq! ( running_install ( & procs [ .. 8 ]), Some ( None ));
assert_eq! ( running_install ( & procs [ .. 7 ]), None );
2026-11-04 18:02:27 +01:00
let lsof = "p101 \n f21 \n n127.0.0.1:3000 \n f22 \n n172.17.0.1:3999 \n p202 \n f9 \n n*:4000 \n p303 \n n[::1]:5000 \n nbogus \n " ;
let found = parse_lsof ( lsof );
assert_eq! ( found . len (), 4 );
assert_eq! (
found [ 0 ],
Listener {
pid : 101 ,
host : "127.0.0.1" . into (),
port : 3000
}
);
assert_eq! (
found [ 2 ],
Listener {
pid : 202 ,
host : "*" . into (),
port : 4000
}
);
assert_eq! (
found [ 3 ],
Listener {
pid : 303 ,
host : "[::1]" . into (),
port : 5000
}
);
assert! ( serves_loopback_port ( & found , 3000 ));
assert! ( serves_loopback_port ( & found , 4000 ));
assert! ( ! serves_loopback_port ( & found , 3999 ));
assert! ( ! serves_loopback_port ( & found , 5000 ));
2026-11-06 17:39:12 +01:00
// The same four sockets as the addresses the app can try, by port.
assert_eq! (
addresses ( & procs , & found , "http://127.0.0.1:3000/" ),
[
"http://127.0.0.1:3000/" ,
"http://172.17.0.1:3999/" ,
"http://127.0.0.1:4000/" ,
"http://[::1]:5000/"
]
);
}
fn server ( pid : u32 , flags : & str ) -> ( u32 , String ) {
( pid , format! ( "node /opt/homebrew/bin/codeman web {flags} " ))
}
fn listener ( pid : u32 , host : & str , port : u16 ) -> Listener {
Listener {
pid ,
host : host . into (),
port ,
}
}
/// found_addresses, as strings. The page sends one back in a `connect`,
/// so each must be an address the connect takes as it is: the app saves
/// a server, and finds its saved login, under that exact string.
fn addresses ( procs : & [( u32 , String )], listeners : & [ Listener ], default : & str ) -> Vec < String > {
found_addresses ( procs , listeners , & u ( default ))
. iter ()
. map ( | url | {
assert_eq! ( policy ::normalize_server_url ( url . as_str ()). as_ref (), Ok ( url ));
url . to_string ()
})
. collect ()
}
#[test]
fn a_found_server_becomes_an_address_the_app_can_try () {
let default = "http://127.0.0.1:3000/" ;
let one = | flags : & str , listeners : & [ Listener ] | addresses ( & [ server ( 1 , flags )], listeners , default );
// Every interface and IPv4 loopback are reached at 127.0.0.1.
for host in [ "*" , "0.0.0.0" , "[::]" , "127.0.0.1" ] {
assert_eq! (
one ( " --port 4000" , & [ listener ( 1 , host , 4000 )]),
[ "http://127.0.0.1:4000/" ],
"{host}"
);
}
// IPv6 loopback keeps its own address only when it is the server's
// only loopback socket.
assert_eq! ( one ( "" , & [ listener ( 1 , "[::1]" , 5000 )]), [ "http://[::1]:5000/" ]);
assert_eq! (
one ( "" , & [ listener ( 1 , "[::1]" , 5000 ), listener ( 1 , "127.0.0.1" , 5000 )]),
[ "http://127.0.0.1:5000/" ]
);
// A dual-stack bind shows as two sockets, both `*`: one address.
assert_eq! (
one ( "" , & [ listener ( 1 , "*" , 5000 ), listener ( 1 , "*" , 5000 )]),
[ "http://127.0.0.1:5000/" ]
);
// A bind to one address stays that address.
assert_eq! (
one ( " --host 192.168.1.5" , & [ listener ( 1 , "192.168.1.5" , 3000 )]),
[ "http://192.168.1.5:3000/" ]
);
// --https and --base-url come from the command line, in both spellings.
assert_eq! (
one ( " --https --port 4000 --base-url /codeman/" , & [ listener ( 1 , "*" , 4000 )]),
[ "https://127.0.0.1:4000/codeman/" ]
);
assert_eq! (
one ( " -p 4000 --base-url=cm" , & [ listener ( 1 , "127.0.0.1" , 4000 )]),
[ "http://127.0.0.1:4000/cm/" ]
);
// The value of --host is never read as a flag, and a base path Codeman
// would refuse counts as none.
assert_eq! (
one ( " --host --https -p 4000" , & [ listener ( 1 , "127.0.0.1" , 4000 )]),
[ "http://127.0.0.1:4000/" ]
);
assert_eq! (
one ( " -p 4000 --base-url /a?b" , & [ listener ( 1 , "127.0.0.1" , 4000 )]),
[ "http://127.0.0.1:4000/" ]
);
// What comes before `web` is node's business.
assert_eq! (
addresses (
& [( 1 , "node --https /Users/k/.codeman/app/dist/index.js web" . to_string ())],
& [ listener ( 1 , "*" , 4000 )],
default
),
[ "http://127.0.0.1:4000/" ]
);
// A server with two listeners. Beside a loopback socket on the same
// port, another one is the same server (the Docker bridge listener);
// on another port, or with no loopback socket, each is an address.
assert_eq! (
one ( "" , & [ listener ( 1 , "127.0.0.1" , 3001 ), listener ( 1 , "172.17.0.1" , 3001 )]),
[ "http://127.0.0.1:3001/" ]
);
assert_eq! (
one ( "" , & [ listener ( 1 , "172.17.0.1" , 3999 ), listener ( 1 , "127.0.0.1" , 3001 )]),
[ "http://127.0.0.1:3001/" , "http://172.17.0.1:3999/" ]
);
assert_eq! (
one ( "" , & [ listener ( 1 , "192.168.1.5" , 3001 ), listener ( 1 , "100.64.0.7" , 3001 )]),
[ "http://100.64.0.7:3001/" , "http://192.168.1.5:3001/" ]
);
// Only the sockets of Codeman servers count: not a control command's,
// another program's, or one whose process `ps` did not list.
let procs = [
server ( 1 , " --port 4000" ),
( 2 , "node /opt/homebrew/bin/codeman attach w1" . to_string ()),
( 3 , "python3 -m http.server 8000" . to_string ()),
];
let sockets = [
listener ( 2 , "*" , 4100 ),
listener ( 3 , "*" , 8000 ),
listener ( 9 , "*" , 9000 ),
listener ( 1 , "*" , 4000 ),
];
assert_eq! ( addresses ( & procs , & sockets , default ), [ "http://127.0.0.1:4000/" ]);
assert! ( addresses ( & procs , & sockets [ .. 3 ], default ). is_empty ());
// An address that makes no URL is left out.
assert! ( one ( "" , & [ listener ( 1 , "not a host" , 3001 )]). is_empty ());
}
#[test]
fn found_addresses_start_with_the_default_one_then_go_by_port () {
// install.sh's launchd job: a bare `web`, the base path in its environment.
let default = "http://127.0.0.1:3001/codeman/" ;
let procs = [
(
10 ,
"node /x/tsx/cli.mjs /Users/k/codeman/src/index.ts web --port 5000" . to_string (),
),
(
20 ,
"/opt/homebrew/bin/node /Users/k/.codeman/app/dist/index.js web" . to_string (),
),
server ( 30 , " -p 4000 --https" ),
// The same address twice: a second process on the port of the first.
server ( 40 , " --port 5000" ),
];
let sockets = [
listener ( 10 , "*" , 5000 ),
listener ( 20 , "*" , 3001 ),
listener ( 30 , "127.0.0.1" , 4000 ),
listener ( 40 , "127.0.0.1" , 5000 ),
];
assert_eq! (
addresses ( & procs , & sockets , default ),
[
"http://127.0.0.1:3001/codeman/" ,
"https://127.0.0.1:4000/" ,
"http://127.0.0.1:5000/"
]
);
// The same list whatever order `ps` and `lsof` gave.
let mut reversed_procs = procs . to_vec ();
reversed_procs . reverse ();
let mut reversed_sockets = sockets . to_vec ();
reversed_sockets . reverse ();
assert_eq! (
addresses ( & reversed_procs , & reversed_sockets , default ),
addresses ( & procs , & sockets , default )
);
// On the default port, a command line with its own base path or
// scheme is taken at its word: it may be another server than the job's.
let on_3001 = | flags : & str | addresses ( & [ server ( 1 , flags )], & [ listener ( 1 , "*" , 3001 )], default );
assert_eq! ( on_3001 ( " --port 3001" ), [ default ]);
assert_eq! ( on_3001 ( " --port 3001 --base-url /codeman" ), [ default ]);
assert_eq! (
on_3001 ( " --port 3001 --base-url /other" ),
[ "http://127.0.0.1:3001/other/" ]
);
assert_eq! ( on_3001 ( " --port 3001 --base-url /" ), [ "http://127.0.0.1:3001/" ]);
assert_eq! ( on_3001 ( " --port 3001 --https" ), [ "https://127.0.0.1:3001/" ]);
// 127.0.0.1 only: a bind to another address is not the default one.
assert_eq! (
addresses ( & [ server ( 1 , "" )], & [ listener ( 1 , "192.168.1.5" , 3001 )], default ),
[ "http://192.168.1.5:3001/" ]
);
}
#[test]
fn a_found_server_row_says_what_answered () {
let default = u ( "http://127.0.0.1:3000/" );
let at = u ( "http://127.0.0.1:4000/" );
let row = | answer : ProbeOutcome | found_server ( & at , & answer , & default );
assert_eq! (
row ( ProbeOutcome ::Ok {
version : "1.49.0" . into ()
}),
FoundServer {
url : "http://127.0.0.1:4000/" . into (),
version : Some ( "1.49.0" . into ()),
state : FoundState ::Running ,
is_default : false ,
}
);
let state = | answer : ProbeOutcome | {
let row = row ( answer );
assert_eq! ( row . version , None );
row . state
};
assert_eq! ( state ( ProbeOutcome ::PasswordChangeRequired ), FoundState ::Running );
for login in [
ProbeOutcome ::NeedsLogin ,
ProbeOutcome ::BadCredentials ,
ProbeOutcome ::RateLimited {
sent_credentials : false ,
retry_after_secs : Some ( 60 ),
},
] {
assert_eq! ( state ( login ), FoundState ::NeedsLogin );
}
for certificate in [
ProbeOutcome ::TlsUntrusted {
detail : "invalid peer certificate: UnknownIssuer" . into (),
},
ProbeOutcome ::MaybeHttps ,
] {
assert_eq! ( state ( certificate ), FoundState ::Certificate );
}
for silent in [
ProbeOutcome ::Refused ,
ProbeOutcome ::Timeout ,
ProbeOutcome ::Unreachable ,
ProbeOutcome ::HostNotAllowed ,
ProbeOutcome ::NotCodeman { status : 403 },
ProbeOutcome ::Failed { detail : "x" . into () },
] {
assert_eq! ( state ( silent ), FoundState ::Unreachable );
}
assert! ( found_server ( & default , & ProbeOutcome ::Refused , & default ). is_default );
// As the connect page reads it.
assert_eq! (
serde_json ::to_value ( row ( ProbeOutcome ::Ok {
version : "1.49.0" . into ()
}))
. unwrap (),
json! ({ "url" : "http://127.0.0.1:4000/" , "version" : "1.49.0" , "state" : "running" , "isDefault" : false })
);
assert_eq! (
serde_json ::to_value ( found_server ( & default , & ProbeOutcome ::NeedsLogin , & default )). unwrap (),
json! ({ "url" : "http://127.0.0.1:3000/" , "version" : null , "state" : "needsLogin" , "isDefault" : true })
);
assert_eq! (
serde_json ::to_value ([ FoundState ::Certificate , FoundState ::Unreachable ]). unwrap (),
json! ([ "certificate" , "unreachable" ])
);
}
#[test]
fn the_tab_is_about_the_default_address_unless_nothing_answers_there () {
let default = u ( "http://127.0.0.1:3000/" );
let ok = ProbeOutcome ::Ok {
version : "1.49.0" . into (),
};
let refused = ProbeOutcome ::Refused ;
let found = vec! [
(
u ( "https://127.0.0.1:4000/" ),
ProbeOutcome ::TlsUntrusted { detail : "x" . into () },
),
( u ( "http://127.0.0.1:5000/" ), ProbeOutcome ::NeedsLogin ),
( u ( "http://127.0.0.1:6000/" ), ok . clone ()),
];
// Nothing at the default address: the first found server that
// answers, one that wants a login included.
assert_eq! (
shown ( & default , & refused , & found ),
( & found [ 1 ]. 0 , & ProbeOutcome ::NeedsLogin )
);
assert_eq! ( shown ( & default , & refused , & found [ 2 .. ]), ( & found [ 2 ]. 0 , & ok ));
// None of them answers: the tab stays on the default address, and
// local_state makes that RunningElsewhere.
assert_eq! ( shown ( & default , & refused , & found [ .. 1 ]), ( & default , & refused ));
assert_eq! ( shown ( & default , & refused , & []), ( & default , & refused ));
// Whatever else the default address says is what the tab shows; the
// servers found elsewhere are only listed.
for answer in [
ok . clone (),
ProbeOutcome ::NeedsLogin ,
ProbeOutcome ::NotCodeman { status : 404 },
ProbeOutcome ::Timeout ,
ProbeOutcome ::MaybeHttps ,
] {
assert_eq! ( shown ( & default , & answer , & found ), ( & default , & answer ));
}
}
/// Against real sockets: every address is asked, at the same time, and
/// the answers come back in the order of the addresses.
#[test]
fn found_servers_are_asked_together () {
2026-11-08 23:55:00 +01:00
use std ::io ::{ Read , Write };
2026-11-06 17:39:12 +01:00
use std ::net ::TcpListener ;
use std ::sync ::mpsc ;
/// A server for one request: it reads it, and answers with `response`
/// if `ready` says so.
fn serve ( response : String , ready : impl FnOnce () -> bool + Send + 'static ) -> Url {
let l = TcpListener ::bind ( "127.0.0.1:0" ). unwrap ();
let port = l . local_addr (). unwrap (). port ();
std ::thread ::spawn ( move || {
if let Ok (( mut s , _ )) = l . accept () {
let mut head = Vec ::new ();
let mut buf = [ 0 u8 ; 4096 ];
while ! head . windows ( 4 ). any ( | w | w == b " \r\n\r\n " ) {
match s . read ( & mut buf ) {
Ok ( 0 ) | Err ( _ ) => break ,
Ok ( n ) => head . extend_from_slice ( & buf [ .. n ]),
}
}
if ready () {
let _ = s . write_all ( response . as_bytes ());
}
}
});
u ( & format! ( "http://127.0.0.1: {port} /" ))
}
fn response ( status_line : & str , body : & str ) -> String {
format! (
"HTTP/1.1 {status_line} \r\n Content-Type: application/json \r\n Content-Length: {} \r\n Connection: close \r\n\r\n {body} " ,
body . len ()
)
}
// The first server answers only once the second has been asked. Asked
// one after the other, it would hang up without an answer.
let ( asked , was_asked ) = mpsc ::channel ::< () > ();
let first = serve (
response ( "200 OK" , r #"{"success":true,"data":{"version":"9.9.9"}}"# ),
move || was_asked . recv_timeout ( Duration ::from_secs ( 4 )). is_ok (),
);
let second = serve ( response ( "401 Unauthorized" , "Unauthorized" ), move || {
asked . send (()). is_ok ()
});
let closed = {
let l = TcpListener ::bind ( "127.0.0.1:0" ). unwrap ();
u ( & format! ( "http://127.0.0.1: {} /" , l . local_addr (). unwrap (). port ()))
};
assert_eq! (
ask_found ( & [ first , second , closed ], probe ::TIMEOUT ),
[
ProbeOutcome ::Ok {
version : "9.9.9" . into ()
},
ProbeOutcome ::NeedsLogin ,
ProbeOutcome ::Refused ,
]
);
// One that does not answer in the time it is given.
let slow = serve ( String ::new (), || {
std ::thread ::sleep ( Duration ::from_secs ( 2 ));
false
});
assert_eq! ( ask_found ( & [ slow ], Duration ::from_millis ( 300 )), [ ProbeOutcome ::Timeout ]);
assert! ( ask_found ( & [], FOUND_TIMEOUT ). is_empty ());
2026-11-04 18:02:27 +01:00
}
#[test]
fn install_port_skips_taken_ones () {
assert_eq! ( pick_port ( | _ | true ), 3000 );
assert_eq! ( pick_port ( | p | p >= 3002 ), 3002 );
assert_eq! ( pick_port ( | _ | false ), 3000 );
}
}