@amplitude/wizard 1.0.0-beta.0

package/dist/src/utils/semver.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fulfillsVersionRange = fulfillsVersionRange;
+exports.createVersionBucket = createVersionBucket;
+const semver_1 = require("semver");
+function fulfillsVersionRange({ version, acceptableVersions, canBeLatest, }) {
+    if (version === 'latest') {
+        return canBeLatest;
+    }
+    let cleanedUserVersion, isRange;
+    if ((0, semver_1.valid)(version)) {
+        cleanedUserVersion = (0, semver_1.valid)(version);
+        isRange = false;
+    }
+    else if ((0, semver_1.validRange)(version)) {
+        cleanedUserVersion = (0, semver_1.validRange)(version);
+        isRange = true;
+    }
+    return (
+    // If the given version is a bogus format, this will still be undefined and we'll automatically reject it
+    !!cleanedUserVersion &&
+        (isRange
+            ? (0, semver_1.subset)(cleanedUserVersion, acceptableVersions)
+            : (0, semver_1.satisfies)(cleanedUserVersion, acceptableVersions)));
+}
+/**
+ * Creates a version bucket function for analytics.
+ * Converts versions like "1.2.3" to "1.x" for grouping in analytics.
+ *
+ * @param minMajorVersion - Optional minimum major version threshold.
+ *   Versions below this will be bucketed as "<{min}.0.0"
+ *
+ * @example
+ * const getVersionBucket = createVersionBucket(); // no minimum
+ * getVersionBucket("1.2.3") // "1.x"
+ *
+ * const getVersionBucket = createVersionBucket(11);
+ * getVersionBucket("15.3.0") // "15.x"
+ * getVersionBucket("10.0.0") // "<11.0.0"
+ */
+function createVersionBucket(minMajorVersion) {
+    return (version) => {
+        if (!version) {
+            return 'none';
+        }
+        try {
+            const minVer = (0, semver_1.minVersion)(version);
+            if (!minVer) {
+                return 'invalid';
+            }
+            const majorVersion = (0, semver_1.major)(minVer);
+            if (minMajorVersion !== undefined && majorVersion < minMajorVersion) {
+                return `<${minMajorVersion}.0.0`;
+            }
+            return `${majorVersion}.x`;
+        }
+        catch {
+            return 'unknown';
+        }
+    };
+}

package/dist/src/utils/setup-utils.d.ts

@@ -0,0 +1,82 @@
+import type { PackageDotJson } from './package-json';
+import { type PackageManager } from './package-manager';
+import type { CloudRegion, WizardOptions } from './types';
+export interface CliSetupConfig {
+    filename: string;
+    name: string;
+    gitignore: boolean;
+    likelyAlreadyHasAuthToken(contents: string): boolean;
+    tokenContent(authToken: string): string;
+    likelyAlreadyHasOrgAndProject(contents: string): boolean;
+    orgAndProjContent(org: string, project: string): string;
+    likelyAlreadyHasUrl?(contents: string): boolean;
+    urlContent?(url: string): string;
+}
+export interface CliSetupConfigContent {
+    authToken: string;
+    org?: string;
+    project?: string;
+    url?: string;
+}
+/** @deprecated Use wizardAbort() directly for new code. */
+export declare function abort(message?: string, status?: number): Promise<never>;
+export declare function isInGitRepo(): boolean;
+export declare function getUncommittedOrUntrackedFiles(): string[];
+export declare function isReact19Installed({ installDir, }: Pick<WizardOptions, 'installDir'>): Promise<boolean>;
+/**
+ * Installs or updates a package with the user's package manager.
+ *
+ * IMPORTANT: This function modifies the `package.json`! Be sure to re-read
+ * it if you make additional modifications to it after calling this function!
+ */
+export declare function installPackage({ packageName, alreadyInstalled, packageNameDisplayLabel, packageManager, forceInstall, integration, installDir, }: {
+    packageName: string;
+    alreadyInstalled: boolean;
+    packageNameDisplayLabel?: string;
+    packageManager?: PackageManager;
+    forceInstall?: boolean;
+    integration?: string;
+    installDir: string;
+}): Promise<{
+    packageManager?: PackageManager;
+}>;
+/**
+ * Get package.json or abort the wizard if not found.
+ * Only use where package.json is required (e.g., package install, overrides).
+ * For detection/version-checks, use tryGetPackageJson() instead.
+ */
+export declare function getPackageDotJson({ installDir, }: Pick<WizardOptions, 'installDir'>): Promise<PackageDotJson>;
+/**
+ * Try to get package.json, returning null if it doesn't exist.
+ * Use this for detection purposes where missing package.json is expected (e.g., Python projects).
+ */
+export declare function tryGetPackageJson({ installDir, }: Pick<WizardOptions, 'installDir'>): Promise<PackageDotJson | null>;
+export declare function updatePackageDotJson(packageDotJson: PackageDotJson, { installDir }: Pick<WizardOptions, 'installDir'>): Promise<void>;
+/**
+ * Detect and return the package manager. Pure — no prompts.
+ * Falls back to first detected or npm if ambiguous.
+ */
+export declare function getPackageManager(options: Pick<WizardOptions, 'installDir'> & {
+    ci?: boolean;
+}): Promise<PackageManager>;
+export declare function isUsingTypeScript({ installDir, }: Pick<WizardOptions, 'installDir'>): boolean;
+/**
+ * Get project data for the wizard via Amplitude OAuth or CI API key.
+ *
+ * Pass installDir to enable fresh-auth detection: when no local ampli.json
+ * exists, the cached ~/.ampli.json token is bypassed so the user explicitly
+ * authenticates and picks the right Amplitude account for this project.
+ */
+export declare function getOrAskForProjectData(_options: Pick<WizardOptions, 'signup' | 'ci' | 'apiKey' | 'projectId'> & {
+    installDir?: string;
+}): Promise<{
+    host: string;
+    projectApiKey: string;
+    accessToken: string;
+    projectId: number;
+    cloudRegion: CloudRegion;
+}>;
+/**
+ * Creates a new config file with the given filepath and codeSnippet.
+ */
+export declare function createNewConfigFile(filepath: string, codeSnippet: string, { installDir }: Pick<WizardOptions, 'installDir'>, moreInformation?: string): Promise<boolean>;

package/dist/src/utils/setup-utils.js

@@ -0,0 +1,467 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abort = abort;
+exports.isInGitRepo = isInGitRepo;
+exports.getUncommittedOrUntrackedFiles = getUncommittedOrUntrackedFiles;
+exports.isReact19Installed = isReact19Installed;
+exports.installPackage = installPackage;
+exports.getPackageDotJson = getPackageDotJson;
+exports.tryGetPackageJson = tryGetPackageJson;
+exports.updatePackageDotJson = updatePackageDotJson;
+exports.getPackageManager = getPackageManager;
+exports.isUsingTypeScript = isUsingTypeScript;
+exports.getOrAskForProjectData = getOrAskForProjectData;
+exports.createNewConfigFile = createNewConfigFile;
+const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const node_path_1 = require("node:path");
+const chalk_1 = __importDefault(require("chalk"));
+const telemetry_1 = require("../telemetry");
+const debug_1 = require("./debug");
+const package_manager_1 = require("./package-manager");
+const package_json_1 = require("./package-json");
+const constants_1 = require("../lib/constants");
+const analytics_1 = require("./analytics");
+const ui_1 = require("../ui");
+const oauth_1 = require("./oauth");
+const api_1 = require("../lib/api");
+const ampli_settings_1 = require("./ampli-settings");
+const constants_2 = require("../lib/constants");
+const urls_1 = require("./urls");
+const semver_1 = require("./semver");
+const wizard_abort_1 = require("./wizard-abort");
+/** @deprecated Use wizardAbort() directly for new code. */
+async function abort(message, status) {
+    return (0, wizard_abort_1.wizardAbort)({ message, exitCode: status });
+}
+function isInGitRepo() {
+    try {
+        childProcess.execSync('git rev-parse --is-inside-work-tree', {
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getUncommittedOrUntrackedFiles() {
+    try {
+        const gitStatus = childProcess
+            .execSync('git status --porcelain=v1', {
+            // we only care about stdout
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString();
+        const files = gitStatus
+            .split(os.EOL)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((f) => `- ${f.split(/\s+/)[1]}`);
+        return files;
+    }
+    catch {
+        return [];
+    }
+}
+async function isReact19Installed({ installDir, }) {
+    try {
+        const packageJson = await tryGetPackageJson({ installDir });
+        if (!packageJson)
+            return false;
+        const reactVersion = (0, package_json_1.getPackageVersion)('react', packageJson);
+        if (!reactVersion) {
+            return false;
+        }
+        return (0, semver_1.fulfillsVersionRange)({
+            version: reactVersion,
+            acceptableVersions: '>=19.0.0',
+            canBeLatest: true,
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Installs or updates a package with the user's package manager.
+ *
+ * IMPORTANT: This function modifies the `package.json`! Be sure to re-read
+ * it if you make additional modifications to it after calling this function!
+ */
+async function installPackage({ packageName, alreadyInstalled, packageNameDisplayLabel, packageManager, forceInstall = false, integration, installDir, }) {
+    return (0, telemetry_1.traceStep)('install-package', async () => {
+        const sdkInstallSpinner = (0, ui_1.getUI)().spinner();
+        const pkgManager = packageManager || (await getPackageManager({ installDir }));
+        const isReact19 = await isReact19Installed({ installDir });
+        const legacyPeerDepsFlag = isReact19 && pkgManager.name === 'npm' ? '--legacy-peer-deps' : '';
+        sdkInstallSpinner.start(`${alreadyInstalled ? 'Updating' : 'Installing'} ${chalk_1.default.bold.cyan(packageNameDisplayLabel ?? packageName)} with ${chalk_1.default.bold(pkgManager.label)}.`);
+        try {
+            await new Promise((resolve, reject) => {
+                childProcess.exec(`${pkgManager.installCommand} ${packageName} ${pkgManager.flags} ${forceInstall ? pkgManager.forceInstallFlag : ''} ${legacyPeerDepsFlag}`.trim(), { cwd: installDir }, (err, stdout, stderr) => {
+                    if (err) {
+                        fs.writeFileSync((0, node_path_1.join)(process.cwd(), `amplitude-wizard-installation-error-${Date.now()}.log`), JSON.stringify({
+                            stdout,
+                            stderr,
+                        }), { encoding: 'utf8' });
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        }
+        catch (e) {
+            sdkInstallSpinner.stop('Installation failed.');
+            (0, ui_1.getUI)().log.error(`${chalk_1.default.red('Encountered the following error during installation:')}\n\n${e}\n\n${chalk_1.default.dim(`The wizard has created a \`amplitude-wizard-installation-error-*.log\` file. If you think this issue is caused by the Amplitude wizard, create an issue on GitHub and include the log file's content:\n${constants_1.ISSUES_URL}`)}`);
+            await abort();
+        }
+        sdkInstallSpinner.stop(`${alreadyInstalled ? 'Updated' : 'Installed'} ${chalk_1.default.bold.cyan(packageNameDisplayLabel ?? packageName)} with ${chalk_1.default.bold(pkgManager.label)}.`);
+        analytics_1.analytics.wizardCapture('package installed', {
+            package_name: packageName,
+            package_manager: pkgManager.name,
+            integration,
+        });
+        return { packageManager: pkgManager };
+    });
+}
+/**
+ * Get package.json or abort the wizard if not found.
+ * Only use where package.json is required (e.g., package install, overrides).
+ * For detection/version-checks, use tryGetPackageJson() instead.
+ */
+async function getPackageDotJson({ installDir, }) {
+    const packageJsonFileContents = await fs.promises
+        .readFile((0, node_path_1.join)(installDir, 'package.json'), 'utf8')
+        .catch(() => {
+        (0, ui_1.getUI)().log.error('Could not find package.json. Make sure to run the wizard in the root of your app!');
+        return abort();
+    });
+    let packageJson = undefined;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        packageJson = JSON.parse(packageJsonFileContents);
+    }
+    catch {
+        (0, ui_1.getUI)().log.error(`Unable to parse your ${chalk_1.default.cyan('package.json')}. Make sure it has a valid format!`);
+        await abort();
+    }
+    return packageJson || {};
+}
+/**
+ * Try to get package.json, returning null if it doesn't exist.
+ * Use this for detection purposes where missing package.json is expected (e.g., Python projects).
+ */
+async function tryGetPackageJson({ installDir, }) {
+    try {
+        const packageJsonFileContents = await fs.promises.readFile((0, node_path_1.join)(installDir, 'package.json'), 'utf8');
+        return JSON.parse(packageJsonFileContents);
+    }
+    catch {
+        return null;
+    }
+}
+async function updatePackageDotJson(packageDotJson, { installDir }) {
+    try {
+        await fs.promises.writeFile((0, node_path_1.join)(installDir, 'package.json'), JSON.stringify(packageDotJson, null, 2), {
+            encoding: 'utf8',
+            flag: 'w',
+        });
+    }
+    catch {
+        (0, ui_1.getUI)().log.error(`Unable to update your ${chalk_1.default.cyan('package.json')}.`);
+        await abort();
+    }
+}
+/**
+ * Detect and return the package manager. Pure — no prompts.
+ * Falls back to first detected or npm if ambiguous.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function getPackageManager(options) {
+    const detectedPackageManagers = (0, package_manager_1.detectAllPackageManagers)({
+        installDir: options.installDir,
+    });
+    if (detectedPackageManagers.length >= 1) {
+        const selected = detectedPackageManagers[0];
+        analytics_1.analytics.setTag('package-manager', selected.name);
+        return selected;
+    }
+    // No package manager detected — default to npm
+    analytics_1.analytics.setTag('package-manager', package_manager_1.NPM.name);
+    return package_manager_1.NPM;
+}
+function isUsingTypeScript({ installDir, }) {
+    try {
+        return fs.existsSync((0, node_path_1.join)(installDir, 'tsconfig.json'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get project data for the wizard via Amplitude OAuth or CI API key.
+ *
+ * Pass installDir to enable fresh-auth detection: when no local ampli.json
+ * exists, the cached ~/.ampli.json token is bypassed so the user explicitly
+ * authenticates and picks the right Amplitude account for this project.
+ */
+async function getOrAskForProjectData(_options) {
+    // If an API key is provided (via --api-key flag, any mode), bypass OAuth entirely.
+    if (_options.apiKey) {
+        if (_options.ci) {
+            (0, ui_1.getUI)().log.info('Using provided API key (CI mode - OAuth bypassed)');
+        }
+        return {
+            host: constants_1.DEFAULT_HOST_URL,
+            projectApiKey: _options.apiKey,
+            accessToken: _options.apiKey,
+            projectId: _options.projectId ?? 0,
+            cloudRegion: 'us',
+        };
+    }
+    // Force fresh OAuth for projects that haven't been set up yet — no local
+    // ampli.json means we don't know which Amplitude org this project belongs to.
+    let forceFresh = false;
+    if (_options.installDir) {
+        const { ampliConfigExists } = await import('../lib/ampli-config.js');
+        forceFresh = !ampliConfigExists(_options.installDir);
+        if (forceFresh) {
+            (0, ui_1.getUI)().log.info(chalk_1.default.dim('No ampli.json found — starting fresh Amplitude authentication for this project.'));
+        }
+    }
+    const result = await (0, telemetry_1.traceStep)('login', () => askForWizardLogin({ forceFresh, installDir: _options.installDir }));
+    return {
+        accessToken: result.accessToken,
+        host: constants_1.DEFAULT_HOST_URL,
+        projectApiKey: result.projectApiKey,
+        projectId: result.projectId,
+        cloudRegion: result.cloudRegion,
+    };
+}
+async function askForWizardLogin(opts = {}) {
+    // ── 1. Authenticate via Amplitude OAuth (reuses ampli CLI session) ──
+    const auth = await (0, oauth_1.performAmplitudeAuth)({
+        zone: constants_2.DEFAULT_AMPLITUDE_ZONE,
+        forceFresh: opts.forceFresh,
+    });
+    // ── 2. Detect actual cloud region (EU users auth via US endpoint but
+    //       their data lives on EU servers — detectRegionFromToken probes both) ──
+    let cloudRegion = 'us';
+    try {
+        cloudRegion = await (0, urls_1.detectRegionFromToken)(auth.accessToken);
+    }
+    catch {
+        // Fall back to 'us' if region detection fails
+    }
+    // ── 3. Fetch user info from Amplitude Data API ────────────────────
+    let userInfo;
+    try {
+        userInfo = await (0, api_1.fetchAmplitudeUser)(auth.idToken, cloudRegion);
+    }
+    catch {
+        // Could not fetch user info — warn and continue without it
+        (0, ui_1.getUI)().log.warn(chalk_1.default.yellow('Could not fetch user info from Amplitude. Continuing without it.'));
+    }
+    let selectedOrg;
+    if (userInfo) {
+        // Persist user details back to ~/.ampli.json (replaces the "pending" entry)
+        (0, ampli_settings_1.storeToken)({
+            id: userInfo.id,
+            firstName: userInfo.firstName,
+            lastName: userInfo.lastName,
+            email: userInfo.email,
+            zone: auth.zone,
+        }, {
+            accessToken: auth.accessToken,
+            idToken: auth.idToken,
+            refreshToken: auth.refreshToken,
+            expiresAt: new Date(Date.now() + 3600 * 1000).toISOString(),
+        });
+        // ── 4. Org resolution (flowchart: sign-in → determine destination org) ──
+        if (userInfo.orgs.length === 0) {
+            // New user who hasn't created an org yet — direct them to the browser
+            (0, ui_1.getUI)().log.error(`${chalk_1.default.red('No Amplitude organization found.')}\n\n` +
+                chalk_1.default.dim('Your account has no organizations. Please complete signup at ' +
+                    chalk_1.default.cyan('https://app.amplitude.com') +
+                    ' and create an organization, then re-run the wizard.'));
+            await abort();
+        }
+        else if (userInfo.orgs.length === 1) {
+            selectedOrg = userInfo.orgs[0];
+        }
+        else {
+            // Multiple orgs — prompt the user to pick one
+            const { select } = await import('@inquirer/prompts');
+            selectedOrg = await select({
+                message: 'Select an Amplitude organization:',
+                choices: userInfo.orgs.map((org) => ({ name: org.name, value: org })),
+            });
+        }
+        (0, ui_1.getUI)().log.success(`Logged in as ${chalk_1.default.bold(userInfo.email)}${selectedOrg ? ` (${selectedOrg.name})` : ''}`);
+        analytics_1.analytics.setDistinctId(userInfo.id);
+        analytics_1.analytics.setTag('opened-wizard-link', true);
+    }
+    let selectedWorkspace;
+    if (selectedOrg) {
+        if (selectedOrg.workspaces.length === 1) {
+            selectedWorkspace = selectedOrg.workspaces[0];
+        }
+        else if (selectedOrg.workspaces.length > 1) {
+            const { select } = await import('@inquirer/prompts');
+            selectedWorkspace = await select({
+                message: `Select a workspace in ${selectedOrg.name}:`,
+                choices: selectedOrg.workspaces.map((ws) => ({
+                    name: ws.name,
+                    value: ws,
+                })),
+            });
+        }
+        // Write ~/.ampli.json so future runs recognise this project
+        if (opts.installDir && selectedWorkspace) {
+            const { writeAmpliConfig } = await import('../lib/ampli-config.js');
+            writeAmpliConfig(opts.installDir, {
+                OrgId: selectedOrg.id,
+                WorkspaceId: selectedWorkspace.id,
+                Zone: cloudRegion,
+            });
+        }
+    }
+    // ── 5. Get the Amplitude project API key ─────────────────────────
+    // The Data API returns apiKey on the Environment → App type, so we
+    // can grab it directly from the workspace data we already fetched.
+    // Falls back to Thunder's agentic API, then manual prompt.
+    let projectApiKey;
+    if (selectedWorkspace) {
+        // Get environments that have an app with an API key, sorted by rank (lowest = primary)
+        const envsWithKey = (selectedWorkspace.environments ?? [])
+            .filter((env) => env.app?.apiKey)
+            .sort((a, b) => a.rank - b.rank);
+        if (envsWithKey.length === 1) {
+            projectApiKey = envsWithKey[0].app.apiKey;
+            (0, ui_1.getUI)().log.success(chalk_1.default.dim(`Retrieved API key for ${chalk_1.default.bold(envsWithKey[0].name)} environment`));
+        }
+        else if (envsWithKey.length > 1) {
+            const { select } = await import('@inquirer/prompts');
+            const selectedEnv = await select({
+                message: 'Select an environment:',
+                choices: envsWithKey.map((env) => ({
+                    name: `${env.name} (${env.app.id})`,
+                    value: env,
+                })),
+            });
+            projectApiKey = selectedEnv.app.apiKey;
+            (0, ui_1.getUI)().log.success(chalk_1.default.dim(`Retrieved API key for ${chalk_1.default.bold(selectedEnv.name)} environment`));
+        }
+        // Persist so future runs don't need to fetch again
+        if (projectApiKey && opts.installDir) {
+            const { persistApiKey } = await import('./api-key-store.js');
+            const source = persistApiKey(projectApiKey, opts.installDir);
+            (0, ui_1.getUI)().log.success(chalk_1.default.dim(source === 'keychain'
+                ? 'API key saved to system keychain'
+                : 'API key saved to .env.local (added to .gitignore)'));
+        }
+    }
+    // Fall back to manual prompt if auto-fetch didn't work
+    if (!projectApiKey) {
+        projectApiKey = await askForAmplitudeApiKey(opts.installDir);
+    }
+    return {
+        accessToken: auth.idToken,
+        projectApiKey,
+        host: constants_1.DEFAULT_HOST_URL,
+        distinctId: userInfo?.id ?? 'unknown',
+        projectId: 0,
+        cloudRegion,
+    };
+}
+async function askForAmplitudeApiKey(installDir) {
+    const { readApiKeyWithSource, persistApiKey } = await import('./api-key-store.js');
+    // Return saved key if available
+    if (installDir) {
+        const result = readApiKeyWithSource(installDir);
+        if (result) {
+            (0, ui_1.getUI)().log.success(chalk_1.default.dim(result.source === 'keychain'
+                ? 'Using saved Amplitude API key from system keychain'
+                : 'Using saved Amplitude API key from .env.local'));
+            return result.key;
+        }
+    }
+    const { input } = await import('@inquirer/prompts');
+    (0, ui_1.getUI)().log.info(`\nTo finish setup, enter your Amplitude project ${chalk_1.default.bold('API Key')}.\n` +
+        chalk_1.default.dim(`Find it at: Amplitude → Settings → Projects → [your project] → API Keys\n`));
+    const apiKey = await input({
+        message: 'Amplitude API Key:',
+        validate: (v) => v.trim().length > 0 || 'API key cannot be empty',
+    });
+    const trimmed = apiKey.trim();
+    // Persist so the user doesn't have to enter it again
+    if (installDir) {
+        const source = persistApiKey(trimmed, installDir);
+        (0, ui_1.getUI)().log.success(chalk_1.default.dim(source === 'keychain'
+            ? 'API key saved to system keychain'
+            : 'API key saved to .env.local (added to .gitignore)'));
+    }
+    return trimmed;
+}
+/**
+ * Creates a new config file with the given filepath and codeSnippet.
+ */
+async function createNewConfigFile(filepath, codeSnippet, { installDir }, moreInformation) {
+    if (!(0, node_path_1.isAbsolute)(filepath)) {
+        (0, debug_1.debug)(`createNewConfigFile: filepath is not absolute: ${filepath}`);
+        return false;
+    }
+    const prettyFilename = chalk_1.default.cyan((0, node_path_1.relative)(installDir, filepath));
+    try {
+        await fs.promises.writeFile(filepath, codeSnippet);
+        (0, ui_1.getUI)().log.success(`Added new ${prettyFilename} file.`);
+        if (moreInformation) {
+            (0, ui_1.getUI)().log.info(chalk_1.default.gray(moreInformation));
+        }
+        return true;
+    }
+    catch (e) {
+        (0, debug_1.debug)(e);
+        (0, ui_1.getUI)().log.warn(`Could not create a new ${prettyFilename} file. Please create one manually and follow the instructions below.`);
+    }
+    return false;
+}

package/dist/src/utils/shell-completions.d.ts

@@ -0,0 +1,10 @@
+type SupportedShell = 'zsh' | 'bash';
+export declare function detectShell(): SupportedShell | null;
+export declare const ZSH_COMPLETION_SCRIPT = "###-begin-amplitude-wizard-completions-###\n\n_amplitude_wizard() {\n  local state\n  local -a commands global_opts wizard_opts\n\n  commands=(\n    'login:Log in to your Amplitude account'\n    'logout:Log out of your Amplitude account'\n    'whoami:Show the currently logged-in Amplitude account'\n    'slack:Set up Amplitude Slack integration'\n    'mcp:MCP server management commands'\n    'completion:Print shell completion script'\n  )\n\n  global_opts=(\n    '--debug[Enable verbose logging]'\n    '--verbose[Print diagnostic info to the run log]'\n    '--signup[Create a new Amplitude account during setup]'\n    '--ci[Enable non-interactive CI mode]'\n    '--api-key[Amplitude project API key]:key:'\n    '--project-id[Amplitude project ID]:id:'\n    '--local-mcp[Use local MCP server at http://localhost:8787/mcp]'\n    {-h,--help}'[Show help]'\n    {-v,--version}'[Show version]'\n  )\n\n  wizard_opts=(\n    '--force-install[Force package install even if peer checks fail]'\n    '--install-dir[Directory to install Amplitude in]:dir:_files -/'\n    '--integration[Framework integration to set up]:integration:(nextjs vue react-router django flask fastapi javascript_web javascript_node python)'\n    '--menu[Show integration selection menu instead of auto-detecting]'\n    '--benchmark[Run in benchmark mode with per-phase token tracking]'\n  )\n\n  _arguments -C \\\n    '1: :->cmd' \\\n    '*:: :->args'\n\n  case $state in\n    cmd)\n      _describe 'command' commands\n      _arguments $global_opts $wizard_opts\n      ;;\n    args)\n      case ${words[1]} in\n        mcp)\n          local -a mcp_cmds\n          mcp_cmds=('add:Install Amplitude MCP server' 'remove:Remove Amplitude MCP server')\n          _arguments -C '1: :->sub' '*:: :->subargs'\n          case $state in\n            sub) _describe 'mcp command' mcp_cmds ;;\n            subargs) _arguments '--local[Use local MCP server at http://localhost:8787]' ;;\n          esac\n          ;;\n        login)\n          _arguments '--zone[Amplitude data center zone]:zone:(us eu)'\n          ;;\n        *)\n          _arguments $global_opts $wizard_opts\n          ;;\n      esac\n      ;;\n  esac\n}\n\n(( $+functions[compdef] )) || { autoload -Uz compinit; compinit; }\ncompdef _amplitude_wizard amplitude-wizard\n###-end-amplitude-wizard-completions-###";
+export declare const BASH_COMPLETION_SCRIPT = "###-begin-amplitude-wizard-completions-###\n_amplitude_wizard_completions() {\n  local cur prev\n  cur=\"${COMP_WORDS[COMP_CWORD]}\"\n  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"\n\n  local commands=\"login logout whoami slack mcp completion\"\n  local global_flags=\"--debug --verbose --signup --ci --api-key --project-id --local-mcp --help --version\"\n  local wizard_flags=\"--force-install --install-dir --integration --menu --benchmark\"\n  local integrations=\"nextjs vue react-router django flask fastapi javascript_web javascript_node python\"\n\n  if [[ ${COMP_CWORD} -eq 1 ]]; then\n    COMPREPLY=($(compgen -W \"$commands $global_flags $wizard_flags\" -- \"$cur\"))\n    return\n  fi\n\n  case \"${COMP_WORDS[1]}\" in\n    mcp)\n      if [[ ${COMP_CWORD} -eq 2 ]]; then\n        COMPREPLY=($(compgen -W \"add remove\" -- \"$cur\"))\n      else\n        COMPREPLY=($(compgen -W \"--local\" -- \"$cur\"))\n      fi\n      ;;\n    login)\n      if [[ \"$prev\" == \"--zone\" ]]; then\n        COMPREPLY=($(compgen -W \"us eu\" -- \"$cur\"))\n      else\n        COMPREPLY=($(compgen -W \"--zone\" -- \"$cur\"))\n      fi\n      ;;\n    *)\n      if [[ \"$prev\" == \"--integration\" ]]; then\n        COMPREPLY=($(compgen -W \"$integrations\" -- \"$cur\"))\n      elif [[ \"$prev\" == \"--install-dir\" ]]; then\n        COMPREPLY=($(compgen -d -- \"$cur\"))\n      else\n        COMPREPLY=($(compgen -W \"$global_flags $wizard_flags\" -- \"$cur\"))\n      fi\n      ;;\n  esac\n}\ncomplete -F _amplitude_wizard_completions amplitude-wizard\n###-end-amplitude-wizard-completions-###";
+/**
+ * Silently appends `eval "$(amplitude-wizard completion)"` to the user's shell
+ * RC file if it isn't already there.  Call fire-and-forget at startup.
+ */
+export declare function installCompletions(): void;
+export {};