@microsoft/managed-apps-cli 0.5.0 → 0.7.0

package/dist/Verbs/CreateMaafApp.js

@@ -1,9 +1,9 @@
 /*!
  * Copyright (C) Microsoft Corporation. All rights reserved.
  */
-import { createAsync, getPlayerServiceConfig, updateEnvironmentName, writeRepoConfig, } from '@microsoft/managed-apps-actions';
+import { authenticateForRepoAsync, createAsync, getPlayerServiceConfig, GrsServerError, updateEnvironmentName, writeRepoConfig, } from '@microsoft/managed-apps-actions';
 import { AppConfigFileName } from '@microsoft/managed-apps-common/config';
-import { getUserRoutingEnvironmentAsync, ManagedGovernanceError, ManagedGovernanceTimeoutError, pollRoutingEnvironmentAsync, } from '@microsoft/managed-apps-common/services';
+import { getUserRoutingEnvironmentAsync } from '@microsoft/managed-apps-common/services';
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import { downloadTemplate } from 'giget';
@@ -13,9 +13,13 @@ import { createDefaultStringOption } from '../CliUtils.js';
 import { CLI_CLIENT_ID } from '../Constants.js';
 import { CLI_BINARY_NAME } from '../Constants/CliConstants.js';
 import { HelpStrings } from '../Constants/HelpStrings.js';
-import { AppError, ConfigurationError, NotFoundError, UsageError } from '../Errors/CliError.js';
-import { printInfo, printJsonSuccess, printSuccess, printWarning } from '../Utils/ConsoleOutput.js';
+import { AppError, ConfigurationError, UsageError } from '../Errors/CliError.js';
+import { mapGitHubServerErrorToCliError, matchGitHubAuthError } from '../Errors/GitHubErrorMap.js';
+import { printInfo, printJsonLine, printJsonSuccess, printSuccess, printWarning, } from '../Utils/ConsoleOutput.js';
+import { resolveRoutingEnvironmentIdAsync } from '../Utils/EnvironmentRoutingUtils.js';
 import { buildGcmConfig } from '../Utils/GitCredentialConfig.js';
+import { ConsoleGitHubDcfDisplay, JsonGitHubDcfDisplay } from '../Utils/GitHubDcfFlow.js';
+import { computeRepoHash, parseGitHubRepoUrl } from '../Utils/RepoUrl.js';
 import { CreateMaafAppArguments } from './VerbConstants.js';
 const DEFAULT_TEMPLATE = 'github:microsoft/Managed-Apps/templates/vite8';
 /**
@@ -32,6 +36,10 @@ const REPO_NONE_SENTINEL = 'none';
  * - `none` (case-insensitive) → `none` (no GRS, no local setup)
  * - any other non-empty value → `github` (external GHE binding, 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 === '') {
@@ -42,6 +50,17 @@ export function parseRepoOption(rawRepoValue) {
     }
     return { repoType: 'github', remoteUrl: rawRepoValue };
 }
+/**
+ * Creates a new MAAF app and (where applicable) sets up local source control.
+ *
+ * Three repo flows, selected by `--repo`:
+ * - `native` (default): server auto-provisions a GRS repo; local clone happens via GCM.
+ * - `github`: external GHE Cloud binding. Clones the user's repo locally. On the first
+ *   `createAsync` call, a missing/expired server-side GitHub identity mapping is
+ *   recoverable in-band: a single inline DCF run + exactly one `createAsync` retry.
+ *   Any other error — or a second mapping failure after DCF — is a hard fail.
+ * - `none`: no git binding at all (just the server record + template + ms.config.json).
+ */
 export async function createMaafAppAsync(argumentProvider) {
     createOptionSchema(argumentProvider);
     await argumentProvider.runVerb();
@@ -60,13 +79,9 @@ export async function createMaafAppAsync(argumentProvider) {
     const appDir = argumentProvider.getPositionalArg(0) ?? process.cwd();
     const template = await argumentProvider.getOption('template', /* ignorePrompt */ true);
     // CLI surface is --repo. Three flows, decided up front so the rest of the verb can
-    // branch on `repoType` instead of inspecting `remoteUrl` everywhere:
-    //   - undefined       → native (GRS-backed; current default)
-    //   - 'none'          → no-source-control (skip GRS + skip every local setup step)
-    //   - any other value → github (external GHE binding; clone the URL locally)
-    // The local variable name `remoteUrl` is preserved on purpose: the wire contract to
-    // RP and the apps-actions param are still `remoteUrl` / `externalRepo.remoteUrl`, so
-    // renaming end-to-end is deferred until those callers move.
+    // branch on `repoType` instead of inspecting `remoteUrl` everywhere. RepoSelection
+    // is a flat interface (not a discriminated union), so we branch on `repoType` and
+    // assert `remoteUrl!` at github use sites where `string` is required.
     const rawRepoValue = await argumentProvider.getOption('repo', 
     /* ignorePrompt */ true);
     const { repoType, remoteUrl } = parseRepoOption(rawRepoValue);
@@ -97,20 +112,16 @@ export async function createMaafAppAsync(argumentProvider) {
     // local-setup failure leaves them orphaned with no clean recovery path.
     // Anything we can validate without hitting the server belongs here.
     //
-    // --repo path: still requires git installed, writable target, and an empty
-    // target (since `git clone` refuses non-empty destinations and we don't
-    // destructively wipe local files). Template-source validation is skipped —
-    // the template is overlaid onto the cloned working tree, but the same
-    // giget call validates the source. To bind a non-empty directory to a
-    // MAAF app, use `ms app init` instead.
+    // --repo path: requires git installed, writable target, and an empty target
+    // (since `git clone` refuses non-empty destinations and we don't destructively
+    // 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, no template — only ms.config.json
-    // gets written locally. The preflight reduces to (1) target dir must be
-    // writable so the config write later won't fail post-create, and (2) the
-    // dir must NOT already contain an ms.config.json (silently rebinding an
-    // existing config to a new app would be a footgun). Empty-dir is NOT
-    // required: the user opted out of scaffolding, so dropping an
-    // ms.config.json next to existing files is the intent.
+    // --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).
     // ──────────────────────────────────────────────────────────────────────────
     if (!jsonMode) {
         printInfo('Running preflight checks...');
@@ -122,30 +133,23 @@ export async function createMaafAppAsync(argumentProvider) {
         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.");
     }
-    // --repo none does not scaffold a template, so a user-supplied --template would be
-    // silently dropped. Reject up front rather than appear to honor it.
-    if (repoType === 'none' && template !== DEFAULT_TEMPLATE) {
-        throw new UsageError("'--template' is not supported with '--repo none' because no files are scaffolded. " +
-            "Remove '--template' or drop '--repo none' if you want template scaffolding.");
-    }
+    ensureTemplateSourceValid(template);
     if (repoType !== 'none') {
         ensureGitInstalled();
     }
-    if (repoType === 'native') {
-        ensureTemplateSourceValid(template);
-    }
     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);
-    }
-    else if (repoType === 'native') {
-        ensureTargetDirectoryEmpty(appDir);
+        // Validate --repo as a *.ghe.com URL before any network call. Throws
+        // UsageError ("not a valid GitHub Enterprise Cloud URL") for
+        // `github.com/...` and other non-GHE hosts, malformed URIs, etc. — mirrors
+        // `git auth refresh`'s up-front check.
+        parseGitHubRepoUrl(remoteUrl);
     }
     else {
-        // --repo none: empty-dir is intentionally not required. We still guard against
-        // overwriting an existing ms.config.json so the user can't silently rebind a
-        // pre-existing app folder to a brand-new server app.
-        ensureNoExistingConfig(appDir);
+        ensureTargetDirectoryEmpty(appDir);
     }
     // ─── End preflight ────────────────────────────────────────────────────────
     // The debug env-var override (MS_CLI_MAAF_DEBUG_ENVIRONMENT_ID) is honored by ArgumentProvider
@@ -170,6 +174,8 @@ export async function createMaafAppAsync(argumentProvider) {
     const buildPath = await argumentProvider.getOption('buildPath', /* ignorePrompt */ true);
     const buildCommand = await argumentProvider.getOption('buildCommand', 
     /* 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 !== undefined
@@ -186,33 +192,118 @@ export async function createMaafAppAsync(argumentProvider) {
     if (repoType === 'github') {
         ensureRepoTargetDirectoryEmpty(appDir);
     }
-    else if (repoType === 'native') {
-        ensureTargetDirectoryEmpty(appDir);
-    }
     else {
-        ensureNoExistingConfig(appDir);
+        ensureTargetDirectoryEmpty(appDir);
     }
-    const { app, cloneUrl } = await createAsync({
+    // Read --no-browser alongside --json so the recovery DCF helper has both
+    // inputs ready without a second async option read inside the catch block.
+    // Commander converts kebab-case flag names to camelCase property keys;
+    // the camelName constant keeps this lookup in sync with NoBrowser.name.
+    const noBrowser = (await argumentProvider.getOption(CreateMaafAppArguments.NoBrowser.camelName, 
+    /* ignorePrompt */ true)) ?? false;
+    // JSON mode (github flow only): emit a structured `create-validation` event
+    // right before the server call so automation parsing NDJSON sees the
+    // validation→createAsync boundary — needed because the github flow has a
+    // catch-and-retry branch where validation precedes a recoverable DCF.
+    // Gated to `github` so we don't change the NDJSON wire contract for
+    // existing `native` / `none` `--json` consumers.
+    if (jsonMode && repoType === 'github') {
+        printJsonLine({ phase: 'create-validation' });
+    }
+    // Hoisted so the first attempt and the post-DCF retry share the exact same
+    // action payload — no risk of the two calls drifting apart and no per-call
+    // object rebuild.
+    const actionsParams = {
+        displayName,
+        description,
+        repositoryId,
+        remoteUrl,
+        repoType,
+    };
+    const runCreate = () => createAsync({
         tenantId,
         environmentId,
         logger,
-        actionsParams: { displayName, description, repositoryId, remoteUrl, repoType },
+        actionsParams,
     });
-    // `--repo none` is the only path where the server intentionally returns no GRS clone
-    // URL (we asked for "no platform-managed repo"). The native and github flows both
-    // expect one: native uses it as origin for the first push; github uses it as the
-    // platform-managed build-artifact store backing the external GHE binding. Treat its
-    // absence on those flows as 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 !== 'none' && !cloneUrl) {
-        const recoveryHint = buildOrphanedAppRecoveryHint(app.id, app.environmentId);
-        if (repoType === 'github') {
-            throw new AppError(`App '${app.displayName}' was created and bound to ${remoteUrl}, but the ` +
-                `platform-managed git repository for build artifact storage was not provisioned. ` +
-                `This is a platform-side issue; please report it.\n` +
-                recoveryHint);
+    // Inline catch-and-retry for recoverable GitHub auth errors. On the github
+    // flow, a missing/expired GitHub identity mapping is recoverable in-band by
+    // running the DCF wrapper inline against
+    // the same GRS environment, then retrying createAsync exactly once. Any
+    // other recognized GrsServerError — on either the first attempt or the
+    // post-DCF retry — is mapped via mapGitHubServerErrorToCliError before
+    // being rethrown so the user sees a friendly CLI-typed error rather than
+    // the raw server payload. Any second mapping-missing/expired after DCF —
+    // and anything not recognized at all — escapes as a hard failure (single-retry
+    // contract; we never loop).
+    let createResult;
+    try {
+        createResult = await runCreate();
+    }
+    catch (err) {
+        if (repoType !== 'github')
+            throw err;
+        const matched = matchGitHubAuthError(err);
+        if (!matched) {
+            if (err instanceof GrsServerError) {
+                const mapped = mapGitHubServerErrorToCliError({
+                    code: err.code,
+                    message: err.message,
+                    status: err.status,
+                    details: err.details,
+                }, { repoUrl: remoteUrl, verb: 'app create' });
+                if (mapped)
+                    throw mapped;
+            }
+            throw err;
+        }
+        await runDcfRecoveryAsync({
+            remoteUrl: remoteUrl,
+            tenantId,
+            jsonMode,
+            noBrowser,
+            verb: 'app create',
+        });
+        try {
+            createResult = await runCreate();
         }
+        catch (retryErr) {
+            const remapped = matchGitHubAuthError(retryErr);
+            if (remapped) {
+                // Single-retry contract: a second mapping-missing/expired surfaces
+                // as a hard AuthenticationError with the standard remediation
+                // pointer. We deliberately do NOT loop DCF — repeated failures
+                // suggest the user can't complete the device-code flow (denied,
+                // wrong account, app uninstalled, etc.) and another loop would
+                // just hang.
+                const mapped = mapGitHubServerErrorToCliError(remapped.payload, {
+                    repoUrl: remoteUrl,
+                    verb: 'app create',
+                });
+                throw mapped ?? retryErr;
+            }
+            if (retryErr instanceof GrsServerError) {
+                const mapped = mapGitHubServerErrorToCliError({
+                    code: retryErr.code,
+                    message: retryErr.message,
+                    status: retryErr.status,
+                    details: retryErr.details,
+                }, { repoUrl: remoteUrl, verb: 'app create' });
+                if (mapped)
+                    throw mapped;
+            }
+            throw retryErr;
+        }
+    }
+    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 GHE 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. ` +
             `This is a platform-side issue; please report it. ` +
             `In the meantime, the partial app needs to be cleaned up.\n` +
@@ -225,7 +316,7 @@ export async function createMaafAppAsync(argumentProvider) {
     //             then overlay the template, then write ms.config.json.
     //   - github: clone the user's external repo, sanity-check it's empty,
     //             overlay the template, then write ms.config.json.
-    //   - none:   no git, no template — just mkdir -p and write ms.config.json.
+    //   - none:   no git, no clone — mkdir -p, overlay the template, write ms.config.json.
     try {
         if (repoType === 'github') {
             // External GitHub Enterprise path: clone the developer's repo. Auth flows through
@@ -253,35 +344,30 @@ export async function createMaafAppAsync(argumentProvider) {
             });
         }
         else {
-            // --repo none: the user opted out of all scaffolding. Just ensure the
-            // target dir exists so the writeRepoConfig call below can land
-            // ms.config.json next to whatever the user already has (or in a fresh
-            // empty dir). `mkdirSync(..., { recursive: true })` is a no-op if the
-            // directory already exists.
+            // --repo none: no git setup. Ensure the target dir exists so the
+            // subsequent downloadTemplate and writeRepoConfig calls can land their
+            // files. The preflight already verified the dir is empty.
             fs.mkdirSync(appDir, { recursive: true });
         }
-        // Overlay the template for the flows that scaffold one. `--repo none` opts out of
-        // scaffolding entirely, so this block is skipped and the user's existing files
-        // (if any) are left alone.
-        if (repoType !== 'none') {
-            if (!jsonMode) {
-                printInfo(`Fetching template '${template}' into ${appDir}...`);
-            }
-            await downloadTemplate(template, { dir: appDir, force: true });
+        if (!jsonMode) {
+            printInfo(`Fetching template '${template}' into ${appDir}...`);
         }
+        await downloadTemplate(template, { dir: appDir, force: true });
         const config = {
             appId: app.id,
             appDisplayName: app.displayName,
             description: app.description,
             environmentId: app.environmentId,
-            // `--repo none` apps have no platform-managed git binding; omit `repositoryId`
-            // from the persisted config so downstream verbs that key off it see the
-            // intentional absence rather than an empty/placeholder value.
-            ...(repoType !== 'none' && { repositoryId: app.repositoryId }),
+            // 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,
             cloud: argumentProvider.getCloud(),
             buildPath: buildPath ?? './dist',
             buildCommand: buildCommand ?? 'npm run build',
+            buildEntryPoint: buildEntryPoint ?? 'index.html',
         };
         await writeRepoConfig(path.join(appDir, AppConfigFileName), config);
     }
@@ -297,23 +383,23 @@ export async function createMaafAppAsync(argumentProvider) {
     if (jsonMode) {
         // `appId` is the bare GUID returned by the server (`MaafAppDefinition.id`) and
         // also written to ms.config.json — used by every subsequent CLI command
-        // (build, deploy, info, etc.). `gitRemoteUrl` is the GRS clone URL (auto-provisioned
-        // alongside the external binding for build artifact storage) and is omitted for
-        // `--repo none` since no platform-managed git repo exists. `externalRepoUrl` is the
-        // user-supplied GHE URL and only appears in the `github` flow. `repoType` is always
-        // emitted so automation can detect the new no-source-control path.
+        // (build, deploy, info, etc.). `gitRemoteUrl` is the GRS clone URL and is only
+        // present for the `native` flow (the only flow that auto-provisions a
+        // platform-managed git repo). `externalRepoUrl` is the user-supplied GHE URL and
+        // only appears in the `github` flow. `repoType` is always emitted so automation
+        // can detect which source-control mode the app was created in.
         printJsonSuccess({
             appId: app.id,
             repoType,
             ...(repoType === 'github' && remoteUrl && { externalRepoUrl: remoteUrl }),
-            ...(repoType !== 'none' && cloneUrl && { gitRemoteUrl: cloneUrl }),
+            ...(repoType === 'native' && cloneUrl && { gitRemoteUrl: cloneUrl }),
             appDir,
         });
     }
     else {
         printSuccess(`Created app '${app.displayName}' in ${appDir}.`);
         if (repoType === 'github') {
-            printInfo(`A platform-managed git repository was also provisioned for build artifact storage (clone URL: ${cloneUrl}).`);
+            printInfo(`Bound to external repository: ${remoteUrl}.`);
         }
         else if (repoType === 'none') {
             printInfo('Your app has been created. Run `git init` (or your VCS of choice) when ready; ' +
@@ -321,43 +407,6 @@ export async function createMaafAppAsync(argumentProvider) {
         }
     }
 }
-async function resolveRoutingEnvironmentIdAsync(resultPromise, httpClient, logger) {
-    // Translate routing-service errors into a UsageError so the user sees an actionable message
-    // rather than the raw "ManagedGovernance request failed with status 403" implementation detail.
-    // NotFoundError throws inside the try also flow through `toRoutingUsageError`, which leaves
-    // non-ManagedGovernance errors unchanged.
-    try {
-        const result = await resultPromise;
-        if (result.status === 200) {
-            const name = result.data.environment?.name;
-            if (!name) {
-                throw new NotFoundError('Routing service returned 200 with no environment name.');
-            }
-            return name;
-        }
-        // 202: provisioning is in progress — poll until it completes.
-        // Non-2xx responses are already thrown as ManagedGovernanceError inside
-        // getUserRoutingEnvironmentAsync, so only 200/202 reach this code path.
-        const routingResponse = await pollRoutingEnvironmentAsync(httpClient, result.pollingUrl, result.authResource, logger);
-        if (!routingResponse.environment?.name) {
-            throw new NotFoundError('Routing service finished provisioning but returned no environment name.');
-        }
-        return routingResponse.environment.name;
-    }
-    catch (err) {
-        throw toRoutingUsageError(err);
-    }
-}
-function toRoutingUsageError(err) {
-    if (err instanceof ManagedGovernanceError) {
-        return new UsageError(`Could not provision a Developer environment for your tenant (status ${err.status}). ` +
-            'Ensure your account has the required permissions to create a Developer environment.');
-    }
-    if (err instanceof ManagedGovernanceTimeoutError) {
-        return new UsageError('Timed out waiting for a Developer environment to provision. Try again.');
-    }
-    return err instanceof Error ? err : new Error(String(err));
-}
 /**
  * Clones the developer's external repo (GitHub Enterprise Cloud in v1) into `directory`.
  * Auth flows through the user's existing git credential setup — the CLI does not inject
@@ -590,19 +639,6 @@ export function ensureRepoTargetDirectoryEmpty(appDir) {
         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.`);
     }
 }
-export function ensureNoExistingConfig(appDir) {
-    // --repo none variant: empty-dir is not required, but we MUST refuse to overwrite an
-    // existing ms.config.json. Silently replacing it would rebind the folder (and any
-    // subsequent `ms app push/build/deploy` invocations) to a different server app — a
-    // footgun loud enough to gate fail-fast in preflight. Called twice (preflight +
-    // just-before-createAsync) for the same TOCTOU reasons as ensureTargetDirectoryEmpty.
-    const configPath = path.join(appDir, AppConfigFileName);
-    if (fs.existsSync(configPath)) {
-        throw new UsageError(`'${configPath}' already exists. --repo none refuses to overwrite an existing app config; ` +
-            `remove the file (or choose a different directory) before retrying, or run 'ms app init' ` +
-            `to bind this directory to a new app interactively.`);
-    }
-}
 export function ensureTargetDirectoryWritable(appDir) {
     // Probe write permission on the target dir (or its nearest existing
     // ancestor, where mkdirSync will need to write). Catches read-only mounts
@@ -634,6 +670,131 @@ export function ensureTargetDirectoryWritable(appDir) {
         throw new ConfigurationError(`'${appDir}' is not writable. Choose a different directory or fix the permissions and retry.`);
     }
 }
+/**
+ * Inline DCF recovery branch for the github catch-and-retry: only the
+ * `github` flow ever calls this — `native` and `none` have no GitHub identity
+ * mapping to refresh. SIGINT handling is scoped to this helper (registered
+ * and removed inside the `try/finally`) so Ctrl+C during the device-code
+ * polling loop doesn't leak a listener back to the verb's outer body. Server
+ * errors thrown by `authenticateForRepoAsync` are mapped through
+ * {@link mapGitHubServerErrorToCliError} before being rethrown so the verb's
+ * outer catch (and the single-retry contract) sees CLI-typed errors.
+ */
+async function runDcfRecoveryAsync(options) {
+    const { remoteUrl, tenantId, jsonMode, noBrowser, verb } = options;
+    // Re-parse here rather than threading the parsed components through every
+    // catch-and-retry call: preflight already validated the URL shape, so this
+    // is a cheap string-split on a rare path.
+    const { host, owner, repo } = parseGitHubRepoUrl(remoteUrl);
+    const repoHash = computeRepoHash(owner, repo);
+    const logger = getCliLogger();
+    // Telemetry: PII-safe — host is the parsed string, repoHash is a truncated
+    // SHA256. Emit Start at the top so a recovery that never reaches the retry
+    // (e.g. user denied auth) is still observable.
+    logger.trackActivityEvent('Maaf.Create.GitHubDcfRecovery', {
+        repoHost: host,
+        repoHash,
+    });
+    if (!jsonMode) {
+        printInfo('GitHub authentication is required to bind this repository.');
+    }
+    const display = composeRecoveryDisplay({ isJson: jsonMode, noBrowser });
+    // SIGINT plumbing: a Ctrl+C during the (potentially 15-minute) polling
+    // loop drops us out cleanly rather than leaving a dangling promise.
+    // Scoped to the recovery block only — createAsync itself doesn't take a
+    // signal yet.
+    const controller = new AbortController();
+    const onSigint = () => {
+        controller.abort();
+    };
+    process.once('SIGINT', onSigint);
+    try {
+        // The resolved auth result (githubLogin, mappingExpiresAt, etc.) is
+        // intentionally discarded: the retry path below doesn't need it — it
+        // just needs the server-side identity mapping to now exist so the next
+        // `createAsync` call clears the 401.
+        await authenticateForRepoAsync({
+            remoteUrl: `https://${host}/${owner}/${repo}`,
+            tenantId,
+            logger,
+            display,
+            // Browser launch is gated by the `display` object selected above:
+            // `composeRecoveryDisplay` returns a display whose `openVerificationUri`
+            // is undefined when `noBrowser` is true. `skipBrowser` here is the
+            // legacy lower-level kill-switch the action exposes; we hardcode it
+            // to false so the display contract is the single source of truth.
+            skipBrowser: false,
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        // Telemetry: pair the Start event with a Failed event on every error path
+        // so a recovery that throws (DCF declined, server error, abort) still
+        // shows up as a closed pair in the activity stream rather than an
+        // orphaned Start. Pattern A (emit Failed in the catch) — chosen over a
+        // success-flag-in-finally to keep the existing throw flow untouched and
+        // avoid restructuring the GrsServerError mapping branch below.
+        logger.trackActivityEvent('Maaf.Create.GitHubDcfRecovery.Failed', {
+            repoHost: host,
+            repoHash,
+        });
+        // Only GrsServerError carries a structured `code` we can translate to a
+        // CLI-typed AppError. Anything else (plain Error, network error, etc.)
+        // propagates as-is — the verb's outer flow treats it as a hard failure
+        // (no retry, no second "Resuming create...").
+        if (error instanceof GrsServerError) {
+            const mapped = mapGitHubServerErrorToCliError({
+                code: error.code,
+                message: error.message,
+                status: error.status,
+                details: error.details,
+            }, { repoUrl: remoteUrl, verb });
+            if (mapped)
+                throw mapped;
+        }
+        throw error;
+    }
+    finally {
+        // Safe in both branches: if SIGINT already fired, `process.once` has
+        // already auto-removed the listener and `removeListener` is a no-op.
+        process.removeListener('SIGINT', onSigint);
+    }
+    logger.trackActivityEvent('Maaf.Create.GitHubDcfRecovery.Complete', {
+        repoHost: host,
+        repoHash,
+    });
+    if (!jsonMode) {
+        // Printed here (before the helper returns) rather than at the retry
+        // call site so it's adjacent to the DCF-completed telemetry event. If
+        // the subsequent createAsync retry hard-fails, the user sees
+        // "Resuming create..." followed by the failure message — still accurate:
+        // we DID resume; the resumed call is what failed.
+        printInfo('Resuming create...');
+    }
+}
+/**
+ * Build the right {@link GitHubDcfDisplay} for the create recovery path:
+ * - JSON mode → NDJSON events, never opens a browser.
+ * - `--no-browser` → console output, browser launch suppressed.
+ * - Default → console output + best-effort browser launch (TTY-gated).
+ *
+ * Note the inverted default vs `git auth refresh`: in recovery the user has
+ * already started a destructive operation (create), so we lean toward
+ * launching a browser by default and require explicit opt-out, instead of
+ * the refresh verb's explicit opt-in.
+ */
+function composeRecoveryDisplay(opts) {
+    if (opts.isJson) {
+        return new JsonGitHubDcfDisplay();
+    }
+    if (opts.noBrowser) {
+        return {
+            ...ConsoleGitHubDcfDisplay,
+            openVerificationUri: undefined,
+        };
+    }
+    return ConsoleGitHubDcfDisplay;
+}
 function createOptionSchema(argumentProvider) {
     argumentProvider.setDescription(HelpStrings.app.create.description);
     argumentProvider.addExamples(HelpStrings.app.create.examples);
@@ -707,6 +868,20 @@ function createOptionSchema(argumentProvider) {
             default: 'npm run build',
             description: HelpStrings.app.create.options.buildCommand,
         }),
+        createDefaultStringOption({
+            flags: {
+                key: CreateMaafAppArguments.BuildEntryPoint.name,
+            },
+            env: CreateMaafAppArguments.BuildEntryPoint.envVar,
+            message: CreateMaafAppArguments.BuildEntryPoint.promptMessage,
+            initialValue: CreateMaafAppArguments.BuildEntryPoint.initialValue,
+            default: 'index.html',
+            description: HelpStrings.app.create.options.buildEntryPoint,
+        }),
     ]);
+    argumentProvider.addSwitch({
+        flags: { key: CreateMaafAppArguments.NoBrowser.name },
+        description: HelpStrings.app.create.options.noBrowser,
+    });
 }
 //# sourceMappingURL=CreateMaafApp.js.map