@microsoft/managed-apps-cli 0.5.0

package/dist/Verbs/CreateMaafApp.js

@@ -0,0 +1,712 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import { createAsync, getPlayerServiceConfig, 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 { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import { downloadTemplate } from 'giget';
+import * as path from 'path';
+import { getCliLogger } from '../CliSettings.js';
+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 { buildGcmConfig } from '../Utils/GitCredentialConfig.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 GHE binding, value flows through as
+ *   `remoteUrl` to the action and the eventual git clone)
+ */
+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 };
+}
+export async function createMaafAppAsync(argumentProvider) {
+    createOptionSchema(argumentProvider);
+    await argumentProvider.runVerb();
+    const tenantId = await argumentProvider.getTenantIdAsync();
+    if (!tenantId) {
+        throw new UsageError('Unable to determine tenant ID. Ensure you are logged in.');
+    }
+    const logger = getCliLogger();
+    const httpClient = argumentProvider.getHttpClient();
+    const { region } = getPlayerServiceConfig();
+    const displayName = await argumentProvider.getOption('displayName');
+    if (!displayName) {
+        throw new UsageError('Argument displayName is required. Use --display-name or -n to specify it.');
+    }
+    // The positional arg (or cwd) is both the git repo root and the app dir.
+    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.
+    const rawRepoValue = await argumentProvider.getOption('repo', 
+    /* ignorePrompt */ true);
+    const { repoType, remoteUrl } = parseRepoOption(rawRepoValue);
+    // Read --repository-id up front (instead of after preflight, like the other prompts)
+    // so the `--repo none` conflict check below has it. It is `optionalInNonInteractive`
+    // and registered with `ignorePrompt: true`, so reading early never triggers an
+    // interactive prompt.
+    const repositoryId = await argumentProvider.getOption('repositoryId', 
+    /* ignorePrompt */ true);
+    // --json emits a single machine-parseable envelope on stdout, so every
+    // informational `printInfo` below is gated behind `!jsonMode` to keep
+    // stdout free of prose ahead of the envelope. `printError` writes to
+    // stderr and is unaffected.
+    const jsonMode = argumentProvider.isJsonMode();
+    // Identity confirmation: print the tenant + region we're targeting before
+    // anything else — preflight, routing, createAsync — so a user with multiple
+    // accounts signed in has the longest possible window to CTRL-C before any
+    // local check runs or server call fires. Environment id isn't known yet
+    // (routing is what resolves it); included in the success line at the end.
+    // Wording is intentionally tentative ("About to create…") so a preflight
+    // failure on the next line doesn't read as contradicting a "Creating…" line.
+    if (!jsonMode) {
+        printInfo(`About to create app '${displayName}' in tenant ${tenantId} (region ${region}).`);
+    }
+    // ─── 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.
+    // 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 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.
+    // ──────────────────────────────────────────────────────────────────────────
+    if (!jsonMode) {
+        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.");
+    }
+    // --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.");
+    }
+    if (repoType !== 'none') {
+        ensureGitInstalled();
+    }
+    if (repoType === 'native') {
+        ensureTemplateSourceValid(template);
+    }
+    ensureTargetDirectoryWritable(appDir);
+    if (repoType === 'github') {
+        ensureRepoTargetDirectoryEmpty(appDir);
+    }
+    else if (repoType === 'native') {
+        ensureTargetDirectoryEmpty(appDir);
+    }
+    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);
+    }
+    // ─── End preflight ────────────────────────────────────────────────────────
+    // The debug env-var override (MS_CLI_MAAF_DEBUG_ENVIRONMENT_ID) is honored by ArgumentProvider
+    // and surfaced via getEnvironmentId(). When set, skip the routing API call entirely.
+    // For the supported user flow, getEnvironmentId() returns undefined here and routing fires.
+    const preResolvedEnvironmentId = argumentProvider.getEnvironmentId();
+    // Fire off PDE routing in parallel with the remaining option prompts. The result is awaited
+    // immediately before createAsync, so prompt latency is hidden behind the network call.
+    // Skipped entirely when the debug override pre-resolved the env id.
+    const routingEnvPromise = preResolvedEnvironmentId
+        ? undefined
+        : getUserRoutingEnvironmentAsync(httpClient, tenantId, CLI_CLIENT_ID, { provisionDataverse: false }, region, logger);
+    // If a later prompt throws before we await the promise, the rejection would otherwise be
+    // unhandled. Log and swallow here; `await routingEnvPromise` below still surfaces the error.
+    routingEnvPromise?.catch((error) => {
+        logger.trackErrorEvent('CreateMaafApp.RoutingEnvironmentBackgroundFailure', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+    const description = await argumentProvider.getOption('description', 
+    /* ignorePrompt */ true);
+    const buildPath = await argumentProvider.getOption('buildPath', /* ignorePrompt */ true);
+    const buildCommand = await argumentProvider.getOption('buildCommand', 
+    /* 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
+        ? preResolvedEnvironmentId
+        : await resolveRoutingEnvironmentIdAsync(routingEnvPromise, httpClient, logger);
+    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
+    // 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.
+    if (repoType === 'github') {
+        ensureRepoTargetDirectoryEmpty(appDir);
+    }
+    else if (repoType === 'native') {
+        ensureTargetDirectoryEmpty(appDir);
+    }
+    else {
+        ensureNoExistingConfig(appDir);
+    }
+    const { app, cloneUrl } = await createAsync({
+        tenantId,
+        environmentId,
+        logger,
+        actionsParams: { displayName, description, repositoryId, remoteUrl, repoType },
+    });
+    // `--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);
+        }
+        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` +
+            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.
+    //   - 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.
+    try {
+        if (repoType === 'github') {
+            // External GitHub Enterprise path: clone the developer's repo. Auth flows through
+            // the user's existing git credential setup (gh, GCM browser OAuth, SSH key, PAT,
+            // x509 client cert, etc.); the CLI does not inject any tokens at this layer (the
+            // Microsoft GitHub App is server-side only per the MAAF GitHub Integration design
+            // doc Requirement 1).
+            cloneRepo({ directory: appDir, repoUrl: remoteUrl });
+            // Post-clone sanity: --repo at P1 expects an empty GHE repo we can scaffold the
+            // template into. If the cloned working tree already has content (existing project,
+            // README, LICENSE, etc.), `ms app init` is the path that handles binding an existing
+            // project to a new MAAF app — bail with that pointer instead of overwriting files.
+            const workingTreeEntries = fs.readdirSync(appDir).filter((entry) => entry !== '.git');
+            if (workingTreeEntries.length > 0) {
+                throw new UsageError(`Repository ${remoteUrl} is not empty. Choose a different repository to create an app or run 'ms app init' to update the existing app.`);
+            }
+        }
+        else if (repoType === 'native') {
+            initLocalRepo({
+                directory: appDir,
+                gitUrl: cloneUrl,
+                loginAuthority: argumentProvider.getLoginAuthority(tenantId),
+                authResource: argumentProvider.getAuthResourceUrl(),
+                jsonMode,
+            });
+        }
+        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.
+            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 });
+        }
+        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 }),
+            repoType,
+            cloud: argumentProvider.getCloud(),
+            buildPath: buildPath ?? './dist',
+            buildCommand: buildCommand ?? 'npm run build',
+        };
+        await writeRepoConfig(path.join(appDir, AppConfigFileName), config);
+    }
+    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) {
+            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));
+    }
+    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.
+        printJsonSuccess({
+            appId: app.id,
+            repoType,
+            ...(repoType === 'github' && remoteUrl && { externalRepoUrl: remoteUrl }),
+            ...(repoType !== 'none' && 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}).`);
+        }
+        else if (repoType === 'none') {
+            printInfo('Your app has been created. Run `git init` (or your VCS of choice) when ready; ' +
+                'subsequent `ms app deploy` calls do not require a git remote.');
+        }
+    }
+}
+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
+ * 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.
+ *
+ * Targeting rules (mirrors `git clone` semantics):
+ *   - directory non-existent → clone creates it
+ *   - directory exists and is empty → clone fills it
+ *   - directory exists and is non-empty → clone fails (caller's pre-network guard
+ *     should reject this case earlier with a clearer message)
+ */
+export function cloneRepo({ directory, repoUrl }) {
+    try {
+        execFileSync('git', ['clone', repoUrl, directory], {
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+    }
+    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)}`);
+    }
+}
+export function initLocalRepo({ directory, gitUrl, loginAuthority, authResource, jsonMode = false, }) {
+    let gcmConfig;
+    try {
+        gcmConfig = buildGcmConfig({ gitUrl, loginAuthority, authResource });
+    }
+    catch (err) {
+        throw new ConfigurationError(`Git credential helper setup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    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.
+    for (const [key, value] of gcmConfig) {
+        execFileSync('git', ['config', '--local', key, value], {
+            cwd: directory,
+            stdio: ['ignore', 'ignore', 'inherit'],
+        });
+    }
+    // `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.
+    try {
+        execFileSync('git', ['remote', 'add', 'origin', gitUrl], {
+            cwd: directory,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+    }
+    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'],
+        });
+    }
+    // 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.
+    if (!jsonMode) {
+        printInfo(`Authenticating to ${new URL(gitUrl).host} for the initial git fetch. ` +
+            'A browser window may open. Sign in with the account associated with this tenant.');
+    }
+    execFileSync('git', ['fetch', 'origin'], {
+        cwd: directory,
+        stdio: ['ignore', 'ignore', 'inherit'],
+    });
+    // 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'],
+        });
+    }
+}
+// ─── 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)
+// strands them. Append this hint to the error message so the user can copy a
+// working `app delete --force` line straight from their terminal and retry.
+// ────────────────────────────────────────────────────────────────────────────
+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`);
+}
+// ─── 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.
+// ────────────────────────────────────────────────────────────────────────────
+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}:'?`);
+    }
+}
+export function ensureTargetDirectoryEmpty(appDir) {
+    // Scaffolding into a non-empty directory would mix the template with the
+    // user's files, and initLocalRepo's `git remote set-url` fallback would
+    // silently replace an existing `origin` remote. Called twice: once in
+    // preflight (fail fast before any network) and once right before
+    // createAsync (catch a TOCTOU race where the dir gets populated during
+    // routing/option resolution).
+    if (!fs.existsSync(appDir))
+        return;
+    const entries = fs.readdirSync(appDir);
+    if (entries.length > 0) {
+        throw new UsageError(`'${appDir}' is not empty. Specify an empty directory as the first argument, or run 'ms app init' to bind an existing project to a new app.`);
+    }
+}
+export function ensureRepoTargetDirectoryEmpty(appDir) {
+    // --repo variant: empty-dir is mandatory. `git clone` refuses non-empty
+    // destinations and we don't destructively wipe local files. To bind an
+    // existing local project to a new MAAF app, use `ms app init` instead.
+    // Called twice (preflight + just-before-createAsync) for the same TOCTOU
+    // reasons as ensureTargetDirectoryEmpty.
+    if (!fs.existsSync(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.`);
+    }
+}
+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
+    // and permission-denied locations before any server-side resource is
+    // created. The empty-dir check is intentionally NOT here — it runs inline
+    // just before initLocalRepo so the TOCTOU window between check and write
+    // stays as small as possible (a directory can become non-empty while the
+    // routing/createAsync calls are in flight).
+    //
+    // Best-effort caveat: `accessSync(W_OK)` is a syscall-level approximation,
+    // not a real write. On Windows in particular, NTFS ACL inheritance can grant
+    // W_OK on the ancestor while the actual CreateDirectory / CreateFile fails
+    // later (UAC virtualization, parent ACE applies but a deny ACE on the leaf
+    // does not). We accept that: catching every Windows ACL edge case requires
+    // a real mkdir+write+delete probe, which leaves debris on success and has
+    // its own TOCTOU. The recovery hint on post-create failures is the
+    // backstop when the probe is too optimistic.
+    let probe = appDir;
+    while (!fs.existsSync(probe)) {
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break;
+        probe = parent;
+    }
+    try {
+        fs.accessSync(probe, fs.constants.W_OK);
+    }
+    catch {
+        throw new ConfigurationError(`'${appDir}' is not writable. Choose a different directory or fix the permissions and retry.`);
+    }
+}
+function createOptionSchema(argumentProvider) {
+    argumentProvider.setDescription(HelpStrings.app.create.description);
+    argumentProvider.addExamples(HelpStrings.app.create.examples);
+    argumentProvider.consumePositionalArg('[directory]');
+    argumentProvider.addOptions([
+        createDefaultStringOption({
+            flags: {
+                key: CreateMaafAppArguments.DisplayName.name,
+                alias: CreateMaafAppArguments.DisplayName.alias,
+            },
+            env: CreateMaafAppArguments.DisplayName.envVar,
+            message: CreateMaafAppArguments.DisplayName.promptMessage,
+            description: HelpStrings.app.create.options.displayName,
+        }),
+        {
+            flags: {
+                key: CreateMaafAppArguments.Description.name,
+                alias: CreateMaafAppArguments.Description.alias,
+            },
+            env: CreateMaafAppArguments.Description.envVar,
+            description: HelpStrings.app.create.options.description,
+            optionalInNonInteractive: true,
+        },
+        {
+            flags: {
+                key: CreateMaafAppArguments.RepositoryId.name,
+                alias: CreateMaafAppArguments.RepositoryId.alias,
+            },
+            env: CreateMaafAppArguments.RepositoryId.envVar,
+            description: HelpStrings.app.create.options.repositoryId,
+            optionalInNonInteractive: true,
+        },
+        {
+            flags: {
+                key: CreateMaafAppArguments.Template.name,
+                alias: CreateMaafAppArguments.Template.alias,
+            },
+            env: CreateMaafAppArguments.Template.envVar,
+            default: DEFAULT_TEMPLATE,
+            description: HelpStrings.app.create.options.template,
+            optionalInNonInteractive: true,
+        },
+        {
+            // No short alias for --repo yet; see VerbConstants.CreateMaafAppArguments.Repo.
+            flags: {
+                key: CreateMaafAppArguments.Repo.name,
+            },
+            env: CreateMaafAppArguments.Repo.envVar,
+            description: HelpStrings.app.create.options.repo,
+            optionalInNonInteractive: true,
+        },
+        createDefaultStringOption({
+            flags: {
+                key: CreateMaafAppArguments.BuildPath.name,
+                alias: CreateMaafAppArguments.BuildPath.alias,
+            },
+            env: CreateMaafAppArguments.BuildPath.envVar,
+            message: CreateMaafAppArguments.BuildPath.promptMessage,
+            initialValue: CreateMaafAppArguments.BuildPath.initialValue,
+            default: './dist',
+            description: HelpStrings.app.create.options.buildPath,
+        }),
+        createDefaultStringOption({
+            flags: {
+                key: CreateMaafAppArguments.BuildCommand.name,
+                alias: CreateMaafAppArguments.BuildCommand.alias,
+            },
+            env: CreateMaafAppArguments.BuildCommand.envVar,
+            message: CreateMaafAppArguments.BuildCommand.promptMessage,
+            initialValue: CreateMaafAppArguments.BuildCommand.initialValue,
+            default: 'npm run build',
+            description: HelpStrings.app.create.options.buildCommand,
+        }),
+    ]);
+}
+//# sourceMappingURL=CreateMaafApp.js.map