xgem-cli 2.0.0-alpha.14 → 2.0.0-alpha.16

package/README.md

@@ -54,7 +54,8 @@ xgem add                      Interactive state-aware addition of remaining fram
 xgem run <framework> <script> Run a workspace automation command script
 xgem terminate                Purge all generated automated layouts completely
 xgem <framework> [help]       View tailored instructions for a specific script layout
-xgem doctor                   Report on your environment (OS, arch, toolchains found)
+xgem doctor                   Toolchain report: versions, where found (fvm/nvm/brew), update checks, install links
+xgem update [tool]            Update installed toolchains (flutter, node, rust, ...) after confirmation
 xgem doctor ios [path]        Report on iOS build readiness: CocoaPods vs SPM, deployment
                                targets per config, and whether they're reconciled
 xgem git cmt "message"        Auto-stage, commit, rebase-pull, and push
@@ -72,7 +73,7 @@ xgem bootstrap                Clone-to-running: detect framework, install, .env,
 xgem ci                       Run lint/test/build for every configured framework, summarized
 xgem --version                Print xgem's version
 
-Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose
+Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose, --no-network (skip update lookups)
 ```
 
 ## Supported frameworks
@@ -97,7 +98,9 @@ bin/xgem       thin dispatcher — no business logic, just resolves paths and ro
 lib/
   logger.sh    log levels + verbose mode
   utils.sh     os/arch detection, confirm(), require_cmd()
-  doctor.sh    environment + feature detection ("xgem doctor")
+  toolchain.sh finds tools behind fvm/nvm/etc., offers installs, checks latest versions
+  update.sh    xgem update
+  doctor.sh    toolchain report ("xgem doctor")
   ios.sh       the SwiftPM-aware iOS build engine
   flutter.sh   flutter command group (build/hard-clean/build-runner), delegates iOS builds to ios.sh
   git.sh       git cmt/init/branch/rm-remote/rm-branch

package/bin/xgem

@@ -21,6 +21,10 @@ export XGEM_HOME
 source "$XGEM_HOME/lib/logger.sh"
 # shellcheck source=lib/utils.sh
 source "$XGEM_HOME/lib/utils.sh"
+# shellcheck source=lib/toolchain.sh
+source "$XGEM_HOME/lib/toolchain.sh"
+# shellcheck source=lib/update.sh
+source "$XGEM_HOME/lib/update.sh"
 # shellcheck source=lib/version.sh
 source "$XGEM_HOME/lib/version.sh"
 # shellcheck source=lib/doctor.sh
@@ -56,6 +60,7 @@ for arg in "$@"; do
         --yes)     XGEM_YES=1 ;;
         --dry-run) XGEM_DRY_RUN=1 ;;
         --verbose) XGEM_VERBOSE=1 ;;
+        --no-network) XGEM_NO_NETWORK=1 ;;
         *) ARGS+=("$arg") ;;
     esac
 done
@@ -79,7 +84,8 @@ print_usage() {
     echo "  xgem run <framework> <script> - Run a workspace automation command script"
     echo "  xgem terminate                - Purge all generated automated layouts completely"
     echo "  xgem <framework> [help]       - View tailored instructions for a specific script layout"
-    echo "  xgem doctor [ios]             - Report on your environment / iOS SwiftPM build readiness"
+    echo "  xgem doctor [ios]             - Toolchain report (finds fvm/nvm installs, links, update checks) / iOS build readiness"
+    echo "  xgem update [tool]            - Update installed toolchains (flutter, node, rust, ...) after confirmation"
     echo "  xgem git cmt \"message\"        - Auto-stage, commit, rebase-pull, and push"
     echo "  xgem git init                 - Setup local repo, attach remote tracker shortcuts"
     echo "  xgem git branch               - Pick, create, or switch branches; remembers your choice"
@@ -95,7 +101,7 @@ print_usage() {
     echo "  xgem ci                       - Run lint/test/build for every configured framework, summarized"
     echo "  xgem --version                - Print xgem's version"
     echo ""
-    echo "Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose"
+    echo "Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose, --no-network (skip update lookups)"
 }
 
 case "${1:-}" in
@@ -218,6 +224,11 @@ case "${1:-}" in
         exit 0
         ;;
 
+    update)
+        cmd_update "${2:-}"
+        exit 0
+        ;;
+
     release)
         cmd_release "${2:-}"
         exit 0

package/bin/xgem.js

@@ -26,6 +26,7 @@ const { registryAdd, registryRemove } = require('../lib-win/registry');
 const { cmdStatus } = require('../lib-win/status');
 const { cmdBootstrap } = require('../lib-win/bootstrap');
 const { cmdCi } = require('../lib-win/ci');
+const { cmdUpdate } = require('../lib-win/update');
 
 const CONFIG_DIR = '.xgem-automate';
 
@@ -47,7 +48,8 @@ function printUsage() {
     console.log('  xgem run <framework> <script> - Run a workspace automation command script');
     console.log('  xgem terminate                - Purge all generated automated layouts completely');
     console.log('  xgem <framework> [help]       - View tailored instructions for a specific script layout');
-    console.log('  xgem doctor [ios]             - Report on your environment / iOS build availability');
+    console.log('  xgem doctor [ios]             - Toolchain report (finds fvm/nvm installs, links, update checks)');
+    console.log('  xgem update [tool]            - Update installed toolchains (flutter, node, rust, ...) after confirmation');
     console.log('  xgem git cmt "message"        - Auto-stage, commit, rebase-pull, and push');
     console.log('  xgem git init                 - Setup local repo, attach remote tracker shortcuts');
     console.log('  xgem git branch               - Pick, create, or switch branches; remembers your choice');
@@ -63,7 +65,7 @@ function printUsage() {
     console.log('  xgem ci                       - Run lint/test/build for every configured framework, summarized');
     console.log('  xgem --version                - Print xgem\'s version');
     console.log('');
-    console.log('Flags (any command): --yes (skip confirmations), --dry-run (show, don\'t apply), --verbose');
+    console.log('Flags (any command): --yes (skip confirmations), --dry-run (show, don\'t apply), --verbose, --no-network (skip update lookups)');
 }
 
 async function selectFramework(options) {
@@ -175,6 +177,7 @@ async function main() {
         if (arg === '--yes') process.env.XGEM_YES = '1';
         else if (arg === '--dry-run') process.env.XGEM_DRY_RUN = '1';
         else if (arg === '--verbose') process.env.XGEM_VERBOSE = '1';
+        else if (arg === '--no-network') process.env.XGEM_NO_NETWORK = '1';
         else args.push(arg);
     }
 
@@ -189,6 +192,7 @@ async function main() {
             if (!a2) die('Usage: xgem git <cmt|init|branch|rm-remote|rm-branch|pr|sync|clean-branches|hooks>');
             return cmdGit(a2, a3, CONFIG_DIR);
         case 'doctor': return cmdDoctor(a2);
+        case 'update': return cmdUpdate(a2);
         case 'release': return cmdRelease(a2);
         case 'status': return cmdStatus(CONFIG_DIR);
         case 'bootstrap': return cmdBootstrap(CONFIG_DIR);

package/lib/bootstrap.sh

@@ -30,6 +30,10 @@ _bootstrap_env_file() {
     local example
     for example in .env.example .env.sample; do
         [ -f "$example" ] || continue
+        if [ "$XGEM_DRY_RUN" = "1" ]; then
+            log_info "(dry-run) would create .env from $example"
+            return 0
+        fi
         cp "$example" .env
         log_success "Created .env from $example."
         local missing
@@ -50,50 +54,76 @@ _bootstrap_node_pm() {
     fi
 }
 
+_bootstrap_preflight() {
+    local fw=$1 tool pm
+    tool=$(fw_required_tool "$fw")
+    [ -n "$tool" ] && [ "$fw" != "docker" ] && { tool_ensure "$tool" || return 1; }
+    case "$fw" in
+        flutter) tool_ensure dart || return 1 ;;
+        node|react|vue|angular|next)
+            pm=$(_bootstrap_node_pm)
+            if [ "$pm" != "npm" ] && ! has_cmd "$pm"; then
+                log_warn "This project uses $pm (lockfile found) but '$pm' isn't installed."
+                echo "  Enable it via Node's bundled corepack:  corepack enable   (or: npm install -g $pm)"
+                if confirm "Run 'npm install -g $pm' now?"; then
+                    _bootstrap_run npm install -g "$pm" || return 1
+                else
+                    return 1
+                fi
+            fi
+            ;;
+    esac
+    return 0
+}
+
+_bootstrap_run() {
+    if [ "$XGEM_DRY_RUN" = "1" ]; then
+        log_info "(dry-run) would run: $*"
+        return 0
+    fi
+    "$@"
+}
+
 _bootstrap_install() {
     local fw=$1
     case "$fw" in
         node|react|vue|angular|next)
             local pm
             pm=$(_bootstrap_node_pm)
+            confirm "Install dependencies with $pm?" || return 0
             log_info "Installing dependencies with $pm..."
             case "$pm" in
-                yarn) yarn ;;
-                pnpm) pnpm install ;;
-                bun)  bun install ;;
-                *)    npm install ;;
+                yarn) _bootstrap_run yarn ;;
+                pnpm) _bootstrap_run pnpm install ;;
+                bun)  _bootstrap_run bun install ;;
+                *)    _bootstrap_run npm install ;;
             esac
             ;;
         flutter)
-            has_cmd flutter || { log_warn "flutter not found — skipping 'flutter pub get'."; return 0; }
-            log_info "Running flutter pub get..."
-            flutter pub get
+            confirm "Run 'flutter pub get'?" || return 0
+            _bootstrap_run flutter pub get
             ;;
         python)
             if [ -f pyproject.toml ] && has_cmd poetry; then
-                log_info "Installing dependencies with poetry..."
-                poetry install
+                confirm "Install dependencies with poetry?" || return 0
+                _bootstrap_run poetry install
             elif [ -f requirements.txt ]; then
-                has_cmd python3 || { log_warn "python3 not found — skipping install."; return 0; }
-                [ -d .venv ] || python3 -m venv .venv
-                log_info "Installing dependencies into .venv..."
-                .venv/bin/pip install -r requirements.txt
+                confirm "Create .venv and install requirements.txt into it?" || return 0
+                [ -d .venv ] || _bootstrap_run python3 -m venv .venv
+                _bootstrap_run .venv/bin/pip install -r requirements.txt
             fi
             ;;
         go)
-            has_cmd go || { log_warn "go not found — skipping 'go mod download'."; return 0; }
-            log_info "Running go mod download..."
-            go mod download
+            confirm "Run 'go mod download'?" || return 0
+            _bootstrap_run go mod download
             ;;
         rust)
-            has_cmd cargo || { log_warn "cargo not found — skipping 'cargo fetch'."; return 0; }
-            log_info "Running cargo fetch..."
-            cargo fetch
+            confirm "Run 'cargo fetch'?" || return 0
+            _bootstrap_run cargo fetch
             ;;
         swift)
-            has_cmd swift || { log_warn "swift not found — skipping 'swift package resolve'."; return 0; }
-            log_info "Running swift package resolve..."
-            swift package resolve
+            confirm "Run 'swift package resolve'?" || return 0
+            _bootstrap_run swift package resolve
             ;;
         docker)
             log_debug "Docker project — nothing to install locally."
@@ -152,6 +182,7 @@ cmd_bootstrap() {
         log_success "Detected: $fw"
     fi
 
+    _bootstrap_preflight "$fw" || die "Bootstrap stopped: a required tool is missing."
     _bootstrap_env_file
     _bootstrap_install "$fw"
     _bootstrap_migrations "$fw"

package/lib/ci.sh

@@ -1,7 +1,35 @@
 #!/bin/bash
-# xgem ci: run lint -> test -> build for every configured framework before
-# you push, so a CI failure gets caught locally first.
-# Depends on lib/logger.sh.
+# xgem ci: run the checks for every configured framework before you push,
+# so a CI failure gets caught locally first.
+# Depends on lib/logger.sh, lib/utils.sh.
+
+# CI=true and a closed stdin make test runners (Vitest, Jest, Angular) run
+# once and exit instead of entering watch mode or waiting on a prompt.
+# Records into results/overall_status of the calling cmd_ci.
+_ci_run_step() {
+    local label=$1
+    shift
+    log_info "Running $label..."
+    if CI=true "$@" < /dev/null; then
+        results+=("PASS  $label")
+    else
+        results+=("FAIL  $label")
+        overall_status=1
+    fi
+}
+
+_ci_flutter() {
+    if ! tool_ensure flutter; then
+        results+=("SKIP  flutter (flutter not found)")
+        return 0
+    fi
+    _ci_run_step "flutter analyze" flutter analyze
+    if [ -d test ]; then
+        _ci_run_step "flutter test" flutter test
+    else
+        results+=("SKIP  flutter test (no test/ directory)")
+    fi
+}
 
 cmd_ci() {
     [ -d "$CONFIG_DIR" ] || die "No $CONFIG_DIR found — run 'xgem init' or 'xgem add' first."
@@ -14,20 +42,27 @@ cmd_ci() {
     for fw_dir in "$CONFIG_DIR"/*/; do
         [ -d "$fw_dir" ] || continue
         fw=$(basename "$fw_dir")
+
+        if [ "$fw" = "flutter" ]; then
+            _ci_flutter
+            continue
+        fi
+
+        local needed
+        needed=$(fw_required_tool "$fw")
+        if [ -n "$needed" ] && [ "$fw" != "docker" ] && ! tool_ensure "$needed"; then
+            results+=("SKIP  $fw ($needed not found)")
+            continue
+        fi
+
         for step in "${steps[@]}"; do
             [ -f "$CONFIG_DIR/$fw/$step.sh" ] || continue
-            log_info "Running $fw $step..."
-            if bash "$CONFIG_DIR/$fw/$step.sh"; then
-                results+=("PASS  $fw $step")
-            else
-                results+=("FAIL  $fw $step")
-                overall_status=1
-            fi
+            _ci_run_step "$fw $step" bash "$CONFIG_DIR/$fw/$step.sh"
         done
     done
 
     if [ ${#results[@]} -eq 0 ]; then
-        log_warn "No lint/test/build scripts found under $CONFIG_DIR to run."
+        log_warn "No checks found under $CONFIG_DIR to run."
         return 0
     fi
 

package/lib/doctor.sh

@@ -37,21 +37,93 @@ flutter_config_spm_enabled() {
     fi
 }
 
+_doctor_tools() {
+    echo git flutter dart node python3 go cargo docker gh fvm
+    [ "$(detect_os)" = "darwin" ] && echo swift
+}
+
+_doctor_tool_row() {
+    local tool=$1 version latest where mgr pin
+    if ! tool_resolve "$tool"; then
+        printf '  %-9s %-11s %s\n' "$tool" "not found" "download: $(tool_url "$tool")"
+        local recipe
+        recipe=$(tool_install_cmd "$tool")
+        [ -n "$recipe" ] && echo "            install:  $recipe   (or run: xgem update $tool)"
+        return 0
+    fi
+
+    version=$(tool_version_of "$tool")
+    mgr=$TOOL_MANAGER
+    where=$(_tool_pretty "$TOOL_PATH")
+    printf '  %-9s %-11s %s%s\n' "$tool" "${version:-unknown}" "$where" "$([ "$mgr" = system ] || [ "$mgr" = other ] || echo " ($mgr)")"
+
+    if [ "$TOOL_ON_PATH" = "0" ] && [ "$tool" != "dart" ]; then
+        echo "            ! not on PATH: found via $mgr, so plain scripts and CI won't see it (an alias such as alias flutter='fvm flutter' isn't visible to scripts; xgem resolves it for its own commands)"
+    fi
+
+    latest=$(XGEM_NO_NETWORK=1 tool_latest "$tool")
+    if [ -n "$version" ] && [ -n "$latest" ] && _tool_ver_lt "$version" "$latest"; then
+        echo "            ^ update available: $version -> $latest   (run: xgem update $tool)"
+    fi
+
+    pin=""
+    [ "$tool" != "dart" ] && pin=$(tool_pin "$tool")
+    if [ -n "$pin" ] && [ -n "$version" ] && [[ "$pin" =~ ^[0-9] ]]; then
+        case "$version" in
+            "$pin"*) ;;
+            *) echo "            ! this project pins $tool $pin but the active one is $version" ;;
+        esac
+    fi
+}
+
+_doctor_version_managers() {
+    local -a found=()
+    [ -d "${NVM_DIR:-$HOME/.nvm}" ] && found+=(nvm)
+    command -v fnm >/dev/null 2>&1 && found+=(fnm)
+    { [ -d "$HOME/.volta" ] || command -v volta >/dev/null 2>&1; } && found+=(volta)
+    { [ -d "$HOME/.asdf" ] || command -v asdf >/dev/null 2>&1; } && found+=(asdf)
+    command -v mise >/dev/null 2>&1 && found+=(mise)
+    { [ -d "$HOME/.pyenv" ] || command -v pyenv >/dev/null 2>&1; } && found+=(pyenv)
+    { [ -x "$HOME/.cargo/bin/rustup" ] || command -v rustup >/dev/null 2>&1; } && found+=(rustup)
+    { [ -d "$HOME/.puro" ] || command -v puro >/dev/null 2>&1; } && found+=(puro)
+    if [ ${#found[@]} -gt 0 ]; then
+        echo "Version managers: ${found[*]}  (fvm is listed with the tools above)"
+    else
+        echo "Version managers: none detected"
+    fi
+}
+
 doctor_print_general() {
     echo -e "\033[1;36m=== xgem doctor ===\033[0m"
-    echo "OS:              $(detect_os)"
-    echo "Arch:            $(detect_arch)$( is_apple_silicon && echo ' (Apple Silicon)' )"
-    echo "git:             $(doctor_tool_version git)"
-    echo "flutter:         $(doctor_tool_version flutter)"
-    echo "dart:            $(doctor_tool_version dart)"
-    echo "node:            $(doctor_tool_version node)"
-    echo "python3:         $(doctor_tool_version python3)"
-    echo "go:              $(doctor_tool_version go version)"
-    echo "cargo:           $(doctor_tool_version cargo)"
-    echo "docker:          $(doctor_tool_version docker)"
+    echo "OS:   $(detect_os)   Arch: $(detect_arch)$( is_apple_silicon && echo ' (Apple Silicon)' )"
+    echo ""
+
+    local t
+    if [ "$XGEM_NO_NETWORK" != "1" ]; then
+        log_info "Checking installed tools and the latest available versions..."
+        for t in $(_doctor_tools); do
+            ( tool_resolve "$t" && tool_latest "$t" ) >/dev/null 2>&1 &
+        done
+        wait
+    fi
+
+    echo -e "\033[1;36mToolchains\033[0m"
+    for t in $(_doctor_tools); do
+        _doctor_tool_row "$t"
+    done
+    echo ""
+    _doctor_version_managers
+
     if [ "$(detect_os)" = "darwin" ]; then
+        echo ""
         echo "xcodebuild:      $(doctor_tool_version xcodebuild -version)"
         echo "pod (CocoaPods): $(doctor_tool_version pod)"
+        has_cmd pod || echo "                 install: brew install cocoapods   (https://cocoapods.org)"
+    fi
+
+    if [ "$XGEM_NO_NETWORK" = "1" ] && [ ! -d "$XGEM_CACHE_DIR" ]; then
+        echo ""
+        log_info "Update checks were skipped (--no-network) and nothing is cached yet."
     fi
 }
 
@@ -115,6 +187,6 @@ cmd_doctor() {
     case "${1:-}" in
         ios) doctor_print_ios "${2:-.}" ;;
         "")  doctor_print_general ;;
-        *)   die "Unknown doctor target '$1'. Usage: xgem doctor [ios]" ;;
+        *)   die "Unknown doctor target '$1'. Usage: xgem doctor [ios] [--no-network]" ;;
     esac
 }

package/lib/flutter.sh

@@ -6,6 +6,7 @@
 # Depends on lib/logger.sh, lib/utils.sh, lib/ios.sh.
 
 cmd_flutter_hard_clean() {
+    require_cmd flutter
     log_info "Cleaning Flutter project..."
     rm -f pubspec.lock
     flutter clean
@@ -41,6 +42,7 @@ cmd_flutter_hard_clean() {
 }
 
 cmd_flutter_build_runner() {
+    require_cmd flutter
     log_info "Running Flutter Build Runner..."
     local verbose_choice
     read -r -p "Run in verbose mode? (Y/n): " verbose_choice
@@ -158,6 +160,7 @@ _flutter_build_ios() {
 }
 
 cmd_flutter_build() {
+    require_cmd flutter
     echo -e "\033[1;34m--- Flutter Build Orchestrator ---\033[0m"
 
     local current_name="" current_num="" current_full

package/lib/git.sh

@@ -33,6 +33,35 @@ _git_base_branch() {
     return 1
 }
 
+_git_resolve_conflicts_help() {
+    local files
+    files=$(git diff --name-only --diff-filter=U 2>/dev/null)
+    if [ -n "$files" ]; then
+        log_warn "Files with conflicts:"
+        echo "$files" | sed 's/^/  - /'
+    fi
+    log_warn "Resolve them, then run: git add <files> && git rebase --continue   (or give up with: git rebase --abort)"
+
+    local open_editor
+    read -r -p "Do you want to open VS Code to resolve this now? (y/n): " open_editor
+    [[ "$open_editor" == "y" || "$open_editor" == "Y" ]] || return 0
+
+    if has_cmd code; then
+        code .
+        return 0
+    fi
+    if [ "$(detect_os)" = "darwin" ]; then
+        local app
+        for app in "Visual Studio Code" "Visual Studio Code - Insiders"; do
+            if [ -d "/Applications/$app.app" ]; then
+                open -a "$app" .
+                return 0
+            fi
+        done
+    fi
+    log_warn "VS Code's 'code' command isn't on your PATH (a shell alias doesn't count — scripts can't see it). In VS Code run Cmd+Shift+P -> 'Shell Command: Install code command in PATH', or open the files above manually."
+}
+
 cmd_git_cmt() {
     local commit_msg=$1
     [ -n "$commit_msg" ] || die "Missing commit message!"
@@ -115,9 +144,7 @@ cmd_git_cmt() {
             log_warn "Your commit is safe locally. Re-run 'xgem git cmt' once connectivity is restored, or push manually: git push $remote_name $current_branch"
             exit 1
         fi
-        local open_editor
-        read -r -p "Do you want to open VS Code to resolve this now? (y/n): " open_editor
-        [[ "$open_editor" == "y" || "$open_editor" == "Y" ]] && code .
+        _git_resolve_conflicts_help
         exit 1
     fi
 
@@ -386,10 +413,7 @@ cmd_git_sync() {
     git_dir=$(git rev-parse --git-dir 2>/dev/null)
     if [ -d "$git_dir/rebase-merge" ] || [ -d "$git_dir/rebase-apply" ]; then
         log_error "MERGE CONFLICT DETECTED!"
-        log_warn "Execution paused. Resolve conflicts, then 'git rebase --continue'."
-        local open_editor
-        read -r -p "Do you want to open VS Code to resolve this now? (y/n): " open_editor
-        [[ "$open_editor" == "y" || "$open_editor" == "Y" ]] && code .
+        _git_resolve_conflicts_help
     else
         log_error "Rebase failed — this looks like a connection problem, not a merge conflict (see the git error above)."
     fi