xgem-cli 2.0.0-alpha.7 → 2.0.0-alpha.9

package/README.md

@@ -1,10 +1,14 @@
 # xgem
 
-A framework-aware automation CLI. `xgem init` scaffolds clean/build/dev scripts
-tailored to your project type (Flutter, Node, Python, React/Vue/Angular, Go,
-Rust, Docker, Swift), `xgem run <framework> <script>` runs them, `xgem doctor`
-reports on your environment, and `xgem git` wraps a common stage → commit →
-rebase-pull → push workflow.
+A framework-aware automation CLI. `xgem init` can create a brand-new project
+(real `npm create vite`/`create-next-app`/`create-vue`/`ng new`/`flutter create`
+scaffolding, framework-specific questions, dependency install, and launching
+the dev server in your browser or the app on a picked device/simulator) or
+just scaffold clean/build/dev scripts into a project you already have
+(Flutter, Node, Python, React/Vue/Angular/Next, Go, Rust, Docker, Swift).
+`xgem run <framework> <script>` runs those scripts, `xgem doctor` reports on
+your environment, and `xgem git` wraps a common stage → commit → rebase-pull
+→ push workflow.
 
 Flutter's iOS builds go through a dedicated engine that detects whether your
 project uses CocoaPods or Swift Package Manager (SPM), figures out the actual
@@ -49,6 +53,7 @@ xgem doctor ios [path]        Report on iOS build readiness: CocoaPods vs SPM, d
                                targets per config, and whether they're reconciled
 xgem git cmt "message"        Auto-stage, commit, rebase-pull, and push
 xgem git init                 Setup local repo, attach remote tracker shortcuts
+xgem git branch               Pick, create, or switch branches; remembers your choice
 xgem git rm-remote            Drop a configured remote
 xgem git rm-branch            Safely drop local and/or remote branch
 xgem --version                Print xgem's version
@@ -58,7 +63,36 @@ Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply),
 
 ## Supported frameworks
 
-flutter, node, python, react, vue, angular, go, rust, docker, swift
+flutter, node, python, react, vue, angular, next, go, rust, docker, swift
+
+## Creating a new project
+
+`xgem init` asks, per framework, whether to create a brand-new project or use
+what's already in the directory:
+
+- **react**: Vite or Create React App ("the normal version"), then TypeScript
+  or JavaScript, then current directory or a new folder.
+- **vue** / **next**: runs the official `create-vue`/`create-next-app` wizard
+  directly, so you get their own real prompts (router, Tailwind, App Router,
+  etc.) rather than a re-implementation of them.
+- **angular**: `ng new` (via a local Angular CLI if you have one, `npx
+  @angular/cli` otherwise).
+- **flutter**: `flutter create`, then lists available devices/simulators
+  (falling back to available-but-not-booted emulators you can launch) and
+  runs on whichever you pick.
+- **node/python/go/rust/docker/swift**: the ecosystem's own minimal init
+  command (`npm init`, a `.venv`, `cargo new`, `go mod init`, a starter
+  Dockerfile, `swift package init`) — no sub-wizard, since these don't have
+  an equivalent "dev server" to launch.
+
+For the frameworks with a dev server (react/vue/angular/next), after
+dependencies install xgem offers to start it and open your default browser —
+it tails the server's own log for the first `http://localhost:PORT` it
+prints rather than guessing a framework's default port, so it works even if
+that port's already taken and a different one gets picked.
+
+Answering "existing" (the default) skips all of this and behaves exactly
+like before — just scaffolds `.xgem-automate/` into the current directory.
 
 ## Architecture
 
@@ -70,8 +104,9 @@ lib/
   doctor.sh    environment + feature detection ("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/rm-remote/rm-branch
+  git.sh       git cmt/init/branch/rm-remote/rm-branch
   scaffold.sh  generic clean/build/dev handling for the other, simpler frameworks
+  create.sh    project creation wizards (react/vue/angular/next/simple frameworks)
 templates/     the actual clean/build/dev script content xgem scaffolds into your project's .xgem-automate/
 ```
 
@@ -133,6 +168,8 @@ Deferred to a follow-up pass, not yet in this release:
 - Shell completions, `--json` output, per-project config caching (stop re-prompting
   build name/number/platform every run)
 - Deeper Android SDK/Java detection
+- Project creation wizards on the Windows engine (`lib-win/`) — react/vue/angular/next
+  scaffolding is pure Node.js tooling and would work fine there too, just not built yet
 
 ## License
 

package/bin/xgem

@@ -33,6 +33,8 @@ source "$XGEM_HOME/lib/ios.sh"
 source "$XGEM_HOME/lib/flutter.sh"
 # shellcheck source=lib/scaffold.sh
 source "$XGEM_HOME/lib/scaffold.sh"
+# shellcheck source=lib/create.sh
+source "$XGEM_HOME/lib/create.sh"
 
 CONFIG_DIR=".xgem-automate"
 
@@ -70,6 +72,7 @@ print_usage() {
     echo "  xgem doctor [ios]             - Report on your environment / iOS SwiftPM build readiness"
     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"
     echo "  xgem git rm-remote            - Drop specified target remote tracing rules"
     echo "  xgem git rm-branch            - Safely drop local and remote workspace branch states"
     echo "  xgem --version                - Print xgem's version"
@@ -84,12 +87,12 @@ case "${1:-}" in
             log_warn "Workspace configuration layer already exists! Use 'xgem add' to append frameworks."
             exit 0
         fi
-        mkdir -p "$CONFIG_DIR"
-
         echo -e "\033[1;34mSelect your starting framework architecture:\033[0m"
         PS3="Enter target selection number: "
         select fw in "${ALL_FRAMEWORKS[@]}"; do
             if [ -n "$fw" ]; then
+                create_project_wizard "$fw"
+                mkdir -p "$CONFIG_DIR"
                 scaffold_inject_templates "$fw" "$CONFIG_DIR"
                 log_success "Successfully appended standard scripts for: $CONFIG_DIR/$fw"
                 break
@@ -107,6 +110,8 @@ case "${1:-}" in
             echo "$CONFIG_DIR/" > .gitignore
             log_success "Created .gitignore and hidden tracking layer folder references."
         fi
+
+        _ask_launch_dev_server
         exit 0
         ;;
 
@@ -182,7 +187,7 @@ case "${1:-}" in
         ;;
 
     git)
-        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|rm-remote|rm-branch>"
+        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|branch|rm-remote|rm-branch>"
         cmd_git "$2" "${3:-}"
         exit 0
         ;;
@@ -197,7 +202,7 @@ case "${1:-}" in
         exit 0
         ;;
 
-    flutter|node|python|react|vue|angular|go|rust|docker|swift)
+    flutter|node|python|react|vue|angular|next|go|rust|docker|swift)
         TARGET_FW=$1
         TARGET_FW_UPPER=$(echo "$TARGET_FW" | tr '[:lower:]' '[:upper:]')
 

package/bin/xgem.js

@@ -45,6 +45,7 @@ function printUsage() {
     console.log('  xgem doctor [ios]             - Report on your environment / iOS build availability');
     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');
     console.log('  xgem git rm-remote            - Drop specified target remote tracing rules');
     console.log('  xgem git rm-branch            - Safely drop local and remote workspace branch states');
     console.log('  xgem --version                - Print xgem\'s version');
@@ -187,7 +188,7 @@ async function main() {
         case 'run': return cmdRun(a2, a3);
         case 'terminate': return cmdTerminate();
         case 'git':
-            if (!a2) die('Usage: xgem git <cmt|init|rm-remote|rm-branch>');
+            if (!a2) die('Usage: xgem git <cmt|init|branch|rm-remote|rm-branch>');
             return cmdGit(a2, a3);
         case 'doctor': return cmdDoctor(a2);
         case '--version':
@@ -203,6 +204,7 @@ async function main() {
         case 'react':
         case 'vue':
         case 'angular':
+        case 'next':
         case 'go':
         case 'rust':
         case 'docker':

package/lib/create.sh

@@ -0,0 +1,226 @@
+#!/bin/bash
+# xgem project creation wizards — runs from `xgem init`, before
+# scaffold_inject_templates, 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. Uses `cd` directly (no
+# subshells) so a newly created project directory persists as the cwd for
+# the rest of `xgem init` (template injection, .gitignore) without the
+# caller needing to track/re-cd into a returned path.
+#
+# Dev-server launch is deliberately deferred: creators only set
+# XGEM_POST_INIT_LAUNCH_CMD (an array) rather than launching immediately,
+# so `xgem init` finishes template injection and .gitignore setup *before*
+# handing the terminal over to a long-running dev server.
+XGEM_POST_INIT_LAUNCH_CMD=()
+
+# _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"
+}
+
+_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
+    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")
+
+    if [[ "$variant" == cra* || "$variant" == CRA* ]]; then
+        require_cmd npx "Install Node.js (npm ships with it): https://nodejs.org"
+        local -a args=(create-react-app)
+        [ "$project_dir" != "." ] && args+=("$project_dir") || args+=(.)
+        [ "$lang" = "ts" ] && args+=(--template typescript)
+        npx "${args[@]}" || die "create-react-app failed."
+    else
+        require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
+        local template="react"
+        [ "$lang" = "ts" ] && template="react-ts"
+        npm create vite@latest "$project_dir" -- --template "$template" || die "npm create vite failed."
+    fi
+
+    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    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")
+    npm create vue@latest "$project_dir" || die "npm create vue failed."
+    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    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")
+    local -a ng_cmd=(ng)
+    has_cmd ng || ng_cmd=(npx @angular/cli@latest)
+
+    if [ "$project_dir" = "." ]; then
+        "${ng_cmd[@]}" new "$(basename "$PWD")" --directory=. || die "ng new failed."
+    else
+        "${ng_cmd[@]}" new "$project_dir" || die "ng new failed."
+        cd "$project_dir" || die "Could not enter $project_dir"
+    fi
+    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")
+    npx create-next-app@latest "$project_dir" || die "create-next-app failed."
+    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    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.
+_create_simple() {
+    local fw=$1
+    local project_dir
+    project_dir=$(_prompt_project_location "$fw")
+    [ "$project_dir" != "." ] && { mkdir -p "$project_dir" && cd "$project_dir" || die "Could not enter $project_dir"; }
+
+    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"
+            if [ "$project_dir" != "." ]; then
+                cd .. || return 1
+                cargo new "$project_dir" || die "cargo new failed."
+                cd "$project_dir" || die "Could not enter $project_dir"
+            else
+                cargo init || die "cargo init failed."
+            fi
+            ;;
+        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; if
+# creating, dispatches to the right per-framework creator. Leaves the
+# process cwd inside the (possibly new) project directory either way.
+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}
+    [[ "$create_choice" == n* || "$create_choice" == N* ]] || return 0
+
+    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." ;;
+    esac
+}

package/lib/flutter.sh

@@ -237,3 +237,106 @@ flutter_run_native_command() {
         *) die "No native flutter command for '$script'." ;;
     esac
 }
+
+# create_flutter_project — used by lib/create.sh's create_project_wizard.
+# `flutter create` needs a target dir; "." scaffolds into the current one.
+create_flutter_project() {
+    require_cmd flutter "Install Flutter: https://docs.flutter.dev/get-started/install"
+    local project_dir
+    project_dir=$(_prompt_project_location "Flutter")
+    if [ "$project_dir" = "." ]; then
+        flutter create . || die "flutter create failed."
+    else
+        flutter create "$project_dir" || die "flutter create failed."
+        cd "$project_dir" || die "Could not enter $project_dir"
+    fi
+    _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
+}
+
+_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
+        flutter run -d "$device_id"
+    else
+        log_warn "No device selected — run 'flutter run' manually once one is available."
+    fi
+}

package/lib/git.sh

@@ -46,6 +46,29 @@ cmd_git_cmt() {
         return 0
     fi
 
+    # A pull needs something to pull FROM. If this branch has never been
+    # pushed before, there's no remote ref to pull, and `git pull --rebase`
+    # fails with "couldn't find remote ref <branch>" — which is not a
+    # connection problem or a conflict, just a brand-new branch. Check for
+    # that specific case first so it gets its own accurate message instead
+    # of being lumped in with real connectivity failures.
+    git ls-remote --exit-code --heads "$remote_name" "$current_branch" >/dev/null 2>&1
+    local ls_remote_status=$?
+
+    if [ "$ls_remote_status" -eq 2 ]; then
+        log_info "'$current_branch' doesn't exist on '$remote_name' yet — pushing to create it..."
+        if git push -u "$remote_name" "$current_branch"; then
+            log_success "Git workflow complete! Branch created and pushed."
+        else
+            die "Push operation failed."
+        fi
+        return 0
+    elif [ "$ls_remote_status" -ne 0 ]; then
+        log_error "Could not reach '$remote_name' to check for '$current_branch' — this looks like a real connection problem."
+        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 ahead_count
     ahead_count=$(git rev-list --count "$remote_name/$current_branch..$current_branch" 2>/dev/null)
     if [ "$ahead_count" = "0" ]; then
@@ -163,13 +186,69 @@ cmd_git_rm_branch() {
     fi
 }
 
-# xgem git <cmt|init|rm-remote|rm-branch> ...
+# cmd_git_branch: lists local branches, lets the user pick one (or create a
+# new one), checks it out, and remembers it as this repo's default so
+# there's a quick way back to it later. `xgem git cmt` always operates on
+# whatever's actually checked out (that's the only thing that's correct for
+# a commit), so this command's job is the checkout + remembering, not
+# changing how cmt picks its branch.
+cmd_git_branch() {
+    local -a branches=()
+    while IFS= read -r line; do
+        [ -n "$line" ] && branches+=("$line")
+    done < <(git branch --format='%(refname:short)' 2>/dev/null)
+
+    [ ${#branches[@]} -gt 0 ] || die "No local branches found."
+
+    local current_branch
+    current_branch=$(git branch --show-current 2>/dev/null)
+
+    echo "Available branches:"
+    local i=1 b
+    for b in "${branches[@]}"; do
+        if [ "$b" = "$current_branch" ]; then
+            echo "$i) $b (current)"
+        else
+            echo "$i) $b"
+        fi
+        i=$((i + 1))
+    done
+    local create_option=$i
+    echo "$create_option) Create new branch"
+
+    local choice
+    read -r -p "Select [1-$create_option]: " choice
+
+    if [ "$choice" = "$create_option" ]; then
+        local new_branch
+        read -r -p "Enter new branch name: " new_branch
+        [ -n "$new_branch" ] || die "Branch name cannot be empty."
+        git checkout -b "$new_branch" || die "Could not create branch '$new_branch'."
+        git config --local xgem.default-branch "$new_branch"
+        log_success "Created and switched to '$new_branch', set as default for this repo."
+        return 0
+    fi
+
+    if ! [[ "$choice" =~ ^[0-9]+$ ]] || [ "$choice" -lt 1 ] || [ "$choice" -gt ${#branches[@]} ]; then
+        die "Invalid selection."
+    fi
+
+    local selected="${branches[$((choice - 1))]}"
+    if [ "$selected" != "$current_branch" ]; then
+        git checkout "$selected" || die "Could not switch to branch '$selected'."
+    fi
+    git config --local xgem.default-branch "$selected"
+    log_success "Switched to '$selected' and set as default for this repo."
+}
+
+# xgem git <cmt|init|rm-remote|rm-branch|branch> ...
 cmd_git() {
     case "$1" in
         cmt)       cmd_git_cmt "$2" ;;
         init)      cmd_git_init ;;
         rm-remote) cmd_git_rm_remote ;;
         rm-branch) cmd_git_rm_branch ;;
-        *) die "Unknown git subcommand '$1'. Usage: xgem git <cmt|init|rm-remote|rm-branch>" ;;
+        branch)    cmd_git_branch ;;
+        *) die "Unknown git subcommand '$1'. Usage: xgem git <cmt|init|rm-remote|rm-branch|branch>" ;;
     esac
 }

package/lib/scaffold.sh

@@ -11,14 +11,14 @@
 #
 # Depends on lib/logger.sh and XGEM_HOME (set by bin/xgem).
 
-ALL_FRAMEWORKS=(flutter node python react vue angular go rust docker swift)
+ALL_FRAMEWORKS=(flutter node python react vue angular next go rust docker swift)
 
 framework_scripts() {
     case "$1" in
         flutter) echo "hard-clean build build-runner" ;;
         node)    echo "hard-clean build start" ;;
         python)  echo "hard-clean install" ;;
-        react|vue|angular) echo "hard-clean build dev" ;;
+        react|vue|angular|next) echo "hard-clean build dev" ;;
         go)      echo "hard-clean build" ;;
         rust)    echo "hard-clean build" ;;
         docker)  echo "hard-clean build-up" ;;
@@ -30,8 +30,8 @@ framework_scripts() {
 _scaffold_template_dir() {
     local framework=$1
     case "$framework" in
-        react|vue|angular) echo "$XGEM_HOME/templates/webframework" ;;
-        *)                 echo "$XGEM_HOME/templates/$framework" ;;
+        react|vue|angular|next) echo "$XGEM_HOME/templates/webframework" ;;
+        *)                      echo "$XGEM_HOME/templates/$framework" ;;
     esac
 }
 

package/lib/version.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # xgem version info.
 
-XGEM_VERSION="2.0.0-alpha.7"
+XGEM_VERSION="2.0.0-alpha.9"
 
 print_version() {
     echo "xgem $XGEM_VERSION"

package/lib-win/git.js

@@ -60,6 +60,26 @@ async function cmdCmt(commitMsg) {
         return;
     }
 
+    // A pull needs something to pull FROM. If this branch has never been
+    // pushed before, there's no remote ref, and `git pull --rebase` fails
+    // with "couldn't find remote ref <branch>" — not a connection problem
+    // or a conflict, just a brand-new branch. Check for that case first.
+    const lsRemoteStatus = spawnSync('git', ['ls-remote', '--exit-code', '--heads', remoteName, currentBranch]).status;
+
+    if (lsRemoteStatus === 2) {
+        logInfo(`'${currentBranch}' doesn't exist on '${remoteName}' yet — pushing to create it...`);
+        if (git(['push', '-u', remoteName, currentBranch]).status === 0) {
+            logSuccess('Git workflow complete! Branch created and pushed.');
+        } else {
+            die('Push operation failed.');
+        }
+        return;
+    } else if (lsRemoteStatus !== 0) {
+        logError(`Could not reach '${remoteName}' to check for '${currentBranch}' — this looks like a real connection problem.`);
+        logWarn(`Your commit is safe locally. Re-run 'xgem git cmt' once connectivity is restored, or push manually: git push ${remoteName} ${currentBranch}`);
+        process.exit(1);
+    }
+
     const aheadCount = gitCapture(['rev-list', '--count', `${remoteName}/${currentBranch}..${currentBranch}`]);
     if (aheadCount === '0') {
         logSuccess(`Already up to date with '${remoteName}/${currentBranch}' — nothing to push.`);
@@ -168,13 +188,53 @@ async function cmdRmBranch() {
     }
 }
 
+// Lists local branches, lets the user pick one (or create a new one),
+// checks it out, and remembers it as this repo's default. cmt always
+// operates on whatever's actually checked out — this command's job is the
+// checkout + remembering, not changing how cmt picks its branch.
+async function cmdBranch() {
+    const branches = gitCapture(['branch', '--format=%(refname:short)']).split(/\r?\n/).filter(Boolean);
+    if (branches.length === 0) die('No local branches found.');
+
+    const currentBranch = gitCapture(['branch', '--show-current']);
+
+    console.log('Available branches:');
+    branches.forEach((b, i) => {
+        console.log(`${i + 1}) ${b}${b === currentBranch ? ' (current)' : ''}`);
+    });
+    const createOption = branches.length + 1;
+    console.log(`${createOption}) Create new branch`);
+
+    const choice = await prompt(`Select [1-${createOption}]`);
+
+    if (choice === String(createOption)) {
+        const newBranch = await prompt('Enter new branch name');
+        if (!newBranch) die('Branch name cannot be empty.');
+        if (git(['checkout', '-b', newBranch]).status !== 0) die(`Could not create branch '${newBranch}'.`);
+        git(['config', '--local', 'xgem.default-branch', newBranch]);
+        logSuccess(`Created and switched to '${newBranch}', set as default for this repo.`);
+        return;
+    }
+
+    const idx = parseInt(choice, 10) - 1;
+    if (Number.isNaN(idx) || idx < 0 || idx >= branches.length) die('Invalid selection.');
+
+    const selected = branches[idx];
+    if (selected !== currentBranch) {
+        if (git(['checkout', selected]).status !== 0) die(`Could not switch to branch '${selected}'.`);
+    }
+    git(['config', '--local', 'xgem.default-branch', selected]);
+    logSuccess(`Switched to '${selected}' and set as default for this repo.`);
+}
+
 async function cmdGit(sub, arg) {
     switch (sub) {
         case 'cmt': return cmdCmt(arg);
         case 'init': return cmdInit();
+        case 'branch': return cmdBranch();
         case 'rm-remote': return cmdRmRemote();
         case 'rm-branch': return cmdRmBranch();
-        default: die(`Unknown git subcommand '${sub}'. Usage: xgem git <cmt|init|rm-remote|rm-branch>`);
+        default: die(`Unknown git subcommand '${sub}'. Usage: xgem git <cmt|init|branch|rm-remote|rm-branch>`);
     }
 }
 

package/lib-win/scaffold.js

@@ -7,7 +7,7 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { logInfo, logSuccess, logWarn, logError, die } = require('./logger');
 
-const ALL_FRAMEWORKS = ['flutter', 'node', 'python', 'react', 'vue', 'angular', 'go', 'rust', 'docker'];
+const ALL_FRAMEWORKS = ['flutter', 'node', 'python', 'react', 'vue', 'angular', 'next', 'go', 'rust', 'docker'];
 
 const FRAMEWORK_SCRIPTS = {
     flutter: ['hard-clean', 'build', 'build-runner'],
@@ -16,6 +16,7 @@ const FRAMEWORK_SCRIPTS = {
     react: ['hard-clean', 'build', 'dev'],
     vue: ['hard-clean', 'build', 'dev'],
     angular: ['hard-clean', 'build', 'dev'],
+    next: ['hard-clean', 'build', 'dev'],
     go: ['hard-clean', 'build'],
     rust: ['hard-clean', 'build'],
     docker: ['hard-clean', 'build-up'],
@@ -27,7 +28,7 @@ function frameworkScripts(fw) {
 
 function templateDir(fw) {
     const templatesRoot = path.join(__dirname, '..', 'templates-win');
-    if (fw === 'react' || fw === 'vue' || fw === 'angular') {
+    if (fw === 'react' || fw === 'vue' || fw === 'angular' || fw === 'next') {
         return path.join(templatesRoot, 'webframework');
     }
     return path.join(templatesRoot, fw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xgem-cli",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0-alpha.9",
   "description": "Framework-aware automation CLI: scaffolds and runs clean/build/dev scripts per project type, an environment doctor, a SwiftPM-aware iOS build engine, and a git workflow helper. Runs natively on macOS, Linux, and Windows.",
   "bin": {
     "xgem": "bin/xgem.js"