xgem-cli 2.0.0-alpha

package/lib/git.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+# xgem git workflow helper: cmt / init / rm-remote / rm-branch.
+# Depends on lib/logger.sh.
+
+cmd_git_cmt() {
+    local commit_msg=$1
+    [ -n "$commit_msg" ] || die "Missing commit message!"
+
+    log_info "Checking repository status..."
+    git status -s
+    echo ""
+
+    local add_choice
+    read -r -p "Do you want to add ALL files (a) or INDIVIDUAL files (i)? [a/i]: " add_choice
+    if [[ "$add_choice" == "a" || "$add_choice" == "A" ]]; then
+        git add .
+        log_success "All files staged."
+    elif [[ "$add_choice" == "i" || "$add_choice" == "I" ]]; then
+        local -a specific_files
+        read -r -p "Enter specific file paths to add (space separated): " -a specific_files
+        git add "${specific_files[@]}"
+        log_success "Selected files staged."
+    else
+        die "Invalid choice. Operation aborted."
+    fi
+
+    log_info "Committing changes..."
+    if ! git commit -m "$commit_msg"; then
+        die "Commit failed. Aborting before pull/push."
+    fi
+
+    local current_branch remote_name
+    current_branch=$(git branch --show-current 2>/dev/null)
+    if git remote | grep -q "^origin$"; then
+        remote_name="origin"
+    else
+        remote_name=$(git remote | head -n 1)
+    fi
+
+    if [ -z "$remote_name" ]; then
+        log_warn "Local commit dropped cleanly, but no remote is configured — sync was skipped."
+        return 0
+    fi
+
+    log_info "Pulling updates from remote '$remote_name' on '$current_branch' via rebase..."
+    if ! git pull --rebase "$remote_name" "$current_branch"; then
+        log_error "MERGE CONFLICT DETECTED!"
+        log_warn "Execution paused. Resolve conflicts to proceed."
+        local open_editor
+        read -r -p "Do you want to open VS Code to resolve this now? (y/n): " open_editor
+        [[ "$open_editor" == "y" || "$open_editor" == "Y" ]] && code .
+        exit 1
+    fi
+
+    log_success "Clean sync pull achieved. Pushing to upstream target..."
+    if git push "$remote_name" "$current_branch"; then
+        log_success "Git workflow complete! Code cleanly committed and synchronized."
+    else
+        die "Push operation failed."
+    fi
+}
+
+cmd_git_init() {
+    log_info "Initializing local Git repository..."
+    git init
+
+    local remote_name="origin" remote_url user_remote_name branch_name
+    read -r -p "Enter remote repository URL: " remote_url
+    if [ -n "$remote_url" ]; then
+        read -r -p "Enter remote name (default: origin): " user_remote_name
+        [ -n "$user_remote_name" ] && remote_name="$user_remote_name"
+
+        if git remote | grep -q "^$remote_name$"; then
+            git remote set-url "$remote_name" "$remote_url"
+            log_success "Remote '$remote_name' already existed. URL updated."
+        else
+            git remote add "$remote_name" "$remote_url"
+            log_success "Remote '$remote_name' successfully added."
+        fi
+    fi
+
+    read -r -p "Enter branch name (default: main): " branch_name
+    branch_name=${branch_name:-main}
+    git branch -M "$branch_name"
+
+    git add .
+    git commit -m "initial changes" 2>/dev/null
+    log_success "Local baseline configuration setup completed."
+}
+
+cmd_git_rm_remote() {
+    log_info "Current configured remotes:"
+    git remote -v
+    echo ""
+
+    local remote_name
+    read -r -p "Enter the short remote name to remove (e.g. origin): " remote_name
+    remote_name=${remote_name:-origin}
+
+    if git remote | grep -q "^$remote_name$"; then
+        git remote remove "$remote_name"
+        log_success "Successfully removed remote reference configuration: $remote_name"
+    else
+        die "Remote tracking short-name '$remote_name' does not exist."
+    fi
+}
+
+cmd_git_rm_branch() {
+    local target_branch
+    read -r -p "Enter the name of the branch you want to target: " target_branch
+    [ -n "$target_branch" ] || die "Branch name cannot be empty."
+
+    local where_choice
+    read -r -p "Where do you want to delete this branch? (l = local only, r = remote only, b = both) [l/r/b]: " where_choice
+    echo ""
+
+    if [[ "$where_choice" =~ ^[lLbB]$ ]]; then
+        local current_branch
+        current_branch=$(git branch --show-current 2>/dev/null)
+        if [ "$current_branch" = "$target_branch" ]; then
+            log_warn "You are currently sitting on '$target_branch'. Switching to safe branch..."
+            git checkout main 2>/dev/null || git checkout master 2>/dev/null || git checkout dev 2>/dev/null
+        fi
+
+        log_info "Force deleting local branch '$target_branch'..."
+        if git branch -D "$target_branch"; then
+            log_success "Successfully deleted local copy of branch."
+        else
+            log_warn "Local branch could not be dropped (it may already be gone)."
+        fi
+    fi
+
+    if [[ "$where_choice" =~ ^[rRbB]$ ]]; then
+        local remote_target
+        read -r -p "Enter remote identifier (short-name like 'origin'): " remote_target
+        remote_target=${remote_target:-origin}
+
+        log_info "Sending deletion request for remote branch '$target_branch' to server..."
+        if git push "$remote_target" --delete "$target_branch"; then
+            log_success "Successfully wiped out remote branch '$target_branch' from server."
+        else
+            die "Server rejected the branch drop execution request."
+        fi
+    fi
+}
+
+# xgem git <cmt|init|rm-remote|rm-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>" ;;
+    esac
+}

package/lib/ios.sh

@@ -0,0 +1,266 @@
+#!/bin/bash
+# xgem iOS build engine — redesigned to handle Swift Package Manager (SPM)
+# reliably, not just CocoaPods.
+#
+# Background (why this exists): Flutter auto-generates a wrapper Swift
+# package, FlutterGeneratedPluginSwiftPackage, that aggregates plugin SPM
+# dependencies. Its declared minimum iOS platform does not always stay in
+# sync with the app's IPHONEOS_DEPLOYMENT_TARGET in project.pbxproj — a
+# confirmed, currently-open upstream Flutter bug (flutter/flutter#186804,
+# #189422, #162072). A single sed patch to pbxproj alone does not fix this
+# reliably: (a) pbxproj has multiple IPHONEOS_DEPLOYMENT_TARGET entries
+# across Debug/Release/Profile x Runner/RunnerTests, and (b) even a fully
+# correct pbxproj patch doesn't force-regenerate the generated package.
+#
+# This engine: detects the actual required deployment target from resolved
+# SPM plugin manifests (instead of hardcoding a guess), patches every
+# pbxproj occurrence, forces regeneration, verifies the regenerated package
+# matches, and falls back to directly patching the generated package as a
+# documented last resort if the upstream desync bug is still present.
+#
+# Depends on lib/logger.sh, lib/utils.sh.
+
+ios_pbxproj_path() {
+    local project_dir=${1:-.}
+    echo "$project_dir/ios/Runner.xcodeproj/project.pbxproj"
+}
+
+ios_project_uses_pods() {
+    local project_dir=${1:-.}
+    [ -f "$project_dir/ios/Podfile" ]
+}
+
+# ios_project_uses_spm: authoritative signal is a reference to the generated
+# aggregate package inside the Xcode project itself, not just Flutter's
+# global config toggle (which reflects intent, not what's actually wired
+# into *this* project).
+ios_project_uses_spm() {
+    local project_dir=${1:-.}
+    local pbxproj
+    pbxproj=$(ios_pbxproj_path "$project_dir")
+    [ -f "$pbxproj" ] && grep -q "FlutterGeneratedPluginSwiftPackage" "$pbxproj"
+}
+
+# ios_deployment_target_for_config <Debug|Release|Profile> [project_dir]
+# Authoritative: asks Xcode itself via -showBuildSettings rather than
+# grepping pbxproj, so it reflects any xcconfig overrides too. Falls back
+# to the pbxproj's own declared value if xcodebuild isn't available.
+ios_deployment_target_for_config() {
+    local config=$1
+    local project_dir=${2:-.}
+    local -a xcb_args=()
+
+    if [ -f "$project_dir/ios/Runner.xcworkspace/contents.xcworkspacedata" ]; then
+        xcb_args=(-workspace "$project_dir/ios/Runner.xcworkspace" -scheme Runner)
+    elif [ -d "$project_dir/ios/Runner.xcodeproj" ]; then
+        xcb_args=(-project "$project_dir/ios/Runner.xcodeproj" -target Runner)
+    else
+        return 1
+    fi
+
+    if has_cmd xcodebuild; then
+        local value
+        value=$(xcodebuild -showBuildSettings "${xcb_args[@]}" -configuration "$config" 2>/dev/null \
+            | grep -m1 'IPHONEOS_DEPLOYMENT_TARGET' | awk '{print $NF}')
+        [ -n "$value" ] && { echo "$value"; return 0; }
+    fi
+
+    log_debug "xcodebuild unavailable or gave no result; falling back to pbxproj grep for $config."
+    ios_pbxproj_current_max_target "$project_dir"
+}
+
+ios_pbxproj_current_max_target() {
+    local project_dir=${1:-.}
+    local pbxproj
+    pbxproj=$(ios_pbxproj_path "$project_dir")
+    [ -f "$pbxproj" ] || return 1
+    grep -oE 'IPHONEOS_DEPLOYMENT_TARGET = [0-9]+(\.[0-9]+)?' "$pbxproj" \
+        | grep -oE '[0-9]+(\.[0-9]+)?' \
+        | sort -g | tail -1
+}
+
+# ios_required_spm_deployment_target [project_dir]
+# Reads .dart_tool/package_config.json (written by `flutter pub get`) to
+# find every resolved package's own ios/Package.swift, and returns the
+# highest .iOS(.vNN) platform floor declared across them. This replaces
+# hardcoding a guessed value (e.g. "15.0") with an actual measurement of
+# what the resolved dependency graph requires.
+ios_required_spm_deployment_target() {
+    local project_dir=${1:-.}
+    local pkg_config="$project_dir/.dart_tool/package_config.json"
+
+    [ -f "$pkg_config" ] || { log_debug "No .dart_tool/package_config.json — run flutter pub get first."; return 1; }
+    has_cmd python3 || { log_debug "python3 not found; cannot parse package_config.json."; return 1; }
+
+    python3 - "$pkg_config" <<'PYEOF'
+import json, os, re, sys
+
+pkg_config_path = sys.argv[1]
+with open(pkg_config_path) as f:
+    data = json.load(f)
+
+base_dir = os.path.dirname(os.path.abspath(pkg_config_path))
+max_target = 0.0
+
+for pkg in data.get("packages", []):
+    root_uri = pkg.get("rootUri", "")
+    if root_uri.startswith("file://"):
+        root = root_uri[len("file://"):]
+    else:
+        root = os.path.normpath(os.path.join(base_dir, root_uri))
+
+    manifest = os.path.join(root, "ios", "Package.swift")
+    if not os.path.isfile(manifest):
+        continue
+    try:
+        with open(manifest, "r", errors="ignore") as mf:
+            content = mf.read()
+    except OSError:
+        continue
+
+    for m in re.finditer(r"\.iOS\(\.v(\d+(?:_\d+)?)\)", content):
+        try:
+            fv = float(m.group(1).replace("_", "."))
+        except ValueError:
+            continue
+        max_target = max(max_target, fv)
+
+if max_target > 0:
+    print(max_target)
+PYEOF
+}
+
+# ios_pbxproj_patch_deployment_target <new_target> [project_dir]
+# Patches EVERY IPHONEOS_DEPLOYMENT_TARGET occurrence (all configs, all
+# targets), unlike a single-match sed. Keeps a timestamped backup.
+ios_pbxproj_patch_deployment_target() {
+    local new_target=$1
+    local project_dir=${2:-.}
+    local pbxproj
+    pbxproj=$(ios_pbxproj_path "$project_dir")
+    [ -f "$pbxproj" ] || die "project.pbxproj not found at $pbxproj"
+
+    local backup="${pbxproj}.xgem-bak-$(date +%Y%m%d%H%M%S)"
+    cp "$pbxproj" "$backup"
+    log_debug "Backed up pbxproj to $backup"
+
+    local tmp
+    tmp=$(mktemp)
+    sed -E "s/(IPHONEOS_DEPLOYMENT_TARGET = )[0-9]+(\.[0-9]+)?;/\1${new_target};/g" "$pbxproj" > "$tmp"
+    mv "$tmp" "$pbxproj"
+
+    local count
+    count=$(grep -c "IPHONEOS_DEPLOYMENT_TARGET = ${new_target};" "$pbxproj")
+    log_success "Patched $count IPHONEOS_DEPLOYMENT_TARGET occurrence(s) in project.pbxproj to $new_target."
+}
+
+# Locates the generated aggregate package. The exact path has moved across
+# Flutter releases, so this feature-detects it via `find` rather than
+# assuming a single fixed location.
+ios_generated_package_swift_path() {
+    local project_dir=${1:-.}
+    local guess="$project_dir/ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage/Package.swift"
+    if [ -f "$guess" ]; then
+        echo "$guess"
+        return 0
+    fi
+    find "$project_dir/ios" -maxdepth 6 -type f -name "Package.swift" \
+        -path "*FlutterGeneratedPluginSwiftPackage*" 2>/dev/null | head -1
+}
+
+ios_generated_package_target() {
+    local project_dir=${1:-.}
+    local pkg
+    pkg=$(ios_generated_package_swift_path "$project_dir")
+    [ -n "$pkg" ] && [ -f "$pkg" ] || return 1
+    grep -oE '\.iOS\(\.v[0-9_]+\)' "$pkg" | head -1 | grep -oE '[0-9_]+' | tr '_' '.'
+}
+
+# Last-resort workaround for the still-open upstream desync bug: directly
+# patch the generated package's platform declaration. Always logged loudly
+# — this is a documented workaround for a known bug, never a silent hack.
+ios_patch_generated_package_target() {
+    local new_target=$1
+    local project_dir=${2:-.}
+    local pkg
+    pkg=$(ios_generated_package_swift_path "$project_dir")
+    if [ -z "$pkg" ] || [ ! -f "$pkg" ]; then
+        log_warn "Could not locate FlutterGeneratedPluginSwiftPackage/Package.swift to patch."
+        return 1
+    fi
+
+    log_warn "Working around known Flutter SPM bug (flutter/flutter#186804): the regenerated package still doesn't match your deployment target, so patching it directly."
+    local token=${new_target//./_}
+    local tmp
+    tmp=$(mktemp)
+    sed -E "s/\.iOS\(\.v[0-9_]+\)/.iOS(.v${token})/g" "$pkg" > "$tmp"
+    mv "$tmp" "$pkg"
+    log_success "Patched generated package platform to iOS $new_target."
+}
+
+ios_regenerate_generated_package() {
+    local project_dir=${1:-.}
+    log_info "Clearing ephemeral iOS config to force a clean regeneration..."
+    rm -rf "$project_dir/ios/Flutter/ephemeral"
+    ( cd "$project_dir" && flutter pub get )
+}
+
+ios_known_issue_check() {
+    log_warn "Known upstream issue (flutter/flutter#186804, #189422, #162072): FlutterGeneratedPluginSwiftPackage's deployment target can desync from your app's IPHONEOS_DEPLOYMENT_TARGET. Currently open — xgem detects and works around it automatically below."
+}
+
+# ios_reconcile_deployment_target [project_dir]
+# The core "self-healing" step: detect a required-vs-current mismatch, plan
+# the fix, confirm (unless --yes/--dry-run), apply, regenerate, verify, and
+# fall back to the documented workaround if the upstream bug is still biting.
+# Returns 0 if no action was needed or the fix succeeded; 1 if it couldn't
+# reconcile and the caller should stop before attempting a build.
+ios_reconcile_deployment_target() {
+    local project_dir=${1:-.}
+
+    ios_project_uses_spm "$project_dir" || { log_debug "Project does not use SwiftPM; skipping deployment-target reconciliation."; return 0; }
+
+    local required current
+    required=$(ios_required_spm_deployment_target "$project_dir")
+    current=$(ios_deployment_target_for_config "Release" "$project_dir")
+
+    if [ -z "$required" ]; then
+        log_debug "Could not determine a required deployment target from resolved SPM plugins; skipping reconciliation."
+        return 0
+    fi
+    if [ -z "$current" ]; then
+        log_warn "Could not determine the project's current deployment target; proceeding without reconciliation."
+        return 0
+    fi
+
+    ios_known_issue_check
+
+    if awk -v a="$required" -v b="$current" 'BEGIN{exit !(a>b)}'; then
+        log_warn "Resolved SwiftPM plugins require iOS $required, but the project targets iOS $current."
+        echo "Plan:"
+        echo "  1. Set IPHONEOS_DEPLOYMENT_TARGET = $required across every build configuration in project.pbxproj"
+        echo "  2. Clear ios/Flutter/ephemeral and re-run 'flutter pub get' to regenerate FlutterGeneratedPluginSwiftPackage"
+        echo "  3. Verify the regenerated package declares iOS $required; if it still doesn't (known upstream bug), patch it directly"
+
+        if ! confirm "Apply this fix?"; then
+            log_warn "Skipped. The build will likely fail SwiftPM resolution until the deployment target is reconciled manually."
+            return 1
+        fi
+
+        ios_pbxproj_patch_deployment_target "$required" "$project_dir"
+        ios_regenerate_generated_package "$project_dir"
+
+        local regenerated
+        regenerated=$(ios_generated_package_target "$project_dir")
+        if [ "$regenerated" = "$required" ]; then
+            log_success "Generated package now correctly declares iOS $regenerated."
+        else
+            log_warn "Generated package declares '${regenerated:-unknown}' after regeneration, not $required."
+            ios_patch_generated_package_target "$required" "$project_dir"
+        fi
+    else
+        log_debug "Deployment target ($current) already satisfies SwiftPM requirement ($required)."
+    fi
+
+    return 0
+}

package/lib/logger.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# xgem logger — consistent log levels + verbose/debug mode.
+# Sourced by bin/xgem before any other lib module.
+
+: "${XGEM_VERBOSE:=0}"
+
+_c_red=$'\033[31m'
+_c_green=$'\033[32m'
+_c_yellow=$'\033[33m'
+_c_blue=$'\033[1;34m'
+_c_gray=$'\033[90m'
+_c_reset=$'\033[0m'
+
+log_info()    { echo -e "${_c_blue}[INFO]${_c_reset} $*"; }
+log_success() { echo -e "${_c_green}[ OK ]${_c_reset} $*"; }
+log_warn()    { echo -e "${_c_yellow}[WARN]${_c_reset} $*" >&2; }
+log_error()   { echo -e "${_c_red}[FAIL]${_c_reset} $*" >&2; }
+
+log_debug() {
+    [ "$XGEM_VERBOSE" = "1" ] || return 0
+    echo -e "${_c_gray}[DBG ] $*${_c_reset}" >&2
+}
+
+# die <message> [exit_code]
+die() {
+    log_error "$1"
+    exit "${2:-1}"
+}

package/lib/scaffold.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# xgem generic scaffold engine for frameworks whose automation is just a
+# canned script (node, python, react/vue/angular, go, rust, docker, swift,
+# and flutter's on-disk copies) — one module driven by template files
+# instead of near-duplicate per-framework code.
+#
+# Flutter's `xgem run flutter <script>` is intercepted earlier by
+# lib/flutter.sh's native commands (see flutter_native_command_exists in
+# bin/xgem's dispatch); the flutter templates here still get scaffolded to
+# `.xgem-automate/flutter/` for manual use and documentation parity.
+#
+# Depends on lib/logger.sh and XGEM_HOME (set by bin/xgem).
+
+ALL_FRAMEWORKS=(flutter node python react vue angular 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" ;;
+        go)      echo "hard-clean build" ;;
+        rust)    echo "hard-clean build" ;;
+        docker)  echo "hard-clean build-up" ;;
+        swift)   echo "hard-clean build" ;;
+        *) return 1 ;;
+    esac
+}
+
+_scaffold_template_dir() {
+    local framework=$1
+    case "$framework" in
+        react|vue|angular) echo "$XGEM_HOME/templates/webframework" ;;
+        *)                 echo "$XGEM_HOME/templates/$framework" ;;
+    esac
+}
+
+# scaffold_inject_templates <framework> <config_dir>
+scaffold_inject_templates() {
+    local framework=$1
+    local config_dir=$2
+    local scripts src_dir dest_dir script
+
+    scripts=$(framework_scripts "$framework") || die "Unknown framework '$framework'."
+    src_dir=$(_scaffold_template_dir "$framework")
+    dest_dir="$config_dir/$framework"
+    mkdir -p "$dest_dir"
+
+    for script in $scripts; do
+        local src="$src_dir/${script}.sh.tmpl"
+        local dest="$dest_dir/${script}.sh"
+        if [ ! -f "$src" ]; then
+            log_warn "Missing template $src, skipping."
+            continue
+        fi
+        sed "s/__FRAMEWORK__/$framework/g" "$src" > "$dest"
+        chmod +x "$dest"
+    done
+}
+
+# scaffold_run_script <framework> <script> <config_dir>
+scaffold_run_script() {
+    local framework=$1
+    local script=$2
+    local config_dir=$3
+    local target="$config_dir/$framework/${script}.sh"
+
+    if [ -f "$target" ]; then
+        log_info "Running script '$script' for $framework..."
+        bash "$target"
+    else
+        log_error "Script not found at $target"
+        if [ -d "$config_dir/$framework" ]; then
+            echo "Available scripts in '$framework':"
+            ls "$config_dir/$framework" | sed 's/\.sh$//' | sed 's/^/  - /'
+        fi
+        exit 1
+    fi
+}
+
+scaffold_get_remaining_frameworks() {
+    local config_dir=$1
+    REMAINING_FWS=()
+    local fw
+    for fw in "${ALL_FRAMEWORKS[@]}"; do
+        [ -d "$config_dir/$fw" ] || REMAINING_FWS+=("$fw")
+    done
+}

package/lib/utils.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# xgem shared utilities — os/arch detection, confirmation prompts, command checks.
+# Depends on lib/logger.sh being sourced first.
+
+: "${XGEM_YES:=0}"
+: "${XGEM_DRY_RUN:=0}"
+
+# detect_os -> darwin | linux | unknown
+detect_os() {
+    case "$(uname -s)" in
+        Darwin) echo "darwin" ;;
+        Linux)  echo "linux" ;;
+        *)      echo "unknown" ;;
+    esac
+}
+
+# detect_arch -> arm64 | x86_64 | <raw uname -m>
+detect_arch() {
+    uname -m
+}
+
+# is_apple_silicon -> 0 (true) if darwin + arm64, 1 otherwise
+is_apple_silicon() {
+    [ "$(detect_os)" = "darwin" ] && [ "$(detect_arch)" = "arm64" ]
+}
+
+# has_cmd <name> -> 0/1, no output
+has_cmd() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# require_cmd <name> [install-hint]
+require_cmd() {
+    local name=$1
+    local hint=${2:-}
+    if ! has_cmd "$name"; then
+        if [ -n "$hint" ]; then
+            die "'$name' is required but not found. $hint"
+        else
+            die "'$name' is required but not found in PATH."
+        fi
+    fi
+}
+
+# confirm "prompt text" -> 0 if approved, 1 otherwise
+# Honors XGEM_YES=1 (from --yes) to auto-approve, and always returns 1
+# (declines) under XGEM_DRY_RUN so callers never apply changes in dry-run mode.
+confirm() {
+    local prompt=$1
+    if [ "$XGEM_DRY_RUN" = "1" ]; then
+        log_info "(dry-run) would prompt: $prompt"
+        return 1
+    fi
+    if [ "$XGEM_YES" = "1" ]; then
+        log_debug "auto-confirmed (--yes): $prompt"
+        return 0
+    fi
+    local reply
+    read -r -p "$prompt [y/N]: " reply
+    [[ "$reply" == "y" || "$reply" == "Y" ]]
+}

package/lib/version.sh

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "xgem-cli",
+  "version": "2.0.0-alpha",
+  "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.",
+  "bin": {
+    "xgem": "bin/xgem"
+  },
+  "files": [
+    "bin/xgem",
+    "lib",
+    "templates"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "test": "bash -n bin/xgem && for f in lib/*.sh; do bash -n \"$f\"; done"
+  },
+  "keywords": [
+    "cli",
+    "automation",
+    "flutter",
+    "node",
+    "build",
+    "git"
+  ],
+  "author": "Paulo Michael",
+  "license": "MIT"
+}

package/templates/docker/build-up.sh.tmpl

@@ -0,0 +1,2 @@
+#!/bin/bash
+docker-compose up --build -d

package/templates/docker/hard-clean.sh.tmpl

@@ -0,0 +1,3 @@
+#!/bin/bash
+echo -e "\033[1;33mPruning unused Docker assets and volumes...\033[0m"
+docker system prune -a --volumes -f

package/templates/flutter/build-runner.sh.tmpl

@@ -0,0 +1,4 @@
+#!/bin/bash
+# This file just delegates to xgem's native flutter engine (lib/flutter.sh)
+# so there's a single source of truth instead of two copies that can drift.
+exec xgem run flutter build-runner

package/templates/flutter/build.sh.tmpl

@@ -0,0 +1,5 @@
+#!/bin/bash
+# This file just delegates to xgem's native flutter engine (lib/flutter.sh),
+# which includes the SwiftPM-aware iOS deployment-target reconciliation.
+# It exists on disk for documentation/manual-run parity with other frameworks.
+exec xgem run flutter build

package/templates/flutter/hard-clean.sh.tmpl

@@ -0,0 +1,5 @@
+#!/bin/bash
+# This file just delegates to xgem's native flutter engine (lib/flutter.sh)
+# so there's a single source of truth instead of two copies that can drift.
+# It exists on disk for documentation/manual-run parity with other frameworks.
+exec xgem run flutter hard-clean

package/templates/go/build.sh.tmpl

@@ -0,0 +1,2 @@
+#!/bin/bash
+go build -o bin/main main.go

package/templates/go/hard-clean.sh.tmpl

@@ -0,0 +1,3 @@
+#!/bin/bash
+echo -e "\033[1;33mCleaning Go module cache...\033[0m"
+go clean -modcache