xgem-cli 2.0.0-alpha.8 → 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
@@ -59,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
 
@@ -73,6 +106,7 @@ lib/
   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
   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/
 ```
 
@@ -134,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"
 
@@ -85,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
@@ -108,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
         ;;
 
@@ -198,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

@@ -204,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/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.8"
+XGEM_VERSION="2.0.0-alpha.9"
 
 print_version() {
     echo "xgem $XGEM_VERSION"

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.8",
+  "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"