xgem-cli 2.0.0-alpha

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Michael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# 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.
+
+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
+deployment target your resolved SPM plugins require (instead of guessing),
+and reconciles it automatically — see [Why the iOS build engine exists](#why-the-ios-build-engine-exists).
+
+## Install
+
+### Homebrew (macOS/Linux)
+
+```sh
+brew tap Code4Hacker/xgem
+brew install xgem
+```
+
+*(requires a separate `homebrew-xgem` tap repo and a tagged release — not set up yet)*
+
+### npm
+
+```sh
+npm install -g xgem-cli
+```
+
+*(not yet published to the npm registry)*
+
+### curl
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Code4Hacker/x-gem-cli/xgem/install.sh | bash
+```
+
+## Usage
+
+```
+xgem init                     Initialize tracking system and add first framework
+xgem add                      Interactive state-aware addition of remaining frameworks
+xgem run <framework> <script> Run a workspace automation command script
+xgem terminate                Purge all generated automated layouts completely
+xgem <framework> [help]       View tailored instructions for a specific script layout
+xgem doctor                   Report on your environment (OS, arch, toolchains found)
+xgem doctor ios [path]        Report on iOS build readiness: CocoaPods vs SPM, deployment
+                               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 rm-remote            Drop a configured remote
+xgem git rm-branch            Safely drop local and/or remote branch
+xgem --version                Print xgem's version
+
+Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose
+```
+
+## Supported frameworks
+
+flutter, node, python, react, vue, angular, go, rust, docker, swift
+
+## Architecture
+
+```
+bin/xgem       thin dispatcher — no business logic, just resolves paths and routes commands
+lib/
+  logger.sh    log levels + verbose mode
+  utils.sh     os/arch detection, confirm(), require_cmd()
+  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
+  scaffold.sh  generic clean/build/dev handling for the other, simpler frameworks
+templates/     the actual clean/build/dev script content xgem scaffolds into your project's .xgem-automate/
+```
+
+`xgem run flutter <script>` always goes through the native engine in `lib/flutter.sh`;
+the `.xgem-automate/flutter/*.sh` files that get scaffolded into your project are thin
+delegators to `xgem run flutter <script>`, so there's a single source of truth instead
+of logic that can drift out of sync with two copies.
+
+## Why the iOS build engine exists
+
+Flutter auto-generates a wrapper Swift package, `FlutterGeneratedPluginSwiftPackage`,
+that aggregates your plugins' SPM dependencies. Its declared minimum iOS platform can
+desync from your app's own `IPHONEOS_DEPLOYMENT_TARGET` — a confirmed, currently-open
+upstream Flutter bug ([flutter/flutter#186804](https://github.com/flutter/flutter/issues/186804),
+[#189422](https://github.com/flutter/flutter/issues/189422),
+[#162072](https://github.com/flutter/flutter/issues/162072)). A single `sed` patch to
+`project.pbxproj` doesn't reliably fix this: there are multiple deployment-target entries
+across Debug/Release/Profile × Runner/RunnerTests, and even a fully correct patch doesn't
+force Flutter to regenerate the generated package.
+
+`xgem run flutter build` (for the iOS target) instead:
+
+1. Detects whether the project uses CocoaPods, SPM, or both.
+2. Computes the deployment target actually required by your *resolved* SPM plugins
+   (by reading their `ios/Package.swift` manifests via `.dart_tool/package_config.json`),
+   instead of assuming a fixed value.
+3. Shows a plan and asks for confirmation (unless `--yes`/`--dry-run`) before patching
+   *every* `IPHONEOS_DEPLOYMENT_TARGET` occurrence in `project.pbxproj`.
+4. Forces a clean regeneration (`flutter pub get` after clearing `ios/Flutter/ephemeral`)
+   and verifies the regenerated package matches.
+5. If it still doesn't (the upstream bug above), patches the generated package directly
+   as a documented, loudly-logged last resort — never silently.
+
+Run `xgem doctor ios` any time for a standalone readiness report without doing a build.
+
+## Roadmap
+
+Deferred to a follow-up pass, not yet in this release:
+- Full self-healing/doctor treatment for the non-Flutter frameworks
+- A plugin system (`xgem plugin install <name>`), starting with docker + firebase
+- Shell completions, `--json` output, per-project config caching (stop re-prompting
+  build name/number/platform every run)
+- Deeper Android SDK/Java detection
+
+## License
+
+MIT

package/bin/xgem

@@ -0,0 +1,230 @@
+#!/bin/bash
+# xgem — framework-aware automation CLI. Entry point only: this dispatches
+# to lib/*.sh modules and holds no business logic of its own.
+
+_resolve_self_dir() {
+    local src="${BASH_SOURCE[0]}"
+    while [ -h "$src" ]; do
+        local dir
+        dir="$(cd -P "$(dirname "$src")" >/dev/null 2>&1 && pwd)"
+        src="$(readlink "$src")"
+        [[ $src != /* ]] && src="$dir/$src"
+    done
+    cd -P "$(dirname "$src")" >/dev/null 2>&1 && pwd
+}
+
+BIN_DIR="$(_resolve_self_dir)"
+XGEM_HOME="$(cd -P "$BIN_DIR/.." >/dev/null 2>&1 && pwd)"
+export XGEM_HOME
+
+# shellcheck source=lib/logger.sh
+source "$XGEM_HOME/lib/logger.sh"
+# shellcheck source=lib/utils.sh
+source "$XGEM_HOME/lib/utils.sh"
+# shellcheck source=lib/version.sh
+source "$XGEM_HOME/lib/version.sh"
+# shellcheck source=lib/doctor.sh
+source "$XGEM_HOME/lib/doctor.sh"
+# shellcheck source=lib/git.sh
+source "$XGEM_HOME/lib/git.sh"
+# shellcheck source=lib/ios.sh
+source "$XGEM_HOME/lib/ios.sh"
+# shellcheck source=lib/flutter.sh
+source "$XGEM_HOME/lib/flutter.sh"
+# shellcheck source=lib/scaffold.sh
+source "$XGEM_HOME/lib/scaffold.sh"
+
+CONFIG_DIR=".xgem-automate"
+
+# ---- Global flags: --yes, --dry-run, --verbose — recognized anywhere in
+# the argument list and stripped before dispatch. ----
+ARGS=()
+for arg in "$@"; do
+    case "$arg" in
+        --yes)     XGEM_YES=1 ;;
+        --dry-run) XGEM_DRY_RUN=1 ;;
+        --verbose) XGEM_VERBOSE=1 ;;
+        *) ARGS+=("$arg") ;;
+    esac
+done
+set -- "${ARGS[@]}"
+
+print_banner() {
+    echo -e "\033[38;5;208m"
+    echo -e "██╗  ██╗       ██████╗ ███████╗███╗   ███╗██╗███╗   ██╗██╗"
+    echo -e "╚██╗██╔╝      ██╔════╝ ██╔════╝████╗ ████║██║████╗  ██║██║"
+    echo -e " ╚███╔╝ █████╗██║  ███╗█████╗  ██╔████╔██║██║██╔██╗ ██║██║"
+    echo -e " ██╔██╗ ╚════╝██║   ██║██╔══╝  ██║╚██╔╝██║██║██║╚██╗██║██║"
+    echo -e "██╔╝ ██╗      ╚██████╔╝███████╗██║ ╚═╝ ██║██║██║ ╚████║██║"
+    echo -e "╚═╝  ╚═╝       ╚═════╝ ╚══════╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝\033[0m"
+    echo -e "\033[1;36m           ....Authored by Paulo Michael....\033[0m\n"
+}
+
+print_usage() {
+    echo "Usage:"
+    echo "  xgem init                     - Initialize tracking system and add first framework"
+    echo "  xgem add                      - Interactive state-aware addition of remaining frameworks"
+    echo "  xgem run <framework> <script> - Run a workspace automation command script"
+    echo "  xgem terminate                - Purge all generated automated layouts completely"
+    echo "  xgem <framework> [help]       - View tailored instructions for a specific script layout"
+    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 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"
+    echo ""
+    echo "Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose"
+}
+
+case "${1:-}" in
+    init)
+        print_banner
+        if [ -d "$CONFIG_DIR" ]; then
+            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
+                scaffold_inject_templates "$fw" "$CONFIG_DIR"
+                log_success "Successfully appended standard scripts for: $CONFIG_DIR/$fw"
+                break
+            else
+                echo "Invalid selection."
+            fi
+        done
+
+        if [ -f .gitignore ]; then
+            if ! grep -q "$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
+        exit 0
+        ;;
+
+    add)
+        [ -d "$CONFIG_DIR" ] || die "System tracking layer not found. Run 'xgem init' first."
+
+        scaffold_get_remaining_frameworks "$CONFIG_DIR"
+
+        if [ ${#REMAINING_FWS[@]} -eq 0 ]; then
+            log_warn "All available framework blocks are already generated inside the workspace!"
+            read -r -p "Do you want to restore/regenerate all framework templates to defaults? (y/n): " restore_choice
+            if [[ "$restore_choice" == "y" || "$restore_choice" == "Y" ]]; then
+                for fw in "${ALL_FRAMEWORKS[@]}"; do
+                    scaffold_inject_templates "$fw" "$CONFIG_DIR"
+                done
+                log_success "All framework automation layouts cleanly re-generated!"
+            fi
+            exit 0
+        fi
+
+        echo -e "\033[1;34mSelect a framework script block to add:\033[0m"
+        PS3="Choose an unconfigured system tool: "
+        select choice in "${REMAINING_FWS[@]}" "Cancel"; do
+            if [ "$choice" == "Cancel" ]; then
+                echo "Operation canceled."
+                exit 0
+            elif [ -n "$choice" ]; then
+                scaffold_inject_templates "$choice" "$CONFIG_DIR"
+                log_success "Successfully loaded and updated files for: $CONFIG_DIR/$choice"
+                break
+            else
+                echo "Invalid option."
+            fi
+        done
+        exit 0
+        ;;
+
+    run)
+        FRAMEWORK=${2:-}
+        SCRIPT_NAME=${3:-}
+        [ -n "$FRAMEWORK" ] && [ -n "$SCRIPT_NAME" ] || die "Usage: xgem run <framework> <script>"
+
+        if [ "$FRAMEWORK" = "flutter" ] && flutter_native_command_exists "$SCRIPT_NAME"; then
+            flutter_run_native_command "$SCRIPT_NAME"
+        else
+            scaffold_run_script "$FRAMEWORK" "$SCRIPT_NAME" "$CONFIG_DIR"
+        fi
+        exit 0
+        ;;
+
+    terminate)
+        [ -d "$CONFIG_DIR" ] || die "Tracking layer $CONFIG_DIR not found. Nothing to terminate."
+
+        log_warn "Initiating core termination sequence for $CONFIG_DIR..."
+        FOLDERS=($(find "$CONFIG_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \;))
+        COUNT=${#FOLDERS[@]}
+
+        confirm "This deletes $CONFIG_DIR and everything in it. Continue?" || { log_info "Cancelled."; exit 0; }
+
+        for fw in "${FOLDERS[@]}"; do
+            echo -e "  \033[31m[ x ]\033[0m Removing $fw..."
+            rm -rf "${CONFIG_DIR:?}/$fw"
+        done
+        rm -rf "$CONFIG_DIR"
+
+        if [ -f .gitignore ]; then
+            grep -v "^$CONFIG_DIR/" .gitignore > tmp_gitignore && mv tmp_gitignore .gitignore
+            log_success "Cleaned up .gitignore tracking records."
+        fi
+
+        log_success "Termination complete. Total blocks destroyed: $COUNT (${FOLDERS[*]:-none})"
+        exit 0
+        ;;
+
+    git)
+        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|rm-remote|rm-branch>"
+        cmd_git "$2" "${3:-}"
+        exit 0
+        ;;
+
+    doctor)
+        cmd_doctor "${2:-}" "${3:-.}"
+        exit 0
+        ;;
+
+    --version|-V|version)
+        print_version
+        exit 0
+        ;;
+
+    flutter|node|python|react|vue|angular|go|rust|docker|swift)
+        TARGET_FW=$1
+        TARGET_FW_UPPER=$(echo "$TARGET_FW" | tr '[:lower:]' '[:upper:]')
+
+        echo -e "\033[1;36m=== $TARGET_FW_UPPER Automation Blueprint ===\033[0m"
+        if [ ! -d "$CONFIG_DIR/$TARGET_FW" ]; then
+            log_warn "Status: Not currently injected in this workspace."
+            echo -e "Run \033[1;32mxgem add\033[0m to instantly append its structural scripts.\n"
+        else
+            log_success "Status: Active & Mounted inside $CONFIG_DIR/$TARGET_FW/"
+            echo ""
+        fi
+
+        echo -e "To execute scripts, use: \033[1;34mxgem run $TARGET_FW <script>\033[0m\n"
+        echo "Configured Commands:"
+        for script in $(framework_scripts "$TARGET_FW"); do
+            echo -e "  \033[1;32m$script\033[0m"
+        done
+        if [ "$TARGET_FW" = "flutter" ]; then
+            echo ""
+            log_info "Flutter builds now use xgem's SwiftPM-aware iOS engine automatically. Run 'xgem doctor ios' for a build-readiness report."
+        fi
+        echo ""
+        exit 0
+        ;;
+
+    *)
+        print_usage
+        exit 0
+        ;;
+esac

package/lib/doctor.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# xgem doctor — environment + feature detection.
+# Never assumes; always probes for the actual capability/version/config present.
+# Depends on lib/logger.sh, lib/utils.sh (and, for `doctor ios`, lib/ios.sh).
+
+doctor_tool_version() {
+    local name=$1
+    local version_flag=${2:---version}
+    if has_cmd "$name"; then
+        "$name" $version_flag 2>&1 | head -1
+    else
+        echo "not found"
+    fi
+}
+
+# flutter_supports_flag <command> <flag>
+# Feature detection instead of version-gating: probe --help output for the
+# flag rather than assuming it exists as of some Flutter version.
+flutter_supports_flag() {
+    local subcmd=$1
+    local flag=$2
+    has_cmd flutter || return 1
+    flutter "$subcmd" --help 2>/dev/null | grep -q -- "$flag"
+}
+
+flutter_config_spm_enabled() {
+    has_cmd flutter || { echo "unknown (flutter not found)"; return; }
+    local line
+    line=$(flutter config 2>/dev/null | grep -i "swift-package-manager")
+    if [ -z "$line" ]; then
+        echo "unknown (not reported by this Flutter version)"
+    else
+        echo "$line" | sed -E 's/^[[:space:]]*//'
+    fi
+}
+
+doctor_print_general() {
+    echo -e "\033[1;36m=== xgem doctor ===\033[0m"
+    echo "OS:              $(detect_os)"
+    echo "Arch:            $(detect_arch)$( is_apple_silicon && echo ' (Apple Silicon)' )"
+    echo "git:             $(doctor_tool_version git)"
+    echo "flutter:         $(doctor_tool_version flutter)"
+    echo "dart:            $(doctor_tool_version dart)"
+    echo "node:            $(doctor_tool_version node)"
+    echo "python3:         $(doctor_tool_version python3)"
+    echo "go:              $(doctor_tool_version go version)"
+    echo "cargo:           $(doctor_tool_version cargo)"
+    echo "docker:          $(doctor_tool_version docker)"
+    if [ "$(detect_os)" = "darwin" ]; then
+        echo "xcodebuild:      $(doctor_tool_version xcodebuild -version)"
+        echo "pod (CocoaPods): $(doctor_tool_version pod)"
+    fi
+}
+
+# doctor_print_ios [project_dir]
+doctor_print_ios() {
+    local project_dir=${1:-.}
+    echo -e "\033[1;36m=== xgem doctor ios ===\033[0m"
+
+    if [ "$(detect_os)" != "darwin" ]; then
+        log_warn "iOS builds require macOS. Detected OS: $(detect_os)."
+    fi
+
+    echo "flutter:                 $(doctor_tool_version flutter)"
+    echo "xcodebuild:              $(doctor_tool_version xcodebuild -version)"
+    echo "CocoaPods:                $(doctor_tool_version pod)"
+    echo "SPM enabled (global cfg): $(flutter_config_spm_enabled)"
+
+    if [ ! -d "$project_dir/ios" ]; then
+        log_warn "No ios/ directory found under '$project_dir' — not a Flutter project with an iOS target, or run this from the project root."
+        return 0
+    fi
+
+    local uses_pods=no uses_spm=no
+    ios_project_uses_pods "$project_dir" && uses_pods=yes
+    ios_project_uses_spm "$project_dir" && uses_spm=yes
+    echo "Project uses CocoaPods:  $uses_pods"
+    echo "Project uses SwiftPM:    $uses_spm"
+    if [ "$uses_pods" = "yes" ] && [ "$uses_spm" = "yes" ]; then
+        log_warn "Mixed CocoaPods + SwiftPM detected. Flutter's own docs note this can cause complex dependency cycles and build errors — prefer migrating fully to SPM where all plugins support it."
+    fi
+
+    for cfg in Debug Release Profile; do
+        local t
+        t=$(ios_deployment_target_for_config "$cfg" "$project_dir" 2>/dev/null)
+        echo "Deployment target [$cfg]: ${t:-unknown}"
+    done
+
+    local required
+    required=$(ios_required_spm_deployment_target "$project_dir" 2>/dev/null)
+    if [ -n "$required" ]; then
+        echo "Required by resolved SwiftPM plugins: $required"
+    else
+        echo "Required by resolved SwiftPM plugins: unable to determine (run 'flutter pub get' first, or no SPM plugins declare an explicit floor)"
+    fi
+
+    if [ "$uses_spm" = "yes" ]; then
+        ios_known_issue_check
+    fi
+}
+
+# xgem doctor [ios]
+cmd_doctor() {
+    case "${1:-}" in
+        ios) doctor_print_ios "${2:-.}" ;;
+        "")  doctor_print_general ;;
+        *)   die "Unknown doctor target '$1'. Usage: xgem doctor [ios]" ;;
+    esac
+}

package/lib/flutter.sh

@@ -0,0 +1,207 @@
+#!/bin/bash
+# xgem flutter command group. iOS builds delegate to lib/ios.sh for
+# SwiftPM-aware deployment-target reconciliation before ever calling
+# `flutter build ios`.
+#
+# Depends on lib/logger.sh, lib/utils.sh, lib/ios.sh.
+
+cmd_flutter_hard_clean() {
+    log_info "Cleaning Flutter project..."
+    rm -f pubspec.lock
+    flutter clean
+
+    if [ -d ios ]; then
+        log_info "Removing iOS ephemeral files..."
+        rm -rf ios/Flutter/ephemeral
+        (
+            cd ios || exit 1
+            if [ -f Podfile ]; then
+                log_info "CocoaPods detected - removing lock and Pods..."
+                rm -f Podfile.lock
+                rm -rf Pods
+            else
+                log_info "Swift Package Manager detected - resolving packages..."
+                xcodebuild -resolvePackageDependencies -workspace Runner.xcworkspace -scheme Runner
+            fi
+        )
+    else
+        log_info "No iOS target found, skipping iOS-specific cleanup."
+    fi
+
+    log_info "Getting Flutter packages..."
+    flutter pub get
+
+    if [ -f ios/Podfile ]; then
+        log_info "Installing iOS Pods..."
+        ( cd ios || exit 1; pod install )
+    fi
+
+    log_info "Running Flutter..."
+    flutter run -v
+}
+
+cmd_flutter_build_runner() {
+    log_info "Running Flutter Build Runner..."
+    local verbose_choice
+    read -r -p "Run in verbose mode? (Y/n): " verbose_choice
+    verbose_choice=${verbose_choice:-Y}
+
+    local -a cmd=(flutter pub run build_runner build --delete-conflicting-outputs)
+    if [[ "$verbose_choice" == "Y" || "$verbose_choice" == "y" ]]; then
+        cmd+=(-v)
+    fi
+    log_info "Executing: ${cmd[*]}"
+    "${cmd[@]}"
+}
+
+_flutter_pubspec_version() {
+    [ -f pubspec.yaml ] || return 1
+    grep '^version:' pubspec.yaml | head -n 1 | awk '{print $2}'
+}
+
+_flutter_build_ios() {
+    local build_name=$1
+    local build_number=$2
+    local mode=$3
+
+    require_cmd xcodebuild "iOS builds require Xcode's command-line tools."
+
+    log_info "Reconciling iOS deployment target against resolved SwiftPM plugins..."
+    if ! ios_reconcile_deployment_target "."; then
+        die "iOS deployment target could not be reconciled; aborting before build."
+    fi
+
+    log_info "Regenerating dependencies..."
+    flutter pub get
+
+    if ios_project_uses_pods "."; then
+        log_info "CocoaPods detected - installing pods..."
+        ( cd ios || exit 1; pod install )
+    elif ios_project_uses_spm "."; then
+        log_info "Swift Package Manager detected - resolving packages..."
+        xcodebuild -resolvePackageDependencies -workspace ios/Runner.xcworkspace -scheme Runner
+    fi
+
+    log_info "Initializing Flutter iOS Build ($mode)..."
+    local log_file
+    log_file=$(mktemp)
+    if ! flutter build ios "$mode" "--build-name=$build_name" "--build-number=$build_number" > "$log_file" 2>&1; then
+        log_error "Build FAILED"
+        cat "$log_file"
+        die "flutter build ios failed" "$?"
+    fi
+    log_success "Build complete."
+
+    log_info "Archiving for Xcode Organizer..."
+    local archive_date archive_time archive_dir archive_path
+    archive_date=$(date +%Y-%m-%d)
+    archive_time=$(date +%H.%M.%S)
+    archive_dir="$HOME/Library/Developer/Xcode/Archives/$archive_date"
+    mkdir -p "$archive_dir"
+    archive_path="$archive_dir/Runner $archive_time.xcarchive"
+
+    if ! xcodebuild -workspace ios/Runner.xcworkspace \
+        -scheme Runner \
+        -sdk iphoneos \
+        -configuration Release \
+        archive \
+        -archivePath "$archive_path" \
+        "BUILD_NUMBER=$build_number" \
+        "MARKETING_VERSION=$build_name" \
+        -allowProvisioningUpdates > "$log_file" 2>&1; then
+        log_error "Archive FAILED"
+        cat "$log_file"
+        die "xcodebuild archive failed" "$?"
+    fi
+    log_success "Archive created at: $archive_path"
+
+    if has_cmd osascript; then
+        osascript -e '
+            tell application "Xcode" to activate
+            delay 1
+            tell application "System Events" to tell process "Xcode"
+                click menu item "Organizer" of menu "Window" of menu bar 1
+            end tell
+        ' 2>/dev/null
+    fi
+    open ios/Runner.xcworkspace 2>/dev/null
+}
+
+cmd_flutter_build() {
+    echo -e "\033[1;34m--- Flutter Build Orchestrator ---\033[0m"
+
+    local current_name="" current_num="" current_full
+    if current_full=$(_flutter_pubspec_version) && [ -n "$current_full" ]; then
+        current_name=${current_full%%+*}
+        current_num=${current_full#*+}
+        [ "$current_name" = "$current_num" ] && current_num="1"
+        log_info "Current pubspec.yaml version: $current_full"
+    fi
+
+    local build_name build_number is_release
+    read -r -p "Enter build version name [${current_name:-1.0.0}]: " build_name
+    build_name=${build_name:-${current_name:-1.0.0}}
+
+    read -r -p "Enter build number [${current_num:-1}]: " build_number
+    build_number=${build_number:-${current_num:-1}}
+
+    read -r -p "Is this a release build? (Y/n) [default: y]: " is_release
+    is_release=${is_release:-y}
+
+    if [ -f pubspec.yaml ]; then
+        local new_version="${build_name}+${build_number}"
+        log_success "Updating pubspec.yaml to version: $new_version"
+        local tmp
+        tmp=$(mktemp)
+        sed -e "s/^version:.*/version: $new_version/" pubspec.yaml > "$tmp" && mv "$tmp" pubspec.yaml
+    fi
+
+    echo ""
+    echo "Select Target Platform:"
+    echo "1) APK (Android)"
+    echo "2) iOS"
+    echo "3) macOS"
+    echo "4) Windows"
+    echo "5) Linux"
+    local platform_choice
+    read -r -p "Choose [1-5]: " platform_choice
+    if ! [[ "$platform_choice" =~ ^[1-5]$ ]]; then
+        die "Invalid platform choice '$platform_choice'."
+    fi
+
+    local mode="--release"
+    [[ "$is_release" == "n" || "$is_release" == "N" ]] && mode="--debug"
+
+    if [ "$platform_choice" -eq 2 ]; then
+        _flutter_build_ios "$build_name" "$build_number" "$mode"
+        return
+    fi
+
+    log_info "Initializing Flutter Build ($mode) for version $build_name+$build_number..."
+    case $platform_choice in
+        1) flutter build apk "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        3) flutter build macos "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        4) flutter build windows "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+        5) flutter build linux "$mode" "--build-name=$build_name" "--build-number=$build_number" ;;
+    esac
+}
+
+# xgem run flutter <script> — native dispatch, called before falling back to
+# any generated .xgem-automate/flutter/<script>.sh template.
+flutter_native_command_exists() {
+    local script=$1
+    case "$script" in
+        hard-clean|build|build-runner) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+flutter_run_native_command() {
+    local script=$1
+    case "$script" in
+        hard-clean)   cmd_flutter_hard_clean ;;
+        build)        cmd_flutter_build ;;
+        build-runner) cmd_flutter_build_runner ;;
+        *) die "No native flutter command for '$script'." ;;
+    esac
+}