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

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
@@ -27,7 +31,8 @@ xgem isn't in Homebrew's central `homebrew-core` (that requires a formal submiss
 npm install -g xgem-cli
 ```
 
-*(not yet published to the npm registry)*
+Works natively on Windows too (no WSL needed) — npm's install runs a small Node.js
+engine there instead of the bash one; see [Windows support](#windows-support).
 
 ### curl
 
@@ -48,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
@@ -57,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
 
@@ -69,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/
 ```
 
@@ -106,6 +142,24 @@ force Flutter to regenerate the generated package.
 
 Run `xgem doctor ios` any time for a standalone readiness report without doing a build.
 
+## Windows support
+
+Homebrew and the curl installer are macOS/Linux only, same as any bash tool — that's
+not going to change. npm is different: it's published with a small native Windows
+engine (`lib-win/`, driven by `bin/xgem.js`) so `npm install -g xgem-cli` actually works
+in `cmd.exe`/PowerShell, no WSL required.
+
+What works on Windows: `init`/`add`/`run`/`terminate`, `doctor`, the git workflow
+commands, and Flutter builds for **APK, App Bundle, and Windows desktop** targets. What doesn't:
+Flutter **iOS/macOS** builds — Xcode has no Windows equivalent, so `xgem doctor ios`
+explains that plainly instead of pretending. `swift` isn't offered as a framework
+choice on Windows for the same reason. If you're inside WSL, none of this applies —
+WSL reports itself as Linux, so you get the full bash engine automatically.
+
+On macOS/Linux, npm installs run the exact same bash engine as Homebrew/curl (`bin/xgem.js`
+is a thin passthrough that execs the real `bin/xgem` script) — there's only one
+implementation to trust on POSIX; Windows is the only platform with a second one.
+
 ## Roadmap
 
 Deferred to a follow-up pass, not yet in this release:
@@ -114,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,18 @@ case "${1:-}" in
             echo "$CONFIG_DIR/" > .gitignore
             log_success "Created .gitignore and hidden tracking layer folder references."
         fi
+
+        _ask_launch_dev_server
+
+        # A child process (this script) can never change the parent
+        # shell's cwd — xgem's own process correctly cd'd into the new
+        # project folder for everything above, but your actual terminal
+        # is still wherever it started. Say so explicitly instead of
+        # leaving you to discover it the confusing way.
+        if [ -n "$XGEM_CREATED_NEW_FOLDER" ]; then
+            echo ""
+            log_info "Your project is in ./$XGEM_CREATED_NEW_FOLDER — your terminal is still in the original directory. Run: cd $XGEM_CREATED_NEW_FOLDER"
+        fi
         exit 0
         ;;
 
@@ -182,7 +197,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 +212,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

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// xgem npm entrypoint. On macOS/Linux this is a thin passthrough to the
+// real, already-tested bash bin/xgem sitting next to it — zero logic
+// duplication, zero behavioral change for POSIX users. On Windows it runs
+// the native lib-win/*.js engine, since bash doesn't exist there.
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+if (process.platform !== 'win32') {
+    const bashScript = path.join(__dirname, 'xgem');
+    const result = spawnSync(bashScript, process.argv.slice(2), { stdio: 'inherit' });
+    process.exit(result.status ?? 0);
+}
+
+// ---- Windows-native engine ----
+const fs = require('node:fs');
+const { logInfo, logSuccess, logWarn, logError, die, paint } = require('../lib-win/logger');
+const { prompt } = require('../lib-win/utils');
+const { cmdDoctor } = require('../lib-win/doctor');
+const { cmdGit } = require('../lib-win/git');
+const { cmdFlutter } = require('../lib-win/flutter');
+const scaffold = require('../lib-win/scaffold');
+
+const CONFIG_DIR = '.xgem-automate';
+
+function printBanner() {
+    console.log(paint('yellow', ''));
+    console.log('██╗  ██╗       ██████╗ ███████╗███╗   ███╗██╗███╗   ██╗██╗');
+    console.log('╚██╗██╔╝      ██╔════╝ ██╔════╝████╗ ████║██║████╗  ██║██║');
+    console.log(' ╚███╔╝ █████╗██║  ███╗█████╗  ██╔████╔██║██║██╔██╗ ██║██║');
+    console.log(' ██╔██╗ ╚════╝██║   ██║██╔══╝  ██║╚██╔╝██║██║██║╚██╗██║██║');
+    console.log('██╔╝ ██╗      ╚██████╔╝███████╗██║ ╚═╝ ██║██║██║ ╚████║██║');
+    console.log('╚═╝  ╚═╝       ╚═════╝ ╚══════╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝');
+    console.log(paint('cyan', '           ....Windows engine....\n'));
+}
+
+function printUsage() {
+    console.log('Usage:');
+    console.log('  xgem init                     - Initialize tracking system and add first framework');
+    console.log('  xgem add                      - Interactive state-aware addition of remaining frameworks');
+    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 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');
+    console.log('');
+    console.log('Flags (any command): --yes (skip confirmations), --dry-run (show, don\'t apply), --verbose');
+}
+
+async function selectFramework(options) {
+    options.forEach((fw, i) => console.log(`${i + 1}) ${fw}`));
+    const choice = await prompt('Enter target selection number');
+    const idx = parseInt(choice, 10) - 1;
+    if (Number.isNaN(idx) || idx < 0 || idx >= options.length) return null;
+    return options[idx];
+}
+
+function updateGitignore() {
+    const gitignorePath = '.gitignore';
+    if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, 'utf8');
+        if (!content.includes(`${CONFIG_DIR}/`)) {
+            fs.appendFileSync(gitignorePath, `\n${CONFIG_DIR}/\n`);
+            logSuccess('Added automation tracking to .gitignore');
+        }
+    } else {
+        fs.writeFileSync(gitignorePath, `${CONFIG_DIR}/\n`);
+        logSuccess('Created .gitignore and hidden tracking layer folder references.');
+    }
+}
+
+async function cmdInit() {
+    printBanner();
+    if (fs.existsSync(CONFIG_DIR)) {
+        logWarn("Workspace configuration layer already exists! Use 'xgem add' to append frameworks.");
+        return;
+    }
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+
+    console.log('Select your starting framework architecture:');
+    const fw = await selectFramework(scaffold.ALL_FRAMEWORKS);
+    if (!fw) die('Invalid selection.');
+    scaffold.injectTemplates(fw, CONFIG_DIR);
+    logSuccess(`Successfully appended standard scripts for: ${CONFIG_DIR}/${fw}`);
+
+    updateGitignore();
+}
+
+async function cmdAdd() {
+    if (!fs.existsSync(CONFIG_DIR)) die("System tracking layer not found. Run 'xgem init' first.");
+
+    const remaining = scaffold.getRemainingFrameworks(CONFIG_DIR);
+    if (remaining.length === 0) {
+        logWarn('All available framework blocks are already generated inside the workspace!');
+        const restore = (await prompt('Do you want to restore/regenerate all framework templates to defaults? (y/n)')).toLowerCase();
+        if (restore === 'y') {
+            for (const fw of scaffold.ALL_FRAMEWORKS) scaffold.injectTemplates(fw, CONFIG_DIR);
+            logSuccess('All framework automation layouts cleanly re-generated!');
+        }
+        return;
+    }
+
+    console.log('Select a framework script block to add:');
+    const fw = await selectFramework(remaining);
+    if (!fw) { console.log('Operation canceled.'); return; }
+    scaffold.injectTemplates(fw, CONFIG_DIR);
+    logSuccess(`Successfully loaded and updated files for: ${CONFIG_DIR}/${fw}`);
+}
+
+async function cmdRun(fw, script) {
+    if (!fw || !script) die('Usage: xgem run <framework> <script>');
+    if (fw === 'flutter' && ['hard-clean', 'build', 'build-runner'].includes(script)) {
+        await cmdFlutter(script);
+    } else {
+        scaffold.runScript(fw, script, CONFIG_DIR);
+    }
+}
+
+async function cmdTerminate() {
+    if (!fs.existsSync(CONFIG_DIR)) die(`Tracking layer ${CONFIG_DIR} not found. Nothing to terminate.`);
+
+    logWarn(`Initiating core termination sequence for ${CONFIG_DIR}...`);
+    const folders = fs.readdirSync(CONFIG_DIR, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+
+    const { confirm } = require('../lib-win/utils');
+    const ok = await confirm(`This deletes ${CONFIG_DIR} and everything in it. Continue?`);
+    if (!ok) { logInfo('Cancelled.'); return; }
+
+    for (const fw of folders) {
+        console.log(`  [ x ] Removing ${fw}...`);
+        fs.rmSync(path.join(CONFIG_DIR, fw), { recursive: true, force: true });
+    }
+    fs.rmSync(CONFIG_DIR, { recursive: true, force: true });
+
+    if (fs.existsSync('.gitignore')) {
+        const lines = fs.readFileSync('.gitignore', 'utf8').split(/\r?\n/).filter((l) => l !== `${CONFIG_DIR}/`);
+        fs.writeFileSync('.gitignore', lines.join('\n'));
+        logSuccess('Cleaned up .gitignore tracking records.');
+    }
+
+    logSuccess(`Termination complete. Total blocks destroyed: ${folders.length} (${folders.join(', ') || 'none'})`);
+}
+
+function printFrameworkHelp(fw) {
+    console.log(paint('cyan', `=== ${fw.toUpperCase()} Automation Blueprint (Windows) ===`));
+    if (!fs.existsSync(path.join(CONFIG_DIR, fw))) {
+        logWarn('Status: Not currently injected in this workspace.');
+        console.log("Run 'xgem add' to instantly append its structural scripts.\n");
+    } else {
+        logSuccess(`Status: Active & Mounted inside ${CONFIG_DIR}/${fw}/`);
+        console.log('');
+    }
+    console.log(`To execute scripts, use: xgem run ${fw} <script>\n`);
+    console.log('Configured Commands:');
+    for (const script of scaffold.frameworkScripts(fw) || []) {
+        console.log(`  ${script}`);
+    }
+    if (fw === 'flutter') {
+        console.log('');
+        logInfo("Flutter builds on Windows support APK, App Bundle, and Windows desktop targets. Run 'xgem doctor ios' for why iOS/macOS aren't available here.");
+    }
+    console.log('');
+}
+
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    const args = [];
+    for (const arg of rawArgs) {
+        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 args.push(arg);
+    }
+
+    const [cmd, a2, a3] = args;
+
+    switch (cmd) {
+        case 'init': return cmdInit();
+        case 'add': return cmdAdd();
+        case 'run': return cmdRun(a2, a3);
+        case 'terminate': return cmdTerminate();
+        case 'git':
+            if (!a2) die('Usage: xgem git <cmt|init|branch|rm-remote|rm-branch>');
+            return cmdGit(a2, a3);
+        case 'doctor': return cmdDoctor(a2);
+        case '--version':
+        case '-V':
+        case 'version': {
+            const pkg = require('../package.json');
+            console.log(`xgem ${pkg.version} (Windows engine)`);
+            return;
+        }
+        case 'flutter':
+        case 'node':
+        case 'python':
+        case 'react':
+        case 'vue':
+        case 'angular':
+        case 'next':
+        case 'go':
+        case 'rust':
+        case 'docker':
+            return printFrameworkHelp(cmd);
+        default:
+            return printUsage();
+    }
+}
+
+main().catch((err) => {
+    logError(err.message || String(err));
+    process.exit(1);
+});

package/lib/create.sh

@@ -0,0 +1,257 @@
+#!/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=()
+
+# 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 (template injection, dev server), but that never propagates back.
+# bin/xgem prints a "cd <name>" reminder using this at the very end.
+XGEM_CREATED_NEW_FOLDER=""
+
+# _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
+
+    # `flutter run` isn't a web dev server — it has no localhost URL to
+    # detect/open, and it depends on a fully-inherited interactive stdin
+    # for its own hot-reload keybindings (r/R/q/etc.), which the
+    # background+log-tail approach below would break. Run it directly.
+    # (Whether to run at all was already confirmed in
+    # _flutter_offer_run_on_device before this command was ever set, 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")
+    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+
+    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"
+        # --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 before it ever reaches template
+        # injection / .gitignore setup below. xgem handles install/launch
+        # itself instead, after everything else is done.
+        npm create vite@latest "$project_dir" -- --template "$template" --no-immediate || 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")
+    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    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")
+    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    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")
+    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    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" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    [ "$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
+}