@microsoft/managed-apps-cli 0.9.2 → 0.11.0

package/dist/Verbs/CreateMaafApp.js

@@ -4,9 +4,7 @@
 import { createAsync, getPlayerServiceConfig, updateEnvironmentName, writeRepoConfig, } from '@microsoft/managed-apps-actions';
 import { AppConfigFileName } from '@microsoft/managed-apps-common/config';
 import { regionToCloudSafe } from '@microsoft/managed-apps-common/services';
-import { execFileSync } from 'child_process';
 import * as fs from 'fs';
-import { downloadTemplate } from 'giget';
 import * as os from 'os';
 import * as path from 'path';
 import { getCliLogger, getSettings } from '../CliSettings.js';
@@ -16,38 +14,17 @@ import { HelpStrings } from '../Constants/HelpStrings.js';
 import { AppError, ConfigurationError, UsageError } from '../Errors/CliError.js';
 import { printInfo, printJsonLine, printJsonSuccess, printSuccess, printWarning, } from '../Utils/ConsoleOutput.js';
 import { withGitHubDcfRecoveryAsync } from '../Utils/DcfRecovery.js';
-import { startPdeRoutingAsync } from '../Utils/EnvironmentRoutingUtils.js';
+import { downloadTemplate, parseGithubTemplate } from '../Utils/DownloadTemplate.js';
+import { awaitRoutingEnvironmentAsync, startPdeRoutingAsync, } from '../Utils/EnvironmentRoutingUtils.js';
 import { buildGcmConfig } from '../Utils/GitCredentialConfig.js';
+import { runGit } from '../Utils/GitRunner.js';
+import { ensureGitInstalled } from '../Utils/GitVersionChecker.js';
+import { buildMaafAppConfig } from '../Utils/MaafAppConfig.js';
+import { pinCliIntoAppPackageJson } from '../Utils/PinCli.js';
+import { parseRepoOption } from '../Utils/RepoOption.js';
+import { CliSpinner } from '../Utils/Spinner.js';
 import { CreateMaafAppArguments } from './VerbConstants.js';
 const DEFAULT_TEMPLATE = 'github:microsoft/Managed-Apps/templates/vite8';
-/**
- * Sentinel value for `--repo` that selects the no-source-control flow: just create the
- * server-side app record, write `ms.config.json` with `repoType: 'none'`, and skip every
- * local-setup step (git init/clone, template overlay, GCM config) plus the server-side
- * GRS auto-provisioning. Comparison is case-insensitive — `none`, `None`, `NONE` all
- * select this flow. Any other non-empty `--repo` value is treated as a remote URL.
- */
-const REPO_NONE_SENTINEL = 'none';
-/**
- * Maps the raw `--repo` flag value to a `(repoType, remoteUrl)` pair.
- * - omitted / empty → `native` (default GRS-backed flow)
- * - `none` (case-insensitive) → `none` (no GRS, no local setup)
- * - any other non-empty value → `github` (external GitHub binding — `*.ghe.com` or `github.com`;
- *   value flows through as `remoteUrl` to the action and the eventual git clone)
- *
- * Runtime invariant: `remoteUrl` is set iff `repoType === 'github'`. Consumers
- * branch on `repoType` and assert `remoteUrl!` at github use sites — see
- * `RepoSelection` for why narrowing is not automatic.
- */
-export function parseRepoOption(rawRepoValue) {
-    if (rawRepoValue === undefined || rawRepoValue === '') {
-        return { repoType: 'native', remoteUrl: undefined };
-    }
-    if (rawRepoValue.trim().toLowerCase() === REPO_NONE_SENTINEL) {
-        return { repoType: 'none', remoteUrl: undefined };
-    }
-    return { repoType: 'github', remoteUrl: rawRepoValue };
-}
 /**
  * Creates a new MAAF app and (where applicable) sets up local source control.
  *
@@ -124,43 +101,60 @@ export async function createMaafAppAsync(argumentProvider) {
     // wipe local files). To bind a non-empty directory to a MAAF app, use `ms app
     // init` instead.
     //
-    // --repo none path: no git, no clone — ms.config.json and the template are
-    // written locally. The preflight reduces to (1) target dir must be writable
-    // so the config and template writes won't fail post-create, and (2) the dir
-    // must be empty (template scaffolding requires a clean target, same as the
-    // other flows).
+    // --repo none path: no source-control git (no `git init`, no `git clone` of a
+    // user-supplied remote). Git itself is still required, because the template
+    // download is a sparse `git clone` of the github-hosted template repo —
+    // hence `ensureGitInstalled` runs unconditionally below.
     // ──────────────────────────────────────────────────────────────────────────
-    if (!jsonMode) {
+    const usePreflightSpinner = !jsonMode && process.stdout.isTTY;
+    if (!jsonMode && !usePreflightSpinner) {
         printInfo('Running preflight checks...');
     }
-    // --repo none is incompatible with --repository-id: the former opts out of any
-    // platform-managed git binding, the latter forces one. Fail fast before any
-    // server call so we don't half-bind the app.
-    if (repoType === 'none' && repositoryId) {
-        throw new UsageError("'--repo none' is incompatible with '--repository-id'. " +
-            "Use '--repo none' for an app with no git binding, or omit '--repo' (or pass a repo URL) to use a backing repository.");
-    }
-    ensureTemplateSourceValid(template);
-    if (repoType !== 'none') {
+    // Spinner runs only in TTY interactive mode; --json keeps stdout clean and
+    // non-TTY (CI, piped output) uses plain prose so log files stay readable.
+    // Most preflight checks are sync, so the spinner frame can pause while a
+    // check runs; we still update the status label before each check so users
+    // always see the current step. The try/finally guarantees we restore the
+    // cursor even if a preflight check throws.
+    const preflightSpinner = usePreflightSpinner ? new CliSpinner() : null;
+    preflightSpinner?.start('Running preflight checks...');
+    try {
+        // --repo none is incompatible with --repository-id: the former opts out of any
+        // platform-managed git binding, the latter forces one. Fail fast before any
+        // server call so we don't half-bind the app.
+        if (repoType === 'none' && repositoryId) {
+            throw new UsageError("'--repo none' is incompatible with '--repository-id'. " +
+                "Use '--repo none' for an app with no git binding, or omit '--repo' (or pass a repo URL) to use a backing repository.");
+        }
+        preflightSpinner?.update('Validating template source...');
+        ensureTemplateSourceValid(template);
+        preflightSpinner?.update('Checking git installation...');
         ensureGitInstalled();
+        preflightSpinner?.update('Verifying target directory is writable...');
+        ensureTargetDirectoryWritable(appDir);
+        if (repoType === 'github') {
+            // RepoSelection is a flat interface (not a discriminated union), so `remoteUrl`
+            // doesn't auto-narrow to `string` here even though the github branch guarantees it.
+            preflightSpinner?.update('Verifying target directory is empty...');
+            ensureRepoTargetDirectoryEmpty(appDir);
+            // Pre-network: cheap partial clone into a temp dir + ls-tree HEAD to detect
+            // a non-empty remote before createAsync runs. Catches the rejection case
+            // without leaving an orphaned server-side app or scaffolded files in
+            // appDir. Cheapest probe shape: --depth=1 --filter=blob:none --no-checkout
+            // pulls refs + the tip commit + its tree(s) only (no blob bytes, no working
+            // tree). On any probe error (network, auth, server doesn't support partial
+            // clone, etc.) we swallow and let the subsequent cloneRepo emit its
+            // friendlier error — see ensureExternalRepoIsEmpty for the rationale.
+            preflightSpinner?.update(`Verifying ${remoteUrl} is empty...`);
+            ensureExternalRepoIsEmpty(remoteUrl);
+        }
+        else {
+            preflightSpinner?.update('Verifying target directory is empty...');
+            ensureTargetDirectoryEmpty(appDir);
+        }
     }
-    ensureTargetDirectoryWritable(appDir);
-    if (repoType === 'github') {
-        // RepoSelection is a flat interface (not a discriminated union), so `remoteUrl`
-        // doesn't auto-narrow to `string` here even though the github branch guarantees it.
-        ensureRepoTargetDirectoryEmpty(appDir);
-        // Pre-network: cheap partial clone into a temp dir + ls-tree HEAD to detect
-        // a non-empty remote before createAsync runs. Catches the rejection case
-        // without leaving an orphaned server-side app or scaffolded files in
-        // appDir. Cheapest probe shape: --depth=1 --filter=blob:none --no-checkout
-        // pulls refs + the tip commit + its tree(s) only (no blob bytes, no working
-        // tree). On any probe error (network, auth, server doesn't support partial
-        // clone, etc.) we swallow and let the subsequent cloneRepo emit its
-        // friendlier error — see ensureExternalRepoIsEmpty for the rationale.
-        ensureExternalRepoIsEmpty(remoteUrl);
-    }
-    else {
-        ensureTargetDirectoryEmpty(appDir);
+    finally {
+        preflightSpinner?.stop();
     }
     // ─── End preflight ────────────────────────────────────────────────────────
     // The debug env-var override (MS_CLI_MAAF_DEBUG_ENVIRONMENT_ID) is honored by ArgumentProvider
@@ -184,9 +178,10 @@ export async function createMaafAppAsync(argumentProvider) {
     /* ignorePrompt */ true);
     const buildEntryPoint = await argumentProvider.getOption('buildEntryPoint', 
     /* ignorePrompt */ true);
-    // Explicit branch keeps the non-null read of routingEnvPromise reachable only when
-    // preResolvedEnvironmentId is undefined — i.e. exactly when routingEnvPromise is defined.
-    const environmentId = preResolvedEnvironmentId ?? (await routingEnvPromise);
+    // Shared environment-routing logic between CreateMaafApp and Init.
+    // `awaitRoutingEnvironmentAsync` prints a `--environment-id` hint on any
+    // failure — HTTP error codes, `operationSuccess: false`, and exceptions.
+    const environmentId = await awaitRoutingEnvironmentAsync(preResolvedEnvironmentId, routingEnvPromise);
     updateEnvironmentName(environmentId);
     // Re-check the directory invariant right before the server call. The same
     // check ran in preflight, but the routing-env resolution between then and
@@ -319,33 +314,49 @@ export async function createMaafAppAsync(argumentProvider) {
         if (!jsonMode) {
             printInfo(`Fetching template '${template}' into ${appDir}...`);
         }
-        await downloadTemplate(template, { dir: appDir, force: true });
-        const config = {
+        downloadTemplate(template, { dir: appDir });
+        // Pin the scaffolding CLI into the app so a later package install provides a
+        // project-local `ms` — which `npx ms` / `pnpm exec` / `bun x` resolve ahead of
+        // any globally-installed CLI — at the exact version the app was created with.
+        // Runs for every repo flow (the template, and therefore its package.json,
+        // lands via downloadTemplate above regardless of `--repo`).
+        pinCliIntoAppPackageJson(appDir, jsonMode);
+        const config = buildMaafAppConfig({
             appId: app.id,
             appDisplayName: app.displayName,
             description: app.description,
             environmentId: app.environmentId,
+            repoType,
+            cloud: argumentProvider.getCloud(),
+            buildPath,
+            buildCommand,
+            buildEntryPoint,
             // Only the `native` flow has a platform-managed git binding. `github` tracks
             // external binding server-side via `externalRepo`, and `none` intentionally has
             // no platform-managed binding. Omit `repositoryId` for both so downstream verbs
             // key off `repoType` instead of a placeholder value.
-            ...(repoType === 'native' && { repositoryId: app.repositoryId }),
-            repoType,
+            repositoryId: repoType === 'native' ? app.repositoryId : undefined,
             // externalRepoUrl is persisted only for github-bound apps so that post-create verbs
             // (build, deploy) know which GitHub host to authenticate against during inline DCF
             // recovery without re-prompting the user for the URL.
-            ...(repoType === 'github' && { externalRepoUrl: remoteUrl }),
-            cloud: argumentProvider.getCloud(),
-            buildPath: buildPath ?? './dist',
-            buildCommand: buildCommand ?? 'npm run build',
-            buildEntryPoint: buildEntryPoint ?? 'index.html',
-        };
+            externalRepoUrl: repoType === 'github' ? remoteUrl : undefined,
+        });
         await writeRepoConfig(path.join(appDir, AppConfigFileName), config);
         // Auto commit + push for git-backed flows (native + github). The `none` flow
         // has no remote, so it's skipped. Push failure is non-fatal — see the warning
         // path in commitAndPushScaffoldAsync.
         if (repoType !== 'none') {
-            pushOutcome = await commitAndPushScaffoldAsync(appDir, jsonMode);
+            // Classify the push only for the native (GRS) flow: we own its GCM browser
+            // OAuth credentials, so we can label an auth/network failure correctly. The
+            // github flow uses the developer's own credentials (gh / SSH / PAT) we don't
+            // control, so it's left unclassified. Unlike fetch, push is non-fatal: the
+            // classified error is caught and turned into a PushOutcome, so its exit code
+            // never propagates. Classification only relabels the cause-specific message —
+            // surfaced as the human-mode warning and carried in the --json error payload.
+            const pushClassify = repoType === 'native' && cloneUrl
+                ? { action: `pushing to ${gitHostLabel(cloneUrl)}` }
+                : undefined;
+            pushOutcome = await commitAndPushScaffoldAsync(appDir, jsonMode, pushClassify);
         }
     }
     catch (setupError) {
@@ -355,7 +366,21 @@ export async function createMaafAppAsync(argumentProvider) {
         if (setupError instanceof UsageError) {
             throw setupError;
         }
-        throw new AppError(`App '${app.displayName}' was created, but local setup failed: ${setupError instanceof Error ? setupError.message : String(setupError)}\n` + buildOrphanedAppRecoveryHint(app.id, app.environmentId));
+        const detail = setupError instanceof Error ? setupError.message : String(setupError);
+        const message = `App '${app.displayName}' was created, but local setup failed: ${detail}\n` +
+            buildOrphanedAppRecoveryHint(app.id, app.environmentId);
+        // Re-message a typed AppError in place rather than re-wrapping it, so the
+        // failure category survives the orphan-hint prefix intact: a classified
+        // AuthenticationError keeps its exit code (3), name, errorData, AND its
+        // subclass identity (`instanceof AuthenticationError` still holds for any
+        // future handler that branches on the class). Constructing a fresh AppError
+        // would downgrade everything to exit 1 and erase the subclass. The original
+        // message is preserved as `detail` inside the new message, so nothing is lost.
+        if (setupError instanceof AppError) {
+            setupError.message = message;
+            throw setupError;
+        }
+        throw new AppError(message);
     }
     if (jsonMode) {
         // `appId` is the bare GUID returned by the server (`MaafAppDefinition.id`) and
@@ -392,17 +417,22 @@ export async function createMaafAppAsync(argumentProvider) {
  * Failure is non-fatal: prints a warning with the retry command and returns
  * `{ success: false, ... }`. The server-side app and local scaffold are unchanged.
  *
- * `stdio: ['ignore', 'ignore', 'inherit']`:
- *   - stdin ignored: child can't prompt for input (would block forever).
- *   - stdout ignored: discards git's progress prose so pretty output stays clean.
- *   - stderr inherited: git's actual error messages reach the user's terminal
- *     so they see git's own context alongside our warning.
+ * All three git commands go through {@link runGit}, so stdin is ignored (the
+ * child can never block waiting for input) and stdout is discarded (git's
+ * progress prose stays out of our pretty output). Stderr handling follows the
+ * runGit policy: the un-classified `add`/`commit` steps re-emit git's stderr on
+ * failure, and the `push` step either streams stderr live (un-classified github
+ * flow, `network: true`) or pipes it for classification (native flow, when a
+ * `pushClassify` context is supplied) — either way git's own error context
+ * reaches the user alongside our warning. Note that a classified push error is
+ * caught here, so (unlike fetch) its exit code never propagates; classification
+ * only shapes the warning text and the `--json` error payload.
  *
  * Commit identity (user.name / user.email) is read by git itself from
  * local-then-global config — we pass nothing. Missing identity surfaces as
- * git's own descriptive commit error through the inherited stderr.
+ * git's own descriptive commit error via runGit's stderr handling.
  */
-export async function commitAndPushScaffoldAsync(appDir, jsonMode) {
+export async function commitAndPushScaffoldAsync(appDir, jsonMode, pushClassify) {
     // Full add+commit+push sequence: any of the three commands may have been the
     // one that failed (e.g. `git commit` errors when user.name/user.email aren't
     // set), so re-running just `git push` wouldn't recover. The sequence is
@@ -411,17 +441,12 @@ export async function commitAndPushScaffoldAsync(appDir, jsonMode) {
     // `git push` still pushes the existing commit.
     const retryCommand = `git add . && git commit -m "Initial scaffold from 'ms app create'" && git push -u origin HEAD`;
     try {
-        execFileSync('git', ['add', '.'], {
-            cwd: appDir,
-            stdio: ['ignore', 'ignore', 'inherit'],
-        });
-        execFileSync('git', ['commit', '-m', "Initial scaffold from 'ms app create'"], {
+        runGit(['add', '.'], { cwd: appDir });
+        runGit(['commit', '-m', "Initial scaffold from 'ms app create'"], { cwd: appDir });
+        runGit(['push', '-u', 'origin', 'HEAD'], {
             cwd: appDir,
-            stdio: ['ignore', 'ignore', 'inherit'],
-        });
-        execFileSync('git', ['push', '-u', 'origin', 'HEAD'], {
-            cwd: appDir,
-            stdio: ['ignore', 'ignore', 'inherit'],
+            network: true,
+            classify: pushClassify,
         });
         return { success: true };
     }
@@ -435,18 +460,88 @@ export async function commitAndPushScaffoldAsync(appDir, jsonMode) {
                 ? { ...err }
                 : { message: String(err) };
         if (!jsonMode) {
+            // A classified native push failure (AuthenticationError / NetworkError)
+            // carries the actionable, cause-specific guidance — plus git's own output —
+            // in its message, but runGit's classify path throws *before* re-emitting
+            // stderr, so without this the human-readable terminal would only see the
+            // generic retry hint. (Unclassified add/commit failures and the live-stderr
+            // github push already surfaced git's output, so only re-print for the
+            // classified case to avoid duplicate noise.)
+            if (err instanceof AppError) {
+                printWarning(err.message);
+            }
             printWarning(`Could not commit and push the initial scaffold. Your app and local scaffold are ready. ` +
                 `To finish wiring it up, run:\n    ${retryCommand}`);
         }
         return { success: false, error: errorPayload, retryCommand };
     }
 }
+const GIT_CLONE_ACCESS_FAILURE_SIGNATURES = [
+    'repository not found',
+    'fatal: repository',
+    'could not read username',
+    'terminal prompts disabled',
+    'authentication failed',
+    'permission denied',
+    '403',
+    'remote: not found',
+];
+function getCapturedStderr(err) {
+    const stderr = err.stderr;
+    if (typeof stderr === 'string') {
+        return stderr;
+    }
+    if (Buffer.isBuffer(stderr)) {
+        return stderr.toString();
+    }
+    if (stderr instanceof Uint8Array) {
+        return Buffer.from(stderr).toString();
+    }
+    return '';
+}
+function getUnderlyingCloneError(err, stderr) {
+    const message = err instanceof Error ? err.message : String(err);
+    const trimmedStderr = stderr.trim();
+    if (!trimmedStderr || message.includes(trimmedStderr)) {
+        return message;
+    }
+    return `${message}\n${trimmedStderr}`;
+}
+function isGitCloneAccessFailure(stderr) {
+    const normalizedStderr = stderr.toLowerCase();
+    return GIT_CLONE_ACCESS_FAILURE_SIGNATURES.some((signature) => normalizedStderr.includes(signature));
+}
+// Shared remediation body for the two access-failure surfaces (the pre-create
+// probe and the post-create clone). Both are LOCAL `git clone` failures. The
+// external-repo clone injects no credentials/config — it relies entirely on the
+// user's own git setup — so the CLI can't meaningfully point at a specific
+// credential mechanism (GCM, gh, SSH, PAT, …); the guidance stays generic.
+// It also deliberately does NOT mention the Microsoft GitHub App or
+// `git auth refresh`, which only affect the server-side Entra↔GitHub mapping.
+// Carries no raw git output either; the raw detail is preserved on the thrown
+// error's `errorData` for telemetry/debug — see the throw sites below.
+function gitHubAccessFailureGuidance() {
+    return `Make sure the repository exists and that you have access to it.`;
+}
+function buildGitHubCloneAccessErrorMessage({ directory, repoUrl }) {
+    return `Failed to clone '${repoUrl}' into '${directory}'. ` + gitHubAccessFailureGuidance();
+}
+// Pre-create variant: the probe runs BEFORE the server app is created, so the
+// lead makes explicit that nothing was created (no orphan / no recovery hint).
+function buildGitHubAccessPreflightErrorMessage(repoUrl) {
+    return (`Cannot access repository '${repoUrl}', so no app was created. ` + gitHubAccessFailureGuidance());
+}
+function buildGenericCloneFailureMessage({ directory, repoUrl }) {
+    return `Failed to clone '${repoUrl}' into '${directory}'. See the git output above for details.`;
+}
 /**
  * Clones the developer's external GitHub repo (`*.ghe.com` tenant or `github.com`) into `directory`.
  * Auth flows through the user's existing git credential setup — the CLI does not inject
  * tokens here. On failure, surfaces a CLI-friendly error pointing the user at the
- * GitHub App install prerequisite; git's own stderr is preserved (stdio: inherit) so
- * the underlying message appears inline above the wrapper.
+ * GitHub App install prerequisite. Git's stderr is captured (via `runGit`, with
+ * `emitStderr: false`) so it can be run through the access-failure classification,
+ * and is re-emitted on failure so the underlying message still appears inline
+ * above the wrapper.
  *
  * Targeting rules (mirrors `git clone` semantics):
  *   - directory non-existent → clone creates it
@@ -456,82 +551,137 @@ export async function commitAndPushScaffoldAsync(appDir, jsonMode) {
  */
 export function cloneRepo({ directory, repoUrl }) {
     try {
-        execFileSync('git', ['clone', repoUrl, directory], {
-            stdio: ['ignore', 'inherit', 'inherit'],
-        });
+        // Pipe + capture stderr (no `network`, so it is not inherited) so the catch
+        // can run it through `isGitCloneAccessFailure`; `emitStderr: false` lets the
+        // catch own the single re-emission below instead of runGit double-printing.
+        runGit(['clone', repoUrl, directory], { emitStderr: false });
     }
     catch (err) {
-        throw new ConfigurationError(`Failed to clone '${repoUrl}' into '${directory}'. Ensure the Microsoft GitHub App is installed and authorized for this repository, and that your git credentials can access it (gh auth login, GCM, or your configured SSH key/PAT). Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+        const stderr = getCapturedStderr(err);
+        if (stderr) {
+            // Re-emit git's own output live so the raw detail is still visible to the
+            // user (and in logs) without polluting the thrown error's message.
+            process.stderr.write(stderr);
+        }
+        const message = isGitCloneAccessFailure(stderr)
+            ? buildGitHubCloneAccessErrorMessage({ directory, repoUrl })
+            : buildGenericCloneFailureMessage({ directory, repoUrl });
+        // Keep the user-facing message clean; preserve the raw git detail on
+        // errorData for telemetry/debug rather than embedding it in the message.
+        // Clone failures span remote access and local git credential configuration.
+        throw new ConfigurationError(message, {
+            underlyingError: getUnderlyingCloneError(err, stderr),
+        });
     }
 }
 export function initLocalRepo({ directory, gitUrl, loginAuthority, authResource, jsonMode = false, }) {
-    let gcmConfig;
+    const gcmConfig = buildGcmConfigOrThrow({ gitUrl, loginAuthority, authResource });
+    gitInit(directory);
+    writeGcmConfig(directory, gcmConfig);
+    addOrUpdateRemote(directory, gitUrl);
+    announceGitAuthentication(gitUrl, jsonMode);
+    fetchOrigin(directory, gitUrl);
+    checkoutMainIfPresent(directory);
+}
+/**
+ * Builds the per-host GCM OAuth config, re-wrapping any URL/protocol validation
+ * failure from {@link buildGcmConfig} as a `ConfigurationError` so the verb's
+ * error handling treats an invalid clone URL as a user-actionable setup problem.
+ */
+function buildGcmConfigOrThrow({ gitUrl, loginAuthority, authResource, }) {
     try {
-        gcmConfig = buildGcmConfig({ gitUrl, loginAuthority, authResource });
+        return buildGcmConfig({ gitUrl, loginAuthority, authResource });
     }
     catch (err) {
         throw new ConfigurationError(`Git credential helper setup failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+}
+/** Creates the target directory (idempotent) and initializes an empty git repo. */
+function gitInit(directory) {
     fs.mkdirSync(directory, { recursive: true });
-    execFileSync('git', ['init'], { cwd: directory, stdio: ['ignore', 'ignore', 'inherit'] });
-    // Write GCM config before fetching so the first network call is already authenticated.
+    runGit(['init'], { cwd: directory });
+}
+/** Writes GCM config before fetching so the first network call is already authenticated. */
+function writeGcmConfig(directory, gcmConfig) {
     for (const [key, value] of gcmConfig) {
-        execFileSync('git', ['config', '--local', key, value], {
-            cwd: directory,
-            stdio: ['ignore', 'ignore', 'inherit'],
-        });
+        runGit(['config', '--local', key, value], { cwd: directory });
     }
-    // `git remote add` fails if origin already exists. Pipe stderr so we can inspect the
-    // message and only fall back to `set-url` for that specific case — other failures
-    // (permissions, corrupt repo) must propagate rather than produce a misleading set-url error.
+}
+/**
+ * Adds `origin`, tolerating the already-exists case by falling back to
+ * `set-url`. `git remote add` fails if origin already exists. Capture stderr
+ * (allowFailure) so we can inspect the message and only fall back to `set-url`
+ * for that specific case — other failures (permissions, corrupt repo) must
+ * propagate rather than produce a misleading set-url error.
+ */
+function addOrUpdateRemote(directory, gitUrl) {
+    const addRemote = runGit(['remote', 'add', 'origin', gitUrl], {
+        cwd: directory,
+        allowFailure: true,
+        emitStderr: false,
+    });
+    if (!addRemote.success) {
+        if (!addRemote.stderr.includes('already exists')) {
+            process.stderr.write(addRemote.stderr);
+            // `runGit` always populates `error` on the failure variant, so no fallback
+            // is needed (the GitResult union guarantees it here).
+            throw addRemote.error;
+        }
+        runGit(['remote', 'set-url', 'origin', gitUrl], { cwd: directory });
+    }
+}
+/**
+ * Best-effort host label for a git remote URL. Returns the URL's host, or — when
+ * the string isn't a parseable URL — the original string. Used for human-facing
+ * action labels (auth/fetch/push messages) where a malformed URL must not turn a
+ * cosmetic label into a thrown `Invalid URL` that masquerades as the real
+ * failure. The platform issues these URLs, so the fallback is effectively
+ * unreachable, but the guard keeps the label site from becoming a crash site.
+ */
+function gitHostLabel(gitUrl) {
     try {
-        execFileSync('git', ['remote', 'add', 'origin', gitUrl], {
-            cwd: directory,
-            stdio: ['ignore', 'ignore', 'pipe'],
-        });
+        return new URL(gitUrl).host;
     }
-    catch (err) {
-        const stderr = err.stderr?.toString() ?? '';
-        if (!stderr.includes('already exists')) {
-            process.stderr.write(stderr);
-            throw err;
-        }
-        execFileSync('git', ['remote', 'set-url', 'origin', gitUrl], {
-            cwd: directory,
-            stdio: ['ignore', 'ignore', 'inherit'],
-        });
+    catch {
+        return gitUrl;
     }
-    // The first `git fetch` triggers GCM's OAuth flow if the user has no cached
-    // credentials, which can pop a browser without warning. Tell the user up
-    // front so they don't see the browser as a surprise (and know which host /
-    // account to authenticate against). Skipped under `--json` so the prose
-    // doesn't end up interleaved with the JSON envelope on stdout.
+}
+/**
+ * Prints the pre-fetch authentication notice. The first `git fetch` triggers
+ * GCM's OAuth flow if the user has no cached credentials, which can pop a
+ * browser without warning. Tell the user up front so they don't see the browser
+ * as a surprise (and know which host / account to authenticate against). Skipped
+ * under `--json` so the prose doesn't end up interleaved with the JSON envelope
+ * on stdout.
+ */
+function announceGitAuthentication(gitUrl, jsonMode) {
     if (!jsonMode) {
-        printInfo(`Authenticating to ${new URL(gitUrl).host} for the initial git fetch. ` +
+        printInfo(`Authenticating to ${gitHostLabel(gitUrl)} for the initial git fetch. ` +
             'A browser window may open. Sign in with the account associated with this tenant.');
     }
-    execFileSync('git', ['fetch', 'origin'], {
+}
+/** Fetches `origin`, classifying any auth/network failure against the remote host. */
+function fetchOrigin(directory, gitUrl) {
+    runGit(['fetch', 'origin'], {
         cwd: directory,
-        stdio: ['ignore', 'ignore', 'inherit'],
+        network: true,
+        classify: { action: `fetching from ${gitHostLabel(gitUrl)}` },
     });
-    // Probe for origin/main locally (no network needed after fetch).
-    // A broad catch here is safe: the only failure mode is "ref doesn't exist".
-    let hasMain = false;
-    try {
-        execFileSync('git', ['rev-parse', '--verify', 'origin/main'], {
-            cwd: directory,
-            stdio: ['ignore', 'ignore', 'ignore'],
-        });
-        hasMain = true;
-    }
-    catch {
-        // Empty GRS repo — origin/main not yet present.
-    }
-    if (hasMain) {
-        execFileSync('git', ['checkout', '-b', 'main', 'origin/main'], {
-            cwd: directory,
-            stdio: ['ignore', 'ignore', 'inherit'],
-        });
+}
+/**
+ * Checks out `main` tracking `origin/main` when that ref exists. Probe for
+ * origin/main locally (no network needed after fetch). A failed probe means the
+ * ref doesn't exist (empty GRS repo); allowFailure turns that expected case into
+ * a `success: false` signal instead of a throw.
+ */
+function checkoutMainIfPresent(directory) {
+    const mainProbe = runGit(['rev-parse', '--verify', 'origin/main'], {
+        cwd: directory,
+        allowFailure: true,
+        emitStderr: false,
+    });
+    if (mainProbe.success) {
+        runGit(['checkout', '-b', 'main', 'origin/main'], { cwd: directory });
     }
 }
 // ─── Recovery hint for post-create failures ─────────────────────────────────
@@ -543,108 +693,21 @@ export function initLocalRepo({ directory, gitUrl, loginAuthority, authResource,
 export function buildOrphanedAppRecoveryHint(serverAppId, environmentId) {
     return (`The server app is still in environment ${environmentId} (id: ${serverAppId}).\n` +
         `If you want to clean it up before retrying, run the following command:\n` +
-        `  npx ${CLI_BINARY_NAME} app delete --app ${serverAppId} --environment-id ${environmentId} --force`);
+        `  ${CLI_BINARY_NAME} app delete --app ${serverAppId} --environment-id ${environmentId} --force`);
 }
 // ─── Preflight helpers ──────────────────────────────────────────────────────
 // All checks below run before any server call so a local misconfiguration
-// (missing git, bad template source, unwritable directory) fails fast and
-// never leaves an orphaned MAAF app + GRS repo on the server.
+// (bad template source, unwritable directory, …) fails fast and never leaves
+// an orphaned MAAF app + GRS repo on the server. The git presence + version
+// check lives in `Utils/GitVersionChecker.ts`.
 // ────────────────────────────────────────────────────────────────────────────
-export function ensureGitInstalled() {
-    try {
-        execFileSync('git', ['--version'], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch {
-        throw new ConfigurationError("'git' is required but was not found on PATH. Install git from https://git-scm.com/ and retry.");
-    }
-}
-// Known giget provider prefixes. Used only for a *soft* "did you mean?" warning —
-// not a hard reject, so adding a new giget provider doesn't silently fail
-// preflight here. Sourced from giget's docs (github, gitlab, bitbucket, sourcehut,
-// http, https) as of the version pinned in package.json. Update opportunistically
-// when bumping giget; a stale entry only suppresses one warning, never blocks
-// a valid template.
-const KNOWN_GIGET_PROVIDERS = new Set([
-    'github',
-    'gitlab',
-    'bitbucket',
-    'sourcehut',
-    'http',
-    'https',
-]);
-// Single-edit Damerau-Levenshtein distance, capped at 1: returns true iff `a`
-// is one substitution, one insertion, one deletion, or one adjacent
-// transposition away from `b`. Used to pick the closest known provider for a
-// "did you mean?" hint without pulling in a dependency.
-function isOneEditAway(a, b) {
-    if (a === b)
-        return false;
-    if (Math.abs(a.length - b.length) > 1)
-        return false;
-    if (a.length === b.length) {
-        let diff = 0;
-        let transposition = null;
-        for (let i = 0; i < a.length; i++) {
-            if (a[i] !== b[i]) {
-                diff++;
-                if (transposition === null)
-                    transposition = i;
-                if (diff > 2)
-                    return false;
-            }
-        }
-        if (diff <= 1)
-            return true;
-        if (diff === 2 && transposition !== null) {
-            // Adjacent swap: gihub vs github, swap positions transposition and transposition+1.
-            return a[transposition] === b[transposition + 1] && a[transposition + 1] === b[transposition];
-        }
-        return false;
-    }
-    // One insertion or deletion away. Walk both strings; allow one skip.
-    const [shorter, longer] = a.length < b.length ? [a, b] : [b, a];
-    let i = 0;
-    let j = 0;
-    let skipped = false;
-    while (i < shorter.length && j < longer.length) {
-        if (shorter[i] === longer[j]) {
-            i++;
-            j++;
-            continue;
-        }
-        if (skipped)
-            return false;
-        skipped = true;
-        j++;
-    }
-    return true;
-}
 export function ensureTemplateSourceValid(source) {
-    // Hard validation: only enforce non-empty. Any further structural validation
-    // (provider name, URL shape, registry lookup) is giget's responsibility —
-    // duplicating its provider list locally goes stale silently when giget adds
-    // support for a new provider, turning a valid template into a misleading
-    // "unknown provider" error at preflight.
-    if (!source) {
-        throw new UsageError('Template source is empty. Use --template to specify one.');
-    }
-    // Soft validation: if the source looks like `<prefix>:<rest>` but the prefix
-    // is one edit away from a known giget provider (e.g. `gihub:` → `github:`),
-    // warn but proceed. giget will produce the authoritative error if the
-    // prefix is genuinely invalid; for the common typo case we surface the fix
-    // before the network round-trip. No hard-fail keeps this forward-compatible
-    // with new giget providers — a stale `KNOWN_GIGET_PROVIDERS` set only
-    // suppresses a warning, it never blocks a valid template.
-    const prefixMatch = /^([a-z][a-z0-9+.-]*):/i.exec(source);
-    if (!prefixMatch)
-        return;
-    const prefix = prefixMatch[1].toLowerCase();
-    if (KNOWN_GIGET_PROVIDERS.has(prefix))
-        return;
-    const suggestion = [...KNOWN_GIGET_PROVIDERS].find((known) => isOneEditAway(prefix, known));
-    if (suggestion) {
-        printWarning(`Template source '${source}' uses an unrecognized provider prefix '${prefix}:'. Did you mean '${suggestion}:'?`);
-    }
+    // Delegates to the github-only parser in DownloadTemplate. The parser throws
+    // `UsageError` for any unsupported shape (non-`github:` prefix, malformed
+    // URL, missing owner/repo) — which is what preflight wants: surface the
+    // problem before any server call. We discard the parsed result; the real
+    // download path re-parses at call time.
+    parseGithubTemplate(source);
 }
 export function ensureTargetDirectoryEmpty(appDir) {
     // Scaffolding into a non-empty directory would mix the template with the
@@ -670,7 +733,7 @@ export function ensureRepoTargetDirectoryEmpty(appDir) {
         return;
     const entries = fs.readdirSync(appDir);
     if (entries.length > 0) {
-        throw new UsageError(`'${appDir}' is not empty. --repo requires an empty target directory; specify an empty directory as the first argument or move to one before running.`);
+        throw new UsageError(`'${appDir}' is not empty. --repo requires an empty target directory; specify an empty directory as the first argument, move to one before running, or run 'ms app init' to bind an existing project to a new app.`);
     }
 }
 /**
@@ -682,14 +745,18 @@ export function ensureRepoTargetDirectoryEmpty(appDir) {
  * bandwidth on the rejection path is tens of KB even for a multi-GB repo. The
  * temp dir is removed in `finally`.
  *
- * Failure semantics — fail-OPEN:
+ * Failure semantics:
  *   - Non-empty tree at HEAD → throws `UsageError` with the "is not empty" /
  *     "ms app init" actionable lead, BEFORE createAsync. No orphan, no leak.
  *   - Empty tree (incl. the cleaned-up-repo edge case: commit1 add, commit2
  *     delete all) → ls-tree returns no lines → returns without throwing.
- *   - Any error from git itself (auth, network blip, server doesn't support
- *     --filter, repo doesn't exist, etc.) → swallow and return. The subsequent
- *     cloneRepo will surface a friendlier message for the user-facing failure;
+ *   - Clone fails with a recognizable access/auth signature (private repo
+ *     hidden as "not found", missing local credentials, 403, …) → throws
+ *     `ConfigurationError` BEFORE createAsync so we never create a server-side
+ *     app the user can't clone (fail FAST, no orphan).
+ *   - Any other git error (network blip, server doesn't support --filter,
+ *     temp-fs hiccup, …) → swallow and return (fail OPEN). The subsequent
+ *     cloneRepo surfaces the friendlier message for the user-facing failure;
  *     we don't want this probe to become a parallel error-message surface.
  */
 export function ensureExternalRepoIsEmpty(repoUrl) {
@@ -703,27 +770,38 @@ export function ensureExternalRepoIsEmpty(repoUrl) {
         return;
     }
     try {
-        try {
-            execFileSync('git', ['clone', '--depth=1', '--filter=blob:none', '--no-checkout', repoUrl, probeDir], { stdio: ['ignore', 'ignore', 'ignore'] });
-        }
-        catch {
-            // Clone itself failed (auth, network, repo not found, server doesn't
-            // support partial clone, etc.). Fail open: the user-facing error will
-            // come from the later cloneRepo which has the friendlier messaging.
+        const probeClone = runGit(['clone', '--depth=1', '--filter=blob:none', '--no-checkout', repoUrl, probeDir], { allowFailure: true, emitStderr: false });
+        if (!probeClone.success) {
+            // Clone failed. When git reports a recognizable access/auth failure
+            // (a private repo hidden as "not found", missing local credentials, a
+            // 403, etc.) fail FAST here — before createAsync — so we never create a
+            // server-side app the user can't clone (no orphan). For ambiguous or
+            // transient errors (server doesn't support --filter, network blip, a
+            // temp-fs hiccup, …) stay fail-OPEN and let the later cloneRepo surface
+            // the friendlier, fuller message.
+            const stderr = probeClone.stderr;
+            if (isGitCloneAccessFailure(stderr)) {
+                // Clean user-facing message; raw git detail kept on errorData for
+                // telemetry/debug. The probe clone is silent (stderr piped, not
+                // inherited), so we don't echo the confusing internal probe command.
+                throw new ConfigurationError(buildGitHubAccessPreflightErrorMessage(repoUrl), {
+                    underlyingError: getUnderlyingCloneError(probeClone.error, stderr),
+                });
+            }
             return;
         }
-        let lsTreeOutput;
-        try {
-            lsTreeOutput = execFileSync('git', ['-C', probeDir, 'ls-tree', '-r', 'HEAD'], {
-                stdio: ['ignore', 'pipe', 'ignore'],
-            }).toString();
-        }
-        catch {
+        const lsTree = runGit(['-C', probeDir, 'ls-tree', '-r', 'HEAD'], {
+            captureStdout: true,
+            allowFailure: true,
+            emitStderr: false,
+        });
+        if (!lsTree.success) {
             // Truly empty repo (no commits, no HEAD): ls-tree errors. Treat as empty
             // so create proceeds; cloneRepo of a no-commits remote produces an empty
             // working tree, which is the happy path.
             return;
         }
+        const lsTreeOutput = lsTree.stdout;
         if (lsTreeOutput.trim().length > 0) {
             // `ls-tree -r HEAD` enumerates every tracked path — including hidden
             // ones (.gitignore, .gitattributes, etc.). Any tracked file at all