@microsoft/managed-apps-cli 0.13.0 → 0.16.0

package/dist/Verbs/CreateMaafApp.js

@@ -3,7 +3,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 { HttpClientError, regionToCloudSafe } from '@microsoft/managed-apps-common/services';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -11,7 +11,7 @@ import { getCliLogger, getSettings } from '../CliSettings.js';
 import { createDefaultStringOption, resolveEnvironmentId } from '../CliUtils.js';
 import { CLI_BINARY_NAME } from '../Constants/CliConstants.js';
 import { HelpStrings } from '../Constants/HelpStrings.js';
-import { AppError, ConfigurationError, UsageError } from '../Errors/CliError.js';
+import { AppError, AuthenticationError, ConfigurationError, NetworkError, UsageError, } from '../Errors/CliError.js';
 import { printInfo, printJsonLine, printJsonSuccess, printSuccess, printWarning, } from '../Utils/ConsoleOutput.js';
 import { withGitHubDcfRecoveryAsync } from '../Utils/DcfRecovery.js';
 import { downloadTemplate, parseGithubTemplate } from '../Utils/DownloadTemplate.js';
@@ -25,6 +25,9 @@ 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';
+/** Commit message for the initial scaffold, shared by the auto-push and every
+ * manual-recovery hint */
+const SCAFFOLD_COMMIT_MESSAGE = "Initial scaffold from 'ms app create'";
 /**
  * Creates a new MAAF app and (where applicable) sets up local source control.
  *
@@ -93,7 +96,7 @@ export async function createMaafAppAsync(argumentProvider) {
     // ─── Preflight ────────────────────────────────────────────────────────────
     // Run all local-only checks before any server call. Once createAsync
     // succeeds the user has a MAAF app + GRS repo on the server; a later
-    // local-setup failure leaves them orphaned with no clean recovery path.
+    // local-setup failure leaves them with created resources that need recovery.
     // Anything we can validate without hitting the server belongs here.
     //
     // --repo path: requires git installed, writable target, and an empty target
@@ -139,7 +142,7 @@ export async function createMaafAppAsync(argumentProvider) {
             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
+            // without leaving a 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
@@ -188,8 +191,8 @@ export async function createMaafAppAsync(argumentProvider) {
     // now is async and may take seconds — long enough for the user (or another
     // tool) to drop a file (or ms.config.json) into appDir. Repeating the check
     // here keeps the TOCTOU window between "directory looks fine" and
-    // "createAsync succeeded" as small as possible without ever orphaning a
-    // server-side app.
+    // "createAsync succeeded" as small as possible without creating a server-side
+    // app before local invariants are verified.
     if (repoType === 'github') {
         ensureRepoTargetDirectoryEmpty(appDir);
     }
@@ -240,21 +243,36 @@ export async function createMaafAppAsync(argumentProvider) {
     // DCF and retrying once; any other recognized server error is mapped to a
     // friendly CLI error. Non-github flows pass through untouched. See
     // `withGitHubDcfRecoveryAsync` for the full contract.
-    const createResult = await withGitHubDcfRecoveryAsync(runCreate, {
-        repoType,
-        externalRepoUrl: remoteUrl,
-        tenantId,
-        jsonMode,
-        openBrowser,
-        verb: 'app create',
-    });
+    //
+    // Any server error that escapes the DCF wrapper (all repo types) is routed
+    // through `translateCreateError`, which keys off the HTTP status code to
+    // surface an actionable message (e.g. a 403 becomes a permission error naming
+    // the environment) instead of the raw `HTTP error status: ...` blob from the RP.
+    let createResult;
+    try {
+        createResult = await withGitHubDcfRecoveryAsync(runCreate, {
+            repoType,
+            externalRepoUrl: remoteUrl,
+            tenantId,
+            jsonMode,
+            openBrowser,
+            verb: 'app create',
+        });
+    }
+    catch (createError) {
+        const translated = translateCreateError(createError, { repoType, environmentId });
+        if (translated)
+            throw translated;
+        throw createError;
+    }
     const { app, cloneUrl } = createResult;
     // Only the `native` flow expects a GRS clone URL — it's the origin for the first
-    // local push to the auto-provisioned platform-managed repo. `github` binds an
-    // external GitHub repo (no GRS) and `none` is by-design source-control-free, so neither
-    // produces a `cloneUrl`. Missing on `native` is a server bug — the hoisted check
-    // below guards both the pretty-output `(clone URL: undefined)` and JSON-envelope
-    // `gitRemoteUrl: undefined` failure modes that would otherwise leak through.
+    // local push to the auto-provisioned platform-managed repo, which GRS seeds with
+    // an initial commit on `main`. `github` binds an external GitHub repo (no GRS)
+    // and `none` is by-design source-control-free, so neither produces a `cloneUrl`.
+    // Missing on `native` is a server bug — the hoisted check below guards both the
+    // pretty-output `(clone URL: undefined)` and JSON-envelope `gitRemoteUrl: undefined`
+    // failure modes that would otherwise leak through.
     if (repoType === 'native' && !cloneUrl) {
         const recoveryHint = buildOrphanedAppRecoveryHint(app.id, app.environmentId);
         throw new AppError(`App '${app.displayName}' was created on the server, but creating a git repository failed. ` +
@@ -263,10 +281,11 @@ export async function createMaafAppAsync(argumentProvider) {
             recoveryHint);
     }
     // Set up local files. Runs after the API calls succeed; if any step here
-    // fails the server app is already created and the recovery hint below tells
-    // the user how to clean it up. The branch per `repoType`:
-    //   - native: init local git repo against the auto-provisioned GRS clone URL,
-    //             then overlay the template, then write ms.config.json.
+    // fails the server app is already created. The branch per `repoType`:
+    //   - native: init local git repo + GCM config for the auto-provisioned GRS
+    //             repo (seeded with an initial commit on `main`), overlay the
+    //             template, then write ms.config.json. The push phase reconciles
+    //             the scaffold onto that seeded history before pushing.
     //   - github: clone the user's external repo, sanity-check it's empty,
     //             overlay the template, then write ms.config.json.
     //   - none:   no git, no clone — mkdir -p, overlay the template, write ms.config.json.
@@ -302,7 +321,6 @@ export async function createMaafAppAsync(argumentProvider) {
                 gitUrl: cloneUrl,
                 loginAuthority: argumentProvider.getLoginAuthority(tenantId),
                 authResource: argumentProvider.getAuthResourceUrl(),
-                jsonMode,
             });
         }
         else {
@@ -315,12 +333,13 @@ export async function createMaafAppAsync(argumentProvider) {
             printInfo(`Fetching template '${template}' into ${appDir}...`);
         }
         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);
+        // Pin the CLI into the app so a later package install provides a project-local
+        // `ms` — resolved by `npx ms` / `pnpm exec` / `bun x` ahead of any globally-
+        // installed CLI — at the version it was created with (or the latest published
+        // version for a prerelease build). Runs for every repo flow (the template, and
+        // therefore its package.json, lands via downloadTemplate above regardless of
+        // `--repo`).
+        await pinCliIntoAppPackageJson(appDir, jsonMode, argumentProvider.getHttpClient());
         const config = buildMaafAppConfig({
             appId: app.id,
             appDisplayName: app.displayName,
@@ -346,31 +365,24 @@ export async function createMaafAppAsync(argumentProvider) {
         // has no remote, so it's skipped. Push failure is non-fatal — see the warning
         // path in commitAndPushScaffoldAsync.
         if (repoType !== 'none') {
-            // 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);
+            pushOutcome = await commitAndPushScaffoldAsync(appDir, jsonMode, repoType === 'native' ? cloneUrl : undefined);
         }
     }
     catch (setupError) {
         // UsageError carries already-actionable messages (e.g. "repo already contains an
-        // app — try ms app init"). Let those through unwrapped so the user sees the
-        // intended phrasing instead of the generic "local setup failed" prefix.
-        if (setupError instanceof UsageError) {
+        // app — try ms app init") and, for the non-native flows that raise it, its own
+        // recovery hint. Let those through unwrapped. The native flow has already created
+        // the server app + repo by the time any setup step throws, so it always routes
+        // through the generic re-messaging below to surface the cleanup hint.
+        if (setupError instanceof UsageError && repoType !== 'native') {
             throw setupError;
         }
         const detail = setupError instanceof Error ? setupError.message : String(setupError);
         const message = `App '${app.displayName}' was created, but local setup failed: ${detail}\n` +
+            `The local directory ${appDir} may contain partial files; remove them or choose a new directory before retrying.\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
+        // failure category survives the setup-recovery 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
@@ -422,31 +434,41 @@ export async function createMaafAppAsync(argumentProvider) {
  * 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.
+ * flow, `network: true`) or pipes it for classification (native flow) — either
+ * way git's own error context reaches the user alongside our warning. A
+ * classified push error is caught here, so 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 via runGit's stderr handling.
  */
-export async function commitAndPushScaffoldAsync(appDir, jsonMode, pushClassify) {
+export async function commitAndPushScaffoldAsync(appDir, jsonMode, nativeGitUrl) {
     // 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
     // idempotent: rerunning `git add .` and `git commit` on an already-committed
     // state either no-ops or errors with "nothing to commit", in which case
     // `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`;
+    //
+    // Native (GRS) has no safe one-line recovery: the failure could be at the
+    // fetch/reconcile step (scaffold not yet re-parented onto the seeded main) or
+    // at the final push (already re-parented), and a single copy-paste command
+    // can't be correct for both. So we surface no command for native and instead
+    // point the user at the local scaffold below.
+    const retryCommand = nativeGitUrl
+        ? undefined
+        : `git add . && git commit -m "${SCAFFOLD_COMMIT_MESSAGE}" && git push -u origin HEAD`;
     try {
         runGit(['add', '.'], { cwd: appDir });
-        runGit(['commit', '-m', "Initial scaffold from 'ms app create'"], { cwd: appDir });
+        runGit(['commit', '-m', SCAFFOLD_COMMIT_MESSAGE], { cwd: appDir });
+        if (nativeGitUrl) {
+            reconcileNativeScaffoldWithSeededMain(appDir, nativeGitUrl, jsonMode);
+        }
         runGit(['push', '-u', 'origin', 'HEAD'], {
             cwd: appDir,
             network: true,
-            classify: pushClassify,
+            classify: nativeGitUrl ? { action: `pushing to ${gitHostLabel(nativeGitUrl)}` } : undefined,
         });
         return { success: true };
     }
@@ -464,18 +486,68 @@ export async function commitAndPushScaffoldAsync(appDir, jsonMode, pushClassify)
             // 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
+            // generic 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);
             }
+            const finishHint = retryCommand
+                ? `To finish wiring it up, run:\n    ${retryCommand}`
+                : `Resolve the git issue above, then finish the initial push from ${appDir}.`;
             printWarning(`Could not commit and push the initial scaffold. Your app and local scaffold are ready. ` +
-                `To finish wiring it up, run:\n    ${retryCommand}`);
+                finishHint);
         }
         return { success: false, error: errorPayload, retryCommand };
     }
 }
+/**
+ * Reconciles the freshly committed local scaffold with the platform-seeded
+ * `main` branch just before the native (GRS) push. GRS provisions the repo
+ * with an initial commit on `main` (a README).
+ *
+ *   1. `git fetch origin`            — bring the seed commit into origin/main
+ *                                       (retried once on a transient auth miss).
+ *   2. `git reset --soft origin/main` — move HEAD onto the seed while keeping the
+ *                                       scaffold tree fully staged.
+ *   3. `git commit`                  — record the scaffold as a child of the seed.
+ */
+function reconcileNativeScaffoldWithSeededMain(appDir, gitUrl, jsonMode) {
+    announceGitAuthentication(gitUrl, jsonMode, 'the initial git fetch and push');
+    fetchOriginWithRetry(appDir, gitUrl);
+    const seededMain = runGit(['rev-parse', '--verify', 'origin/main'], {
+        cwd: appDir,
+        allowFailure: true,
+        emitStderr: false,
+    });
+    if (!seededMain.success) {
+        return;
+    }
+    runGit(['reset', '--soft', 'origin/main'], { cwd: appDir });
+    runGit(['commit', '-m', SCAFFOLD_COMMIT_MESSAGE], { cwd: appDir });
+}
+/**
+ * Fetches `origin`, retrying exactly once if the first attempt fails.
+ *
+ * The first attempt is silent (`allowFailure`, stderr piped-not-emitted) so a
+ * recoverable miss produces no scary output.
+ */
+function fetchOriginWithRetry(appDir, gitUrl) {
+    const firstAttempt = runGit(['fetch', 'origin'], {
+        cwd: appDir,
+        network: true,
+        allowFailure: true,
+        emitStderr: false,
+    });
+    if (firstAttempt.success) {
+        return;
+    }
+    runGit(['fetch', 'origin'], {
+        cwd: appDir,
+        network: true,
+        classify: { action: `fetching from ${gitHostLabel(gitUrl)}` },
+    });
+}
 const GIT_CLONE_ACCESS_FAILURE_SIGNATURES = [
     'repository not found',
     'fatal: repository',
@@ -527,7 +599,7 @@ 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).
+// lead makes explicit that nothing was created (no cleanup / no recovery hint).
 function buildGitHubAccessPreflightErrorMessage(repoUrl) {
     return (`Cannot access repository '${repoUrl}', so no app was created. ` + gitHubAccessFailureGuidance());
 }
@@ -574,14 +646,11 @@ export function cloneRepo({ directory, repoUrl }) {
         });
     }
 }
-export function initLocalRepo({ directory, gitUrl, loginAuthority, authResource, jsonMode = false, }) {
+export function initLocalRepo({ directory, gitUrl, loginAuthority, authResource, }) {
     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
@@ -596,12 +665,19 @@ function buildGcmConfigOrThrow({ gitUrl, loginAuthority, authResource, }) {
         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. */
+/**
+ * Creates the target directory (idempotent) and initializes an empty git repo
+ * whose initial branch is `main`.
+ */
 function gitInit(directory) {
     fs.mkdirSync(directory, { recursive: true });
     runGit(['init'], { cwd: directory });
+    // use `git symbolic-ref HEAD refs/heads/main` to set the initial branch to `main` instead of `master`. This is
+    // used instead of `git init -b main` / `-c init.defaultBranch=main` because both
+    // of those landed in git 2.28, one minor above this package's enforced 2.27 floor
+    runGit(['symbolic-ref', 'HEAD', 'refs/heads/main'], { cwd: directory });
 }
-/** Writes GCM config before fetching so the first network call is already authenticated. */
+/** Writes GCM config before pushing so the first network call is already authenticated. */
 function writeGcmConfig(directory, gcmConfig) {
     for (const [key, value] of gcmConfig) {
         runGit(['config', '--local', key, value], { cwd: directory });
@@ -633,7 +709,7 @@ function addOrUpdateRemote(directory, gitUrl) {
 /**
  * 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
+ * action labels (auth/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.
@@ -647,43 +723,19 @@ function gitHostLabel(gitUrl) {
     }
 }
 /**
- * Prints the pre-fetch authentication notice. The first `git fetch` triggers
+ * Prints the pre-network authentication notice. The first git network call 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) {
+function announceGitAuthentication(gitUrl, jsonMode, action) {
     if (!jsonMode) {
-        printInfo(`Authenticating to ${gitHostLabel(gitUrl)} for the initial git fetch. ` +
+        printInfo(`Authenticating to ${gitHostLabel(gitUrl)} for ${action}. ` +
             'A browser window may open. Sign in with the account associated with this tenant.');
     }
 }
-/** Fetches `origin`, classifying any auth/network failure against the remote host. */
-function fetchOrigin(directory, gitUrl) {
-    runGit(['fetch', 'origin'], {
-        cwd: directory,
-        network: true,
-        classify: { action: `fetching from ${gitHostLabel(gitUrl)}` },
-    });
-}
-/**
- * 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 ─────────────────────────────────
 // Once createAsync returns, the MAAF app + GRS repo exist on the server; any
 // later failure (no gitUrl, initLocalRepo, downloadTemplate, writeRepoConfig)
@@ -695,10 +747,86 @@ export function buildOrphanedAppRecoveryHint(serverAppId, environmentId) {
         `If you want to clean it up before retrying, run the following command:\n` +
         `  ${CLI_BINARY_NAME} app delete --app ${serverAppId} --environment-id ${environmentId} --force`);
 }
+/** Extracts `error.message` from a JSON `{ error: { message } }` envelope; `undefined` otherwise. */
+function extractServerMessage(err) {
+    if (!err.body)
+        return undefined;
+    try {
+        const parsed = JSON.parse(err.body);
+        if (typeof parsed?.error?.message === 'string' && parsed.error.message.trim()) {
+            return parsed.error.message;
+        }
+    }
+    catch {
+        // not JSON; fall through
+    }
+    return undefined;
+}
+/**
+ * Translates a server error thrown while creating the app (the `createAsync`
+ * RP/GRS calls) into a user-facing {@link AppError}, or returns `null` to signal
+ * "not handled — propagate the original". For the handled status codes below we
+ * key off the HTTP status to pick the error category (which drives the exit code)
+ * and surface an actionable message rather than the raw HTTP error blob
+ * (`HTTP error status: 403 for POST ...: {...}`). Unrecognized statuses (e.g. 500)
+ * return `null` and propagate unchanged, so the raw error can still surface for
+ * those — we only suppress the blob for the statuses we explicitly handle.
+ *
+ * The RP returns a structured `{ error: { code, message } }` envelope whose
+ * `message` is the source of truth — it names the offending principal and
+ * environment (e.g. "User '<oid>' does not have permission to create
+ * repositories in environment '<id>'."). We prefer that server message and fall
+ * back to CLI-generated text only when the body carries no usable message.
+ *
+ * Only translates {@link HttpClientError}. Errors already mapped to a typed
+ * {@link AppError} by the GitHub DCF recovery path (see `withGitHubDcfRecoveryAsync`)
+ * are passed through untouched.
+ */
+function translateCreateError(err, ctx) {
+    if (!(err instanceof HttpClientError))
+        return null;
+    const { environmentId } = ctx;
+    // Prefer the RP's own `error.message` — it's the source of truth and carries
+    // specifics (principal object id, environment id) the CLI can't reconstruct.
+    const serverMessage = extractServerMessage(err);
+    // The `native` (default) flow auto-provisions a platform-managed GRS repository,
+    // so a permission failure there is specifically about repository creation. The
+    // `github` / `none` flows don't provision a repo, so the denial is about creating
+    // the app itself. Used only for the fallback wording when the RP sends no message.
+    const creatingRepo = ctx.repoType === 'native';
+    // Operation-agnostic so it reads correctly whether it's appended to the RP's
+    // "...create repositories..." message, the "...create an app..." fallback, or
+    // the native/github variants — avoids a "repositories" vs "apps" mismatch.
+    const grantHint = 'Ask an admin to grant you the required permission in this environment.';
+    if (err.status === 401) {
+        return new AuthenticationError(serverMessage ??
+            'Your sign-in session has expired or is invalid. Run `ms auth login` and try again.');
+    }
+    if (err.status === 403) {
+        const base = serverMessage ??
+            (creatingRepo
+                ? `You do not have permission to create repositories in environment ${environmentId}.`
+                : `You do not have permission to create an app in environment ${environmentId}.`);
+        return new AuthenticationError(`${base} ${grantHint}`);
+    }
+    if (err.status === 404) {
+        return new UsageError(serverMessage ??
+            `Environment ${environmentId} was not found. Verify the environment id and that you have access to it.`);
+    }
+    if (err.status === 409) {
+        return new UsageError(serverMessage ??
+            `An app with the same name already exists in environment ${environmentId}. Choose a different name.`);
+    }
+    if (err.status === 429 || err.status === 503) {
+        return new NetworkError(serverMessage ??
+            'The service is temporarily unavailable or rate-limited. Wait a moment and try again.');
+    }
+    return null;
+}
 // ─── Preflight helpers ──────────────────────────────────────────────────────
 // All checks below run before any server call so a local misconfiguration
-// (bad template source, unwritable directory, …) fails fast and never leaves
-// an orphaned MAAF app + GRS repo on the server. The git presence + version
+// (bad template source, unwritable directory, …) fails fast before it creates
+// a MAAF app + GRS repo on the server. The git presence + version
 // check lives in `Utils/GitVersionChecker.ts`.
 // ────────────────────────────────────────────────────────────────────────────
 export function ensureTemplateSourceValid(source) {
@@ -747,13 +875,13 @@ export function ensureRepoTargetDirectoryEmpty(appDir) {
  *
  * 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.
+ *     "ms app init" actionable lead, BEFORE createAsync. Nothing created.
  *   - Empty tree (incl. the cleaned-up-repo edge case: commit1 add, commit2
  *     delete all) → ls-tree returns no lines → returns without throwing.
  *   - 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).
+ *     app the user can't clone.
  *   - 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;
@@ -775,7 +903,7 @@ export function ensureExternalRepoIsEmpty(repoUrl) {
             // 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
+            // server-side app the user can't clone. 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.