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

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
 
@@ -68,31 +74,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 +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 — 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

@@ -91,26 +91,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

package/bin/xgem.js

@@ -61,8 +61,23 @@ async function selectFramework(options) {
     return options[idx];
 }
 
-function updateGitignore() {
+// 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}/`)) {
@@ -89,7 +104,7 @@ async function cmdInit() {
     scaffold.injectTemplates(fw, CONFIG_DIR);
     logSuccess(`Successfully appended standard scripts for: ${CONFIG_DIR}/${fw}`);
 
-    updateGitignore();
+    await updateGitignore();
 }
 
 async function cmdAdd() {

package/lib/create.sh

@@ -1,29 +1,76 @@
 #!/bin/bash
-# xgem project creation wizards — runs from `xgem init`, before
-# scaffold_inject_templates, for frameworks with a real "ask sub-choice ->
-# scaffold -> install -> launch" story worth building (react/vue/angular/
-# next/flutter). The rest (node/python/go/rust/docker/swift) get a lighter
-# "create with the ecosystem's own standard init command" step.
+# xgem project creation wizards — runs from `xgem init`, for frameworks
+# with a real "ask sub-choice -> scaffold -> install -> launch" story
+# worth building (react/vue/angular/next/flutter). The rest (node/python/
+# go/rust/docker/swift) get a lighter "create with the ecosystem's own
+# standard init command" step.
 #
-# Depends on lib/logger.sh, lib/utils.sh. Uses `cd` directly (no
-# subshells) so a newly created project directory persists as the cwd for
-# the rest of `xgem init` (template injection, .gitignore) without the
-# caller needing to track/re-cd into a returned path.
+# Depends on lib/logger.sh, lib/utils.sh, lib/scaffold.sh. Uses `cd`
+# directly (no subshells) so a newly created project directory persists as
+# the cwd for the rest of `xgem init`.
 #
-# Dev-server launch is deliberately deferred: creators only set
-# XGEM_POST_INIT_LAUNCH_CMD (an array) rather than launching immediately,
-# so `xgem init` finishes template injection and .gitignore setup *before*
-# handing the terminal over to a long-running dev server.
+# Ordering principle (this file's main correctness property): xgem's own
+# bookkeeping (.xgem-automate + .gitignore, via _xgem_bookkeeping) always
+# runs BEFORE the slow, interruptible step of each framework (an install,
+# or an atomic scaffold+install like `ng new`) — never after. A real user
+# hit this: Ctrl-C during `ng new`'s multi-minute install killed the whole
+# xgem process before .xgem-automate was ever created, since it used to run
+# only at the very end. Where a tool supports decoupling scaffold-from-
+# install (--no-immediate, --skip-install, --no-pub), xgem scaffolds first
+# (fast), does its own bookkeeping, then runs the install itself. Where a
+# tool has no such flag (create-react-app), bookkeeping runs right after
+# that one atomic call returns — a small residual risk, documented at the
+# call site, not silently left as-was.
+#
+# Dev-server / device-run launch is deliberately deferred: creators only
+# set XGEM_POST_INIT_LAUNCH_CMD (an array) rather than launching
+# immediately, so `xgem init` finishes well before handing the terminal
+# over to a long-running dev server.
 XGEM_POST_INIT_LAUNCH_CMD=()
 
 # Set by creators when a NEW folder was created (not "current directory").
 # A child process can never change its parent shell's cwd, so once `xgem
 # init` exits, the user's actual terminal is back wherever it started —
 # xgem's own process is correctly cd'd into the new folder for the rest of
-# ITS run (template injection, dev server), but that never propagates back.
-# bin/xgem prints a "cd <name>" reminder using this at the very end.
+# ITS run, but that never propagates back. bin/xgem prints a "cd <name>"
+# reminder using this at the very end.
 XGEM_CREATED_NEW_FOLDER=""
 
+# _xgem_bookkeeping <framework>
+# Creates .xgem-automate + updates .gitignore. Called as early as the
+# target directory allows, always before any slow/interruptible step.
+_xgem_bookkeeping() {
+    local fw=$1
+    mkdir -p "$CONFIG_DIR"
+    scaffold_inject_templates "$fw" "$CONFIG_DIR"
+    log_success "Successfully appended standard scripts for: $CONFIG_DIR/$fw"
+
+    # 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.
+    local ignore_choice
+    read -r -p "Should $CONFIG_DIR/ be ignored by git (private to you), or tracked so collaborators get the same scripts? [ignore/track] (default: ignore): " ignore_choice
+    ignore_choice=${ignore_choice:-ignore}
+
+    if [[ "$ignore_choice" == t* || "$ignore_choice" == T* ]]; then
+        if [ -f .gitignore ] && grep -qx "$CONFIG_DIR/" .gitignore; then
+            local tmp
+            tmp=$(mktemp)
+            grep -vx "$CONFIG_DIR/" .gitignore > "$tmp" && mv "$tmp" .gitignore
+            log_info "Removed existing $CONFIG_DIR/ entry from .gitignore since you chose to track it."
+        fi
+        log_success "$CONFIG_DIR/ will be tracked in git."
+    elif [ -f .gitignore ]; then
+        if ! grep -qx "$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
+}
+
 # _prompt_project_location <human label> -> echoes "." or a new folder name.
 # Pure prompt-and-echo, no other stdout output, so it's safe to capture via
 # command substitution.
@@ -42,6 +89,15 @@ _prompt_project_location() {
     echo "$name"
 }
 
+# _enter_project_dir <project_dir> — mkdir+cd if a new folder was chosen,
+# and records XGEM_CREATED_NEW_FOLDER. No-op for "." (current directory).
+_enter_project_dir() {
+    local project_dir=$1
+    [ "$project_dir" = "." ] && return 0
+    XGEM_CREATED_NEW_FOLDER="$project_dir"
+    mkdir -p "$project_dir" && cd "$project_dir" || die "Could not enter $project_dir"
+}
+
 _open_url() {
     local url=$1
     case "$(detect_os)" in
@@ -89,13 +145,11 @@ _launch_dev_server_and_open_browser() {
 _ask_launch_dev_server() {
     [ ${#XGEM_POST_INIT_LAUNCH_CMD[@]} -gt 0 ] || return 0
 
-    # `flutter run` isn't a web dev server — it has no localhost URL to
-    # detect/open, and it depends on a fully-inherited interactive stdin
-    # for its own hot-reload keybindings (r/R/q/etc.), which the
-    # background+log-tail approach below would break. Run it directly.
-    # (Whether to run at all was already confirmed in
-    # _flutter_offer_run_on_device before this command was ever set, so
-    # this doesn't ask again.)
+    # `flutter run` isn't a web dev server — no localhost URL to detect/
+    # open, and it depends on fully-inherited interactive stdin for its
+    # own hot-reload keybindings, which the background+log-tail approach
+    # would break. Run it directly. (Whether to run at all was already
+    # confirmed in _flutter_offer_run_on_device, so this doesn't ask again.)
     if [ "${XGEM_POST_INIT_LAUNCH_CMD[0]}" = "flutter" ]; then
         "${XGEM_POST_INIT_LAUNCH_CMD[@]}"
         return 0
@@ -114,27 +168,33 @@ _create_react() {
     read -r -p "TypeScript or JavaScript? [ts/js] (default: ts): " lang
     lang=${lang:-ts}
     project_dir=$(_prompt_project_location "React")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    _enter_project_dir "$project_dir"
 
     if [[ "$variant" == cra* || "$variant" == CRA* ]]; then
         require_cmd npx "Install Node.js (npm ships with it): https://nodejs.org"
-        local -a args=(create-react-app)
-        [ "$project_dir" != "." ] && args+=("$project_dir") || args+=(.)
+        # create-react-app has no flag to decouple scaffold-from-install
+        # (confirmed: nothing in --help), so this one atomic call does
+        # both — a Ctrl-C during its own install (it's known to be slow)
+        # would still lose xgem's bookkeeping below. Accepted residual
+        # risk for this specific, non-default, legacy-leaning option.
+        log_info "Create React App scaffolds and installs in one step and can take a few minutes — best to let it finish without interrupting."
+        local -a args=(create-react-app .)
         [ "$lang" = "ts" ] && args+=(--template typescript)
         npx "${args[@]}" || die "create-react-app failed."
-    else
-        require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
-        local template="react"
-        [ "$lang" = "ts" ] && template="react-ts"
-        # --no-immediate: create-vite's own "install deps and start dev
-        # server" prompt would otherwise block here and, if Ctrl-C'd, kill
-        # this whole xgem process before it ever reaches template
-        # injection / .gitignore setup below. xgem handles install/launch
-        # itself instead, after everything else is done.
-        npm create vite@latest "$project_dir" -- --template "$template" --no-immediate || die "npm create vite failed."
+        _xgem_bookkeeping react
+        return 0
     fi
 
-    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
+    local template="react"
+    [ "$lang" = "ts" ] && template="react-ts"
+    # --no-immediate: create-vite's own "install deps and start dev server"
+    # prompt would otherwise block here (and if Ctrl-C'd, kill this whole
+    # xgem process). --overwrite: harmless here since the only files that
+    # could exist at this point are ones xgem itself hasn't created yet
+    # (bookkeeping happens after this call, deliberately).
+    npm create vite@latest . -- --template "$template" --no-immediate --overwrite || die "npm create vite failed."
+    _xgem_bookkeeping react
     log_info "Installing dependencies..."
     npm install
     XGEM_POST_INIT_LAUNCH_CMD=(npm run dev)
@@ -144,9 +204,13 @@ _create_vue() {
     require_cmd npm "Install Node.js (npm ships with it): https://nodejs.org"
     local project_dir
     project_dir=$(_prompt_project_location "Vue")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
-    npm create vue@latest "$project_dir" || die "npm create vue failed."
-    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    _enter_project_dir "$project_dir"
+    # create-vue doesn't install automatically (confirmed: no node_modules
+    # after it runs), so there's already a natural gap here to bookkeep in
+    # before the slow step. --force since this dir may be genuinely empty
+    # or (for "current directory") may already contain unrelated files.
+    npm create vue@latest . --force || die "npm create vue failed."
+    _xgem_bookkeeping vue
     log_info "Installing dependencies..."
     npm install
     XGEM_POST_INIT_LAUNCH_CMD=(npm run dev)
@@ -155,16 +219,20 @@ _create_vue() {
 _create_angular() {
     local project_dir
     project_dir=$(_prompt_project_location "Angular")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
+    _enter_project_dir "$project_dir"
     local -a ng_cmd=(ng)
     has_cmd ng || ng_cmd=(npx @angular/cli@latest)
 
-    if [ "$project_dir" = "." ]; then
-        "${ng_cmd[@]}" new "$(basename "$PWD")" --directory=. || die "ng new failed."
-    else
-        "${ng_cmd[@]}" new "$project_dir" || die "ng new failed."
-        cd "$project_dir" || die "Could not enter $project_dir"
-    fi
+    # --skip-install: ng new's own install is a multi-minute step (Angular
+    # dependency trees are large) — decoupling it is exactly what let a
+    # real user's Ctrl-C lose xgem's bookkeeping before this fix.
+    # --skip-git: xgem has its own `xgem git init`; ng new's own auto-
+    # commit would happen before .xgem-automate even exists.
+    "${ng_cmd[@]}" new "$(basename "$PWD")" --directory=. --skip-install --skip-git \
+        || die "ng new failed."
+    _xgem_bookkeeping angular
+    log_info "Installing dependencies..."
+    npm install
     XGEM_POST_INIT_LAUNCH_CMD=(npm run start)
 }
 
@@ -172,20 +240,26 @@ _create_next() {
     require_cmd npx "Install Node.js (npm ships with it): https://nodejs.org"
     local project_dir
     project_dir=$(_prompt_project_location "Next.js")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
-    npx create-next-app@latest "$project_dir" || die "create-next-app failed."
-    [ "$project_dir" != "." ] && { cd "$project_dir" || die "Could not enter $project_dir"; }
+    _enter_project_dir "$project_dir"
+    # --skip-install: decouple from create-next-app's own install, same
+    # reasoning as Angular above.
+    npx create-next-app@latest . --skip-install || die "create-next-app failed."
+    _xgem_bookkeeping next
+    log_info "Installing dependencies..."
+    npm install
     XGEM_POST_INIT_LAUNCH_CMD=(npm run dev)
 }
 
 # Lighter path for frameworks without a dev-server/browser story — just the
-# ecosystem's own standard init command, no sub-wizard.
+# ecosystem's own standard init command, no sub-wizard. These are all fast
+# (no multi-minute install step), so bookkeeping-then-init is low-risk
+# regardless of ordering, but it's kept bookkeeping-first for consistency.
 _create_simple() {
     local fw=$1
     local project_dir
     project_dir=$(_prompt_project_location "$fw")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
-    [ "$project_dir" != "." ] && { mkdir -p "$project_dir" && cd "$project_dir" || die "Could not enter $project_dir"; }
+    _enter_project_dir "$project_dir"
+    _xgem_bookkeeping "$fw"
 
     case "$fw" in
         node)
@@ -206,13 +280,7 @@ _create_simple() {
             ;;
         rust)
             require_cmd cargo "Install Rust: https://www.rust-lang.org/tools/install"
-            if [ "$project_dir" != "." ]; then
-                cd .. || return 1
-                cargo new "$project_dir" || die "cargo new failed."
-                cd "$project_dir" || die "Could not enter $project_dir"
-            else
-                cargo init || die "cargo init failed."
-            fi
+            cargo init || die "cargo init failed."
             ;;
         swift)
             require_cmd swift "Install Swift: https://www.swift.org/install/"
@@ -235,15 +303,21 @@ EOF
 }
 
 # create_project_wizard <framework>
-# Asks whether to create a new project or use what's already here; if
-# creating, dispatches to the right per-framework creator. Leaves the
-# process cwd inside the (possibly new) project directory either way.
+# Asks whether to create a new project or use what's already here. Either
+# way, xgem's own bookkeeping (.xgem-automate + .gitignore) is guaranteed
+# to happen — for "existing", immediately (nothing to interrupt); for
+# "new", each creator handles it internally at the earliest safe point,
+# per the ordering principle documented at the top of this file.
 create_project_wizard() {
     local fw=$1
     local create_choice
     read -r -p "Create a brand-new $fw project, or use what's already in this directory? [new/existing] (default: existing): " create_choice
     create_choice=${create_choice:-existing}
-    [[ "$create_choice" == n* || "$create_choice" == N* ]] || return 0
+
+    if [[ "$create_choice" != n* && "$create_choice" != N* ]]; then
+        _xgem_bookkeeping "$fw"
+        return 0
+    fi
 
     case "$fw" in
         react)   _create_react ;;
@@ -252,6 +326,9 @@ create_project_wizard() {
         next)    _create_next ;;
         flutter) create_flutter_project ;;
         node|python|go|rust|docker|swift) _create_simple "$fw" ;;
-        *) log_debug "No creation wizard for '$fw'; using current directory as-is." ;;
+        *)
+            log_debug "No creation wizard for '$fw'; using current directory as-is."
+            _xgem_bookkeeping "$fw"
+            ;;
     esac
 }

package/lib/flutter.sh

@@ -239,18 +239,20 @@ flutter_run_native_command() {
 }
 
 # create_flutter_project — used by lib/create.sh's create_project_wizard.
-# `flutter create` needs a target dir; "." scaffolds into the current one.
+# --no-pub decouples scaffolding from the (slower, network-dependent)
+# `flutter pub get` step, so xgem's own bookkeeping (_xgem_bookkeeping) can
+# happen in between — same ordering principle as the other creators in
+# lib/create.sh: bookkeeping before any slow/interruptible step, never after.
 create_flutter_project() {
     require_cmd flutter "Install Flutter: https://docs.flutter.dev/get-started/install"
     local project_dir
     project_dir=$(_prompt_project_location "Flutter")
-    [ "$project_dir" != "." ] && XGEM_CREATED_NEW_FOLDER="$project_dir"
-    if [ "$project_dir" = "." ]; then
-        flutter create . || die "flutter create failed."
-    else
-        flutter create "$project_dir" || die "flutter create failed."
-        cd "$project_dir" || die "Could not enter $project_dir"
-    fi
+    _enter_project_dir "$project_dir"
+
+    flutter create --no-pub . || die "flutter create failed."
+    _xgem_bookkeeping flutter
+    log_info "Resolving packages..."
+    flutter pub get
     _flutter_offer_run_on_device
 }
 

package/lib/git.sh

@@ -102,31 +102,67 @@ cmd_git_cmt() {
     fi
 }
 
-cmd_git_init() {
-    log_info "Initializing local Git repository..."
-    git init
+_cmd_git_init_manual_remote() {
+    local remote_name=$1
+    local remote_url user_remote_name
+    read -r -p "Enter remote repository URL (or leave blank to skip): " remote_url
+    [ -n "$remote_url" ] || return 0
 
-    local remote_name="origin" remote_url user_remote_name branch_name
-    read -r -p "Enter remote repository URL: " remote_url
-    if [ -n "$remote_url" ]; then
-        read -r -p "Enter remote name (default: origin): " user_remote_name
-        [ -n "$user_remote_name" ] && remote_name="$user_remote_name"
+    read -r -p "Enter remote name (default: $remote_name): " user_remote_name
+    [ -n "$user_remote_name" ] && remote_name="$user_remote_name"
 
-        if git remote | grep -q "^$remote_name$"; then
-            git remote set-url "$remote_name" "$remote_url"
-            log_success "Remote '$remote_name' already existed. URL updated."
-        else
-            git remote add "$remote_name" "$remote_url"
-            log_success "Remote '$remote_name' successfully added."
-        fi
+    if git remote | grep -q "^$remote_name$"; then
+        git remote set-url "$remote_name" "$remote_url"
+        log_success "Remote '$remote_name' already existed. URL updated."
+    else
+        git remote add "$remote_name" "$remote_url"
+        log_success "Remote '$remote_name' successfully added."
     fi
+}
 
+cmd_git_init() {
+    log_info "Initializing local Git repository..."
+    git init
+
+    local branch_name
     read -r -p "Enter branch name (default: main): " branch_name
     branch_name=${branch_name:-main}
     git branch -M "$branch_name"
 
     git add .
     git commit -m "initial changes" 2>/dev/null
+
+    # Real GitHub repo creation, not just wiring a remote to a URL you
+    # already had to go create by hand — this is the whole point of
+    # `xgem git init` over plain `git init`. Falls back to the manual-URL
+    # flow if `gh` isn't installed/authenticated.
+    if has_cmd gh && gh auth status >/dev/null 2>&1; then
+        local create_choice
+        read -r -p "Create a new GitHub repository for this project right now? (Y/n): " create_choice
+        create_choice=${create_choice:-y}
+        if [[ "$create_choice" == "y" || "$create_choice" == "Y" ]]; then
+            local repo_name visibility vis_flag
+            read -r -p "Repository name (default: $(basename "$PWD")): " repo_name
+            repo_name=${repo_name:-$(basename "$PWD")}
+            read -r -p "Public or private? [public/private] (default: private): " visibility
+            visibility=${visibility:-private}
+            vis_flag="--private"
+            [[ "$visibility" == pub* || "$visibility" == Pub* ]] && vis_flag="--public"
+
+            if gh repo create "$repo_name" "$vis_flag" --source=. --remote=origin --push; then
+                log_success "Created GitHub repo '$repo_name' and pushed '$branch_name' to it."
+            else
+                log_error "gh repo create failed — falling back to manual remote setup."
+                _cmd_git_init_manual_remote origin
+            fi
+            log_success "Local baseline configuration setup completed."
+            return 0
+        fi
+    elif has_cmd gh; then
+        log_warn "GitHub CLI (gh) is installed but not authenticated — run 'gh auth login' to enable one-step repo creation next time."
+    fi
+
+    _cmd_git_init_manual_remote origin
     log_success "Local baseline configuration setup completed."
 }
 

package/lib/scaffold.sh

@@ -13,12 +13,31 @@
 
 ALL_FRAMEWORKS=(flutter node python react vue angular next go rust docker swift)
 
+# _package_json_has_script <script> — checks the CURRENT directory's
+# package.json, not a guess. Used to only offer lint/test automation when
+# the project actually has those scripts, instead of always generating
+# scripts that fail with "Missing script" on projects that don't.
+_package_json_has_script() {
+    [ -f package.json ] || return 1
+    grep -qE "\"$1\"[[:space:]]*:" package.json 2>/dev/null
+}
+
 framework_scripts() {
     case "$1" in
         flutter) echo "hard-clean build build-runner" ;;
-        node)    echo "hard-clean build start" ;;
+        node)
+            local scripts="hard-clean build start"
+            _package_json_has_script lint && scripts="$scripts lint"
+            _package_json_has_script test && scripts="$scripts test"
+            echo "$scripts"
+            ;;
         python)  echo "hard-clean install" ;;
-        react|vue|angular|next) echo "hard-clean build dev" ;;
+        react|vue|angular|next)
+            local scripts="hard-clean build dev"
+            _package_json_has_script lint && scripts="$scripts lint"
+            _package_json_has_script test && scripts="$scripts test"
+            echo "$scripts"
+            ;;
         go)      echo "hard-clean build" ;;
         rust)    echo "hard-clean build" ;;
         docker)  echo "hard-clean build-up" ;;

package/lib/version.sh

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

package/lib-win/git.js

@@ -3,14 +3,23 @@
 // commit-exit-code check and origin-preference fix already in lib/git.sh
 // carry over here too.
 
+const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { logInfo, logSuccess, logWarn, logError, die } = require('./logger');
-const { prompt } = require('./utils');
+const { prompt, hasCmd } = require('./utils');
 
 function git(args, opts = {}) {
     return spawnSync('git', args, { stdio: 'inherit', ...opts });
 }
 
+function gh(args, opts = {}) {
+    return spawnSync('gh', args, { stdio: 'inherit', ...opts });
+}
+
+function ghAuthenticated() {
+    return spawnSync('gh', ['auth', 'status'], { stdio: 'ignore' }).status === 0;
+}
+
 function gitCapture(args) {
     const result = spawnSync('git', args, { encoding: 'utf8' });
     return (result.stdout || '').trim();
@@ -90,7 +99,6 @@ async function cmdCmt(commitMsg) {
     const pullResult = git(['pull', '--rebase', remoteName, currentBranch]);
     if (pullResult.status !== 0) {
         const gitDir = gitCapture(['rev-parse', '--git-dir']);
-        const path = require('node:path');
         const fs = require('node:fs');
         const inConflict = fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'));
         if (inConflict) {
@@ -112,30 +120,60 @@ async function cmdCmt(commitMsg) {
     }
 }
 
-async function cmdInit() {
-    logInfo('Initializing local Git repository...');
-    git(['init']);
+async function manualRemoteSetup(defaultRemoteName) {
+    let remoteName = defaultRemoteName;
+    const remoteUrl = await prompt('Enter remote repository URL (or leave blank to skip)');
+    if (!remoteUrl) return;
 
-    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;
+    const userRemoteName = await prompt(`Enter remote name (default: ${remoteName})`);
+    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.`);
-        }
+    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.`);
     }
+}
+
+async function cmdInit() {
+    logInfo('Initializing local Git repository...');
+    git(['init']);
 
     const branchName = (await prompt('Enter branch name (default: main)')) || 'main';
     git(['branch', '-M', branchName]);
 
     git(['add', '.']);
     git(['commit', '-m', 'initial changes']);
+
+    // Real GitHub repo creation, not just wiring a remote to a URL you
+    // already had to go create by hand — the whole point of `xgem git
+    // init` over plain `git init`. Falls back to the manual-URL flow if
+    // `gh` isn't installed/authenticated.
+    if (hasCmd('gh') && ghAuthenticated()) {
+        const createChoice = (await prompt('Create a new GitHub repository for this project right now? (Y/n)')) || 'y';
+        if (createChoice.toLowerCase() === 'y') {
+            const cwdName = path.basename(process.cwd());
+            const repoName = (await prompt(`Repository name (default: ${cwdName})`)) || cwdName;
+            const visibility = ((await prompt('Public or private? [public/private] (default: private)')) || 'private').toLowerCase();
+            const visFlag = visibility.startsWith('pub') ? '--public' : '--private';
+
+            const result = gh(['repo', 'create', repoName, visFlag, '--source=.', '--remote=origin', '--push']);
+            if (result.status === 0) {
+                logSuccess(`Created GitHub repo '${repoName}' and pushed '${branchName}' to it.`);
+            } else {
+                logError('gh repo create failed — falling back to manual remote setup.');
+                await manualRemoteSetup('origin');
+            }
+            logSuccess('Local baseline configuration setup completed.');
+            return;
+        }
+    } else if (hasCmd('gh')) {
+        logWarn("GitHub CLI (gh) is installed but not authenticated — run 'gh auth login' to enable one-step repo creation next time.");
+    }
+
+    await manualRemoteSetup('origin');
     logSuccess('Local baseline configuration setup completed.');
 }
 

package/lib-win/scaffold.js

@@ -22,8 +22,30 @@ const FRAMEWORK_SCRIPTS = {
     docker: ['hard-clean', 'build-up'],
 };
 
+const WEB_FRAMEWORKS = ['node', 'react', 'vue', 'angular', 'next'];
+
+// Only offer lint/test automation when the current directory's
+// package.json actually declares those scripts, instead of always
+// generating scripts that fail with "Missing script" on projects that
+// don't have them.
+function packageJsonHasScript(scriptName) {
+    try {
+        const pkg = JSON.parse(require('node:fs').readFileSync('package.json', 'utf8'));
+        return Boolean(pkg.scripts && pkg.scripts[scriptName]);
+    } catch {
+        return false;
+    }
+}
+
 function frameworkScripts(fw) {
-    return FRAMEWORK_SCRIPTS[fw] || null;
+    const base = FRAMEWORK_SCRIPTS[fw];
+    if (!base) return null;
+    if (!WEB_FRAMEWORKS.includes(fw)) return base;
+
+    const scripts = [...base];
+    if (packageJsonHasScript('lint')) scripts.push('lint');
+    if (packageJsonHasScript('test')) scripts.push('test');
+    return scripts;
 }
 
 function templateDir(fw) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xgem-cli",
-  "version": "2.0.0-alpha.10",
+  "version": "2.0.0-alpha.12",
   "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.js"

package/templates/node/build.sh.tmpl

@@ -1,3 +1,11 @@
 #!/bin/bash
 echo -e "\033[1;34mBuilding Node project...\033[0m"
-npm run build
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run build
+elif [ -f yarn.lock ]; then
+    yarn build
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run build
+else
+    npm run build
+fi

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

@@ -1,3 +1,35 @@
 #!/bin/bash
-echo -e "\033[1;33mNuking node_modules and resetting package locks...\033[0m"
-rm -rf node_modules package-lock.json yarn.lock && npm install
+# Detect the package manager actually in use instead of assuming npm —
+# blindly deleting yarn.lock/pnpm-lock.yaml on a project that uses them
+# and running `npm install` instead corrupts the project by introducing a
+# conflicting lockfile.
+PKG_MANAGER=npm
+if [ -f pnpm-lock.yaml ]; then
+    PKG_MANAGER=pnpm
+elif [ -f yarn.lock ]; then
+    PKG_MANAGER=yarn
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    PKG_MANAGER=bun
+elif [ -f package.json ]; then
+    declared=$(grep -o '"packageManager"[[:space:]]*:[[:space:]]*"[a-z]*' package.json 2>/dev/null | grep -oE '[a-z]+$')
+    case "$declared" in npm|yarn|pnpm|bun) PKG_MANAGER=$declared ;; esac
+fi
+
+if [ -f .nvmrc ] && command -v node >/dev/null 2>&1; then
+    wanted=$(tr -d 'v[:space:]' < .nvmrc)
+    have=$(node -v | tr -d 'v')
+    case "$have" in
+        "$wanted"*) ;;
+        *) echo -e "\033[33mWarning: .nvmrc wants Node $wanted, but 'node -v' reports $have.\033[0m" ;;
+    esac
+fi
+
+echo -e "\033[1;33mNuking node_modules and resetting package locks (package manager: $PKG_MANAGER)...\033[0m"
+rm -rf node_modules
+
+case "$PKG_MANAGER" in
+    yarn) rm -f yarn.lock; yarn install ;;
+    pnpm) rm -f pnpm-lock.yaml; pnpm install ;;
+    bun)  rm -f bun.lockb bun.lock; bun install ;;
+    *)    rm -f package-lock.json; npm install ;;
+esac

package/templates/node/lint.sh.tmpl

@@ -0,0 +1,10 @@
+#!/bin/bash
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run lint
+elif [ -f yarn.lock ]; then
+    yarn lint
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run lint
+else
+    npm run lint
+fi

package/templates/node/start.sh.tmpl

@@ -1,2 +1,10 @@
 #!/bin/bash
-npm run start
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run start
+elif [ -f yarn.lock ]; then
+    yarn start
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run start
+else
+    npm run start
+fi

package/templates/node/test.sh.tmpl

@@ -0,0 +1,10 @@
+#!/bin/bash
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run test
+elif [ -f yarn.lock ]; then
+    yarn test
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run test
+else
+    npm run test
+fi

package/templates/webframework/build.sh.tmpl

@@ -1,2 +1,11 @@
 #!/bin/bash
-npm run build
+# Use whatever package manager this project actually uses.
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run build
+elif [ -f yarn.lock ]; then
+    yarn build
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run build
+else
+    npm run build
+fi

package/templates/webframework/dev.sh.tmpl

@@ -1,2 +1,10 @@
 #!/bin/bash
-npm run dev
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run dev
+elif [ -f yarn.lock ]; then
+    yarn dev
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run dev
+else
+    npm run dev
+fi

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

@@ -1,3 +1,36 @@
 #!/bin/bash
-echo -e "\033[1;33mResetting __FRAMEWORK__ dependencies...\033[0m"
-rm -rf node_modules package-lock.json yarn.lock && npm install
+# Detect the package manager actually in use instead of assuming npm —
+# blindly deleting yarn.lock/pnpm-lock.yaml on a project that uses them
+# and running `npm install` instead corrupts the project by introducing a
+# conflicting lockfile.
+PKG_MANAGER=npm
+if [ -f pnpm-lock.yaml ]; then
+    PKG_MANAGER=pnpm
+elif [ -f yarn.lock ]; then
+    PKG_MANAGER=yarn
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    PKG_MANAGER=bun
+elif [ -f package.json ]; then
+    declared=$(grep -o '"packageManager"[[:space:]]*:[[:space:]]*"[a-z]*' package.json 2>/dev/null | grep -oE '[a-z]+$')
+    case "$declared" in npm|yarn|pnpm|bun) PKG_MANAGER=$declared ;; esac
+fi
+
+# Warn (don't block) on a Node version mismatch against .nvmrc, if present.
+if [ -f .nvmrc ] && command -v node >/dev/null 2>&1; then
+    wanted=$(tr -d 'v[:space:]' < .nvmrc)
+    have=$(node -v | tr -d 'v')
+    case "$have" in
+        "$wanted"*) ;;
+        *) echo -e "\033[33mWarning: .nvmrc wants Node $wanted, but 'node -v' reports $have.\033[0m" ;;
+    esac
+fi
+
+echo -e "\033[1;33mResetting __FRAMEWORK__ dependencies (package manager: $PKG_MANAGER)...\033[0m"
+rm -rf node_modules
+
+case "$PKG_MANAGER" in
+    yarn) rm -f yarn.lock; yarn install ;;
+    pnpm) rm -f pnpm-lock.yaml; pnpm install ;;
+    bun)  rm -f bun.lockb bun.lock; bun install ;;
+    *)    rm -f package-lock.json; npm install ;;
+esac

package/templates/webframework/lint.sh.tmpl

@@ -0,0 +1,10 @@
+#!/bin/bash
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run lint
+elif [ -f yarn.lock ]; then
+    yarn lint
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run lint
+else
+    npm run lint
+fi

package/templates/webframework/test.sh.tmpl

@@ -0,0 +1,10 @@
+#!/bin/bash
+if [ -f pnpm-lock.yaml ]; then
+    pnpm run test
+elif [ -f yarn.lock ]; then
+    yarn test
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+    bun run test
+else
+    npm run test
+fi

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

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-console.log('Building Node project...');
-execSync('npm run build', { stdio: 'inherit' });
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run build';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run build';
+else if (existsSync('yarn.lock')) cmd = 'yarn build';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run build';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -1,9 +1,28 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-import { rmSync } from 'node:fs';
+import { existsSync, rmSync, readFileSync } from 'node:fs';
 
-console.log('Nuking node_modules and resetting package locks...');
+function detectPkgManager() {
+    if (existsSync('pnpm-lock.yaml')) return 'pnpm';
+    if (existsSync('yarn.lock')) return 'yarn';
+    if (existsSync('bun.lockb') || existsSync('bun.lock')) return 'bun';
+    if (existsSync('package.json')) {
+        try {
+            const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+            if (['npm', 'yarn', 'pnpm', 'bun'].includes(pkg.packageManager?.split('@')[0])) {
+                return pkg.packageManager.split('@')[0];
+            }
+        } catch { /* ignore malformed package.json */ }
+    }
+    return 'npm';
+}
+
+const pm = detectPkgManager();
+console.log(`Nuking node_modules and resetting package locks (package manager: ${pm})...`);
 rmSync('node_modules', { recursive: true, force: true });
-rmSync('package-lock.json', { force: true });
-rmSync('yarn.lock', { force: true });
-execSync('npm install', { stdio: 'inherit' });
+
+const lockfiles = { npm: ['package-lock.json'], yarn: ['yarn.lock'], pnpm: ['pnpm-lock.yaml'], bun: ['bun.lockb', 'bun.lock'] };
+for (const f of lockfiles[pm]) rmSync(f, { force: true });
+
+const installCmd = { npm: 'npm install', yarn: 'yarn', pnpm: 'pnpm install', bun: 'bun install' };
+execSync(installCmd[pm], { stdio: 'inherit' });

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run lint';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run lint';
+else if (existsSync('yarn.lock')) cmd = 'yarn lint';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run lint';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-execSync('npm run start', { stdio: 'inherit' });
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run start';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run start';
+else if (existsSync('yarn.lock')) cmd = 'yarn start';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run start';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run test';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run test';
+else if (existsSync('yarn.lock')) cmd = 'yarn test';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run test';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-execSync('npm run build', { stdio: 'inherit' });
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run build';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run build';
+else if (existsSync('yarn.lock')) cmd = 'yarn build';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run build';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-execSync('npm run dev', { stdio: 'inherit' });
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run dev';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run dev';
+else if (existsSync('yarn.lock')) cmd = 'yarn dev';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run dev';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -1,9 +1,32 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-import { rmSync } from 'node:fs';
+import { existsSync, rmSync, readFileSync } from 'node:fs';
 
-console.log('Resetting __FRAMEWORK__ dependencies...');
+// Detect the package manager actually in use instead of assuming npm —
+// blindly deleting yarn.lock/pnpm-lock.yaml on a project that uses them
+// and running `npm install` instead corrupts the project by introducing a
+// conflicting lockfile.
+function detectPkgManager() {
+    if (existsSync('pnpm-lock.yaml')) return 'pnpm';
+    if (existsSync('yarn.lock')) return 'yarn';
+    if (existsSync('bun.lockb') || existsSync('bun.lock')) return 'bun';
+    if (existsSync('package.json')) {
+        try {
+            const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+            if (['npm', 'yarn', 'pnpm', 'bun'].includes(pkg.packageManager?.split('@')[0])) {
+                return pkg.packageManager.split('@')[0];
+            }
+        } catch { /* ignore malformed package.json */ }
+    }
+    return 'npm';
+}
+
+const pm = detectPkgManager();
+console.log(`Resetting __FRAMEWORK__ dependencies (package manager: ${pm})...`);
 rmSync('node_modules', { recursive: true, force: true });
-rmSync('package-lock.json', { force: true });
-rmSync('yarn.lock', { force: true });
-execSync('npm install', { stdio: 'inherit' });
+
+const lockfiles = { npm: ['package-lock.json'], yarn: ['yarn.lock'], pnpm: ['pnpm-lock.yaml'], bun: ['bun.lockb', 'bun.lock'] };
+for (const f of lockfiles[pm]) rmSync(f, { force: true });
+
+const installCmd = { npm: 'npm install', yarn: 'yarn', pnpm: 'pnpm install', bun: 'bun install' };
+execSync(installCmd[pm], { stdio: 'inherit' });

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run lint';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run lint';
+else if (existsSync('yarn.lock')) cmd = 'yarn lint';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run lint';
+
+execSync(cmd, { stdio: 'inherit' });

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+let cmd = 'npm run test';
+if (existsSync('pnpm-lock.yaml')) cmd = 'pnpm run test';
+else if (existsSync('yarn.lock')) cmd = 'yarn test';
+else if (existsSync('bun.lockb') || existsSync('bun.lock')) cmd = 'bun run test';
+
+execSync(cmd, { stdio: 'inherit' });