gt 2.22.4 → 2.23.0

package/dist/cli/base.js

@@ -1,26 +1,28 @@
 import { logger } from "../console/logger.js";
 import { isPackageInstalled, searchForPackageJson } from "../utils/packageJson.js";
-import { DEFAULT_TRANSLATIONS_DIR, DEFAULT_VITE_TRANSLATIONS_DIR } from "../utils/constants.js";
+import "../utils/constants.js";
 import { parseGlobPatterns } from "../console/promptParsing.js";
 import { INLINE_LIBRARIES } from "../types/libraries.js";
 import { displayHeader, exitSync, logErrorAndExit, promptConfirm, promptGlobPatterns, promptMultiSelect, promptSelect, promptText } from "../console/logging.js";
 import findFilepath from "../fs/findFilepath.js";
 import { lottieTranslateError } from "../console/index.js";
-import { loadConfig } from "../fs/config/loadConfig.js";
-import { FILE_EXT_TO_EXT_LABEL } from "../formats/files/supportedFiles.js";
-import { UserAuthError } from "../auth/errors.js";
-import { hasLogin, login, logout, whoAmI } from "../auth/oauth.js";
+import { loadConfig, withJsonExtension } from "../fs/config/loadConfig.js";
+import { FILE_EXT_TO_EXT_LABEL, SETUP_FILE_FORMATS, SUPPORTED_FILE_EXTENSIONS } from "../formats/files/supportedFiles.js";
+import { resolveProjectId } from "../fs/utils.js";
+import { UserAuthError, createUserAuthError } from "../auth/errors.js";
+import { hasLogin, logout, whoAmI } from "../auth/oauth.js";
 import { resolveConfig } from "../config/resolveConfig.js";
 import { api } from "../utils/api.js";
 import { generateSettings } from "../config/generateSettings.js";
-import { createOrUpdateConfig } from "../fs/config/setupConfig.js";
-import { getPackageManager } from "../utils/packageManager.js";
-import { installPackage } from "../utils/installPackage.js";
-import { getFrameworkDisplayName, getReactFrameworkLibrary } from "../setup/frameworkUtils.js";
-import { handleSetupReactCommand } from "../setup/wizard.js";
+import { createOrUpdateConfig, mergeSetupConfig } from "../fs/config/setupConfig.js";
+import { executeReactSetup, resolveReactSetup } from "../setup/wizard.js";
 import { getDesiredLocales } from "../setup/userInput.js";
-import { areCredentialsSet } from "../utils/credentials.js";
-import { provisionDevelopmentCredentials } from "../setup/developmentCredentials.js";
+import { areCredentialsSet, getDevelopmentEnvNames, inspectCredentialsEnvFile } from "../utils/credentials.js";
+import { loginInteractively } from "../auth/interactiveLogin.js";
+import { getBuildToolSetup } from "../setup/buildTools/index.js";
+import { INIT_SOURCE_HELP, OnboardingError, asRecord, attachConfigureFlags, attachInitFlags, describeDefaults, displaySetupHeader, getConfiguredFramework, installWithProgress, parseFilePatterns, readSetupConfig, reportJsonExitsBeforeOnboarding, resolvePackageManager, runOnboarding, setupConfigPath, validateSetupPattern } from "../setup/onboarding.js";
+import { checkDevelopmentProjectInputs, productionRuntimeKeyGuidance, provisionDevelopmentCredentials, resolveDevelopmentProject, signInForSetup } from "../setup/developmentCredentials.js";
+import { exitIfUnsupportedSetupTarget } from "../setup/setupTarget.js";
 import { clearWarnings } from "../state/translateWarnings.js";
 import { hasValidCredentials, hasValidServiceLocales } from "./commands/utils/validation.js";
 import { upload } from "./commands/upload.js";
@@ -32,7 +34,7 @@ import { clearDownloaded, getNeedsPostprocessing } from "../state/recentDownload
 import { handleDownload } from "./commands/download.js";
 import { handleTranslate, postProcessTranslations } from "./commands/translate.js";
 import { displayTranslateSummary } from "../console/displayTranslateSummary.js";
-import { createLoadTranslationsFile } from "../fs/createLoadTranslationsFile.js";
+import { createLoadTranslationsFile, findLoadTranslationsFiles } from "../fs/createLoadTranslationsFile.js";
 import { saveLocalEdits } from "../api/saveLocalEdits.js";
 import processSharedStaticAssets, { mirrorAssetsToLocales } from "../utils/sharedStaticAssets.js";
 import { setupLocadex } from "../locadex/setupFlow.js";
@@ -42,11 +44,9 @@ import { splitMintlifyLanguageRefs } from "../utils/splitMintlifyLanguageRefs.js
 import { runMergeDriver } from "../git/mergeDrivers.js";
 import { setupGitMergeDrivers } from "../git/setupMergeDrivers.js";
 import { warnReactPackageCompatibility } from "../utils/reactPackageCompatibility.js";
-import { setupViteSPA } from "../setup/setupViteSPA.js";
 import { handleApiCommand } from "./commands/api.js";
 import chalk from "chalk";
 import path from "node:path";
-import fs from "node:fs";
 import { createDiagnosticMessage, formatDiagnosticErrorDetails } from "generaltranslation/diagnostics";
 import { ProjectApiKeyPermission } from "generaltranslation/api";
 import { manifestDirectlyDeclaresGTVue } from "@generaltranslation/vue-extractor/integration";
@@ -61,13 +61,6 @@ const ID_COMPATIBILITY_WARNING_COMMANDS = new Set([
 	"translate",
 	"validate"
 ]);
-const workspaceRootSetupError = createDiagnosticMessage({
-	source: "gt",
-	severity: "Error",
-	whatHappened: "The setup wizard cannot run from a monorepo workspace root",
-	why: "GT must be configured in the specific app you want to localize",
-	fix: "Change to that app's directory and rerun `npx gt@latest`"
-});
 function createProjectCommandError(whatHappened, error) {
 	return createDiagnosticMessage({
 		source: "gt",
@@ -85,42 +78,14 @@ function parseApiKeyName(value) {
 	if (!name) throw new InvalidArgumentError(emptyApiKeyNameError);
 	return name;
 }
-const electronSetupError = createDiagnosticMessage({
-	source: "gt",
-	severity: "Error",
-	whatHappened: "The automatic setup wizard is not ready for Electron applications",
-	docsUrl: "https://generaltranslation.com/docs/react"
-});
-/** .env.local never reaches production; the runtime key there is set on the host. */
-function productionRuntimeKeyGuidance(dashboardUrl) {
-	return `${chalk.dim("For runtime translation in production, create an API key in the dashboard")} ${chalk.cyan(dashboardUrl)} ${chalk.dim("and set GT_API_KEY and GT_PROJECT_ID in your hosting environment.")}`;
-}
-async function loginInteractively(baseUrl, useBrowser = true) {
-	await login({
-		baseUrl,
-		noBrowser: !useBrowser,
-		onDeviceCode: ({ userCode, verificationUri, verificationUriComplete }) => {
-			logger.message(`Visit:\n\n${chalk.cyan(verificationUriComplete ?? verificationUri)}\n\nThen ${verificationUriComplete ? "confirm" : "enter"} the code ${chalk.bold(userCode)}.\nWaiting for authentication...`);
-		},
-		onAuthorizationUrl: (url) => {
-			logger.message(`Opening your browser to sign in. If it does not open, visit:\n${chalk.cyan(url)}`);
-		}
-	});
-}
-function createUserAuthError(whatHappened, error) {
-	if (error instanceof UserAuthError) return error.message;
-	return createDiagnosticMessage({
-		source: "gt",
-		severity: "Error",
-		whatHappened,
-		details: formatDiagnosticErrorDetails(error),
-		fix: "Run `gt login` and try again"
-	});
-}
-async function exitIfUnsupportedSetupTarget() {
-	const packageJson = await searchForPackageJson();
-	if (packageJson && isPackageInstalled("electron", packageJson, false, true)) logErrorAndExit(electronSetupError);
-	if (fs.existsSync(path.join(process.cwd(), "pnpm-workspace.yaml")) || packageJson?.workspaces) logErrorAndExit(workspaceRootSetupError);
+/** Credential failures keep their own diagnostic or get the setup context. */
+async function withCredentialsError(run) {
+	try {
+		return await run();
+	} catch (error) {
+		if (error instanceof OnboardingError) throw error;
+		throw new Error(error instanceof UserAuthError ? error.message : createProjectCommandError("Failed to set up the development credentials", error));
+	}
 }
 var BaseCLI = class {
 	library;
@@ -133,8 +98,9 @@ var BaseCLI = class {
 		this.program.option("--skip-version-check", "Skip the monorepo GT package version consistency check");
 		this.program.option("--suppress-id-compatibility-warning", "Suppress the React package ID compatibility warning");
 		this.program.option("-q, --quiet", "Suppress informational output; only warnings and errors are shown");
-		this.program.hook("preAction", (_thisCommand, actionCommand) => {
-			logger.setConsoleOutput(actionCommand.parent?.name() === "api-key" ? "stderr" : "stdout");
+		this.program.hook("preAction", (thisCommand, actionCommand) => {
+			logger.setConsoleOutput(actionCommand.parent?.name() === "api-key" || actionCommand.opts().json ? "stderr" : "stdout");
+			if (actionCommand.opts().json && actionCommand.parent === thisCommand && ["init", "configure"].includes(actionCommand.name())) reportJsonExitsBeforeOnboarding(actionCommand.name());
 		});
 		this.program.hook("preAction", () => {
 			logger.setQuiet(Boolean(this.program.opts().quiet));
@@ -360,10 +326,10 @@ var BaseCLI = class {
 		});
 	}
 	setupUserAuthCommands() {
-		this.program.command("login").description("Sign in to your General Translation account").option("--no-browser", "Do not open a browser; show a sign-in URL to use on any device instead").action(async (options) => {
+		this.program.command("login").description("Sign in to your General Translation account").option("--no-browser", "Do not open a browser; show a sign-in URL to use on any device instead").option("-c, --config <path>", "Filepath to config file, by default gt.config.json").action(async (options) => {
 			displayHeader("Signing in to General Translation...");
 			try {
-				const baseUrl = resolveConfig(process.cwd())?.config.baseUrl;
+				const baseUrl = (options.config ? loadConfig(withJsonExtension(options.config)) : resolveConfig(process.cwd())?.config)?.baseUrl;
 				await loginInteractively(typeof baseUrl === "string" ? baseUrl : void 0, options.browser);
 				logger.endCommand("You are now signed in.");
 			} catch (error) {
@@ -388,61 +354,87 @@ var BaseCLI = class {
 		});
 	}
 	setupInitCommand() {
-		this.program.command("init").description("Run the setup wizard to configure your project for General Translation").option("--src <paths...>", "Space-separated list of glob patterns containing the app's source code, by default 'src/**/*.{js,jsx,ts,tsx}' 'app/**/*.{js,jsx,ts,tsx}' 'pages/**/*.{js,jsx,ts,tsx}' 'components/**/*.{js,jsx,ts,tsx}'").option("-c, --config <path>", "Filepath to config file, by default gt.config.json", findFilepath(["gt.config.json"])).action(async (options) => {
+		attachInitFlags(this.program.command("init").description("Run the setup wizard to configure your project for General Translation. Flags answer its questions; unanswered ones are asked, or listed as missing with --no-interactive"), INIT_SOURCE_HELP).action((options) => this.handleInitWizard(options));
+	}
+	async handleInitWizard(options) {
+		await runOnboarding("init", options, async (session) => {
 			await exitIfUnsupportedSetupTarget();
-			const settings = await generateSettings(options);
-			displayHeader("Running setup wizard...");
-			const framework = await detectFramework();
-			if (await (async () => {
-				let useAgentMessage;
-				if (framework.name === "mintlify") useAgentMessage = `Mintlify project detected. Would you like to connect to GitHub so that the Locadex AI Agent can translate your project automatically?`;
-				if (framework.name === "next-app") useAgentMessage = `Next.js App Router detected. Would you like to connect to GitHub so that the Locadex AI Agent can set up your project automatically?`;
-				if (useAgentMessage) return await promptConfirm({
-					message: useAgentMessage,
-					defaultValue: false
-				});
-				return false;
-			})()) {
-				await setupLocadex(settings);
-				logger.endCommand("Once installed, Locadex will open a PR to your repository. See the docs for more information: https://generaltranslation.com/docs/locadex");
-			} else {
-				const frameworkDisplayName = framework.type === "react" ? getFrameworkDisplayName(framework) : null;
-				const library = framework.type === "react" ? getReactFrameworkLibrary(framework) : null;
-				const defaultTranslationsDir = framework.name === "vite" ? DEFAULT_VITE_TRANSLATIONS_DIR : DEFAULT_TRANSLATIONS_DIR;
-				const defaultsDescription = framework.name === "vite" ? `${library} & initializeGTSPA, ${frameworkDisplayName}, Files saved locally in ${defaultTranslationsDir}` : framework.type === "react" ? `${library} & GTProvider, ${frameworkDisplayName}, Files saved locally in ${defaultTranslationsDir}` : `Files saved locally in ${defaultTranslationsDir}`;
-				const useDefaults = await promptConfirm({
-					message: `Would you like to use the recommended General Translation defaults? ${chalk.dim(`(${defaultsDescription})`)}`,
-					defaultValue: true
-				});
-				let ranReactSetup = false;
-				if (framework.type === "react") {
-					if (useDefaults ? true : await promptConfirm({
-						message: framework.name === "vite" ? `Would you like to install ${library} and configure initializeGTSPA? See the docs for more information: https://generaltranslation.com/docs/react/tutorials/quickstart` : `Would you like to install ${library} and add the GTProvider? See the docs for more information: https://generaltranslation.com/docs/react/tutorials/quickstart`,
-						defaultValue: true
-					})) {
-						logger.info(`${chalk.yellow("[EXPERIMENTAL]")} Configuring project...`);
-						await handleSetupReactCommand(options, framework, useDefaults);
-						logger.endCommand(`Done! Since this wizard is experimental, please review the changes and make modifications as needed.
-\nNext step: start internationalizing! See the docs for more information: https://generaltranslation.com/docs/react/tutorials/quickstart`);
-						ranReactSetup = true;
-					}
+			displaySetupHeader(session, "Running setup wizard...");
+			const detected = await detectFramework();
+			const reactDetected = detected.type === "react" ? detected : void 0;
+			if (options.framework && !reactDetected) session.reject("--framework applies only to projects detected as React applications");
+			const configFilepath = setupConfigPath(options);
+			const configured = getConfiguredFramework(readSetupConfig(configFilepath));
+			const configuredReact = configured !== "mintlify" ? configured : void 0;
+			if (options.defaults !== void 0) session.defaults = options.defaults;
+			const gateFramework = options.framework ?? configured ?? detected.name;
+			if (gateFramework === "mintlify" || gateFramework === "next-app") {
+				if (await session.answer("--locadex", {
+					explicit: options.locadex,
+					recommended: false,
+					ask: () => promptConfirm({
+						message: gateFramework === "mintlify" ? `Mintlify project detected. Would you like to connect to GitHub so that the Locadex AI Agent can translate your project automatically?` : `Next.js App Router detected. Would you like to connect to GitHub so that the Locadex AI Agent can set up your project automatically?`,
+						defaultValue: false
+					})
+				})) {
+					session.assertResolved();
+					const url = await setupLocadex(await generateSettings({ config: options.config }), { openBrowser: session.interactive });
+					session.emit({
+						type: "handoff",
+						url,
+						reason: "locadex"
+					});
+					logger.endCommand("Once installed, Locadex will open a PR to your repository. See the docs for more information: https://generaltranslation.com/docs/locadex");
+					return {
+						outcome: "needs_human_action",
+						url
+					};
 				}
-				if (ranReactSetup) logger.startCommand("Setting up project config...");
-				await this.handleInitCommand(ranReactSetup, useDefaults, framework.name === "vite", options, framework.name);
-				logger.endCommand("Done! Check out our docs for more information on how to use General Translation: https://generaltranslation.com/docs");
-			}
+			} else if (options.locadex) session.reject("--locadex applies only to Mintlify and Next.js App Router projects");
+			const shownFramework = reactDetected && {
+				...reactDetected,
+				name: options.framework ?? configuredReact ?? reactDetected.name
+			};
+			session.defaults = await session.answer("--defaults", {
+				explicit: options.defaults,
+				fallback: false,
+				ask: () => promptConfirm({
+					message: `Would you like to use the recommended General Translation defaults? ${chalk.dim(`(${describeDefaults(shownFramework)})`)}`,
+					defaultValue: true
+				})
+			}) === true;
+			const reactSetup = reactDetected ? await resolveReactSetup(session, options, reactDetected, configuredReact) : void 0;
+			const framework = reactSetup?.framework ?? options.framework ?? configured ?? detected.name;
+			await this.handleInitCommand(session, options, {
+				configFilepath,
+				framework,
+				saveFramework: Boolean(reactSetup || options.framework),
+				reactSetup,
+				keepAppSource: !reactSetup
+			});
+			logger.endCommand("Done! Check out our docs for more information on how to use General Translation: https://generaltranslation.com/docs");
+			return { outcome: "success" };
 		});
 	}
 	setupConfigureCommand() {
-		this.program.command("configure").description("Configure your project for General Translation. This will create a gt.config.json file in your codebase.").action(() => this.handleConfigureCommand());
+		attachConfigureFlags(this.program.command("configure").description("Configure your project for General Translation. This will create a gt.config.json file in your codebase. Flags answer its questions; unanswered ones are asked, or listed as missing with --no-interactive"), INIT_SOURCE_HELP).action((options) => this.handleConfigureCommand(options));
 	}
-	async handleConfigureCommand(options) {
-		await exitIfUnsupportedSetupTarget();
-		displayHeader("Configuring project...");
-		logger.info("Welcome! This tool will help you configure your gt.config.json file. See the docs: https://generaltranslation.com/docs/cli/reference/config for more information.");
-		const framework = await detectFramework();
-		await this.handleInitCommand(false, false, framework.name === "vite", options);
-		logger.endCommand("Done! Make sure you have an API key and project ID to use General Translation. Get them on the dashboard: https://generaltranslation.com/dashboard");
+	async handleConfigureCommand(options, command = "configure") {
+		await runOnboarding(command, options, async (session) => {
+			await exitIfUnsupportedSetupTarget();
+			displaySetupHeader(session, "Configuring project...");
+			logger.info("Welcome! This tool will help you configure your gt.config.json file. See the docs: https://generaltranslation.com/docs/cli/reference/config for more information.");
+			session.defaults = options.defaults ?? false;
+			const detected = await detectFramework();
+			const configFilepath = setupConfigPath(options);
+			const framework = getConfiguredFramework(readSetupConfig(configFilepath)) ?? detected.name;
+			await this.handleInitCommand(session, options, {
+				configFilepath,
+				framework
+			});
+			logger.endCommand("Done! Make sure you have an API key and project ID to use General Translation. Get them on the dashboard: https://generaltranslation.com/dashboard");
+			return { outcome: "success" };
+		});
 	}
 	async handleUploadCommand(settings) {
 		if (!settings.files) return;
@@ -466,8 +458,8 @@ var BaseCLI = class {
 		return !runtimeSetup.hasVueRuntime;
 	}
 	/** Returns whether setup should generate a local runtime loader. */
-	shouldGenerateLocalTranslationLoader(isVite, runtimeSetup) {
-		if (isVite) return false;
+	shouldGenerateLocalTranslationLoader(buildToolOwnsLoader, runtimeSetup) {
+		if (buildToolOwnsLoader) return false;
 		if (!runtimeSetup.hasVueRuntime) return true;
 		return runtimeSetup.hasOtherInlineRuntime || runtimeSetup.ranReactSetup;
 	}
@@ -482,21 +474,35 @@ Configure createGT({ loadTranslations }) to load files from that directory.
 See https://www.npmjs.com/package/gt-vue`);
 		return guidance.length > 0 ? guidance.join("\n") : void 0;
 	}
-	async handleInitCommand(ranReactSetup, useDefaults = false, isVite = false, options, framework) {
-		const configFilepath = options?.config || (!isVite && fs.existsSync("src/gt.config.json") ? "src/gt.config.json" : "gt.config.json");
-		const { defaultLocale, locales } = await getDesiredLocales(loadConfig(configFilepath));
-		const packageJson = await searchForPackageJson();
-		const runtimeSetup = packageJson ? this.getInlineRuntimeSetup(packageJson, ranReactSetup) : {
+	/**
+	* Resolves every configuration answer and validates the resulting config,
+	* checks the project and signs in before the first change, then applies
+	* the React setup, gt.config.json, installs and development credentials.
+	*/
+	async handleInitCommand(session, options, setup) {
+		const { configFilepath, reactSetup } = setup;
+		const buildTool = getBuildToolSetup(setup.framework);
+		const cwd = process.cwd();
+		const existingConfig = readSetupConfig(configFilepath);
+		const { defaultLocale, locales } = await getDesiredLocales(session, existingConfig, options);
+		const packageJson = reactSetup?.packageJson ?? await searchForPackageJson();
+		const runtimeSetup = packageJson ? this.getInlineRuntimeSetup(packageJson, Boolean(reactSetup)) : {
 			hasOtherInlineRuntime: false,
 			hasVueRuntime: false,
-			ranReactSetup
+			ranReactSetup: false
 		};
 		const isUsingGT = runtimeSetup.ranReactSetup || runtimeSetup.hasOtherInlineRuntime || runtimeSetup.hasVueRuntime;
-		const usingCDN = await (async () => {
-			if (!isUsingGT) return false;
-			if (useDefaults) return false;
-			if (!this.supportsCDNStorage(runtimeSetup)) return false;
-			return await promptSelect({
+		const supportsCDN = this.supportsCDNStorage(runtimeSetup);
+		const existingFiles = asRecord(existingConfig.files) ?? {};
+		const existingGtOutput = asRecord(existingFiles.gt)?.output;
+		const configuredOutput = typeof existingGtOutput === "string" ? existingGtOutput : void 0;
+		const configuredStorage = configuredOutput ? "local" : existingConfig.publish === true ? "cdn" : void 0;
+		if (isUsingGT && !supportsCDN && options.storage === "cdn") session.reject("gt-vue cannot load translations from the CDN; use --storage local");
+		const storage = !isUsingGT ? void 0 : !supportsCDN ? "local" : await session.answer("--storage", {
+			explicit: options.storage,
+			configured: configuredStorage,
+			recommended: "local",
+			ask: () => promptSelect({
 				message: `Would you like to save translation files locally or use the General Translation CDN to store them?`,
 				options: [{
 					value: "local",
@@ -506,116 +512,215 @@ See https://www.npmjs.com/package/gt-vue`);
 					label: "Use CDN"
 				}],
 				defaultValue: "local"
-			}) === "cdn";
-		})();
-		const defaultTranslationsDir = isVite ? DEFAULT_VITE_TRANSLATIONS_DIR : DEFAULT_TRANSLATIONS_DIR;
-		const finalTranslationsDir = (isUsingGT && !usingCDN ? useDefaults ? defaultTranslationsDir : await promptText({
-			message: "What is the path to the directory where you would like to store your translation files?",
-			defaultValue: defaultTranslationsDir
-		}) : null)?.trim() || defaultTranslationsDir;
-		if (isUsingGT && !usingCDN) {
-			const generatedLoader = this.shouldGenerateLocalTranslationLoader(isVite, runtimeSetup);
-			if (generatedLoader) await createLoadTranslationsFile(process.cwd(), finalTranslationsDir, locales);
-			const guidance = this.getLocalTranslationGuidance({
-				generatedLoader,
-				runtimeSetup,
-				translationsDir: finalTranslationsDir
-			});
-			if (guidance) logger.message(guidance);
+			})
+		});
+		const defaultTranslationsDir = buildTool?.defaultTranslationsDir ?? "./public/_gt";
+		const outputMatch = configuredOutput?.match(/^(?:(.+)[\\/])?\[locale\]\.json$/);
+		const configuredTranslationsDir = outputMatch ? outputMatch[1] ?? "." : void 0;
+		const translationsDir = storage === "local" ? await session.answer("--translations-dir", {
+			explicit: options.translationsDir?.trim() || void 0,
+			configured: configuredTranslationsDir,
+			recommended: defaultTranslationsDir,
+			ask: async () => (await promptText({
+				message: "What is the path to the directory where you would like to store your translation files?",
+				defaultValue: defaultTranslationsDir
+			})).trim() || defaultTranslationsDir
+		}) : void 0;
+		const filePatterns = parseFilePatterns(session, options.filePatterns);
+		const selectedFormats = options.fileFormats?.filter((format) => format !== "none");
+		if (options.fileFormats?.includes("none") && (selectedFormats?.length ?? 0) > 0) session.reject("--file-formats none cannot be combined with formats");
+		const configuredFormats = SETUP_FILE_FORMATS.filter((format) => format in existingFiles);
+		const otherFormats = SUPPORTED_FILE_EXTENSIONS.filter((format) => format in existingFiles && !SETUP_FILE_FORMATS.includes(format));
+		const hasOtherFormats = otherFormats.length > 0;
+		if (options.fileFormats && hasOtherFormats) {
+			const kept = otherFormats.map((format) => `files.${format}`).join(", ");
+			logger.warn(createDiagnosticMessage({
+				source: "gt",
+				severity: "Warning",
+				whatHappened: `${kept} stays in ${configFilepath}`,
+				why: "--file-formats only changes the formats setup offers",
+				fix: `Remove ${kept} from ${configFilepath} to stop translating those files`
+			}));
 		}
-		const message = !isUsingGT ? "What is the format of your language resource files? Select as many as applicable.\nAdditionally, you can translate any other files you have in your project." : `Do you have any additional files in this project to translate? For example, Markdown files for docs. ${chalk.dim("(To continue without selecting press Enter)")}`;
-		const fileExtensions = useDefaults && isUsingGT ? [] : await promptMultiSelect({
-			message,
-			options: [
-				{
-					value: "json",
-					label: FILE_EXT_TO_EXT_LABEL.json
-				},
-				{
-					value: "md",
-					label: FILE_EXT_TO_EXT_LABEL.md
-				},
-				{
-					value: "mdx",
-					label: FILE_EXT_TO_EXT_LABEL.mdx
-				},
-				{
-					value: "ts",
-					label: FILE_EXT_TO_EXT_LABEL.ts
-				},
-				{
-					value: "js",
-					label: FILE_EXT_TO_EXT_LABEL.js
-				},
-				{
-					value: "yaml",
-					label: FILE_EXT_TO_EXT_LABEL.yaml
-				}
-			],
-			required: !isUsingGT
+		const fileFormats = await session.answer("--file-formats", {
+			explicit: selectedFormats ?? (filePatterns.size > 0 ? [...filePatterns.keys()] : void 0),
+			configured: configuredFormats.length > 0 || hasOtherFormats ? configuredFormats : void 0,
+			recommended: isUsingGT ? [] : void 0,
+			ask: () => promptMultiSelect({
+				message: !isUsingGT ? "What is the format of your language resource files? Select as many as applicable.\nAdditionally, you can translate any other files you have in your project." : `Do you have any additional files in this project to translate? For example, Markdown files for docs. ${chalk.dim("(To continue without selecting press Enter)")}`,
+				options: SETUP_FILE_FORMATS.map((format) => ({
+					value: format,
+					label: FILE_EXT_TO_EXT_LABEL[format]
+				})),
+				required: !isUsingGT
+			})
 		});
+		if (fileFormats && fileFormats.length === 0 && !isUsingGT && !hasOtherFormats) session.reject("No GT runtime is installed, so select at least one file format to translate");
+		for (const format of filePatterns.keys()) if (fileFormats && !fileFormats.includes(format)) session.reject(`--file-patterns ${format}= needs ${format} in --file-formats`);
 		const files = {};
-		for (const fileExtension of fileExtensions) {
-			const label = FILE_EXT_TO_EXT_LABEL[fileExtension];
-			files[fileExtension] = { include: parseGlobPatterns(await promptGlobPatterns({
-				label,
-				message: `${chalk.cyan(FILE_EXT_TO_EXT_LABEL[fileExtension])}: Enter a space-separated list of glob patterns matching the location of the ${FILE_EXT_TO_EXT_LABEL[fileExtension]} files you would like to translate.\nMake sure to include [locale] in the patterns.\nSee https://generaltranslation.com/docs/cli/reference/config#include for more information.`,
-				defaultValue: `./**/[locale]/*.${fileExtension}`
-			})) };
+		for (const fileExtension of fileFormats ?? []) {
+			const existingFormat = asRecord(existingFiles[fileExtension]);
+			const configuredInclude = Array.isArray(existingFormat?.include) ? existingFormat.include : void 0;
+			const include = await session.answer(`--file-patterns ${fileExtension}=<glob>`, {
+				explicit: filePatterns.get(fileExtension),
+				configured: configuredInclude,
+				recommended: [`./**/[locale]/*.${fileExtension}`],
+				ask: async () => parseGlobPatterns(await promptGlobPatterns({
+					label: FILE_EXT_TO_EXT_LABEL[fileExtension],
+					message: `${chalk.cyan(FILE_EXT_TO_EXT_LABEL[fileExtension])}: Enter a space-separated list of glob patterns matching the location of the ${FILE_EXT_TO_EXT_LABEL[fileExtension]} files you would like to translate.\nMake sure to include [locale] in the patterns.\nSee https://generaltranslation.com/docs/cli/reference/config#include for more information.`,
+					defaultValue: `./**/[locale]/*.${fileExtension}`,
+					validate: (value) => parseGlobPatterns(value).map(validateSetupPattern).find((problem) => problem !== true) ?? true
+				}))
+			});
+			if (include && include !== configuredInclude) files[fileExtension] = {
+				...existingFormat,
+				include
+			};
 		}
-		if (isUsingGT && !usingCDN) files.gt = { output: path.join(finalTranslationsDir, `[locale].json`) };
-		await createOrUpdateConfig(configFilepath, {
+		if (translationsDir && translationsDir !== configuredTranslationsDir) files.gt = { output: path.join(translationsDir, `[locale].json`) };
+		const envFramework = setup.framework ?? getConfiguredFramework(existingConfig);
+		const projectId = options.projectId || (typeof existingConfig.projectId === "string" ? existingConfig.projectId : void 0) || process.env[getDevelopmentEnvNames(envFramework).projectId];
+		const configUpdate = {
 			defaultLocale,
 			locales,
-			src: options?.src,
+			src: options.src,
 			files: Object.keys(files).length > 0 ? files : void 0,
-			framework: isVite ? "vite" : void 0,
-			publish: isUsingGT && usingCDN,
-			clearPublish: runtimeSetup.hasVueRuntime && !usingCDN
-		});
-		logger.success(`Edit ${chalk.cyan(configFilepath)} to customize your translation setup. Docs: https://generaltranslation.com/docs/cli/reference/config`);
-		if (ranReactSetup && isVite) await setupViteSPA({
-			appDirectory: process.cwd(),
-			configFilepath,
-			defaultLocale,
-			locales,
-			translationsDir: usingCDN ? void 0 : finalTranslationsDir
-		});
-		if (!(packageJson ? isPackageInstalled("gt", packageJson, true, true) : true) && !(isUsingGT && isVite)) {
-			const packageManager = await getPackageManager();
-			const spinner = logger.createSpinner();
-			spinner.start(`Installing gt as a dev dependency with ${packageManager.name}...`);
-			await installPackage("gt", packageManager, true);
-			spinner.stop(chalk.green("Installed gt."));
+			framework: setup.saveFramework && setup.framework || buildTool?.framework,
+			publish: storage === "cdn",
+			clearPublish: storage === "local" && (options.storage === "local" || configuredStorage !== "local" || !supportsCDN),
+			clearGtOutput: storage === "cdn" && configuredOutput !== void 0,
+			removeFiles: selectedFormats ? configuredFormats.filter((format) => !selectedFormats.includes(format)) : void 0
+		};
+		session.assertResolved();
+		const { projectId: _writtenProjectId, ...effectiveConfig } = mergeSetupConfig(existingConfig, configUpdate);
+		const settings = await generateSettings({
+			config: configFilepath,
+			...projectId && { projectId }
+		}, cwd, { resolvedConfig: effectiveConfig });
+		const runtimeProjectId = process.env[getDevelopmentEnvNames(envFramework).projectId] ?? resolveProjectId();
+		const runtimeProjectMatches = runtimeProjectId === void 0 || runtimeProjectId === settings.projectId;
+		const credentialsSet = runtimeProjectMatches && areCredentialsSet(settings, envFramework);
+		const credentialsOption = storage === "local" && buildTool?.devCredentialsOption || "--dev-credentials";
+		const provision = !credentialsSet && (credentialsOption === "--live-translations" ? await session.answer("--live-translations", {
+			explicit: options.liveTranslations ?? options.devCredentials,
+			recommended: false,
+			ask: () => promptConfirm({
+				message: "Would you like to set up live development translations? This requires signing in or an API key.",
+				defaultValue: false
+			})
+		}) : await session.answer("--dev-credentials", {
+			explicit: options.devCredentials,
+			ask: () => promptConfirm({
+				message: "Would you like to set up a project ID and hot-reload key in .env.local?",
+				defaultValue: true
+			})
+		})) === true;
+		if (!runtimeProjectMatches && !provision) session.reject(`The runtime credentials in the environment belong to project ${runtimeProjectId}, not ${settings.projectId}; pass --dev-credentials to replace them in .env.local`);
+		if (options.projectId && (existingConfig.projectId || !provision)) configUpdate.projectId = options.projectId;
+		if (provision) {
+			checkDevelopmentProjectInputs(session, settings, options, options.projectId ? "--project-id" : typeof existingConfig.projectId === "string" && existingConfig.projectId ? configFilepath : "the environment");
+			await withCredentialsError(() => inspectCredentialsEnvFile(cwd, { framework: envFramework }));
 		}
-		const localVite = isVite && isUsingGT && !usingCDN;
-		const enableLiveTranslations = localVite && await promptConfirm({
-			message: "Would you like to set up live development translations? This requires signing in or an API key.",
-			defaultValue: false
-		});
-		if (!localVite || enableLiveTranslations) {
-			const settings = await generateSettings({ config: configFilepath });
-			const envFramework = framework ?? (isVite ? "vite" : settings.framework);
-			if (!settings.apiKey && !await hasLogin({ baseUrl: settings.baseUrl })) try {
-				await loginInteractively(settings.baseUrl);
-				logger.message("You are now signed in.");
-			} catch (error) {
-				logErrorAndExit(createUserAuthError("Sign in failed", error));
+		if (reactSetup && buildTool) await buildTool.preflight(cwd);
+		const installGT = packageJson !== null && !isPackageInstalled("gt", packageJson, true, true) && !buildTool?.skipsGTInstall(isUsingGT);
+		const packageManager = reactSetup?.install || installGT ? await resolvePackageManager(session, options.packageManager) : void 0;
+		session.assertResolved();
+		if (provision && !settings.apiKey && !await hasLogin({ baseUrl: settings.baseUrl })) await signInForSetup(session, settings.baseUrl);
+		const project = provision ? await withCredentialsError(() => resolveDevelopmentProject(session, settings, options, cwd)) : void 0;
+		session.assertResolved();
+		const resolvedLocales = locales;
+		if (reactSetup) {
+			logger.info(`${chalk.yellow("[EXPERIMENTAL]")} Configuring project...`);
+			if (reactSetup.install && packageManager) await installWithProgress(session, reactSetup.install, packageManager, false);
+			await executeReactSetup(session, reactSetup, options);
+			logger.endCommand(`Done! Since this wizard is experimental, please review the changes and make modifications as needed.
+\nNext step: start internationalizing! See the docs for more information: https://generaltranslation.com/docs/react/tutorials/quickstart`);
+			logger.startCommand("Setting up project config...");
+		}
+		const reportManualAction = ({ whatHappened, fix }) => {
+			session.humanActions.push(fix);
+			logger.warn(createDiagnosticMessage({
+				source: "gt",
+				severity: "Warning",
+				whatHappened,
+				fix
+			}));
+		};
+		const reportSetupResult = ({ steps, manualActions }) => {
+			for (const step of steps) session.step(step);
+			manualActions.forEach(reportManualAction);
+		};
+		const translationFilesError = (error) => new Error(createDiagnosticMessage({
+			source: "gt",
+			severity: "Error",
+			whatHappened: `Could not create the translation files in ${translationsDir}`,
+			details: formatDiagnosticErrorDetails(error),
+			fix: "Choose another --translations-dir or fix the path, then rerun the command"
+		}));
+		const buildToolContext = {
+			appDirectory: cwd,
+			configFilepath,
+			defaultLocale: settings.defaultLocale,
+			locales: resolvedLocales,
+			translationsDir: storage === "local" ? translationsDir : void 0,
+			previousTranslationsDir: configuredTranslationsDir
+		};
+		if (storage === "local" && translationsDir) {
+			if (buildTool && !reactSetup) reportSetupResult(await buildTool.syncLoader({
+				...buildToolContext,
+				translationsDir,
+				keepAppSource: setup.keepAppSource
+			}).catch((error) => {
+				throw translationFilesError(error);
+			}));
+			const generatedLoader = this.shouldGenerateLocalTranslationLoader(buildTool?.ownsLoader ?? false, runtimeSetup);
+			const loader = generatedLoader ? await createLoadTranslationsFile({
+				appDirectory: cwd,
+				translationsDir,
+				defaultLocale: settings.defaultLocale,
+				locales: resolvedLocales,
+				previousTranslationsDir: configuredTranslationsDir
+			}).catch((error) => {
+				throw translationFilesError(error);
+			}) : void 0;
+			if (loader === "created" || loader === "updated") session.step(`${loader} loadTranslations.js`);
+			if (loader === "custom" && translationsDir !== configuredTranslationsDir) {
+				const loaderFile = path.relative(cwd, findLoadTranslationsFiles(cwd)[0] ?? "loadTranslations.js");
+				reportManualAction({
+					whatHappened: `Your custom ${loaderFile} was left unchanged, but translations now go to ${translationsDir}`,
+					fix: `Update your custom ${loaderFile} to load translations from ${translationsDir}`
+				});
 			}
-			if (!areCredentialsSet(settings, envFramework)) {
-				if (useDefaults || enableLiveTranslations ? true : await promptConfirm({
-					message: "Would you like to set up a project ID and hot-reload key in .env.local?",
-					defaultValue: true
-				})) {
-					try {
-						await provisionDevelopmentCredentials(settings, envFramework);
-					} catch (error) {
-						logErrorAndExit(error instanceof UserAuthError ? error.message : createProjectCommandError("Failed to set up the development credentials", error));
-					}
-					logger.message(productionRuntimeKeyGuidance(settings.dashboardUrl));
-				}
+			const guidance = this.getLocalTranslationGuidance({
+				generatedLoader: generatedLoader && loader !== "custom",
+				runtimeSetup,
+				translationsDir
+			});
+			if (guidance) logger.message(guidance);
+		} else if (storage === "cdn" && buildTool && !reactSetup && configuredTranslationsDir !== void 0) reportManualAction({
+			whatHappened: `Translations now load from the CDN, but ${buildTool.initializer} may still receive the local loader for ${configuredTranslationsDir}`,
+			fix: `Remove the loadTranslations option and its import from the ${buildTool.initializer}() call so translations load from the CDN`
+		});
+		else if (storage === "cdn" && !buildTool && configuredTranslationsDir !== void 0) {
+			const loaders = findLoadTranslationsFiles(cwd).map((loader) => path.relative(cwd, loader));
+			if (loaders.length > 0) {
+				const loaderFiles = loaders.join(", ");
+				const [them, loads] = loaders.length === 1 ? ["it", "loads"] : ["them", "load"];
+				reportManualAction({
+					whatHappened: `Translations now load from the CDN, but ${loaderFiles} still ${loads} them from ${configuredTranslationsDir}`,
+					fix: `Delete ${loaderFiles}, and remove ${them} from your GT setup if you pass ${them} there, so translations load from the CDN`
+				});
 			}
 		}
+		await createOrUpdateConfig(configFilepath, configUpdate);
+		session.step(`updated ${configFilepath}`);
+		logger.success(`Edit ${chalk.cyan(configFilepath)} to customize your translation setup. Docs: https://generaltranslation.com/docs/cli/reference/config`);
+		if (reactSetup && buildTool) reportSetupResult(await buildTool.apply(buildToolContext));
+		if (installGT && packageManager) await installWithProgress(session, "gt", packageManager, true);
+		if (project) {
+			await withCredentialsError(() => provisionDevelopmentCredentials(session, project, settings, envFramework, cwd));
+			logger.message(productionRuntimeKeyGuidance(settings.dashboardUrl));
+		}
 	}
 };
 //#endregion