xgem-cli 2.0.0-alpha.1 → 2.0.0-alpha.12

package/lib/create.sh

@@ -0,0 +1,334 @@
+#!/bin/bash
+# xgem project creation wizards — runs from `xgem init`, for frameworks
+# with a real "ask sub-choice -> scaffold -> install -> launch" story
+# worth building (react/vue/angular/next/flutter). The rest (node/python/
+# go/rust/docker/swift) get a lighter "create with the ecosystem's own
+# standard init command" step.
+#
+# Depends on lib/logger.sh, lib/utils.sh, lib/scaffold.sh. Uses `cd`
+# directly (no subshells) so a newly created project directory persists as
+# the cwd for the rest of `xgem init`.
+#
+# Ordering principle (this file's main correctness property): xgem's own
+# bookkeeping (.xgem-automate + .gitignore, via _xgem_bookkeeping) always
+# runs BEFORE the slow, interruptible step of each framework (an install,
+# or an atomic scaffold+install like `ng new`) — never after. A real user
+# hit this: Ctrl-C during `ng new`'s multi-minute install killed the whole
+# xgem process before .xgem-automate was ever created, since it used to run
+# only at the very end. Where a tool supports decoupling scaffold-from-
+# install (--no-immediate, --skip-install, --no-pub), xgem scaffolds first
+# (fast), does its own bookkeeping, then runs the install itself. Where a
+# tool has no such flag (create-react-app), bookkeeping runs right after
+# that one atomic call returns — a small residual risk, documented at the
+# call site, not silently left as-was.
+#
+# Dev-server / device-run launch is deliberately deferred: creators only
+# set XGEM_POST_INIT_LAUNCH_CMD (an array) rather than launching
+# immediately, so `xgem init` finishes well before handing the terminal
+# over to a long-running dev server.
+XGEM_POST_INIT_LAUNCH_CMD=()
+
+# Set by creators when a NEW folder was created (not "current directory").
+# A child process can never change its parent shell's cwd, so once `xgem
+# init` exits, the user's actual terminal is back wherever it started —
+# xgem's own process is correctly cd'd into the new folder for the rest of
+# ITS run, but that never propagates back. bin/xgem prints a "cd <name>"
+# reminder using this at the very end.
+XGEM_CREATED_NEW_FOLDER=""
+
+# _xgem_bookkeeping <framework>
+# Creates .xgem-automate + updates .gitignore. Called as early as the
+# target directory allows, always before any slow/interruptible step.
+_xgem_bookkeeping() {
+    local fw=$1
+    mkdir -p "$CONFIG_DIR"
+    scaffold_inject_templates "$fw" "$CONFIG_DIR"
+    log_success "Successfully appended standard scripts for: $CONFIG_DIR/$fw"
+
+    # Some teams want the generated scripts checked in so collaborators get
+    # the same automation; others want them private/local-only. Ask instead
+    # of always gitignoring.
+    local ignore_choice
+    read -r -p "Should $CONFIG_DIR/ be ignored by git (private to you), or tracked so collaborators get the same scripts? [ignore/track] (default: ignore): " ignore_choice
+    ignore_choice=${ignore_choice:-ignore}
+
+    if [[ "$ignore_choice" == t* || "$ignore_choice" == T* ]]; then
+        if [ -f .gitignore ] && grep -qx "$CONFIG_DIR/" .gitignore; then
+            local tmp
+            tmp=$(mktemp)
+            grep -vx "$CONFIG_DIR/" .gitignore > "$tmp" && mv "$tmp" .gitignore
+            log_info "Removed existing $CONFIG_DIR/ entry from .gitignore since you chose to track it."
+        fi
+        log_success "$CONFIG_DIR/ will be tracked in git."
+    elif [ -f .gitignore ]; then
+        if ! grep -qx "$CONFIG_DIR/" .gitignore; then
+            echo -e "\n$CONFIG_DIR/" >> .gitignore
+            log_success "Added automation tracking to .gitignore"
+        fi
+    else
+        echo "$CONFIG_DIR/" > .gitignore
+        log_success "Created .gitignore and hidden tracking layer folder references."
+    fi
+}
+
+# _prompt_project_location <human label> -> echoes "." or a new folder name.
+# Pure prompt-and-echo, no other stdout output, so it's safe to capture via
+# command substitution.
+_prompt_project_location() {
+    local label=$1
+    local choice
+    read -r -p "Initialize $label in the current directory, or create a new folder? [current/new] (default: new): " choice
+    choice=${choice:-new}
+    if [[ "$choice" == c* || "$choice" == C* ]]; then
+        echo "."
+        return 0
+    fi
+    local name
+    read -r -p "Project name: " name
+    [ -n "$name" ] || die "Project name cannot be empty."
+    echo "$name"
+}
+
+# _enter_project_dir <project_dir> — mkdir+cd if a new folder was chosen,
+# and records XGEM_CREATED_NEW_FOLDER. No-op for "." (current directory).
+_enter_project_dir() {
+    local project_dir=$1
+    [ "$project_dir" = "." ] && return 0
+    XGEM_CREATED_NEW_FOLDER="$project_dir"
+    mkdir -p "$project_dir" && cd "$project_dir" || die "Could not enter $project_dir"
+}
+
+_open_url() {
+    local url=$1
+    case "$(detect_os)" in
+        darwin) open "$url" 2>/dev/null ;;
+        linux)  xdg-open "$url" 2>/dev/null ;;
+        *) log_debug "Don't know how to open a browser on this OS — visit $url manually." ;;
+    esac
+}
+
+# _launch_dev_server_and_open_browser <cmd...>
+# Starts the dev server in the background, tails its log for the first
+# http://localhost URL it prints — this works across Vite/CRA/Next/Angular
+# without hardcoding any one framework's default port (which can differ or
+# be taken already) — opens it, then waits so Ctrl-C stops the server
+# normally instead of leaving it orphaned in the background.
+_launch_dev_server_and_open_browser() {
+    local log_file
+    log_file=$(mktemp)
+    log_info "Starting dev server: $*"
+    "$@" > "$log_file" 2>&1 &
+    local server_pid=$!
+
+    local url="" waited=0
+    while [ -z "$url" ] && [ "$waited" -lt 30 ] && kill -0 "$server_pid" 2>/dev/null; do
+        url=$(grep -oE 'https?://(localhost|127\.0\.0\.1)[:0-9]*[^[:space:]]*' "$log_file" 2>/dev/null | head -1)
+        if [ -z "$url" ]; then
+            sleep 1
+            waited=$((waited + 1))
+        fi
+    done
+
+    if [ -n "$url" ]; then
+        log_success "Dev server up at $url"
+        _open_url "$url"
+    elif kill -0 "$server_pid" 2>/dev/null; then
+        log_warn "Dev server is running (pid $server_pid) but its URL wasn't detected automatically after ${waited}s — check the output below."
+    else
+        log_error "Dev server exited early."
+    fi
+
+    cat "$log_file" &
+    wait "$server_pid" 2>/dev/null
+}
+
+_ask_launch_dev_server() {
+    [ ${#XGEM_POST_INIT_LAUNCH_CMD[@]} -gt 0 ] || return 0
+
+    # `flutter run` isn't a web dev server — no localhost URL to detect/
+    # open, and it depends on fully-inherited interactive stdin for its
+    # own hot-reload keybindings, which the background+log-tail approach
+    # would break. Run it directly. (Whether to run at all was already
+    # confirmed in _flutter_offer_run_on_device, so this doesn't ask again.)
+    if [ "${XGEM_POST_INIT_LAUNCH_CMD[0]}" = "flutter" ]; then
+        "${XGEM_POST_INIT_LAUNCH_CMD[@]}"
+        return 0
+    fi
+
+    local answer
+    read -r -p "Launch the dev server now and open it in your browser? (Y/n): " answer
+    answer=${answer:-y}
+    [[ "$answer" == "y" || "$answer" == "Y" ]] && _launch_dev_server_and_open_browser "${XGEM_POST_INIT_LAUNCH_CMD[@]}"
+}
+
+_create_react() {
+    local variant lang project_dir
+    read -r -p "Use Vite or Create React App (the 'normal' version)? [vite/cra] (default: vite): " variant
+    variant=${variant:-vite}
+    read -r -p "TypeScript or JavaScript? [ts/js] (default: ts): " lang
+    lang=${lang:-ts}
+    project_dir=$(_prompt_project_location "React")
+    _enter_project_dir "$project_dir"
+
+    if [[ "$variant" == cra* || "$variant" == CRA* ]]; then
+        require_cmd npx "Install Node.js (npm ships with it): https://nodejs.org"
+        # create-react-app has no flag to decouple scaffold-from-install
+        # (confirmed: nothing in --help), so this one atomic call does
+        # both — a Ctrl-C during its own install (it's known to be slow)
+        # would still lose xgem's bookkeeping below. Accepted residual
+        # risk for this specific, non-default, legacy-leaning option.
+        log_info "Create React App scaffolds and installs in one step and can take a few minutes — best to let it finish without interrupting."
+        local -a args=(create-react-app .)
+        [ "$lang" = "ts" ] && args+=(--template typescript)
+        npx "${args[@]}" || die "create-react-app failed."
+        _xgem_bookkeeping react
+        return 0
+    fi
+
+    require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
+    local template="react"
+    [ "$lang" = "ts" ] && template="react-ts"
+    # --no-immediate: create-vite's own "install deps and start dev server"
+    # prompt would otherwise block here (and if Ctrl-C'd, kill this whole
+    # xgem process). --overwrite: harmless here since the only files that
+    # could exist at this point are ones xgem itself hasn't created yet
+    # (bookkeeping happens after this call, deliberately).
+    npm create vite@latest . -- --template "$template" --no-immediate --overwrite || die "npm create vite failed."
+    _xgem_bookkeeping react
+    log_info "Installing dependencies..."
+    npm install
+    XGEM_POST_INIT_LAUNCH_CMD=(npm run dev)
+}
+
+_create_vue() {
+    require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
+    local project_dir
+    project_dir=$(_prompt_project_location "Vue")
+    _enter_project_dir "$project_dir"
+    # create-vue doesn't install automatically (confirmed: no node_modules
+    # after it runs), so there's already a natural gap here to bookkeep in
+    # before the slow step. --force since this dir may be genuinely empty
+    # or (for "current directory") may already contain unrelated files.
+    npm create vue@latest . --force || die "npm create vue failed."
+    _xgem_bookkeeping vue
+    log_info "Installing dependencies..."
+    npm install
+    XGEM_POST_INIT_LAUNCH_CMD=(npm run dev)
+}
+
+_create_angular() {
+    local project_dir
+    project_dir=$(_prompt_project_location "Angular")
+    _enter_project_dir "$project_dir"
+    local -a ng_cmd=(ng)
+    has_cmd ng || ng_cmd=(npx @angular/cli@latest)
+
+    # --skip-install: ng new's own install is a multi-minute step (Angular
+    # dependency trees are large) — decoupling it is exactly what let a
+    # real user's Ctrl-C lose xgem's bookkeeping before this fix.
+    # --skip-git: xgem has its own `xgem git init`; ng new's own auto-
+    # commit would happen before .xgem-automate even exists.
+    "${ng_cmd[@]}" new "$(basename "$PWD")" --directory=. --skip-install --skip-git \
+        || die "ng new failed."
+    _xgem_bookkeeping angular
+    log_info "Installing dependencies..."
+    npm install
+    XGEM_POST_INIT_LAUNCH_CMD=(npm run start)
+}
+
+_create_next() {
+    require_cmd npx "Install Node.js (npm ships with it): https://nodejs.org"
+    local project_dir
+    project_dir=$(_prompt_project_location "Next.js")
+    _enter_project_dir "$project_dir"
+    # --skip-install: decouple from create-next-app's own install, same
+    # reasoning as Angular above.
+    npx create-next-app@latest . --skip-install || die "create-next-app failed."
+    _xgem_bookkeeping next
+    log_info "Installing dependencies..."
+    npm install
+    XGEM_POST_INIT_LAUNCH_CMD=(npm run dev)
+}
+
+# Lighter path for frameworks without a dev-server/browser story — just the
+# ecosystem's own standard init command, no sub-wizard. These are all fast
+# (no multi-minute install step), so bookkeeping-then-init is low-risk
+# regardless of ordering, but it's kept bookkeeping-first for consistency.
+_create_simple() {
+    local fw=$1
+    local project_dir
+    project_dir=$(_prompt_project_location "$fw")
+    _enter_project_dir "$project_dir"
+    _xgem_bookkeeping "$fw"
+
+    case "$fw" in
+        node)
+            require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
+            npm init -y
+            ;;
+        python)
+            require_cmd python3 "Install Python 3: https://www.python.org/downloads/"
+            python3 -m venv .venv
+            log_success "Created .venv — activate with 'source .venv/bin/activate'."
+            ;;
+        go)
+            require_cmd go "Install Go: https://go.dev/doc/install"
+            local module_name
+            read -r -p "Module name (e.g. github.com/you/project): " module_name
+            [ -n "$module_name" ] || module_name=$(basename "$PWD")
+            go mod init "$module_name"
+            ;;
+        rust)
+            require_cmd cargo "Install Rust: https://www.rust-lang.org/tools/install"
+            cargo init || die "cargo init failed."
+            ;;
+        swift)
+            require_cmd swift "Install Swift: https://www.swift.org/install/"
+            swift package init --type executable
+            ;;
+        docker)
+            if [ ! -f Dockerfile ]; then
+                cat > Dockerfile << 'EOF'
+FROM alpine:latest
+WORKDIR /app
+COPY . .
+CMD ["sh"]
+EOF
+                log_success "Created a starter Dockerfile — edit it for your actual base image/entrypoint."
+            else
+                log_warn "Dockerfile already exists, leaving it as-is."
+            fi
+            ;;
+    esac
+}
+
+# create_project_wizard <framework>
+# Asks whether to create a new project or use what's already here. Either
+# way, xgem's own bookkeeping (.xgem-automate + .gitignore) is guaranteed
+# to happen — for "existing", immediately (nothing to interrupt); for
+# "new", each creator handles it internally at the earliest safe point,
+# per the ordering principle documented at the top of this file.
+create_project_wizard() {
+    local fw=$1
+    local create_choice
+    read -r -p "Create a brand-new $fw project, or use what's already in this directory? [new/existing] (default: existing): " create_choice
+    create_choice=${create_choice:-existing}
+
+    if [[ "$create_choice" != n* && "$create_choice" != N* ]]; then
+        _xgem_bookkeeping "$fw"
+        return 0
+    fi
+
+    case "$fw" in
+        react)   _create_react ;;
+        vue)     _create_vue ;;
+        angular) _create_angular ;;
+        next)    _create_next ;;
+        flutter) create_flutter_project ;;
+        node|python|go|rust|docker|swift) _create_simple "$fw" ;;
+        *)
+            log_debug "No creation wizard for '$fw'; using current directory as-is."
+            _xgem_bookkeeping "$fw"
+            ;;
+    esac
+}

package/lib/doctor.sh

@@ -26,7 +26,10 @@ flutter_supports_flag() {
 flutter_config_spm_enabled() {
     has_cmd flutter || { echo "unknown (flutter not found)"; return; }
     local line
-    line=$(flutter config 2>/dev/null | grep -i "swift-package-manager")
+    # Anchored to "enable-swift-package-manager:" (the current-value line)
+    # so this doesn't instead match the "--[no-]enable-swift-package-manager"
+    # flag-syntax help line that `flutter config` also prints.
+    line=$(flutter config 2>/dev/null | grep -im1 -E '^[[:space:]]*enable-swift-package-manager:')
     if [ -z "$line" ]; then
         echo "unknown (not reported by this Flutter version)"
     else
@@ -86,7 +89,7 @@ doctor_print_ios() {
         echo "Deployment target [$cfg]: ${t:-unknown}"
     done
 
-    local required
+    local required generated
     required=$(ios_required_spm_deployment_target "$project_dir" 2>/dev/null)
     if [ -n "$required" ]; then
         echo "Required by resolved SwiftPM plugins: $required"
@@ -94,6 +97,14 @@ doctor_print_ios() {
         echo "Required by resolved SwiftPM plugins: unable to determine (run 'flutter pub get' first, or no SPM plugins declare an explicit floor)"
     fi
 
+    if [ "$uses_spm" = "yes" ]; then
+        generated=$(ios_generated_package_target "$project_dir" 2>/dev/null)
+        echo "FlutterGeneratedPluginSwiftPackage declares: ${generated:-unknown}"
+        if [ -n "$required" ] && [ -n "$generated" ] && _ios_ver_lt "$generated" "$required"; then
+            log_warn "This is stale — it declares iOS $generated but plugins need $required. This can happen even when your app's own deployment target is already high enough; 'xgem run flutter build' will detect and fix this."
+        fi
+    fi
+
     if [ "$uses_spm" = "yes" ]; then
         ios_known_issue_check
     fi

package/lib/flutter.sh

@@ -66,14 +66,19 @@ _flutter_build_ios() {
 
     require_cmd xcodebuild "iOS builds require Xcode's command-line tools."
 
+    # Must run pub get BEFORE reconciling: the required-deployment-target
+    # check reads .dart_tool/package_config.json, and that file only
+    # reflects the plugin versions actually in use after a fresh pub get.
+    # Reconciling against a stale package_config.json can silently pass a
+    # check that the real, just-resolved dependency graph would fail.
+    log_info "Regenerating dependencies..."
+    flutter pub get
+
     log_info "Reconciling iOS deployment target against resolved SwiftPM plugins..."
     if ! ios_reconcile_deployment_target "."; then
         die "iOS deployment target could not be reconciled; aborting before build."
     fi
 
-    log_info "Regenerating dependencies..."
-    flutter pub get
-
     if ios_project_uses_pods "."; then
         log_info "CocoaPods detected - installing pods..."
         ( cd ios || exit 1; pod install )
@@ -100,7 +105,7 @@ _flutter_build_ios() {
     mkdir -p "$archive_dir"
     archive_path="$archive_dir/Runner $archive_time.xcarchive"
 
-    if ! xcodebuild -workspace ios/Runner.xcworkspace \
+    local -a archive_cmd=(xcodebuild -workspace ios/Runner.xcworkspace \
         -scheme Runner \
         -sdk iphoneos \
         -configuration Release \
@@ -108,10 +113,35 @@ _flutter_build_ios() {
         -archivePath "$archive_path" \
         "BUILD_NUMBER=$build_number" \
         "MARKETING_VERSION=$build_name" \
-        -allowProvisioningUpdates > "$log_file" 2>&1; then
-        log_error "Archive FAILED"
-        cat "$log_file"
-        die "xcodebuild archive failed" "$?"
+        -allowProvisioningUpdates)
+
+    if ! "${archive_cmd[@]}" > "$log_file" 2>&1; then
+        # Static pre-checks can miss cases the real SwiftPM resolution
+        # catches (different plugin manifest layouts, symlinked package
+        # dirs, etc.) — Xcode's own error is authoritative, so parse it
+        # directly and retry once before giving up.
+        local retry_required
+        retry_required=$(ios_parse_required_from_build_log "$log_file")
+        if [ -n "$retry_required" ]; then
+            log_warn "Archive failed on a SwiftPM platform-version mismatch Xcode reports directly (requires iOS $retry_required). Retrying with that applied..."
+            ios_pbxproj_patch_deployment_target "$retry_required" "."
+            ios_regenerate_generated_package "."
+            local regenerated
+            regenerated=$(ios_generated_package_target ".")
+            if [ -z "$regenerated" ] || _ios_ver_lt "$regenerated" "$retry_required"; then
+                ios_patch_generated_package_target "$retry_required" "."
+            fi
+
+            if ! "${archive_cmd[@]}" > "$log_file" 2>&1; then
+                log_error "Archive FAILED again after retry"
+                cat "$log_file"
+                die "xcodebuild archive failed" "$?"
+            fi
+        else
+            log_error "Archive FAILED"
+            cat "$log_file"
+            die "xcodebuild archive failed" "$?"
+        fi
     fi
     log_success "Archive created at: $archive_path"
 
@@ -159,20 +189,21 @@ cmd_flutter_build() {
     echo ""
     echo "Select Target Platform:"
     echo "1) APK (Android)"
-    echo "2) iOS"
-    echo "3) macOS"
-    echo "4) Windows"
-    echo "5) Linux"
+    echo "2) App Bundle (Android, .aab — required for Play Store uploads)"
+    echo "3) iOS"
+    echo "4) macOS"
+    echo "5) Windows"
+    echo "6) Linux"
     local platform_choice
-    read -r -p "Choose [1-5]: " platform_choice
-    if ! [[ "$platform_choice" =~ ^[1-5]$ ]]; then
+    read -r -p "Choose [1-6]: " platform_choice
+    if ! [[ "$platform_choice" =~ ^[1-6]$ ]]; then
         die "Invalid platform choice '$platform_choice'."
     fi
 
     local mode="--release"
     [[ "$is_release" == "n" || "$is_release" == "N" ]] && mode="--debug"
 
-    if [ "$platform_choice" -eq 2 ]; then
+    if [ "$platform_choice" -eq 3 ]; then
         _flutter_build_ios "$build_name" "$build_number" "$mode"
         return
     fi
@@ -180,9 +211,10 @@ cmd_flutter_build() {
     log_info "Initializing Flutter Build ($mode) for version $build_name+$build_number..."
     case $platform_choice in
         1) flutter build apk "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
-        3) flutter build macos "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
-        4) flutter build windows "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
-        5) flutter build linux "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        2) flutter build appbundle "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        4) flutter build macos "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        5) flutter build windows "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        6) flutter build linux "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
     esac
 }
 
@@ -205,3 +237,116 @@ flutter_run_native_command() {
         *) die "No native flutter command for '$script'." ;;
     esac
 }
+
+# create_flutter_project — used by lib/create.sh's create_project_wizard.
+# --no-pub decouples scaffolding from the (slower, network-dependent)
+# `flutter pub get` step, so xgem's own bookkeeping (_xgem_bookkeeping) can
+# happen in between — same ordering principle as the other creators in
+# lib/create.sh: bookkeeping before any slow/interruptible step, never after.
+create_flutter_project() {
+    require_cmd flutter "Install Flutter: https://docs.flutter.dev/get-started/install"
+    local project_dir
+    project_dir=$(_prompt_project_location "Flutter")
+    _enter_project_dir "$project_dir"
+
+    flutter create --no-pub . || die "flutter create failed."
+    _xgem_bookkeeping flutter
+    log_info "Resolving packages..."
+    flutter pub get
+    _flutter_offer_run_on_device
+}
+
+# _flutter_select_device -> echoes the chosen device id, or nothing if
+# none available/selected. Uses `flutter devices --machine` (JSON) parsed
+# with python3 — already a soft dependency elsewhere in lib/ios.sh for the
+# same reason (no jq assumed present).
+_flutter_select_device() {
+    require_cmd python3 "Needed to parse 'flutter devices --machine' output."
+    local devices_json_file
+    devices_json_file=$(mktemp)
+    flutter devices --machine > "$devices_json_file" 2>/dev/null
+
+    local -a ids=() labels=()
+    while IFS='|' read -r id label; do
+        [ -n "$id" ] || continue
+        ids+=("$id")
+        labels+=("$label")
+    done < <(python3 - "$devices_json_file" <<'PYEOF'
+import json, sys
+
+try:
+    with open(sys.argv[1]) as f:
+        devices = json.load(f)
+except Exception:
+    devices = []
+
+for d in devices:
+    platform = d.get("platform") or d.get("targetPlatform") or ""
+    name = d.get("name", "unknown")
+    device_id = d.get("id", "")
+    print(f"{device_id}|{name} ({platform})")
+PYEOF
+)
+    rm -f "$devices_json_file"
+
+    if [ ${#ids[@]} -eq 0 ]; then
+        log_warn "No running devices/simulators found."
+        _flutter_offer_launch_emulator
+        return 1
+    fi
+
+    echo "Available devices:" >&2
+    local i
+    for i in "${!ids[@]}"; do
+        echo "$((i + 1))) ${labels[$i]}" >&2
+    done
+
+    local choice
+    read -r -p "Select a device [1-${#ids[@]}]: " choice
+    if ! [[ "$choice" =~ ^[0-9]+$ ]] || [ "$choice" -lt 1 ] || [ "$choice" -gt "${#ids[@]}" ]; then
+        log_warn "Invalid selection."
+        return 1
+    fi
+    echo "${ids[$((choice - 1))]}"
+}
+
+# No running devices — check for available-but-not-booted emulators and
+# offer to launch one, matching the "check available simulators... then
+# launch it" behavior the user asked for.
+_flutter_offer_launch_emulator() {
+    local emulators_output
+    emulators_output=$(flutter emulators 2>/dev/null)
+    [ -n "$emulators_output" ] || return 1
+
+    echo "$emulators_output"
+    local launch_choice
+    read -r -p "Launch one of these emulators? Enter its id, or leave blank to skip: " launch_choice
+    [ -n "$launch_choice" ] || return 1
+
+    log_info "Launching emulator '$launch_choice'..."
+    flutter emulators --launch "$launch_choice"
+    log_info "Waiting for it to boot..."
+    sleep 5
+}
+
+# Only picks the device and records the launch command in
+# XGEM_POST_INIT_LAUNCH_CMD — does NOT run `flutter run` itself. That's a
+# long-running blocking process; running it here (before xgem's own
+# template injection / .gitignore setup) means a Ctrl-C on it would kill
+# this whole xgem process before that setup ever runs, same class of bug
+# as create-vite's own --immediate flag caused for React. Device selection
+# itself is just a quick menu prompt, so it's safe to do now.
+_flutter_offer_run_on_device() {
+    local run_choice
+    read -r -p "Run the app now on a device/simulator? (Y/n): " run_choice
+    run_choice=${run_choice:-y}
+    [[ "$run_choice" == "y" || "$run_choice" == "Y" ]] || return 0
+
+    local device_id
+    device_id=$(_flutter_select_device)
+    if [ -n "$device_id" ]; then
+        XGEM_POST_INIT_LAUNCH_CMD=(flutter run -d "$device_id")
+    else
+        log_warn "No device selected — run 'flutter run' manually once one is available."
+    fi
+}