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

package/README.md

@@ -1,15 +1,25 @@
 # xgem
 
-A framework-aware automation CLI. `xgem init` scaffolds clean/build/dev scripts
-tailored to your project type (Flutter, Node, Python, React/Vue/Angular, Go,
-Rust, Docker, Swift), `xgem run <framework> <script>` runs them, `xgem doctor`
-reports on your environment, and `xgem git` wraps a common stage → commit →
-rebase-pull → push workflow.
+A framework-aware automation CLI. `xgem init` can create a brand-new project
+(real `npm create vite`/`create-next-app`/`create-vue`/`ng new`/`flutter create`
+scaffolding, framework-specific questions, dependency install, and launching
+the dev server in your browser or the app on a picked device/simulator) or
+just scaffold clean/build/dev scripts into a project you already have
+(Flutter, Node, Python, React/Vue/Angular/Next, Go, Rust, Docker, Swift).
+`xgem run <framework> <script>` runs those scripts, `xgem doctor` reports on
+your environment, and `xgem git` wraps a common stage → commit → rebase-pull
+→ push workflow.
 
 Flutter's iOS builds go through a dedicated engine that detects whether your
 project uses CocoaPods or Swift Package Manager (SPM), figures out the actual
 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
 
@@ -27,7 +37,8 @@ xgem isn't in Homebrew's central `homebrew-core` (that requires a formal submiss
 npm install -g xgem-cli
 ```
 
-*(not yet published to the npm registry)*
+Works natively on Windows too (no WSL needed) — npm's install runs a small Node.js
+engine there instead of the bash one; see [Windows support](#windows-support).
 
 ### curl
 
@@ -48,6 +59,7 @@ xgem doctor ios [path]        Report on iOS build readiness: CocoaPods vs SPM, d
                                targets per config, and whether they're reconciled
 xgem git cmt "message"        Auto-stage, commit, rebase-pull, and push
 xgem git init                 Setup local repo, attach remote tracker shortcuts
+xgem git branch               Pick, create, or switch branches; remembers your choice
 xgem git rm-remote            Drop a configured remote
 xgem git rm-branch            Safely drop local and/or remote branch
 xgem --version                Print xgem's version
@@ -57,7 +69,18 @@ Flags (any command): --yes (skip confirmations), --dry-run (show, don't apply),
 
 ## Supported frameworks
 
-flutter, node, python, react, vue, angular, go, rust, docker, swift
+flutter, node, python, react, vue, angular, next, go, rust, docker, swift
+
+## Creating a new project
+
+`xgem init` asks, per framework, whether to create a brand-new project or use
+what's already in the directory — 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
 
@@ -69,8 +92,9 @@ lib/
   doctor.sh    environment + feature detection ("xgem doctor")
   ios.sh       the SwiftPM-aware iOS build engine
   flutter.sh   flutter command group (build/hard-clean/build-runner), delegates iOS builds to ios.sh
-  git.sh       git cmt/init/rm-remote/rm-branch
+  git.sh       git cmt/init/branch/rm-remote/rm-branch
   scaffold.sh  generic clean/build/dev handling for the other, simpler frameworks
+  create.sh    project creation wizards (react/vue/angular/next/simple frameworks)
 templates/     the actual clean/build/dev script content xgem scaffolds into your project's .xgem-automate/
 ```
 
@@ -82,29 +106,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. 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
 
@@ -114,6 +134,8 @@ Deferred to a follow-up pass, not yet in this release:
 - Shell completions, `--json` output, per-project config caching (stop re-prompting
   build name/number/platform every run)
 - Deeper Android SDK/Java detection
+- Project creation wizards on the Windows engine (`lib-win/`) — react/vue/angular/next
+  scaffolding is pure Node.js tooling and would work fine there too, just not built yet
 
 ## License
 

package/bin/xgem

@@ -33,6 +33,8 @@ source "$XGEM_HOME/lib/ios.sh"
 source "$XGEM_HOME/lib/flutter.sh"
 # shellcheck source=lib/scaffold.sh
 source "$XGEM_HOME/lib/scaffold.sh"
+# shellcheck source=lib/create.sh
+source "$XGEM_HOME/lib/create.sh"
 
 CONFIG_DIR=".xgem-automate"
 
@@ -70,6 +72,7 @@ print_usage() {
     echo "  xgem doctor [ios]             - Report on your environment / iOS SwiftPM build readiness"
     echo "  xgem git cmt \"message\"        - Auto-stage, commit, rebase-pull, and push"
     echo "  xgem git init                 - Setup local repo, attach remote tracker shortcuts"
+    echo "  xgem git branch               - Pick, create, or switch branches; remembers your choice"
     echo "  xgem git rm-remote            - Drop specified target remote tracing rules"
     echo "  xgem git rm-branch            - Safely drop local and remote workspace branch states"
     echo "  xgem --version                - Print xgem's version"
@@ -84,28 +87,32 @@ case "${1:-}" in
             log_warn "Workspace configuration layer already exists! Use 'xgem add' to append frameworks."
             exit 0
         fi
-        mkdir -p "$CONFIG_DIR"
-
         echo -e "\033[1;34mSelect your starting framework architecture:\033[0m"
         PS3="Enter target selection number: "
         select fw in "${ALL_FRAMEWORKS[@]}"; do
             if [ -n "$fw" ]; then
-                scaffold_inject_templates "$fw" "$CONFIG_DIR"
-                log_success "Successfully appended standard scripts for: $CONFIG_DIR/$fw"
+                # 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"
                 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."
+        _ask_launch_dev_server
+
+        # A child process (this script) can never change the parent
+        # shell's cwd — xgem's own process correctly cd'd into the new
+        # project folder for everything above, but your actual terminal
+        # is still wherever it started. Say so explicitly instead of
+        # leaving you to discover it the confusing way.
+        if [ -n "$XGEM_CREATED_NEW_FOLDER" ]; then
+            echo ""
+            log_info "Your project is in ./$XGEM_CREATED_NEW_FOLDER — your terminal is still in the original directory. Run: cd $XGEM_CREATED_NEW_FOLDER"
         fi
         exit 0
         ;;
@@ -182,7 +189,7 @@ case "${1:-}" in
         ;;
 
     git)
-        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|rm-remote|rm-branch>"
+        [ -n "${2:-}" ] || die "Usage: xgem git <cmt|init|branch|rm-remote|rm-branch>"
         cmd_git "$2" "${3:-}"
         exit 0
         ;;
@@ -197,7 +204,7 @@ case "${1:-}" in
         exit 0
         ;;
 
-    flutter|node|python|react|vue|angular|go|rust|docker|swift)
+    flutter|node|python|react|vue|angular|next|go|rust|docker|swift)
         TARGET_FW=$1
         TARGET_FW_UPPER=$(echo "$TARGET_FW" | tr '[:lower:]' '[:upper:]')
 

package/bin/xgem.js

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