gt 2.22.4 → 2.23.0

package/dist/setup/developmentCredentials.js

@@ -1,50 +1,117 @@
 import { logger } from "../console/logger.js";
-import { logErrorAndExit, promptSelect, promptText } from "../console/logging.js";
+import { promptConfirm, promptSelect, promptText } from "../console/logging.js";
+import { createUserAuthError } from "../auth/errors.js";
 import { api } from "../utils/api.js";
-import { inspectCredentialsEnvFile, setCredentials } from "../utils/credentials.js";
+import { setCredentials } from "../utils/credentials.js";
+import { loginInteractively } from "../auth/interactiveLogin.js";
+import { OnboardingError } from "./onboarding.js";
 import chalk from "chalk";
 import path from "node:path";
-import { createDiagnosticMessage } from "generaltranslation/diagnostics";
+import { createDiagnosticMessage, formatDiagnosticErrorDetails } from "generaltranslation/diagnostics";
 import { ProjectApiKeyPermission } from "generaltranslation/api";
+import { ApiError } from "generaltranslation/errors";
 //#region src/setup/developmentCredentials.ts
 const DEVELOPMENT_KEY_NAME = "Development key (gt init)";
-function noCreatableOrgError(dashboardUrl) {
+/** .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.")}`;
+}
+/**
+* Interactive setup keeps the browser login with its device fallback;
+* noninteractive setup always shows a device code (and emits it as a JSON
+* event) and waits for a person to approve it, without opening a browser.
+*/
+async function signInForSetup(session, baseUrl) {
+	try {
+		await loginInteractively(baseUrl, session.interactive, (deviceCode) => session.emit({
+			type: "authorization_required",
+			...deviceCode
+		}));
+	} catch (error) {
+		throw new OnboardingError(createUserAuthError("Sign in failed", error));
+	}
+	logger.message("You are now signed in.");
+}
+function noAccessibleOrgError(dashboardUrl) {
 	return createDiagnosticMessage({
 		source: "gt",
 		severity: "Error",
-		whatHappened: "You are not a member of an organization that can create projects",
+		whatHappened: "No accessible organizations were found",
 		fix: `Create an organization in the dashboard ${dashboardUrl} or ask an admin for access, then rerun the setup wizard`
 	});
 }
-async function createProject(settings, cwd) {
-	const orgs = await api.listOrgs();
-	if (orgs.length === 0) return logErrorAndExit(noCreatableOrgError(settings.dashboardUrl));
-	const orgId = orgs.length === 1 ? orgs[0].id : await promptSelect({
-		message: "Which organization should own the new project?",
-		options: orgs.map((org) => ({
-			value: org.id,
-			label: org.name
-		}))
+function projectCreationDeniedError(orgId, error) {
+	return createDiagnosticMessage({
+		source: "gt",
+		severity: "Error",
+		whatHappened: `Project creation was denied for organization ${orgId}`,
+		why: "Listing an organization does not confirm permission to create projects in it",
+		fix: "Ask an organization admin for org:projects:create, or use credentials that have that permission for this organization",
+		details: formatDiagnosticErrorDetails(error)
 	});
-	const name = await promptText({
-		message: "What should the project be called?",
-		defaultValue: path.basename(cwd),
-		validate: (value) => value.trim().length > 0 || "Enter a project name"
+}
+const noProjectChosenError = createDiagnosticMessage({
+	source: "gt",
+	severity: "Error",
+	whatHappened: "No project was chosen for the development credentials",
+	reassurance: "No project files were changed",
+	fix: "Rerun with --project-id <id> or --create-project, or skip them with --no-dev-credentials"
+});
+async function resolveNewProject(session, settings, options, cwd) {
+	const orgs = await api.listOrgs();
+	if (orgs.length === 0) throw new OnboardingError(noAccessibleOrgError(settings.dashboardUrl));
+	if (options.orgId && !orgs.some((org) => org.id === options.orgId)) session.reject(`--org-id ${options.orgId} is not an accessible organization`);
+	const orgId = await session.answer("--org-id", {
+		explicit: options.orgId,
+		configured: orgs.length === 1 ? orgs[0].id : void 0,
+		ask: () => promptSelect({
+			message: "Which organization should own the new project?",
+			options: orgs.map((org) => ({
+				value: org.id,
+				label: org.name
+			}))
+		})
 	});
-	const { project } = await api.createProject(orgId, {
-		name: name.trim() || path.basename(cwd),
-		defaultLocale: settings.defaultLocale
+	const name = await session.answer("--project-name", {
+		explicit: options.projectName?.trim() || void 0,
+		ask: async () => (await promptText({
+			message: "What should the project be called?",
+			defaultValue: path.basename(cwd)
+		})).trim() || path.basename(cwd)
 	});
-	logger.info(`Created ${project.name} (${project.id})`);
-	return project.id;
+	return orgId && name ? { create: {
+		orgId,
+		name
+	} } : void 0;
+}
+/**
+* Records project inputs a noninteractive run is missing, before signing in,
+* so it never waits for approval only to fail on a missing flag.
+*/
+function checkDevelopmentProjectInputs(session, settings, options, projectIdSource) {
+	if (settings.projectId && options.createProject) session.reject(`--create-project cannot be combined with project ${settings.projectId} from ${projectIdSource}; remove --create-project to keep using it, or remove the project ID from ${projectIdSource} to create a new project`);
+	if (settings.projectId || session.interactive) return;
+	if (!options.createProject) session.require("--project-id or --create-project");
+	else if (!options.projectName?.trim()) session.require("--project-name");
 }
-async function selectProject(settings, cwd) {
+/**
+* Chooses the project for development credentials without creating anything:
+* a supplied or configured ID, explicit creation inputs, or (interactively)
+* a selection among the account's projects.
+*/
+async function resolveDevelopmentProject(session, settings, options, cwd = process.cwd()) {
+	if (settings.projectId) return { id: settings.projectId };
+	if (options.createProject) return resolveNewProject(session, settings, options, cwd);
 	const projects = await api.listProjects();
 	if (projects.length === 0) {
-		logger.info("No projects found for your account; creating one.");
-		return createProject(settings, cwd);
+		const create = await session.answer("--project-id or --create-project", { ask: () => promptConfirm({
+			message: "No projects found for your account. Create a new project?",
+			defaultValue: true
+		}) });
+		if (create === false) throw new OnboardingError(noProjectChosenError);
+		return create ? resolveNewProject(session, settings, options, cwd) : void 0;
 	}
-	const choice = await promptSelect({
+	const choice = await session.answer("--project-id or --create-project", { ask: () => promptSelect({
 		message: "Which project should this app use?",
 		options: [...projects.map((project) => ({
 			value: project,
@@ -54,29 +121,44 @@ async function selectProject(settings, cwd) {
 			value: null,
 			label: "Create a new project"
 		}]
-	});
-	return choice ? choice.id : createProject(settings, cwd);
+	}) });
+	if (choice === void 0) return void 0;
+	return choice ? { id: choice.id } : resolveNewProject(session, settings, options, cwd);
 }
 /**
-* Picks or creates the project, mints a development key limited to runtime
-* translation, and saves both to .env.local. The file is checked before any
-* key exists, every service call completes before anything is written, and
-* the key is never printed.
+* Creates the chosen project if needed, mints a development key limited to
+* runtime translation, and saves both to .env.local. Callers inspect
+* .env.local first; the key is never printed.
 */
-async function provisionDevelopmentCredentials(settings, framework, cwd = process.cwd()) {
-	await inspectCredentialsEnvFile(cwd);
-	const projectId = settings.projectId || await selectProject(settings, cwd);
+async function provisionDevelopmentCredentials(session, project, settings, framework, cwd = process.cwd()) {
+	let projectId;
+	if ("id" in project) projectId = project.id;
+	else {
+		const { orgId, name } = project.create;
+		const { project: created } = await api.createProject(orgId, {
+			name,
+			defaultLocale: settings.defaultLocale
+		}).catch((error) => {
+			if (!(error instanceof ApiError) || error.code !== 403) throw error;
+			throw new OnboardingError(projectCreationDeniedError(orgId, error));
+		});
+		logger.info(`Created ${created.name} (${created.id})`);
+		session.step(`created project ${created.id}`);
+		projectId = created.id;
+	}
 	const { apiKey } = await api.createProjectApiKey(projectId, {
 		name: DEVELOPMENT_KEY_NAME,
 		permissions: [ProjectApiKeyPermission["PROJECT:TRANSLATIONS:GENERATE"]]
 	});
+	session.step("created a development key");
 	await setCredentials({
 		projectId,
 		apiKey: apiKey.key
 	}, framework, cwd);
+	session.step("saved development credentials to .env.local");
 	logger.success(`Saved the project ID and a development key to ${chalk.cyan(".env.local")}.`);
 }
 //#endregion
-export { provisionDevelopmentCredentials };
+export { checkDevelopmentProjectInputs, productionRuntimeKeyGuidance, provisionDevelopmentCredentials, resolveDevelopmentProject, signInForSetup };
 
 //# sourceMappingURL=developmentCredentials.js.map

package/dist/setup/developmentCredentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"developmentCredentials.js","names":[],"sources":["../../src/setup/developmentCredentials.ts"],"sourcesContent":["import path from 'node:path';\nimport chalk from 'chalk';\nimport { ProjectApiKeyPermission } from 'generaltranslation/api';\nimport { createDiagnosticMessage } from 'generaltranslation/diagnostics';\nimport { logger } from '../console/logger.js';\nimport {\n  logErrorAndExit,\n  promptSelect,\n  promptText,\n} from '../console/logging.js';\nimport type { Settings, SupportedFrameworks } from '../types/index.js';\nimport { api } from '../utils/api.js';\nimport {\n  inspectCredentialsEnvFile,\n  setCredentials,\n} from '../utils/credentials.js';\n\nconst DEVELOPMENT_KEY_NAME = 'Development key (gt init)';\n\ntype ProjectChoice = Awaited<ReturnType<typeof api.listProjects>>[number];\n\nfunction noCreatableOrgError(dashboardUrl: string): string {\n  return createDiagnosticMessage({\n    source: 'gt',\n    severity: 'Error',\n    whatHappened:\n      'You are not a member of an organization that can create projects',\n    fix: `Create an organization in the dashboard ${dashboardUrl} or ask an admin for access, then rerun the setup wizard`,\n  });\n}\n\nasync function createProject(settings: Settings, cwd: string) {\n  // Organizations are only needed to create; picking an existing project\n  // must work for members without create access.\n  const orgs = await api.listOrgs();\n  if (orgs.length === 0) {\n    return logErrorAndExit(noCreatableOrgError(settings.dashboardUrl));\n  }\n  const orgId =\n    orgs.length === 1\n      ? orgs[0].id\n      : await promptSelect({\n          message: 'Which organization should own the new project?',\n          options: orgs.map((org) => ({ value: org.id, label: org.name })),\n        });\n  const name = await promptText({\n    message: 'What should the project be called?',\n    defaultValue: path.basename(cwd),\n    validate: (value) => value.trim().length > 0 || 'Enter a project name',\n  });\n  const { project } = await api.createProject(orgId, {\n    name: name.trim() || path.basename(cwd),\n    defaultLocale: settings.defaultLocale,\n  });\n  logger.info(`Created ${project.name} (${project.id})`);\n  return project.id;\n}\n\nasync function selectProject(settings: Settings, cwd: string) {\n  const projects = await api.listProjects();\n  if (projects.length === 0) {\n    logger.info('No projects found for your account; creating one.');\n    return createProject(settings, cwd);\n  }\n  const choice = await promptSelect<ProjectChoice | null>({\n    message: 'Which project should this app use?',\n    options: [\n      ...projects.map((project) => ({\n        value: project,\n        label: project.name,\n        hint: project.orgName,\n      })),\n      { value: null, label: 'Create a new project' },\n    ],\n  });\n  return choice ? choice.id : createProject(settings, cwd);\n}\n\n/**\n * Picks or creates the project, mints a development key limited to runtime\n * translation, and saves both to .env.local. The file is checked before any\n * key exists, every service call completes before anything is written, and\n * the key is never printed.\n */\nexport async function provisionDevelopmentCredentials(\n  settings: Settings,\n  framework: SupportedFrameworks | undefined,\n  cwd: string = process.cwd()\n): Promise<void> {\n  await inspectCredentialsEnvFile(cwd);\n  const projectId = settings.projectId || (await selectProject(settings, cwd));\n  const { apiKey } = await api.createProjectApiKey(projectId, {\n    name: DEVELOPMENT_KEY_NAME,\n    permissions: [ProjectApiKeyPermission['PROJECT:TRANSLATIONS:GENERATE']],\n  });\n  await setCredentials({ projectId, apiKey: apiKey.key }, framework, cwd);\n  logger.success(\n    `Saved the project ID and a development key to ${chalk.cyan('.env.local')}.`\n  );\n}\n"],"mappings":";;;;;;;;;AAiBA,MAAM,uBAAuB;AAI7B,SAAS,oBAAoB,cAA8B;AACzD,QAAO,wBAAwB;EAC7B,QAAQ;EACR,UAAU;EACV,cACE;EACF,KAAK,2CAA2C,aAAa;EAC9D,CAAC;;AAGJ,eAAe,cAAc,UAAoB,KAAa;CAG5D,MAAM,OAAO,MAAM,IAAI,UAAU;AACjC,KAAI,KAAK,WAAW,EAClB,QAAO,gBAAgB,oBAAoB,SAAS,aAAa,CAAC;CAEpE,MAAM,QACJ,KAAK,WAAW,IACZ,KAAK,GAAG,KACR,MAAM,aAAa;EACjB,SAAS;EACT,SAAS,KAAK,KAAK,SAAS;GAAE,OAAO,IAAI;GAAI,OAAO,IAAI;GAAM,EAAE;EACjE,CAAC;CACR,MAAM,OAAO,MAAM,WAAW;EAC5B,SAAS;EACT,cAAc,KAAK,SAAS,IAAI;EAChC,WAAW,UAAU,MAAM,MAAM,CAAC,SAAS,KAAK;EACjD,CAAC;CACF,MAAM,EAAE,YAAY,MAAM,IAAI,cAAc,OAAO;EACjD,MAAM,KAAK,MAAM,IAAI,KAAK,SAAS,IAAI;EACvC,eAAe,SAAS;EACzB,CAAC;AACF,QAAO,KAAK,WAAW,QAAQ,KAAK,IAAI,QAAQ,GAAG,GAAG;AACtD,QAAO,QAAQ;;AAGjB,eAAe,cAAc,UAAoB,KAAa;CAC5D,MAAM,WAAW,MAAM,IAAI,cAAc;AACzC,KAAI,SAAS,WAAW,GAAG;AACzB,SAAO,KAAK,oDAAoD;AAChE,SAAO,cAAc,UAAU,IAAI;;CAErC,MAAM,SAAS,MAAM,aAAmC;EACtD,SAAS;EACT,SAAS,CACP,GAAG,SAAS,KAAK,aAAa;GAC5B,OAAO;GACP,OAAO,QAAQ;GACf,MAAM,QAAQ;GACf,EAAE,EACH;GAAE,OAAO;GAAM,OAAO;GAAwB,CAC/C;EACF,CAAC;AACF,QAAO,SAAS,OAAO,KAAK,cAAc,UAAU,IAAI;;;;;;;;AAS1D,eAAsB,gCACpB,UACA,WACA,MAAc,QAAQ,KAAK,EACZ;AACf,OAAM,0BAA0B,IAAI;CACpC,MAAM,YAAY,SAAS,aAAc,MAAM,cAAc,UAAU,IAAI;CAC3E,MAAM,EAAE,WAAW,MAAM,IAAI,oBAAoB,WAAW;EAC1D,MAAM;EACN,aAAa,CAAC,wBAAwB,iCAAiC;EACxE,CAAC;AACF,OAAM,eAAe;EAAE;EAAW,QAAQ,OAAO;EAAK,EAAE,WAAW,IAAI;AACvE,QAAO,QACL,iDAAiD,MAAM,KAAK,aAAa,CAAC,GAC3E"}
+{"version":3,"file":"developmentCredentials.js","names":[],"sources":["../../src/setup/developmentCredentials.ts"],"sourcesContent":["import path from 'node:path';\nimport chalk from 'chalk';\nimport { ProjectApiKeyPermission } from 'generaltranslation/api';\nimport {\n  createDiagnosticMessage,\n  formatDiagnosticErrorDetails,\n} from 'generaltranslation/diagnostics';\nimport { ApiError } from 'generaltranslation/errors';\nimport { logger } from '../console/logger.js';\nimport { promptConfirm, promptSelect, promptText } from '../console/logging.js';\nimport type { Settings, SupportedFrameworks } from '../types/index.js';\nimport { api } from '../utils/api.js';\nimport { setCredentials } from '../utils/credentials.js';\nimport { createUserAuthError } from '../auth/errors.js';\nimport { loginInteractively } from '../auth/interactiveLogin.js';\nimport { OnboardingError, type OnboardingSession } from './onboarding.js';\n\nconst DEVELOPMENT_KEY_NAME = 'Development key (gt init)';\n\n/** .env.local never reaches production; the runtime key there is set on the host. */\nexport function productionRuntimeKeyGuidance(dashboardUrl: string): string {\n  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.')}`;\n}\n\n/**\n * Interactive setup keeps the browser login with its device fallback;\n * noninteractive setup always shows a device code (and emits it as a JSON\n * event) and waits for a person to approve it, without opening a browser.\n */\nexport async function signInForSetup(\n  session: OnboardingSession,\n  baseUrl: string | undefined\n): Promise<void> {\n  try {\n    await loginInteractively(baseUrl, session.interactive, (deviceCode) =>\n      session.emit({ type: 'authorization_required', ...deviceCode })\n    );\n  } catch (error) {\n    throw new OnboardingError(createUserAuthError('Sign in failed', error));\n  }\n  logger.message('You are now signed in.');\n}\n\ntype ProjectChoice = Awaited<ReturnType<typeof api.listProjects>>[number];\n\n/** An existing project, or the inputs for creating one. */\nexport type DevelopmentProject =\n  | { id: string }\n  | { create: { orgId: string; name: string } };\n\nexport type DevelopmentProjectOptions = {\n  createProject?: boolean;\n  orgId?: string;\n  projectName?: string;\n};\n\nfunction noAccessibleOrgError(dashboardUrl: string): string {\n  return createDiagnosticMessage({\n    source: 'gt',\n    severity: 'Error',\n    whatHappened: 'No accessible organizations were found',\n    fix: `Create an organization in the dashboard ${dashboardUrl} or ask an admin for access, then rerun the setup wizard`,\n  });\n}\n\nfunction projectCreationDeniedError(orgId: string, error: unknown): string {\n  return createDiagnosticMessage({\n    source: 'gt',\n    severity: 'Error',\n    whatHappened: `Project creation was denied for organization ${orgId}`,\n    why: 'Listing an organization does not confirm permission to create projects in it',\n    fix: 'Ask an organization admin for org:projects:create, or use credentials that have that permission for this organization',\n    details: formatDiagnosticErrorDetails(error),\n  });\n}\n\nconst noProjectChosenError = createDiagnosticMessage({\n  source: 'gt',\n  severity: 'Error',\n  whatHappened: 'No project was chosen for the development credentials',\n  reassurance: 'No project files were changed',\n  fix: 'Rerun with --project-id <id> or --create-project, or skip them with --no-dev-credentials',\n});\n\nasync function resolveNewProject(\n  session: OnboardingSession,\n  settings: Settings,\n  options: DevelopmentProjectOptions,\n  cwd: string\n): Promise<DevelopmentProject | undefined> {\n  // Discovery lists accessible organizations, not creation permissions.\n  // The API enforces creation permission when provisioning the project.\n  const orgs = await api.listOrgs();\n  if (orgs.length === 0) {\n    throw new OnboardingError(noAccessibleOrgError(settings.dashboardUrl));\n  }\n  if (options.orgId && !orgs.some((org) => org.id === options.orgId)) {\n    session.reject(\n      `--org-id ${options.orgId} is not an accessible organization`\n    );\n  }\n  const orgId = await session.answer('--org-id', {\n    explicit: options.orgId,\n    // One organization is not a choice between options.\n    configured: orgs.length === 1 ? orgs[0].id : undefined,\n    ask: () =>\n      promptSelect({\n        message: 'Which organization should own the new project?',\n        options: orgs.map((org) => ({ value: org.id, label: org.name })),\n      }),\n  });\n  const name = await session.answer('--project-name', {\n    explicit: options.projectName?.trim() || undefined,\n    ask: async () =>\n      (\n        await promptText({\n          message: 'What should the project be called?',\n          defaultValue: path.basename(cwd),\n        })\n      ).trim() || path.basename(cwd),\n  });\n  return orgId && name ? { create: { orgId, name } } : undefined;\n}\n\n/**\n * Records project inputs a noninteractive run is missing, before signing in,\n * so it never waits for approval only to fail on a missing flag.\n */\nexport function checkDevelopmentProjectInputs(\n  session: OnboardingSession,\n  settings: Settings,\n  options: DevelopmentProjectOptions,\n  /** Where settings.projectId came from, so a person can remove it. */\n  projectIdSource: string\n): void {\n  if (settings.projectId && options.createProject) {\n    session.reject(\n      `--create-project cannot be combined with project ${settings.projectId} from ${projectIdSource}; remove --create-project to keep using it, or remove the project ID from ${projectIdSource} to create a new project`\n    );\n  }\n  if (settings.projectId || session.interactive) return;\n  if (!options.createProject) {\n    session.require('--project-id or --create-project');\n  } else if (!options.projectName?.trim()) {\n    session.require('--project-name');\n  }\n}\n\n/**\n * Chooses the project for development credentials without creating anything:\n * a supplied or configured ID, explicit creation inputs, or (interactively)\n * a selection among the account's projects.\n */\nexport async function resolveDevelopmentProject(\n  session: OnboardingSession,\n  settings: Settings,\n  options: DevelopmentProjectOptions,\n  cwd: string = process.cwd()\n): Promise<DevelopmentProject | undefined> {\n  if (settings.projectId) return { id: settings.projectId };\n  if (options.createProject) {\n    return resolveNewProject(session, settings, options, cwd);\n  }\n  const projects = await api.listProjects();\n  if (projects.length === 0) {\n    // Creating a project is its own choice, separate from creating a key.\n    const create = await session.answer('--project-id or --create-project', {\n      ask: () =>\n        promptConfirm({\n          message: 'No projects found for your account. Create a new project?',\n          defaultValue: true,\n        }),\n    });\n    if (create === false) throw new OnboardingError(noProjectChosenError);\n    return create\n      ? resolveNewProject(session, settings, options, cwd)\n      : undefined;\n  }\n  const choice = await session.answer<ProjectChoice | null>(\n    '--project-id or --create-project',\n    {\n      ask: () =>\n        promptSelect<ProjectChoice | null>({\n          message: 'Which project should this app use?',\n          options: [\n            ...projects.map((project) => ({\n              value: project,\n              label: project.name,\n              hint: project.orgName,\n            })),\n            { value: null, label: 'Create a new project' },\n          ],\n        }),\n    }\n  );\n  if (choice === undefined) return undefined;\n  return choice\n    ? { id: choice.id }\n    : resolveNewProject(session, settings, options, cwd);\n}\n\n/**\n * Creates the chosen project if needed, mints a development key limited to\n * runtime translation, and saves both to .env.local. Callers inspect\n * .env.local first; the key is never printed.\n */\nexport async function provisionDevelopmentCredentials(\n  session: OnboardingSession,\n  project: DevelopmentProject,\n  settings: Settings,\n  framework: SupportedFrameworks | undefined,\n  cwd: string = process.cwd()\n): Promise<void> {\n  let projectId: string;\n  if ('id' in project) {\n    projectId = project.id;\n  } else {\n    const { orgId, name } = project.create;\n    const { project: created } = await api\n      .createProject(orgId, { name, defaultLocale: settings.defaultLocale })\n      .catch((error: unknown) => {\n        if (!(error instanceof ApiError) || error.code !== 403) throw error;\n        throw new OnboardingError(projectCreationDeniedError(orgId, error));\n      });\n    logger.info(`Created ${created.name} (${created.id})`);\n    session.step(`created project ${created.id}`);\n    projectId = created.id;\n  }\n  const { apiKey } = await api.createProjectApiKey(projectId, {\n    name: DEVELOPMENT_KEY_NAME,\n    permissions: [ProjectApiKeyPermission['PROJECT:TRANSLATIONS:GENERATE']],\n  });\n  session.step('created a development key');\n  await setCredentials({ projectId, apiKey: apiKey.key }, framework, cwd);\n  session.step('saved development credentials to .env.local');\n  logger.success(\n    `Saved the project ID and a development key to ${chalk.cyan('.env.local')}.`\n  );\n}\n"],"mappings":"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"}

package/dist/setup/instructions/base.md

@@ -4,7 +4,7 @@ This project is using [General Translation](https://generaltranslation.com/docs/
 
 ## Configuration
 
-The General Translation configuration file is called `gt.config.json`. It is usually located in the root or src directory of a project.
+The General Translation configuration file is called `gt.config.json`. It is located in the root of a project; pass `--config` to use a different path.
 
 ```json
 {

package/dist/setup/onboarding.d.ts

@@ -0,0 +1,131 @@
+import { Command } from 'commander';
+import { type FrameworkObject, type SupportedReactFrameworks } from '../types/index.js';
+import { type SetupFileFormat } from '../formats/files/supportedFiles.js';
+import { type PackageManager } from '../utils/packageManager.js';
+/** Answers accepted by `gt configure` (and the gt-vue `gt init`). */
+export type ConfigureOptions = {
+    config: string;
+    src?: string[];
+    interactive?: boolean;
+    json?: boolean;
+    defaults?: boolean;
+    defaultLocale?: string;
+    locales?: string[];
+    storage?: 'local' | 'cdn';
+    translationsDir?: string;
+    fileFormats?: Array<SetupFileFormat | 'none'>;
+    filePatterns?: string[];
+    liveTranslations?: boolean;
+    devCredentials?: boolean;
+    projectId?: string;
+    createProject?: boolean;
+    orgId?: string;
+    projectName?: string;
+    packageManager?: string;
+};
+/** Answers accepted by the React-aware `gt init`. */
+export type InitOptions = ConfigureOptions & {
+    locadex?: boolean;
+    reactSetup?: boolean;
+    framework?: SupportedReactFrameworks;
+    format?: boolean;
+};
+/** Flags for every configuration question; values prefill interactive runs. */
+export declare function attachConfigureFlags(command: Command, sourceHelp: string): Command;
+/**
+ * Pre-action hooks, such as the monorepo version check, can exit before
+ * runOnboarding installs its own result reporting; `--json` callers still
+ * get a result. runOnboarding takes over once it starts.
+ */
+export declare function reportJsonExitsBeforeOnboarding(command: string): void;
+/** Configuration flags plus the React application setup and Locadex choices. */
+export declare function attachInitFlags(command: Command, sourceHelp: string): Command;
+export type OnboardingEvent = {
+    type: 'authorization_required';
+    verificationUri: string;
+    verificationUriComplete?: string;
+    userCode: string;
+} | {
+    type: 'handoff';
+    url: string;
+    reason: 'locadex';
+} | {
+    type: 'result';
+    command: string;
+    outcome: 'success' | 'needs_human_action' | 'failed';
+    completedSteps: string[];
+    url?: string;
+    /** Manual steps setup could not do, for needs_human_action. */
+    actions?: string[];
+    missingOptions?: string[];
+    error?: string;
+};
+/** Needs-input and validation failures, raised before setup changes files. */
+export declare class OnboardingError extends Error {
+    readonly missingOptions: string[];
+    constructor(message: string, missingOptions?: string[]);
+}
+/**
+ * One setup run: how unanswered questions are resolved, which options are
+ * still missing, and which steps already changed the project.
+ */
+export declare class OnboardingSession {
+    readonly command: string;
+    readonly interactive: boolean;
+    readonly json: boolean;
+    defaults: boolean;
+    readonly completedSteps: string[];
+    /** Manual steps left for a person; they make the outcome needs_human_action. */
+    readonly humanActions: string[];
+    private readonly missing;
+    private readonly invalid;
+    private reported;
+    constructor(command: string, options: Pick<ConfigureOptions, 'json' | 'interactive'>);
+    /**
+     * Explicit flag, then existing config, then the recommended value when
+     * defaults were accepted, then a prompt. Noninteractive runs use the
+     * fallback of an optional question, or record the option as missing.
+     */
+    answer<T>(option: string, { explicit, configured, recommended, fallback, ask, }: {
+        explicit?: T;
+        configured?: T;
+        recommended?: T;
+        fallback?: T;
+        ask: () => Promise<T>;
+    }): Promise<T | undefined>;
+    require(option: string): void;
+    reject(problem: string): void;
+    /** Stops before any change when an answer is missing or invalid. */
+    assertResolved(): void;
+    step(name: string): void;
+    emit(event: OnboardingEvent): void;
+    /** A result for exits that bypass runOnboarding (e.g. settings validation). */
+    reportUnexpectedExit(code: number): void;
+}
+export type OnboardingOutcome = {
+    outcome: 'success';
+} | {
+    outcome: 'needs_human_action';
+    url: string;
+};
+/**
+ * Runs one setup command: selects prompt and output modes, then reports the
+ * outcome. Failures exit nonzero with the steps that already ran.
+ */
+export declare function runOnboarding(command: string, options: Pick<ConfigureOptions, 'json' | 'interactive'>, run: (session: OnboardingSession) => Promise<OnboardingOutcome>): Promise<void>;
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+/** Reads the setup config, failing before any change when it is unusable. */
+export declare function readSetupConfig(configFilepath: string): Record<string, unknown>;
+export declare const INIT_SOURCE_HELP = "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}'";
+export declare function setupConfigPath(options: Pick<ConfigureOptions, 'config'>): string;
+export declare function getConfiguredFramework(config: Record<string, unknown>): SupportedReactFrameworks | 'mintlify' | undefined;
+/** JSON mode keeps the banner off stdout. */
+export declare function displaySetupHeader(session: OnboardingSession, message: string): void;
+export declare function describeDefaults(framework: FrameworkObject | undefined): string;
+/** Setup patterns name where each locale's files live, so they need [locale]. */
+export declare function validateSetupPattern(pattern: string): true | string;
+/** Parses `--file-patterns <format>=<glob>` values, grouped by format. */
+export declare function parseFilePatterns(session: OnboardingSession, values?: string[]): Map<SetupFileFormat, string[]>;
+/** Detects the package manager, or asks only when prompts are allowed. */
+export declare function resolvePackageManager(session: OnboardingSession, specified?: string): Promise<PackageManager | undefined>;
+export declare function installWithProgress(session: OnboardingSession, packageName: string, packageManager: PackageManager, asDevDependency: boolean): Promise<void>;