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

package/lib/create.sh

@@ -1,29 +1,77 @@
 #!/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.
+# 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. 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.
+# 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`.
 #
-# 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.
+# 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 (template injection, dev server), but that never propagates back.
-# bin/xgem prints a "cd <name>" reminder using this at the very end.
+# 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"
+    registry_add "$(pwd)"
+    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.
@@ -42,13 +90,13 @@ _prompt_project_location() {
     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
+# _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"
 }
 
 # _launch_dev_server_and_open_browser <cmd...>
@@ -89,13 +137,11 @@ _launch_dev_server_and_open_browser() {
 _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.)
+    # `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
@@ -114,27 +160,33 @@ _create_react() {
     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"
+    _enter_project_dir "$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+=(.)
+        # 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."
-    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."
+        _xgem_bookkeeping react
+        return 0
     fi
 
-    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    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)
@@ -144,9 +196,13 @@ _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"; }
+    _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)
@@ -155,16 +211,20 @@ _create_vue() {
 _create_angular() {
     local project_dir
     project_dir=$(_prompt_project_location "Angular")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    _enter_project_dir "$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
+    # --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)
 }
 
@@ -172,20 +232,26 @@ _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"; }
+    _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.
+# 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")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
-    [ "$project_dir" != "." ] && { mkdir -p "$project_dir" && cd "$project_dir" || die "Could not enter $project_dir"; }
+    _enter_project_dir "$project_dir"
+    _xgem_bookkeeping "$fw"
 
     case "$fw" in
         node)
@@ -206,13 +272,7 @@ _create_simple() {
             ;;
         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
+            cargo init || die "cargo init failed."
             ;;
         swift)
             require_cmd swift "Install Swift: https://www.swift.org/install/"
@@ -235,15 +295,21 @@ EOF
 }
 
 # 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.
+# 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}
-    [[ "$create_choice" == n* || "$create_choice" == N* ]] || return 0
+
+    if [[ "$create_choice" != n* && "$create_choice" != N* ]]; then
+        _xgem_bookkeeping "$fw"
+        return 0
+    fi
 
     case "$fw" in
         react)   _create_react ;;
@@ -252,6 +318,9 @@ create_project_wizard() {
         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." ;;
+        *)
+            log_debug "No creation wizard for '$fw'; using current directory as-is."
+            _xgem_bookkeeping "$fw"
+            ;;
     esac
 }

package/lib/flutter.sh

@@ -239,18 +239,20 @@ flutter_run_native_command() {
 }
 
 # create_flutter_project — used by lib/create.sh's create_project_wizard.
-# `flutter create` needs a target dir; "." scaffolds into the current one.
+# --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")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
-    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
+    _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
 }