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

package/README.md

@@ -27,7 +27,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
 
@@ -106,6 +107,24 @@ force Flutter to regenerate the generated package.
 
 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 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.
+
 ## Roadmap
 
 Deferred to a follow-up pass, not yet in this release:

package/bin/xgem.js

@@ -0,0 +1,218 @@
+#!/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 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];
+}
+
+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)) {
+        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}`);
+
+    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 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|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 'go':
+        case 'rust':
+        case 'docker':
+            return printFrameworkHelp(cmd);
+        default:
+            return printUsage();
+    }
+}
+
+main().catch((err) => {
+    logError(err.message || String(err));
+    process.exit(1);
+});

package/lib-win/doctor.js

@@ -0,0 +1,44 @@
+// xgem Windows engine doctor — mirrors lib/doctor.sh's general report.
+// No iOS/SwiftPM engine exists here (see flutter.js) since Xcode has no
+// Windows equivalent; `doctor ios` explains that instead of pretending.
+
+const { getVersion, detectArch } = require('./utils');
+const { paint } = require('./logger');
+
+function printGeneral() {
+    console.log(paint('cyan', '=== xgem doctor (Windows) ==='));
+    console.log(`OS:              win32`);
+    console.log(`Arch:            ${detectArch()}`);
+    console.log(`git:             ${getVersion('git') || 'not found'}`);
+    console.log(`flutter:         ${getVersion('flutter') || 'not found'}`);
+    console.log(`dart:            ${getVersion('dart') || 'not found'}`);
+    console.log(`node:            ${getVersion('node') || 'not found'}`);
+    console.log(`python:          ${getVersion('python') || getVersion('python3') || 'not found'}`);
+    console.log(`go:              ${getVersion('go', ['version']) || 'not found'}`);
+    console.log(`cargo:           ${getVersion('cargo') || 'not found'}`);
+    console.log(`docker:          ${getVersion('docker') || 'not found'}`);
+}
+
+function printIos() {
+    console.log(paint('cyan', '=== xgem doctor ios (Windows) ==='));
+    console.log(paint('yellow', 'iOS/macOS builds are not available on Windows — Xcode has no Windows equivalent.'));
+    console.log('Use WSL2 with a Mac, or a real Mac, for Flutter iOS builds.');
+    const flutterVersion = getVersion('flutter');
+    if (flutterVersion) {
+        console.log(`\nflutter is installed here (${flutterVersion}) and can still build Android/Windows targets:`);
+        console.log('  xgem run flutter build   (choose APK or Windows)');
+    }
+}
+
+function cmdDoctor(target) {
+    if (target === 'ios') {
+        printIos();
+    } else if (!target) {
+        printGeneral();
+    } else {
+        const { die } = require('./logger');
+        die(`Unknown doctor target '${target}'. Usage: xgem doctor [ios]`);
+    }
+}
+
+module.exports = { cmdDoctor, printGeneral, printIos };

package/lib-win/flutter.js

@@ -0,0 +1,97 @@
+// xgem Windows engine flutter commands. hard-clean/build-runner have no
+// platform-specific dependency and work as-is. build only offers targets
+// that are actually buildable from a Windows host (APK, Windows desktop) —
+// iOS/macOS need Xcode (a Mac), and Flutter can't cross-compile Linux
+// desktop from Windows either, so those fail fast with a clear message
+// instead of attempting anything.
+
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { logInfo, logSuccess, logError, die } = require('./logger');
+const { prompt, requireCmd } = require('./utils');
+
+function flutter(args) {
+    return spawnSync('flutter', args, { stdio: 'inherit' });
+}
+
+async function cmdHardClean() {
+    requireCmd('flutter', 'Install Flutter: https://docs.flutter.dev/get-started/install/windows');
+    logInfo('Cleaning Flutter project...');
+    fs.rmSync('pubspec.lock', { force: true });
+    flutter(['clean']);
+    logInfo('Getting Flutter packages...');
+    flutter(['pub', 'get']);
+    logInfo('Running Flutter...');
+    flutter(['run', '-v']);
+}
+
+async function cmdBuildRunner() {
+    requireCmd('flutter', 'Install Flutter: https://docs.flutter.dev/get-started/install/windows');
+    logInfo('Running Flutter Build Runner...');
+    const verboseChoice = ((await prompt('Run in verbose mode? (Y/n)')) || 'Y').toLowerCase();
+    const args = ['pub', 'run', 'build_runner', 'build', '--delete-conflicting-outputs'];
+    if (verboseChoice === 'y') args.push('-v');
+    logInfo(`Executing: flutter ${args.join(' ')}`);
+    flutter(args);
+}
+
+function pubspecVersion() {
+    if (!fs.existsSync('pubspec.yaml')) return null;
+    const content = fs.readFileSync('pubspec.yaml', 'utf8');
+    const match = content.match(/^version:\s*(\S+)/m);
+    return match ? match[1] : null;
+}
+
+async function cmdBuild() {
+    requireCmd('flutter', 'Install Flutter: https://docs.flutter.dev/get-started/install/windows');
+    console.log('--- Flutter Build Orchestrator (Windows) ---');
+
+    let currentName = '';
+    let currentNum = '';
+    const currentFull = pubspecVersion();
+    if (currentFull) {
+        [currentName, currentNum = '1'] = currentFull.split('+');
+        logInfo(`Current pubspec.yaml version: ${currentFull}`);
+    }
+
+    const buildName = (await prompt('Enter build version name', currentName || '1.0.0'));
+    const buildNumber = (await prompt('Enter build number', currentNum || '1'));
+    const isRelease = ((await prompt('Is this a release build? (Y/n)', 'y'))).toLowerCase();
+
+    if (fs.existsSync('pubspec.yaml')) {
+        const newVersion = `${buildName}+${buildNumber}`;
+        logSuccess(`Updating pubspec.yaml to version: ${newVersion}`);
+        const content = fs.readFileSync('pubspec.yaml', 'utf8');
+        fs.writeFileSync('pubspec.yaml', content.replace(/^version:.*/m, `version: ${newVersion}`));
+    }
+
+    console.log('\nSelect Target Platform:');
+    console.log('1) APK (Android)');
+    console.log('2) Windows');
+    console.log('(iOS/macOS require a Mac; Linux desktop can\'t be cross-built from Windows.)');
+    const platformChoice = await prompt('Choose [1-2]');
+
+    const mode = (isRelease === 'n') ? '--debug' : '--release';
+    const buildArgs = [`--build-name=${buildName}`, `--build-number=${buildNumber}`];
+
+    if (platformChoice === '1') {
+        logInfo(`Building APK (${mode})...`);
+        flutter(['build', 'apk', mode, ...buildArgs]);
+    } else if (platformChoice === '2') {
+        logInfo(`Building Windows desktop app (${mode})...`);
+        flutter(['build', 'windows', mode, ...buildArgs]);
+    } else {
+        die(`'${platformChoice}' isn't buildable from Windows. iOS/macOS need a Mac (xgem doctor ios explains more); Linux desktop needs a Linux host.`);
+    }
+}
+
+async function cmdFlutter(script) {
+    switch (script) {
+        case 'hard-clean': return cmdHardClean();
+        case 'build': return cmdBuild();
+        case 'build-runner': return cmdBuildRunner();
+        default: die(`No native flutter command for '${script}'.`);
+    }
+}
+
+module.exports = { cmdFlutter };

package/lib-win/git.js

@@ -0,0 +1,161 @@
+// xgem Windows engine git workflow — port of lib/git.sh (cmt/init/rm-remote/rm-branch).
+// git.exe behaves the same on Windows, so this is a straight port; the
+// commit-exit-code check and origin-preference fix already in lib/git.sh
+// carry over here too.
+
+const { spawnSync } = require('node:child_process');
+const { logInfo, logSuccess, logWarn, logError, die } = require('./logger');
+const { prompt } = require('./utils');
+
+function git(args, opts = {}) {
+    return spawnSync('git', args, { stdio: 'inherit', ...opts });
+}
+
+function gitCapture(args) {
+    const result = spawnSync('git', args, { encoding: 'utf8' });
+    return (result.stdout || '').trim();
+}
+
+function remoteExists(name) {
+    return gitCapture(['remote']).split(/\r?\n/).includes(name);
+}
+
+async function cmdCmt(commitMsg) {
+    if (!commitMsg) die('Missing commit message!');
+
+    logInfo('Checking repository status...');
+    git(['status', '-s']);
+    console.log('');
+
+    const addChoice = (await prompt('Do you want to add ALL files (a) or INDIVIDUAL files (i)? [a/i]')).toLowerCase();
+    if (addChoice === 'a') {
+        git(['add', '.']);
+        logSuccess('All files staged.');
+    } else if (addChoice === 'i') {
+        const files = await prompt('Enter specific file paths to add (space separated)');
+        const fileList = files.split(/\s+/).filter(Boolean);
+        if (fileList.length === 0) die('No files given.');
+        git(['add', ...fileList]);
+        logSuccess('Selected files staged.');
+    } else {
+        die('Invalid choice. Operation aborted.');
+    }
+
+    logInfo('Committing changes...');
+    const commitResult = git(['commit', '-m', commitMsg]);
+    if (commitResult.status !== 0) {
+        die('Commit failed. Aborting before pull/push.');
+    }
+
+    const currentBranch = gitCapture(['branch', '--show-current']);
+    const remoteName = remoteExists('origin') ? 'origin' : gitCapture(['remote']).split(/\r?\n/)[0];
+
+    if (!remoteName) {
+        logWarn('Local commit dropped cleanly, but no remote is configured — sync was skipped.');
+        return;
+    }
+
+    logInfo(`Pulling updates from remote '${remoteName}' on '${currentBranch}' via rebase...`);
+    const pullResult = git(['pull', '--rebase', remoteName, currentBranch]);
+    if (pullResult.status !== 0) {
+        logError('MERGE CONFLICT DETECTED!');
+        logWarn('Execution paused. Resolve conflicts to proceed.');
+        process.exit(1);
+    }
+
+    logSuccess('Clean sync pull achieved. Pushing to upstream target...');
+    const pushResult = git(['push', remoteName, currentBranch]);
+    if (pushResult.status === 0) {
+        logSuccess('Git workflow complete! Code cleanly committed and synchronized.');
+    } else {
+        die('Push operation failed.');
+    }
+}
+
+async function cmdInit() {
+    logInfo('Initializing local Git repository...');
+    git(['init']);
+
+    let remoteName = 'origin';
+    const remoteUrl = await prompt('Enter remote repository URL');
+    if (remoteUrl) {
+        const userRemoteName = await prompt('Enter remote name (default: origin)');
+        if (userRemoteName) remoteName = userRemoteName;
+
+        if (remoteExists(remoteName)) {
+            git(['remote', 'set-url', remoteName, remoteUrl]);
+            logSuccess(`Remote '${remoteName}' already existed. URL updated.`);
+        } else {
+            git(['remote', 'add', remoteName, remoteUrl]);
+            logSuccess(`Remote '${remoteName}' successfully added.`);
+        }
+    }
+
+    const branchName = (await prompt('Enter branch name (default: main)')) || 'main';
+    git(['branch', '-M', branchName]);
+
+    git(['add', '.']);
+    git(['commit', '-m', 'initial changes']);
+    logSuccess('Local baseline configuration setup completed.');
+}
+
+async function cmdRmRemote() {
+    logInfo('Current configured remotes:');
+    git(['remote', '-v']);
+    console.log('');
+
+    const remoteName = (await prompt('Enter the short remote name to remove (e.g. origin)')) || 'origin';
+    if (remoteExists(remoteName)) {
+        git(['remote', 'remove', remoteName]);
+        logSuccess(`Successfully removed remote reference configuration: ${remoteName}`);
+    } else {
+        die(`Remote tracking short-name '${remoteName}' does not exist.`);
+    }
+}
+
+async function cmdRmBranch() {
+    const targetBranch = await prompt('Enter the name of the branch you want to target');
+    if (!targetBranch) die('Branch name cannot be empty.');
+
+    const whereChoice = (await prompt('Where do you want to delete this branch? (l = local only, r = remote only, b = both) [l/r/b]')).toLowerCase();
+    console.log('');
+
+    if (whereChoice === 'l' || whereChoice === 'b') {
+        const currentBranch = gitCapture(['branch', '--show-current']);
+        if (currentBranch === targetBranch) {
+            logWarn(`You are currently sitting on '${targetBranch}'. Switching to safe branch...`);
+            for (const fallback of ['main', 'master', 'dev']) {
+                if (git(['checkout', fallback], { stdio: 'ignore' }).status === 0) break;
+            }
+        }
+
+        logInfo(`Force deleting local branch '${targetBranch}'...`);
+        if (git(['branch', '-D', targetBranch]).status === 0) {
+            logSuccess('Successfully deleted local copy of branch.');
+        } else {
+            logWarn('Local branch could not be dropped (it may already be gone).');
+        }
+    }
+
+    if (whereChoice === 'r' || whereChoice === 'b') {
+        const remoteTarget = (await prompt("Enter remote identifier (short-name like 'origin')")) || 'origin';
+        logInfo(`Sending deletion request for remote branch '${targetBranch}' to server...`);
+        if (git(['push', remoteTarget, '--delete', targetBranch]).status === 0) {
+            logSuccess(`Successfully wiped out remote branch '${targetBranch}' from server.`);
+        } else {
+            die('Server rejected the branch drop execution request.');
+        }
+    }
+}
+
+async function cmdGit(sub, arg) {
+    switch (sub) {
+        case 'cmt': return cmdCmt(arg);
+        case 'init': return cmdInit();
+        case 'rm-remote': return cmdRmRemote();
+        case 'rm-branch': return cmdRmBranch();
+        default: die(`Unknown git subcommand '${sub}'. Usage: xgem git <cmt|init|rm-remote|rm-branch>`);
+    }
+}
+
+module.exports = { cmdGit };

package/lib-win/logger.js

@@ -0,0 +1,35 @@
+// xgem Windows engine logger — mirrors lib/logger.sh's levels/colors.
+// Manual ANSI codes (no dependency): Windows 10+ cmd.exe and PowerShell
+// both support ANSI escapes natively, and we skip color entirely when
+// stdout isn't a TTY (e.g. piped output).
+
+const isTTY = process.stdout.isTTY === true;
+
+const colors = {
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[1;34m',
+    cyan: '\x1b[1;36m',
+    gray: '\x1b[90m',
+    reset: '\x1b[0m',
+};
+
+function paint(color, text) {
+    return isTTY ? `${colors[color]}${text}${colors.reset}` : text;
+}
+
+const VERBOSE = process.env.XGEM_VERBOSE === '1';
+
+function logInfo(msg) { console.log(`${paint('blue', '[INFO]')} ${msg}`); }
+function logSuccess(msg) { console.log(`${paint('green', '[ OK ]')} ${msg}`); }
+function logWarn(msg) { console.error(`${paint('yellow', '[WARN]')} ${msg}`); }
+function logError(msg) { console.error(`${paint('red', '[FAIL]')} ${msg}`); }
+function logDebug(msg) { if (VERBOSE) console.error(`${paint('gray', `[DBG ] ${msg}`)}`); }
+
+function die(msg, code = 1) {
+    logError(msg);
+    process.exit(code);
+}
+
+module.exports = { paint, logInfo, logSuccess, logWarn, logError, logDebug, die, isTTY };

package/lib-win/scaffold.js

@@ -0,0 +1,79 @@
+// xgem Windows engine generic scaffold — mirrors lib/scaffold.sh, but
+// writes/runs .mjs templates instead of .sh. `swift` is intentionally
+// omitted: there's no meaningful Windows Swift toolchain story.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { logInfo, logSuccess, logWarn, logError, die } = require('./logger');
+
+const ALL_FRAMEWORKS = ['flutter', 'node', 'python', 'react', 'vue', 'angular', 'go', 'rust', 'docker'];
+
+const FRAMEWORK_SCRIPTS = {
+    flutter: ['hard-clean', 'build', 'build-runner'],
+    node: ['hard-clean', 'build', 'start'],
+    python: ['hard-clean', 'install'],
+    react: ['hard-clean', 'build', 'dev'],
+    vue: ['hard-clean', 'build', 'dev'],
+    angular: ['hard-clean', 'build', 'dev'],
+    go: ['hard-clean', 'build'],
+    rust: ['hard-clean', 'build'],
+    docker: ['hard-clean', 'build-up'],
+};
+
+function frameworkScripts(fw) {
+    return FRAMEWORK_SCRIPTS[fw] || null;
+}
+
+function templateDir(fw) {
+    const templatesRoot = path.join(__dirname, '..', 'templates-win');
+    if (fw === 'react' || fw === 'vue' || fw === 'angular') {
+        return path.join(templatesRoot, 'webframework');
+    }
+    return path.join(templatesRoot, fw);
+}
+
+function injectTemplates(fw, configDir) {
+    const scripts = frameworkScripts(fw);
+    if (!scripts) die(`Unknown framework '${fw}'.`);
+
+    const srcDir = templateDir(fw);
+    const destDir = path.join(configDir, fw);
+    fs.mkdirSync(destDir, { recursive: true });
+
+    for (const script of scripts) {
+        const src = path.join(srcDir, `${script}.mjs.tmpl`);
+        const dest = path.join(destDir, `${script}.mjs`);
+        if (!fs.existsSync(src)) {
+            logWarn(`Missing template ${src}, skipping.`);
+            continue;
+        }
+        const content = fs.readFileSync(src, 'utf8').replace(/__FRAMEWORK__/g, fw);
+        fs.writeFileSync(dest, content);
+    }
+}
+
+function runScript(fw, script, configDir) {
+    const target = path.join(configDir, fw, `${script}.mjs`);
+    if (fs.existsSync(target)) {
+        logInfo(`Running script '${script}' for ${fw}...`);
+        const result = spawnSync(process.execPath, [target], { stdio: 'inherit' });
+        process.exitCode = result.status ?? 0;
+    } else {
+        logError(`Script not found at ${target}`);
+        const fwDir = path.join(configDir, fw);
+        if (fs.existsSync(fwDir)) {
+            console.log(`Available scripts in '${fw}':`);
+            for (const f of fs.readdirSync(fwDir)) {
+                console.log(`  - ${f.replace(/\.mjs$/, '')}`);
+            }
+        }
+        process.exitCode = 1;
+    }
+}
+
+function getRemainingFrameworks(configDir) {
+    return ALL_FRAMEWORKS.filter((fw) => !fs.existsSync(path.join(configDir, fw)));
+}
+
+module.exports = { ALL_FRAMEWORKS, frameworkScripts, injectTemplates, runScript, getRemainingFrameworks };

package/lib-win/utils.js

@@ -0,0 +1,67 @@
+// xgem Windows engine utilities — mirrors lib/utils.sh.
+
+const { spawnSync } = require('node:child_process');
+const readline = require('node:readline');
+const { logInfo, logDebug } = require('./logger');
+
+function detectArch() {
+    return process.arch === 'x64' ? 'x64' : process.arch;
+}
+
+// hasCmd(name) -> boolean, checked via `where` (a Windows builtin) so it
+// works regardless of whether the tool itself supports --version.
+function hasCmd(name) {
+    const result = spawnSync('where', [name], { stdio: 'ignore', shell: false });
+    return result.status === 0;
+}
+
+function requireCmd(name, hint) {
+    if (!hasCmd(name)) {
+        const { die } = require('./logger');
+        die(hint ? `'${name}' is required but not found. ${hint}` : `'${name}' is required but not found in PATH.`);
+    }
+}
+
+// getVersion(name, args) -> first line of stdout, or null if the command
+// isn't present / errors out.
+function getVersion(name, args = ['--version']) {
+    if (!hasCmd(name)) return null;
+    const result = spawnSync(name, args, { encoding: 'utf8' });
+    if (result.error || result.status !== 0) return null;
+    const out = (result.stdout || result.stderr || '').split(/\r?\n/)[0];
+    return out ? out.trim() : null;
+}
+
+// confirm(prompt) -> Promise<boolean>. Honors XGEM_YES (auto-approve) and
+// XGEM_DRY_RUN (always decline, just like lib/utils.sh's confirm()).
+function confirm(prompt) {
+    if (process.env.XGEM_DRY_RUN === '1') {
+        logInfo(`(dry-run) would prompt: ${prompt}`);
+        return Promise.resolve(false);
+    }
+    if (process.env.XGEM_YES === '1') {
+        logDebug(`auto-confirmed (--yes): ${prompt}`);
+        return Promise.resolve(true);
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${prompt} [y/N]: `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+
+// prompt(question, defaultValue) -> Promise<string>
+function prompt(question, defaultValue = '') {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultValue ? ` [${defaultValue}]` : '';
+    return new Promise((resolve) => {
+        rl.question(`${question}${suffix}: `, (answer) => {
+            rl.close();
+            resolve(answer.trim() || defaultValue);
+        });
+    });
+}
+
+module.exports = { detectArch, hasCmd, requireCmd, getVersion, confirm, prompt };

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "xgem-cli",
-  "version": "2.0.0-alpha.1",
-  "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.",
+  "version": "2.0.0-alpha.2",
+  "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. Runs natively on macOS, Linux, and Windows.",
   "bin": {
-    "xgem": "bin/xgem"
+    "xgem": "bin/xgem.js"
   },
   "files": [
     "bin/xgem",
+    "bin/xgem.js",
     "lib",
+    "lib-win",
     "templates",
-    "scripts/check-platform.js"
+    "templates-win"
   ],
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "scripts": {
-    "preinstall": "node scripts/check-platform.js",
-    "test": "bash -n bin/xgem && for f in lib/*.sh; do bash -n \"$f\"; done"
+    "test": "bash -n bin/xgem && for f in lib/*.sh; do bash -n \"$f\"; done && for f in bin/xgem.js lib-win/*.js; do node --check \"$f\"; done"
   },
   "keywords": [
     "cli",

package/templates-win/docker/build-up.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('docker-compose up --build -d', { stdio: 'inherit' });

package/templates-win/docker/hard-clean.mjs.tmpl

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+console.log('Pruning unused Docker assets and volumes...');
+execSync('docker system prune -a --volumes -f', { stdio: 'inherit' });

package/templates-win/flutter/build-runner.mjs.tmpl

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+const r = spawnSync('xgem', ['run', 'flutter', 'build-runner'], { stdio: 'inherit', shell: true });
+process.exit(r.status ?? 0);

package/templates-win/flutter/build.mjs.tmpl

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+const r = spawnSync('xgem', ['run', 'flutter', 'build'], { stdio: 'inherit', shell: true });
+process.exit(r.status ?? 0);

package/templates-win/flutter/hard-clean.mjs.tmpl

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Delegates to xgem's native Windows flutter engine — single source of
+// truth instead of a second copy of the logic.
+import { spawnSync } from 'node:child_process';
+const r = spawnSync('xgem', ['run', 'flutter', 'hard-clean'], { stdio: 'inherit', shell: true });
+process.exit(r.status ?? 0);

package/templates-win/go/build.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('go build -o bin\\main.exe main.go', { stdio: 'inherit' });

package/templates-win/go/hard-clean.mjs.tmpl

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+console.log('Cleaning Go module cache...');
+execSync('go clean -modcache', { stdio: 'inherit' });

package/templates-win/node/build.mjs.tmpl

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+console.log('Building Node project...');
+execSync('npm run build', { stdio: 'inherit' });

package/templates-win/node/hard-clean.mjs.tmpl

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+
+console.log('Nuking node_modules and resetting package locks...');
+rmSync('node_modules', { recursive: true, force: true });
+rmSync('package-lock.json', { force: true });
+rmSync('yarn.lock', { force: true });
+execSync('npm install', { stdio: 'inherit' });

package/templates-win/node/start.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('npm run start', { stdio: 'inherit' });

package/templates-win/python/hard-clean.mjs.tmpl

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+
+console.log('Cleaning Python cache and rebuilding environment...');
+rmSync('__pycache__', { recursive: true, force: true });
+rmSync('.venv', { recursive: true, force: true });
+execSync('python -m venv .venv', { stdio: 'inherit' });

package/templates-win/python/install.mjs.tmpl

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+// Windows venvs don't have an "activate && run" equivalent worth using in
+// a spawned process — call the venv's own pip.exe directly instead.
+if (existsSync('.venv\\Scripts\\pip.exe')) {
+    execSync('.venv\\Scripts\\pip.exe install -r requirements.txt', { stdio: 'inherit' });
+} else {
+    console.error('Error: Virtual environment (.venv) not found.');
+    process.exit(1);
+}

package/templates-win/rust/build.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('cargo build --release', { stdio: 'inherit' });

package/templates-win/rust/hard-clean.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('cargo clean', { stdio: 'inherit' });

package/templates-win/webframework/build.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('npm run build', { stdio: 'inherit' });

package/templates-win/webframework/dev.mjs.tmpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+execSync('npm run dev', { stdio: 'inherit' });

package/templates-win/webframework/hard-clean.mjs.tmpl

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+
+console.log('Resetting __FRAMEWORK__ dependencies...');
+rmSync('node_modules', { recursive: true, force: true });
+rmSync('package-lock.json', { force: true });
+rmSync('yarn.lock', { force: true });
+execSync('npm install', { stdio: 'inherit' });

package/scripts/check-platform.js

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-// Runs as npm's preinstall step. xgem is a bash CLI (osascript/xcodebuild
-// for the iOS engine, sh-isms throughout) with no Windows-native equivalent,
-// so this exists purely to fail with an actionable message instead of npm's
-// generic EBADPLATFORM error.
-
-if (process.platform !== 'darwin' && process.platform !== 'linux') {
-    console.error('');
-    console.error('\x1b[31mxgem does not run natively on Windows.\x1b[0m');
-    console.error("It's a bash CLI, and its Flutter iOS build engine shells out to Xcode tools that only exist on macOS.");
-    console.error('');
-    console.error('\x1b[36mTo use xgem on Windows, install WSL2 first:\x1b[0m');
-    console.error('  https://learn.microsoft.com/windows/wsl/install');
-    console.error('Then run this same install command again from inside your WSL terminal (it reports itself as Linux).');
-    console.error('');
-    process.exit(1);
-}