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

package/README.md

@@ -13,7 +13,13 @@ your environment, and `xgem git` wraps a common stage → commit → rebase-pull
 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).
+and reconciles it automatically.
+
+**Full documentation: [docs/](https://github.com/Code4Hacker/x-gem-cli/blob/xgem/docs/README.md)** — getting started, every command in
+depth, exactly what each framework's project-creation wizard does, the iOS build
+engine explained, Windows support, and troubleshooting. This README is a summary.
+(Absolute link on purpose — `docs/` isn't shipped inside the npm package itself,
+so a relative link would 404 on npmjs.com's rendered README.)
 
 ## Install
 
@@ -56,6 +62,14 @@ 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 git pr                   Push current branch and open a GitHub PR (gh-backed)
+xgem git sync                 Rebase current branch onto the repo's base branch
+xgem git clean-branches       Delete local branches already merged into the base branch
+xgem git hooks <install|uninstall> Manage a pre-commit lint/test hook
+xgem release [major|minor|patch] Bump version, update CHANGELOG.md, tag, push
+xgem status                   Dashboard across every xgem-tracked project
+xgem bootstrap                Clone-to-running: detect framework, install, .env, migrate, launch
+xgem ci                       Run lint/test/build for every configured framework, summarized
 xgem --version                Print xgem's version
 
 Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose
@@ -68,31 +82,13 @@ 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.
+what's already in the directory — real `create-vite`/`create-vue`/`ng new`/
+`create-next-app`/`flutter create` scaffolding, with framework-specific
+questions and a working dev-server/device launch at the end. Package manager
+(npm/yarn/pnpm/bun) is auto-detected everywhere, never assumed. Answering
+"existing" (the default) skips all of this and just scaffolds
+`.xgem-automate/` into the current directory. Full detail, including exactly
+what runs for each framework: **[docs/frameworks.md](https://github.com/Code4Hacker/x-gem-cli/blob/xgem/docs/frameworks.md)**.
 
 ## Architecture
 
@@ -118,47 +114,25 @@ 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),
+whose declared minimum iOS platform can desync from your app's own
+`IPHONEOS_DEPLOYMENT_TARGET` — independently, even when your app's own target is
+already high enough. This is 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.
+[#162072](https://github.com/flutter/flutter/issues/162072)). `xgem run flutter build`
+(iOS target) detects the actual requirement from your resolved SPM plugins, patches
+every deployment-target occurrence, forces a clean regeneration, verifies it, and
+falls back to a documented direct patch if the upstream bug is still biting — full
+detail: **[docs/ios-build-engine.md](https://github.com/Code4Hacker/x-gem-cli/blob/xgem/docs/ios-build-engine.md)**. 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.
+Homebrew and the curl installer are macOS/Linux only, same as any bash tool. npm is
+different: it ships a small native Windows engine (`lib-win/`) so `npm install -g
+xgem-cli` actually works in `cmd.exe`/PowerShell, no WSL required — everything except
+Flutter iOS/macOS builds (Xcode has no Windows equivalent) and the project-creation
+wizards (not ported yet). Full detail: **[docs/windows.md](https://github.com/Code4Hacker/x-gem-cli/blob/xgem/docs/windows.md)**.
 
 ## Roadmap
 

package/bin/xgem

@@ -35,6 +35,16 @@ source "$XGEM_HOME/lib/flutter.sh"
 source "$XGEM_HOME/lib/scaffold.sh"
 # shellcheck source=lib/create.sh
 source "$XGEM_HOME/lib/create.sh"
+# shellcheck source=lib/release.sh
+source "$XGEM_HOME/lib/release.sh"
+# shellcheck source=lib/registry.sh
+source "$XGEM_HOME/lib/registry.sh"
+# shellcheck source=lib/status.sh
+source "$XGEM_HOME/lib/status.sh"
+# shellcheck source=lib/bootstrap.sh
+source "$XGEM_HOME/lib/bootstrap.sh"
+# shellcheck source=lib/ci.sh
+source "$XGEM_HOME/lib/ci.sh"
 
 CONFIG_DIR=".xgem-automate"
 
@@ -75,6 +85,14 @@ print_usage() {
     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 git pr                   - Push current branch and open a GitHub PR (gh-backed)"
+    echo "  xgem git sync                 - Rebase current branch onto the repo's base branch"
+    echo "  xgem git clean-branches       - Delete local branches already merged into the base branch"
+    echo "  xgem git hooks <install|uninstall> - Manage a pre-commit lint/test hook"
+    echo "  xgem release [major|minor|patch] - Bump version, update CHANGELOG.md, tag, push"
+    echo "  xgem status                   - Dashboard across every xgem-tracked project"
+    echo "  xgem bootstrap                - Clone-to-running: detect framework, install, .env, migrate, launch"
+    echo "  xgem ci                       - Run lint/test/build for every configured framework, summarized"
     echo "  xgem --version                - Print xgem's version"
     echo ""
     echo "Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply), --verbose"
@@ -91,26 +109,18 @@ case "${1:-}" in
         PS3="Enter target selection number: "
         select fw in "${ALL_FRAMEWORKS[@]}"; do
             if [ -n "$fw" ]; then
+                # create_project_wizard handles ALL of xgem's own
+                # bookkeeping (.xgem-automate + .gitignore) internally now,
+                # at the earliest safe point for each framework — never
+                # after a slow/interruptible step, so a Ctrl-C during (say)
+                # `ng new`'s install can no longer lose it. See lib/create.sh.
                 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
             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
-
         _ask_launch_dev_server
 
         # A child process (this script) can never change the parent
@@ -169,7 +179,7 @@ case "${1:-}" in
         else
             scaffold_run_script "$FRAMEWORK" "$SCRIPT_NAME" "$CONFIG_DIR"
         fi
-        exit 0
+        exit $?
         ;;
 
     terminate)
@@ -186,6 +196,7 @@ case "${1:-}" in
             rm -rf "${CONFIG_DIR:?}/$fw"
         done
         rm -rf "$CONFIG_DIR"
+        registry_remove "$(pwd)"
 
         if [ -f .gitignore ]; then
             grep -v "^$CONFIG_DIR/" .gitignore > tmp_gitignore && mv tmp_gitignore .gitignore
@@ -197,7 +208,7 @@ case "${1:-}" in
         ;;
 
     git)
-        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|branch|rm-remote|rm-branch>"
+        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|branch|rm-remote|rm-branch|pr|sync|clean-branches|hooks>"
         cmd_git "$2" "${3:-}"
         exit 0
         ;;
@@ -207,6 +218,26 @@ case "${1:-}" in
         exit 0
         ;;
 
+    release)
+        cmd_release "${2:-}"
+        exit 0
+        ;;
+
+    status)
+        cmd_status
+        exit 0
+        ;;
+
+    bootstrap)
+        cmd_bootstrap
+        exit 0
+        ;;
+
+    ci)
+        cmd_ci
+        exit $?
+        ;;
+
     --version|-V|version)
         print_version
         exit 0

package/bin/xgem.js

@@ -21,6 +21,11 @@ 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 { cmdRelease } = require('../lib-win/release');
+const { registryAdd, registryRemove } = require('../lib-win/registry');
+const { cmdStatus } = require('../lib-win/status');
+const { cmdBootstrap } = require('../lib-win/bootstrap');
+const { cmdCi } = require('../lib-win/ci');
 
 const CONFIG_DIR = '.xgem-automate';
 
@@ -48,6 +53,14 @@ function printUsage() {
     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 git pr                   - Push current branch and open a GitHub PR (gh-backed)');
+    console.log('  xgem git sync                 - Rebase current branch onto the repo\'s base branch');
+    console.log('  xgem git clean-branches       - Delete local branches already merged into the base branch');
+    console.log('  xgem git hooks <install|uninstall> - Manage a pre-commit lint/test hook');
+    console.log('  xgem release [major|minor|patch] - Bump version, update CHANGELOG.md, tag, push');
+    console.log('  xgem status                   - Dashboard across every xgem-tracked project');
+    console.log('  xgem bootstrap                - Clone-to-running: detect framework, install, .env, migrate, launch');
+    console.log('  xgem ci                       - Run lint/test/build for every configured framework, summarized');
     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');
@@ -61,20 +74,6 @@ async function selectFramework(options) {
     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)) {
@@ -82,14 +81,12 @@ async function cmdInit() {
         return;
     }
     fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    registryAdd(process.cwd());
 
     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();
+    await scaffold.bookkeeping(fw, CONFIG_DIR);
 }
 
 async function cmdAdd() {
@@ -139,6 +136,7 @@ async function cmdTerminate() {
         fs.rmSync(path.join(CONFIG_DIR, fw), { recursive: true, force: true });
     }
     fs.rmSync(CONFIG_DIR, { recursive: true, force: true });
+    registryRemove(process.cwd());
 
     if (fs.existsSync('.gitignore')) {
         const lines = fs.readFileSync('.gitignore', 'utf8').split(/\r?\n/).filter((l) => l !== `${CONFIG_DIR}/`);
@@ -188,9 +186,13 @@ async function main() {
         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);
+            if (!a2) die('Usage: xgem git <cmt|init|branch|rm-remote|rm-branch|pr|sync|clean-branches|hooks>');
+            return cmdGit(a2, a3, CONFIG_DIR);
         case 'doctor': return cmdDoctor(a2);
+        case 'release': return cmdRelease(a2);
+        case 'status': return cmdStatus(CONFIG_DIR);
+        case 'bootstrap': return cmdBootstrap(CONFIG_DIR);
+        case 'ci': return cmdCi(CONFIG_DIR);
         case '--version':
         case '-V':
         case 'version': {

package/lib/bootstrap.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# xgem bootstrap: clone-to-running in one command, for a project you just
+# checked out (not creating a new one — that's `xgem init`'s job).
+# Depends on lib/logger.sh, lib/utils.sh, lib/scaffold.sh, lib/create.sh.
+
+# _detect_framework -> a name from ALL_FRAMEWORKS, or empty if nothing
+# recognizable was found. Never assumes; probes for marker files the same
+# way lib/doctor.sh probes for tools instead of guessing.
+_detect_framework() {
+    [ -f pubspec.yaml ] && { echo flutter; return 0; }
+    [ -f go.mod ] && { echo go; return 0; }
+    [ -f Cargo.toml ] && { echo rust; return 0; }
+    { [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; } && { echo python; return 0; }
+    [ -f Package.swift ] && { echo swift; return 0; }
+    if [ -f package.json ]; then
+        if grep -q '"next"' package.json; then echo next
+        elif grep -q '"@angular/core"' package.json; then echo angular
+        elif grep -q '"vue"' package.json; then echo vue
+        elif grep -q '"react"' package.json; then echo react
+        else echo node
+        fi
+        return 0
+    fi
+    [ -f Dockerfile ] && { echo docker; return 0; }
+    return 1
+}
+
+_bootstrap_env_file() {
+    [ -f .env ] && { log_debug ".env already exists, leaving it as-is."; return 0; }
+    local example
+    for example in .env.example .env.sample; do
+        [ -f "$example" ] || continue
+        cp "$example" .env
+        log_success "Created .env from $example."
+        local missing
+        missing=$(grep -E '^[A-Za-z_][A-Za-z0-9_]*=[[:space:]]*$' .env | cut -d= -f1)
+        if [ -n "$missing" ]; then
+            log_warn "These .env keys are empty — fill them in:"
+            echo "$missing" | sed 's/^/  - /'
+        fi
+        return 0
+    done
+}
+
+_bootstrap_node_pm() {
+    if [ -f pnpm-lock.yaml ]; then echo pnpm
+    elif [ -f yarn.lock ]; then echo yarn
+    elif [ -f bun.lockb ] || [ -f bun.lock ]; then echo bun
+    else echo npm
+    fi
+}
+
+_bootstrap_install() {
+    local fw=$1
+    case "$fw" in
+        node|react|vue|angular|next)
+            local pm
+            pm=$(_bootstrap_node_pm)
+            log_info "Installing dependencies with $pm..."
+            case "$pm" in
+                yarn) yarn ;;
+                pnpm) pnpm install ;;
+                bun)  bun install ;;
+                *)    npm install ;;
+            esac
+            ;;
+        flutter)
+            has_cmd flutter || { log_warn "flutter not found — skipping 'flutter pub get'."; return 0; }
+            log_info "Running flutter pub get..."
+            flutter pub get
+            ;;
+        python)
+            if [ -f pyproject.toml ] && has_cmd poetry; then
+                log_info "Installing dependencies with poetry..."
+                poetry install
+            elif [ -f requirements.txt ]; then
+                has_cmd python3 || { log_warn "python3 not found — skipping install."; return 0; }
+                [ -d .venv ] || python3 -m venv .venv
+                log_info "Installing dependencies into .venv..."
+                .venv/bin/pip install -r requirements.txt
+            fi
+            ;;
+        go)
+            has_cmd go || { log_warn "go not found — skipping 'go mod download'."; return 0; }
+            log_info "Running go mod download..."
+            go mod download
+            ;;
+        rust)
+            has_cmd cargo || { log_warn "cargo not found — skipping 'cargo fetch'."; return 0; }
+            log_info "Running cargo fetch..."
+            cargo fetch
+            ;;
+        swift)
+            has_cmd swift || { log_warn "swift not found — skipping 'swift package resolve'."; return 0; }
+            log_info "Running swift package resolve..."
+            swift package resolve
+            ;;
+        docker)
+            log_debug "Docker project — nothing to install locally."
+            ;;
+    esac
+}
+
+_bootstrap_migrations() {
+    local fw=$1
+    if [ "$fw" = "node" ] || [ "$fw" = "react" ] || [ "$fw" = "vue" ] || [ "$fw" = "angular" ] || [ "$fw" = "next" ]; then
+        if _package_json_has_script migrate; then
+            local pm
+            pm=$(_bootstrap_node_pm)
+            confirm "Run the project's 'migrate' script (via $pm)?" || return 0
+            case "$pm" in
+                yarn) yarn migrate ;;
+                pnpm) pnpm run migrate ;;
+                bun)  bun run migrate ;;
+                *)    npm run migrate ;;
+            esac
+            return 0
+        fi
+    fi
+    if [ -f prisma/schema.prisma ]; then
+        confirm "Run 'npx prisma migrate dev'?" && npx prisma migrate dev
+    elif [ -f manage.py ]; then
+        has_cmd python3 && confirm "Run 'python3 manage.py migrate'?" && python3 manage.py migrate
+    fi
+}
+
+_bootstrap_offer_dev_server() {
+    local fw=$1
+    local script=""
+    case "$fw" in
+        node) script=start ;;
+        react|vue|angular|next) script=dev ;;
+        *) return 0 ;;
+    esac
+    [ -f "$CONFIG_DIR/$fw/$script.sh" ] || return 0
+    confirm "Launch the dev server now ('xgem run $fw $script')?" && scaffold_run_script "$fw" "$script" "$CONFIG_DIR"
+}
+
+cmd_bootstrap() {
+    log_info "Detecting project framework..."
+    local fw
+    fw=$(_detect_framework)
+    if [ -z "$fw" ]; then
+        log_warn "Could not auto-detect the framework from any known marker file."
+        echo "Pick one:"
+        PS3="Enter target selection number: "
+        select fw in "${ALL_FRAMEWORKS[@]}"; do
+            [ -n "$fw" ] && break
+            echo "Invalid selection."
+        done
+    else
+        log_success "Detected: $fw"
+    fi
+
+    _bootstrap_env_file
+    _bootstrap_install "$fw"
+    _bootstrap_migrations "$fw"
+
+    if [ ! -d "$CONFIG_DIR" ]; then
+        confirm "Scaffold xgem automation scripts (.xgem-automate) for $fw too?" && _xgem_bookkeeping "$fw"
+    fi
+
+    _bootstrap_offer_dev_server "$fw"
+    log_success "Bootstrap complete."
+}

package/lib/ci.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# xgem ci: run lint -> test -> build for every configured framework before
+# you push, so a CI failure gets caught locally first.
+# Depends on lib/logger.sh.
+
+cmd_ci() {
+    [ -d "$CONFIG_DIR" ] || die "No $CONFIG_DIR found — run 'xgem init' or 'xgem add' first."
+
+    local -a steps=(lint test build)
+    local -a results=()
+    local overall_status=0
+    local fw_dir fw step
+
+    for fw_dir in "$CONFIG_DIR"/*/; do
+        [ -d "$fw_dir" ] || continue
+        fw=$(basename "$fw_dir")
+        for step in "${steps[@]}"; do
+            [ -f "$CONFIG_DIR/$fw/$step.sh" ] || continue
+            log_info "Running $fw $step..."
+            if bash "$CONFIG_DIR/$fw/$step.sh"; then
+                results+=("PASS  $fw $step")
+            else
+                results+=("FAIL  $fw $step")
+                overall_status=1
+            fi
+        done
+    done
+
+    if [ ${#results[@]} -eq 0 ]; then
+        log_warn "No lint/test/build scripts found under $CONFIG_DIR to run."
+        return 0
+    fi
+
+    echo ""
+    echo "=== xgem ci summary ==="
+    printf '%s\n' "${results[@]}"
+
+    if [ "$overall_status" -eq 0 ]; then
+        log_success "All checks passed."
+    else
+        log_error "Some checks failed."
+    fi
+    return "$overall_status"
+}