2026-10-23 10:09:18 -07:00
//! The Node 18+ check (FR-13). The console and the skills run on Node, so the
//! app refuses to start without it and says what to install.
//!
//! An app started from the Dock, Finder or a `.desktop` file, rather than a
//! terminal, inherits a minimal PATH: none of nvm, Homebrew or Volta's
//! directories, which a login shell's own profile adds. `resolved_path`
//! (Task 9.9) is what every process this app spawns (the console, an update,
//! an agent CLI) should run with, not the bare inherited one; `node_check`,
//! `console_supervisor`, `versions` and `agents` all use it.
use std ::process ::Command ;
2026-10-26 06:36:45 -07:00
use std ::sync ::Mutex ;
2026-10-23 10:09:18 -07:00
pub const MIN_NODE_MAJOR : u32 = 18 ;
#[derive(Debug, PartialEq, Eq)]
pub enum NodeStatus {
Ok ( String ),
TooOld ( String ),
Missing ,
}
/// Major version from `node --version` output such as `v20.11.1`.
pub fn parse_node_major ( output : & str ) -> Option < u32 > {
let text = output . trim (). strip_prefix ( 'v' ) ? ;
text . split ( '.' ). next () ? . parse (). ok ()
}
/// Classify the output of `node --version`.
pub fn classify ( output : & str ) -> NodeStatus {
let version = output . trim (). to_string ();
match parse_node_major ( output ) {
Some ( major ) if major >= MIN_NODE_MAJOR => NodeStatus ::Ok ( version ),
Some ( _ ) => NodeStatus ::TooOld ( version ),
None => NodeStatus ::Missing ,
}
}
pub fn check_node () -> NodeStatus {
2026-11-08 13:48:28 -08:00
let mut command = Command ::new ( "node" );
command . env ( "PATH" , resolved_path ()). arg ( "--version" );
#[cfg(windows)]
2026-10-26 20:20:35 -07:00
{
2026-11-08 13:48:28 -08:00
use std ::os ::windows ::process ::CommandExt ;
command . creation_flags ( 0x0800_0000 ); // CREATE_NO_WINDOW
}
match command . output () {
2026-10-23 10:09:18 -07:00
Ok ( out ) if out . status . success () => classify ( & String ::from_utf8_lossy ( & out . stdout )),
_ => NodeStatus ::Missing ,
}
}
/// `--node <path>` or `--node=<path>`: the launcher's own `node`, already
/// resolved under the person's real shell. Only its directory is used here,
/// so it joins the PATH the normal way rather than replacing every lookup.
fn node_override_dir ( args : & [ String ]) -> Option < String > {
let mut i = 1 ; // args[0] is the program name
while i < args . len () {
let value = if args [ i ] == "--node" {
args . get ( i + 1 ). cloned ()
} else {
args [ i ]. strip_prefix ( "--node=" ). map ( str ::to_string )
};
if let Some ( path ) = value . filter ( | v | ! v . is_empty ()) {
2026-10-26 20:20:35 -07:00
return std ::path ::Path ::new ( & path )
. parent ()
. map ( | dir | dir . to_string_lossy (). into_owned ());
2026-10-23 10:09:18 -07:00
}
i += 1 ;
}
None
}
/// The login shell's own PATH: running it as a login shell sources
/// `.zprofile`, `.bash_profile` or `.profile`, which a GUI launch never does.
/// Windows sets PATH outside any shell's startup files, so this is unix only.
#[cfg(unix)]
fn login_shell_path () -> Option < String > {
let shell = std ::env ::var ( "SHELL" ). unwrap_or_else ( | _ | "/bin/sh" . to_string ());
2026-10-26 20:20:35 -07:00
let out = Command ::new ( & shell )
. args ([ "-lc" , "echo $PATH" ])
. output ()
. ok () ? ;
2026-10-23 10:09:18 -07:00
let path = String ::from_utf8_lossy ( & out . stdout ). trim (). to_string ();
( out . status . success () && ! path . is_empty ()). then_some ( path )
}
2026-10-26 06:36:45 -07:00
static RESOLVED_PATH : Mutex < Option < String >> = Mutex ::new ( None );
2026-10-23 10:09:18 -07:00
/// The PATH every process this app spawns should run with: an explicit
/// `--node`'s directory first, then (macOS and Linux) the login shell's own
2026-10-26 06:36:45 -07:00
/// PATH, then this process's own PATH, each included only once. Worked out
/// once per launch, and again only on `refresh_path`.
pub fn resolved_path () -> String {
let mut cached = RESOLVED_PATH . lock (). unwrap_or_else ( | e | e . into_inner ());
cached . get_or_insert_with ( || build_path ( false )). clone ()
}
/// Work the PATH out again, for "Check again" after an agent CLI was
/// installed: an installer may have added a folder (the login shell's
/// profile on macOS and Linux, the saved user or system PATH on Windows)
/// that this process's own PATH has never had.
pub fn refresh_path () {
let fresh = build_path ( true );
* RESOLVED_PATH . lock (). unwrap_or_else ( | e | e . into_inner ()) = Some ( fresh );
}
fn build_path ( fresh : bool ) -> String {
let args : Vec < String > = std ::env ::args (). collect ();
let inherited = std ::env ::var ( "PATH" ). unwrap_or_default ();
let mut parts = Vec ::new ();
if let Some ( dir ) = node_override_dir ( & args ) {
parts . push ( dir );
}
#[cfg(unix)]
if let Some ( login ) = login_shell_path () {
parts . push ( login );
}
2026-10-27 21:48:43 -07:00
// This process's PATH is whatever its parent had, which is stale when
// that parent (a terminal, the launcher) started before an installer
// added a folder: a custom agent was then offered only some of the time.
// A refresh puts the saved PATH first; at start it only fills in after
// the inherited one, so that keeps its order.
#[cfg(windows)]
let saved = saved_windows_path ();
2026-10-26 06:36:45 -07:00
#[cfg(windows)]
if fresh {
2026-10-27 21:48:43 -07:00
parts . extend ( saved . clone ());
2026-10-26 06:36:45 -07:00
}
#[cfg(not(windows))]
let _ = fresh ;
if ! inherited . is_empty () {
parts . push ( inherited );
}
2026-10-27 21:48:43 -07:00
#[cfg(windows)]
if ! fresh {
parts . extend ( saved );
}
2026-10-26 06:36:45 -07:00
parts . join ( if cfg! ( windows ) { ";" } else { ":" })
}
/// The system then the user PATH as saved in the registry, with `%NAME%`
/// expanded: what a newly opened terminal would get.
#[cfg(windows)]
fn saved_windows_path () -> Vec < String > {
use std ::os ::windows ::process ::CommandExt ;
2026-10-26 20:20:35 -07:00
let keys = [
r "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" ,
r "HKCU\Environment" ,
];
2026-10-26 06:36:45 -07:00
keys . iter ()
. filter_map ( | key | {
let out = Command ::new ( "reg" )
. args ([ "query" , key , "/v" , "Path" ])
. creation_flags ( 0x0800_0000 ) // CREATE_NO_WINDOW
. output ()
. ok () ? ;
let value = parse_reg_query_value ( & String ::from_utf8_lossy ( & out . stdout )) ? ;
Some ( expand_percent_vars ( & value , | name | std ::env ::var ( name ). ok ()))
})
. collect ()
}
/// The value from `reg query <key> /v <name>` output: the text after the
/// `REG_SZ` or `REG_EXPAND_SZ` column on its line.
#[cfg_attr(not(windows), allow(dead_code))]
fn parse_reg_query_value ( output : & str ) -> Option < String > {
output . lines (). find_map ( | line | {
2026-10-26 20:20:35 -07:00
let ( _ , rest ) = line
. split_once ( "REG_EXPAND_SZ" )
. or_else ( || line . split_once ( "REG_SZ" )) ? ;
2026-10-26 06:36:45 -07:00
let value = rest . trim ();
( ! value . is_empty ()). then ( || value . to_string ())
2026-10-23 10:09:18 -07:00
})
}
2026-11-03 04:08:27 -08:00
/// The saved system and user PATH as one PATH string (Windows only): what a
/// newly opened terminal gets, kept apart from the process PATH so the agent
/// lookup can answer `saved-path`. "" elsewhere / when tests ask it off
/// (PLAN2CODE_NO_SAVED_PATH, as the launcher's addSavedWindowsPath() honors).
pub fn saved_path_value () -> String {
#[cfg(windows)]
{
if std ::env ::var_os ( "PLAN2CODE_NO_SAVED_PATH" ). is_some_and ( | v | ! v . is_empty ()) {
return String ::new ();
}
saved_windows_path (). join ( ";" )
}
#[cfg(not(windows))]
{
String ::new ()
}
}
2026-10-26 06:36:45 -07:00
/// `%NAME%` replaced with `lookup(NAME)`; an unknown name stays as written.
#[cfg_attr(not(windows), allow(dead_code))]
2026-11-03 04:08:27 -08:00
pub ( crate ) fn expand_percent_vars ( text : & str , lookup : impl Fn ( & str ) -> Option < String > ) -> String {
2026-10-26 06:36:45 -07:00
let mut out = String ::new ();
let mut rest = text ;
while let Some ( start ) = rest . find ( '%' ) {
out . push_str ( & rest [ .. start ]);
let after = & rest [ start + 1 .. ];
match after . find ( '%' ) {
Some ( end ) if end > 0 => match lookup ( & after [ .. end ]) {
Some ( value ) => {
out . push_str ( & value );
rest = & after [ end + 1 .. ];
}
None => {
out . push ( '%' );
rest = after ;
}
},
_ => {
out . push ( '%' );
rest = after ;
}
}
}
out . push_str ( rest );
out
}
2026-10-23 10:09:18 -07:00
/// Where `node` actually resolves, with `resolved_path`: for the first-run
/// checklist to name (Task 9.9), not for `check_node` itself to decide with.
pub fn node_binary_path () -> Option < String > {
2026-10-26 20:20:35 -07:00
let ( program , arg ) = if cfg! ( windows ) {
( "where" , "node" )
} else {
( "which" , "node" )
};
2026-11-08 13:48:28 -08:00
let mut command = Command ::new ( program );
command . env ( "PATH" , resolved_path ()). arg ( arg );
#[cfg(windows)]
{
use std ::os ::windows ::process ::CommandExt ;
command . creation_flags ( 0x0800_0000 ); // CREATE_NO_WINDOW
}
let out = command . output (). ok () ? ;
2026-10-23 10:09:18 -07:00
if ! out . status . success () {
return None ;
}
2026-10-26 20:20:35 -07:00
String ::from_utf8_lossy ( & out . stdout )
. lines ()
. next ()
. map ( str ::trim )
. filter ( | s | ! s . is_empty ())
. map ( str ::to_string )
2026-10-23 10:09:18 -07:00
}
/// The plain message shown when the check fails; `None` when Node is fine.
pub fn problem_message ( status : & NodeStatus ) -> Option < String > {
match status {
NodeStatus ::Ok ( _ ) => None ,
NodeStatus ::TooOld ( v ) => Some ( format! (
"Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and this computer has {v} . \n\n Install the current LTS release from https://nodejs.org and start Plan2Code again."
)),
NodeStatus ::Missing => Some ( format! (
"Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and it was not found. \n\n Install the current LTS release from https://nodejs.org and start Plan2Code again."
)),
}
}
#[cfg(test)]
mod tests {
use super ::* ;
#[test]
fn accepts_node_18_and_newer () {
assert_eq! ( classify ( "v18.0.0 \n " ), NodeStatus ::Ok ( "v18.0.0" . into ()));
assert_eq! ( classify ( "v20.11.1" ), NodeStatus ::Ok ( "v20.11.1" . into ()));
assert_eq! ( classify ( "v24.12.0 \r\n " ), NodeStatus ::Ok ( "v24.12.0" . into ()));
}
#[test]
fn rejects_node_older_than_18 () {
assert_eq! ( classify ( "v16.20.2" ), NodeStatus ::TooOld ( "v16.20.2" . into ()));
assert_eq! ( classify ( "v17.9.1" ), NodeStatus ::TooOld ( "v17.9.1" . into ()));
}
#[test]
fn treats_garbage_as_missing () {
assert_eq! ( classify ( "not a version" ), NodeStatus ::Missing );
assert_eq! ( classify ( "" ), NodeStatus ::Missing );
assert_eq! ( classify ( "v" ), NodeStatus ::Missing );
assert_eq! ( classify ( "vx.1.2" ), NodeStatus ::Missing );
}
#[test]
fn message_only_for_a_problem () {
assert! ( problem_message ( & NodeStatus ::Ok ( "v20.0.0" . into ())). is_none ());
2026-10-26 20:20:35 -07:00
assert! ( problem_message ( & NodeStatus ::Missing )
. unwrap ()
. contains ( "nodejs.org" ));
assert! ( problem_message ( & NodeStatus ::TooOld ( "v16.0.0" . into ()))
. unwrap ()
. contains ( "v16.0.0" ));
2026-10-23 10:09:18 -07:00
}
fn args ( list : & [ & str ]) -> Vec < String > {
2026-10-26 20:20:35 -07:00
std ::iter ::once ( "plan2code-app" )
. chain ( list . iter (). copied ())
. map ( str ::to_string )
. collect ()
2026-10-23 10:09:18 -07:00
}
#[test]
fn the_node_override_names_its_directory_in_both_forms () {
2026-10-26 20:20:35 -07:00
let want = if cfg! ( windows ) {
"C: \\ nvm \\ v20"
} else {
"/home/x/.nvm/v20"
};
let bin = if cfg! ( windows ) {
"C: \\ nvm \\ v20 \\ node.exe"
} else {
"/home/x/.nvm/v20/node"
};
assert_eq! (
node_override_dir ( & args ( & [ "--node" , bin ])). as_deref (),
Some ( want )
);
assert_eq! (
node_override_dir ( & args ( & [ & format! ( "--node= {bin} " )])). as_deref (),
Some ( want )
);
2026-10-23 10:09:18 -07:00
}
#[test]
fn no_override_or_a_missing_value_is_none () {
assert_eq! ( node_override_dir ( & args ( & [])), None );
assert_eq! ( node_override_dir ( & args ( & [ "--node" ])), None );
assert_eq! ( node_override_dir ( & args ( & [ "--node=" ])), None );
assert_eq! ( node_override_dir ( & args ( & [ "--agent" , "claude" ])), None );
}
2026-10-26 06:36:45 -07:00
#[test]
fn reads_the_saved_path_out_of_reg_query_output () {
let out = " \r\n HKEY_CURRENT_USER \\ Environment \r\n Path REG_EXPAND_SZ %USERPROFILE% \\ .local \\ bin;C: \\ Tools \r\n\r\n " ;
2026-10-26 20:20:35 -07:00
assert_eq! (
parse_reg_query_value ( out ). as_deref (),
Some ( "%USERPROFILE% \\ .local \\ bin;C: \\ Tools" )
);
2026-10-26 06:36:45 -07:00
let plain = "HKEY_LOCAL_MACHINE \\ x \r\n Path REG_SZ C: \\ Windows \r\n " ;
assert_eq! ( parse_reg_query_value ( plain ). as_deref (), Some ( "C: \\ Windows" ));
2026-10-26 20:20:35 -07:00
assert_eq! (
parse_reg_query_value (
"ERROR: The system was unable to find the specified registry key or value. \r\n "
),
None
);
2026-10-26 06:36:45 -07:00
}
#[test]
fn expands_known_percent_names_and_keeps_the_rest () {
let lookup = | name : & str | ( name == "USERPROFILE" ). then ( || "C: \\ Users \\ sam" . to_string ());
2026-10-26 20:20:35 -07:00
assert_eq! (
expand_percent_vars ( "%USERPROFILE% \\ .local \\ bin;C: \\ x" , lookup ),
"C: \\ Users \\ sam \\ .local \\ bin;C: \\ x"
);
assert_eq! (
expand_percent_vars ( "%NOPE% \\ bin;%USERPROFILE%" , lookup ),
"%NOPE% \\ bin;C: \\ Users \\ sam"
);
2026-10-26 06:36:45 -07:00
assert_eq! ( expand_percent_vars ( "50%" , lookup ), "50%" );
assert_eq! ( expand_percent_vars ( "a%%b" , lookup ), "a%%b" );
}
#[test]
fn refresh_path_keeps_this_process_path () {
refresh_path ();
let inherited = std ::env ::var ( "PATH" ). unwrap_or_default ();
assert! ( resolved_path (). ends_with ( & inherited ));
}
2026-10-23 10:09:18 -07:00
}