@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/dist/bin.js

@@ -37,12 +37,127 @@ if (!(0, semver_1.satisfies)(process.version, NODE_VERSION_RANGE)) {
     (0, logging_1.red)(`Amplitude wizard requires Node.js ${NODE_VERSION_RANGE}. You are using Node.js ${process.version}. Please upgrade your Node.js version.`);
     process.exit(1);
 }
-const run_1 = require("./src/run");
 const environment_1 = require("./src/utils/environment");
 const ui_1 = require("./src/ui");
 const logging_ui_1 = require("./src/ui/logging-ui");
 const shell_completions_1 = require("./src/utils/shell-completions");
-const api_key_store_1 = require("./src/utils/api-key-store");
+const exit_codes_1 = require("./src/lib/exit-codes");
+// Dynamic import to avoid preloading wizard-session.ts as CJS, which
+// prevents the TUI's ESM dynamic imports from resolving named exports.
+const lazyRunWizard = async (...args) => {
+    const { runWizard } = await import('./src/run.js');
+    return runWizard(...args);
+};
+/**
+ * Build a WizardSession from CLI argv, avoiding the repeated 12-field literal.
+ */
+const buildSessionFromOptions = async (options, overrides) => {
+    const { buildSession } = await import('./src/lib/wizard-session.js');
+    return buildSession({
+        debug: options.debug,
+        verbose: options.verbose,
+        forceInstall: options.forceInstall,
+        installDir: options.installDir,
+        ci: overrides?.ci ?? false,
+        signup: options.signup,
+        localMcp: options.localMcp,
+        apiKey: options.apiKey,
+        menu: options.menu,
+        integration: options.integration,
+        benchmark: options.benchmark,
+        projectId: options.projectId,
+    });
+};
+/**
+ * Shared credential resolution for non-interactive modes (agent + CI).
+ * Handles --api-key shortcut, OAuth token refresh, and pendingOrgs.
+ *
+ * @param mode - 'agent' prompts via AgentUI, 'ci' auto-selects first env
+ */
+const resolveNonInteractiveCredentials = async (session, options, mode, agentUI) => {
+    // If --api-key was provided, skip OAuth entirely
+    if (session.apiKey) {
+        const { DEFAULT_HOST_URL } = await import('./src/lib/constants.js');
+        session.credentials = {
+            accessToken: session.apiKey,
+            projectApiKey: session.apiKey,
+            host: DEFAULT_HOST_URL,
+            projectId: session.projectId ?? 0,
+        };
+        session.projectHasData = false;
+        return;
+    }
+    // Resolve credentials from stored OAuth tokens
+    const { resolveCredentials, resolveEnvironmentSelection } = await import('./src/lib/credential-resolution.js');
+    await resolveCredentials(session, {
+        requireOrgId: false,
+        org: options.org,
+        env: options.env,
+    });
+    // Handle multiple environments
+    if (session.pendingOrgs && !session.credentials) {
+        if (mode === 'ci') {
+            // CI mode: auto-select first environment with an API key
+            for (const org of session.pendingOrgs) {
+                for (const ws of org.workspaces) {
+                    const env = (ws.environments ?? [])
+                        .filter((e) => e.app?.apiKey)
+                        .sort((a, b) => a.rank - b.rank)[0];
+                    if (env) {
+                        await resolveEnvironmentSelection(session, {
+                            orgId: org.id,
+                            workspaceId: ws.id,
+                            env: env.name,
+                        });
+                        (0, ui_1.getUI)().log.info(`Resolved Amplitude API key non-interactively (CI mode): ${org.name} / ${ws.name} / ${env.name}`);
+                        break;
+                    }
+                }
+                if (session.credentials)
+                    break;
+            }
+        }
+        else if (agentUI) {
+            // Agent mode: list envs and prompt via stdin
+            const envList = [];
+            for (const org of session.pendingOrgs) {
+                for (const ws of org.workspaces) {
+                    for (const env of ws.environments ?? []) {
+                        if (env.app?.apiKey) {
+                            envList.push(`  --env "${env.name}"  (${org.name} / ${ws.name})`);
+                        }
+                    }
+                }
+            }
+            (0, ui_1.getUI)().log.info(`Multiple environments found. Re-run with one of:\n${envList.join('\n')}`);
+            const selection = await agentUI.promptEnvironmentSelection(session.pendingOrgs);
+            const resolved = await resolveEnvironmentSelection(session, selection);
+            if (!resolved) {
+                process.exit(exit_codes_1.ExitCode.AUTH_REQUIRED);
+            }
+        }
+    }
+    // If we still don't have credentials, auth is required
+    if (!session.credentials) {
+        if (mode === 'agent') {
+            (0, ui_1.getUI)().log.error('Could not resolve credentials. ' +
+                'Please log in first by running: amplitude-wizard login');
+            process.exit(exit_codes_1.ExitCode.AUTH_REQUIRED);
+        }
+        // CI mode falls through — runWizard will handle missing credentials
+    }
+    // Log what was resolved so the caller can see it
+    if (mode === 'agent' && session.credentials) {
+        const parts = [
+            session.selectedOrgName,
+            session.selectedWorkspaceName,
+            session.selectedProjectName,
+        ].filter(Boolean);
+        if (parts.length > 0) {
+            (0, ui_1.getUI)().log.info(`Using: ${parts.join(' / ')}`);
+        }
+    }
+};
 if (process.env.NODE_ENV === 'test') {
     void (async () => {
         try {
@@ -98,6 +213,14 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         describe: 'Amplitude project ID to use (optional; when not set, uses default from API key or OAuth)\nenv: AMPLITUDE_WIZARD_PROJECT_ID',
         type: 'string',
     },
+    org: {
+        describe: 'Amplitude org name to use (for multi-org accounts)\nenv: AMPLITUDE_WIZARD_ORG',
+        type: 'string',
+    },
+    env: {
+        describe: 'Environment name to use (e.g. "Production", "Development")\nenv: AMPLITUDE_WIZARD_ENV',
+        type: 'string',
+    },
 })
     .command(['$0'], 'Run the Amplitude setup wizard', (yargs) => {
     return yargs.options({
@@ -135,30 +258,62 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
             describe: 'Run in benchmark mode with per-phase token tracking\nenv: AMPLITUDE_WIZARD_BENCHMARK',
             type: 'boolean',
         },
+        agent: {
+            default: false,
+            describe: 'Run in agent mode with structured JSON output\nenv: AMPLITUDE_WIZARD_AGENT',
+            type: 'boolean',
+        },
+        yes: {
+            alias: 'y',
+            default: false,
+            describe: 'Skip all prompts and use defaults (same as --ci)',
+            type: 'boolean',
+        },
+        classic: {
+            default: false,
+            describe: 'Use the classic prompt-based UI instead of the rich TUI\nenv: AMPLITUDE_WIZARD_CLASSIC',
+            type: 'boolean',
+        },
     });
 }, (argv) => {
     const options = { ...argv };
     // CI mode validation and TTY check
-    if (options.ci) {
-        // Use LoggingUI for CI mode (no dependencies, no prompts)
+    if (options.agent ||
+        process.env.AMPLITUDE_WIZARD_AGENT === '1' ||
+        (!options.ci &&
+            !options.yes &&
+            !options.classic &&
+            process.env.AMPLITUDE_WIZARD_CLASSIC !== '1' &&
+            (0, environment_1.isNonInteractiveEnvironment)())) {
+        // Agent mode (explicit --agent or auto-detected non-TTY)
+        if (!options.agent)
+            options.agent = true;
+        void (async () => {
+            const { AgentUI } = await import('./src/ui/agent-ui.js');
+            const agentUI = new AgentUI();
+            (0, ui_1.setUI)(agentUI);
+            if (!options.installDir)
+                options.installDir = process.cwd();
+            const session = await buildSessionFromOptions(options);
+            await resolveNonInteractiveCredentials(session, options, 'agent', agentUI);
+            await lazyRunWizard(options, session);
+        })();
+    }
+    else if (options.ci || options.yes) {
+        // CI mode: no prompts, auto-select first environment
         (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
-        if (!options.installDir) {
-            (0, ui_1.getUI)().intro(chalk_1.default.inverse(`Amplitude Wizard`));
-            (0, ui_1.getUI)().log.error('CI mode requires --install-dir (directory to install Amplitude in)');
-            process.exit(1);
-        }
-        void (0, run_1.runWizard)(options);
+        if (!options.installDir)
+            options.installDir = process.cwd();
+        void (async () => {
+            const session = await buildSessionFromOptions(options, { ci: true });
+            await resolveNonInteractiveCredentials(session, options, 'ci');
+            await lazyRunWizard(options, session);
+        })();
     }
-    else if ((0, environment_1.isNonInteractiveEnvironment)()) {
-        // Non-interactive non-CI: error out
-        (0, ui_1.getUI)().intro(chalk_1.default.inverse(`Amplitude Wizard`));
-        (0, ui_1.getUI)().log.error('This installer requires an interactive terminal (TTY) to run.\n' +
-            'It appears you are running in a non-interactive environment.\n' +
-            'Please run the wizard in an interactive terminal.\n\n' +
-            'For CI/CD environments, use --ci mode:\n' +
-            '  npx @amplitude/wizard --ci --install-dir . [--api-key <your-key>]\n' +
-            '  (--api-key is optional when a key can be resolved from env or stored credentials.)');
-        process.exit(1);
+    else if (options.classic ||
+        process.env.AMPLITUDE_WIZARD_CLASSIC === '1') {
+        // Classic mode: interactive prompts without the rich TUI
+        void lazyRunWizard(options);
     }
     else {
         // Interactive TTY: launch the Ink TUI
@@ -168,23 +323,9 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
             installCompletions();
             try {
                 const { startTUI } = await import('./src/ui/tui/start-tui.js');
-                const { buildSession } = await import('./src/lib/wizard-session.js');
                 const tui = startTUI(WIZARD_VERSION);
                 // Build session from CLI args and attach to store
-                const session = buildSession({
-                    debug: options.debug,
-                    verbose: options.verbose,
-                    forceInstall: options.forceInstall,
-                    installDir: options.installDir,
-                    ci: false,
-                    signup: options.signup,
-                    localMcp: options.localMcp,
-                    apiKey: options.apiKey,
-                    menu: options.menu,
-                    integration: options.integration,
-                    benchmark: options.benchmark,
-                    projectId: options.projectId,
-                });
+                const session = await buildSessionFromOptions(options);
                 // If --api-key was provided, skip the OAuth/TUI auth flow entirely.
                 if (session.apiKey) {
                     const { DEFAULT_HOST_URL } = await import('./src/lib/constants.js');
@@ -197,170 +338,56 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     session.projectHasData = false;
                 }
                 else {
-                    // Pre-populate region + credentials from all available sources for
-                    // returning users. This skips RegionSelect and Auth without requiring
-                    // a persisted OAuth token.
-                    const installDir = session.installDir;
-                    const [{ getStoredUser, getStoredToken }, { readAmpliConfig }, { getAPIKey }, { getHostFromRegion }, { logToFile }, { fetchAmplitudeUser },] = await Promise.all([
-                        import('./src/utils/ampli-settings.js'),
-                        import('./src/lib/ampli-config.js'),
-                        import('./src/utils/get-api-key.js'),
-                        import('./src/utils/urls.js'),
-                        import('./src/utils/debug.js'),
-                        import('./src/lib/api.js'),
-                    ]);
-                    // Zone: prefer a real (non-pending) stored user, fall back to
-                    // the Zone field in the project-level ampli.json.
-                    const storedUser = getStoredUser();
-                    const realUser = storedUser && storedUser.id !== 'pending' ? storedUser : null;
-                    const projectConfig = readAmpliConfig(installDir);
-                    const projectZone = projectConfig.ok
-                        ? projectConfig.config.Zone
-                        : undefined;
-                    const zone = realUser?.zone ?? projectZone ?? null;
-                    if (zone) {
-                        session.region = zone;
-                    }
-                    // Skip Auth when we have a stored OAuth token — use it to fetch
-                    // (or look up) the project API key, then pre-populate credentials.
-                    // When the workspace has multiple environments (projects), defer to
-                    // AuthScreen so the user can pick which project to instrument.
-                    if (zone) {
-                        const storedToken = realUser
-                            ? getStoredToken(realUser.id, realUser.zone)
-                            : getStoredToken(undefined, zone);
-                        if (storedToken) {
-                            // Check local storage first — if a key is already persisted
-                            // for this install dir, use it without fetching user data.
-                            const { readApiKeyWithSource } = await import('./src/utils/api-key-store.js');
-                            const localKey = readApiKeyWithSource(installDir);
-                            if (localKey) {
-                                logToFile('[bin] using locally stored API key');
-                                session.credentials = {
-                                    accessToken: storedToken.idToken,
-                                    idToken: storedToken.idToken,
-                                    projectApiKey: localKey.key,
-                                    host: getHostFromRegion(zone),
-                                    projectId: 0,
-                                };
-                                session.activationLevel = 'none';
-                                session.projectHasData = false;
-                            }
-                            else {
-                                // Fetch user data to check how many environments are available.
-                                const { fetchAmplitudeUser } = await import('./src/lib/api.js');
-                                try {
-                                    const userInfo = await fetchAmplitudeUser(storedToken.idToken, zone);
-                                    const workspaceId = session.selectedWorkspaceId ?? undefined;
-                                    // Find the relevant workspace and its environments
-                                    let envsWithKey = [];
-                                    for (const org of userInfo.orgs) {
-                                        const ws = workspaceId
-                                            ? org.workspaces.find((w) => w.id === workspaceId)
-                                            : org.workspaces[0];
-                                        if (ws?.environments) {
-                                            envsWithKey = ws.environments
-                                                .filter((env) => env.app?.apiKey)
-                                                .sort((a, b) => a.rank - b.rank);
-                                            break;
-                                        }
-                                    }
-                                    if (envsWithKey.length === 1) {
-                                        // Single environment — auto-select as before
-                                        const apiKey = envsWithKey[0].app.apiKey;
-                                        session.selectedProjectName = envsWithKey[0].name;
-                                        logToFile('[bin] single environment — auto-selecting API key');
-                                        (0, api_key_store_1.persistApiKey)(apiKey, installDir);
-                                        session.credentials = {
-                                            accessToken: storedToken.idToken,
-                                            idToken: storedToken.idToken,
-                                            projectApiKey: apiKey,
-                                            host: getHostFromRegion(zone),
-                                            projectId: 0,
-                                        };
-                                        session.activationLevel = 'none';
-                                        session.projectHasData = false;
-                                    }
-                                    else if (envsWithKey.length > 1) {
-                                        // Multiple environments — show the project picker via
-                                        // AuthScreen instead of auto-selecting.
-                                        logToFile(`[bin] ${envsWithKey.length} environments found — deferring to project picker`);
-                                        session.pendingOrgs = userInfo.orgs;
-                                        session.pendingAuthIdToken = storedToken.idToken;
-                                        session.pendingAuthAccessToken = storedToken.idToken;
-                                    }
-                                    else {
-                                        logToFile('[bin] no environments with API keys — showing apiKeyNotice');
-                                        session.apiKeyNotice =
-                                            "Your API key couldn't be fetched automatically. " +
-                                                'Only organization admins can access project API keys — ' +
-                                                'if you need one, ask an admin to share it with you.';
-                                    }
-                                }
-                                catch (err) {
-                                    logToFile(`[bin] fetchAmplitudeUser failed: ${err instanceof Error ? err.message : 'unknown'}`);
-                                    // Fall back to getAPIKey for backward compatibility
-                                    const projectApiKey = await getAPIKey({
-                                        installDir,
-                                        idToken: storedToken.idToken,
-                                        zone,
-                                        workspaceId: session.selectedWorkspaceId ?? undefined,
-                                    });
-                                    if (projectApiKey) {
-                                        (0, api_key_store_1.persistApiKey)(projectApiKey, installDir);
-                                        session.credentials = {
-                                            accessToken: storedToken.idToken,
-                                            idToken: storedToken.idToken,
-                                            projectApiKey,
-                                            host: getHostFromRegion(zone),
-                                            projectId: 0,
-                                        };
-                                        session.activationLevel = 'none';
-                                        session.projectHasData = false;
-                                    }
-                                    else {
-                                        session.apiKeyNotice =
-                                            "Your API key couldn't be fetched automatically. " +
-                                                'Only organization admins can access project API keys — ' +
-                                                'if you need one, ask an admin to share it with you.';
-                                    }
-                                }
-                            }
-                        }
-                    }
-                    // Pre-populate org/workspace from ampli.json so activation checks
-                    // (DataSetupScreen, DataIngestionCheckScreen) have the IDs they need
-                    // even when the SUSI flow was skipped.
-                    if (projectConfig.ok && projectConfig.config.OrgId) {
-                        session.selectedOrgId = String(projectConfig.config.OrgId);
-                    }
-                    if (projectConfig.ok && projectConfig.config.WorkspaceId) {
-                        session.selectedWorkspaceId = projectConfig.config.WorkspaceId;
+                    // Pre-populate region + credentials from stored OAuth tokens.
+                    const { logToFile } = await import('./src/utils/debug.js');
+                    // Check for crash-recovery checkpoint
+                    const { loadCheckpoint } = await import('./src/lib/session-checkpoint.js');
+                    const checkpoint = loadCheckpoint(session.installDir);
+                    if (checkpoint) {
+                        Object.assign(session, checkpoint);
+                        session.introConcluded = false;
+                        session._restoredFromCheckpoint = true;
+                        logToFile('[bin] restored session from crash-recovery checkpoint');
                     }
+                    // Resolve credentials using shared logic (token refresh,
+                    // env auto-select, pendingOrgs population)
+                    const { resolveCredentials } = await import('./src/lib/credential-resolution.js');
+                    await resolveCredentials(session);
                     // Resolve org/workspace display names so /whoami shows them.
-                    // Uses the stored token to fetch user info — fire-and-forget so it
-                    // doesn't block startup.
-                    if (zone && session.selectedOrgId) {
+                    // Fire-and-forget so it doesn't block startup.
+                    if (session.region && session.selectedOrgId) {
+                        const { getStoredUser, getStoredToken } = await import('./src/utils/ampli-settings.js');
+                        const { fetchAmplitudeUser } = await import('./src/lib/api.js');
+                        const storedUser = getStoredUser();
+                        const realUser = storedUser && storedUser.id !== 'pending' ? storedUser : null;
+                        const zone = session.region;
                         const storedToken = realUser
                             ? getStoredToken(realUser.id, realUser.zone)
                             : getStoredToken(undefined, zone);
                         if (storedToken) {
                             fetchAmplitudeUser(storedToken.idToken, zone)
                                 .then((userInfo) => {
-                                const org = userInfo.orgs.find((o) => o.id === session.selectedOrgId);
-                                if (org) {
-                                    session.selectedOrgName = org.name;
-                                    const ws = session.selectedWorkspaceId
-                                        ? org.workspaces.find((w) => w.id === session.selectedWorkspaceId)
-                                        : undefined;
-                                    if (ws) {
-                                        session.selectedWorkspaceName = ws.name;
-                                    }
-                                    // Update the store if it's already been assigned
-                                    if (tui.store.session === session) {
-                                        tui.store.emitChange();
+                                let changed = false;
+                                if (userInfo.email && !session.userEmail) {
+                                    session.userEmail = userInfo.email;
+                                    changed = true;
+                                }
+                                if (session.selectedOrgId) {
+                                    const org = userInfo.orgs.find((o) => o.id === session.selectedOrgId);
+                                    if (org) {
+                                        session.selectedOrgName = org.name;
+                                        changed = true;
+                                        const ws = session.selectedWorkspaceId
+                                            ? org.workspaces.find((w) => w.id === session.selectedWorkspaceId)
+                                            : undefined;
+                                        if (ws) {
+                                            session.selectedWorkspaceName = ws.name;
+                                        }
                                     }
                                 }
+                                if (changed && tui.store.session === session) {
+                                    tui.store.emitChange();
+                                }
                             })
                                 .catch(() => {
                                 // Non-fatal — /whoami will just show (none)
@@ -369,6 +396,30 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     }
                 }
                 tui.store.session = session;
+                // Load event plan from a previous run (if it exists) so the
+                // Events tab is available immediately on returning runs.
+                try {
+                    const fs = await import('fs');
+                    const evtPath = (0, path_1.resolve)(session.installDir, '.amplitude-events.json');
+                    const evtContent = fs.readFileSync(evtPath, 'utf-8');
+                    const evtSchema = zod_1.z.array(zod_1.z.object({
+                        name: zod_1.z.string().optional(),
+                        event: zod_1.z.string().optional(),
+                        eventName: zod_1.z.string().optional(),
+                        description: zod_1.z.string().optional(),
+                        eventDescriptionAndReasoning: zod_1.z.string().optional(),
+                    }));
+                    const evtResult = evtSchema.safeParse(JSON.parse(evtContent));
+                    if (evtResult.success && evtResult.data.length > 0) {
+                        tui.store.setEventPlan(evtResult.data.map((e) => ({
+                            name: e.name ?? e.event ?? e.eventName ?? '',
+                            description: e.description ?? e.eventDescriptionAndReasoning ?? '',
+                        })));
+                    }
+                }
+                catch {
+                    // No event plan file yet — that's fine
+                }
                 // Initialize Amplitude Experiment feature flags (non-blocking).
                 const { initFeatureFlags } = await import('./src/lib/feature-flags.js');
                 await initFeatureFlags().catch(() => {
@@ -411,16 +462,18 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                         const { DEFAULT_AMPLITUDE_ZONE } = await import('./src/lib/constants.js');
                         const { storeToken } = await import('./src/utils/ampli-settings.js');
                         const forceFresh = !ampliConfigExists(installDir);
-                        // Wait for the user to pick a region (or for it to be pre-populated
-                        // from ~/.ampli.json for returning users) before opening the OAuth URL,
-                        // since the auth endpoint differs between US and EU.
+                        // Wait for the user to dismiss the welcome screen AND pick a
+                        // region before opening the OAuth URL. This ensures the logo
+                        // and intro are visible before the browser opens.
                         await new Promise((resolve) => {
-                            if (tui.store.session.region !== null) {
+                            if (tui.store.session.introConcluded &&
+                                tui.store.session.region !== null) {
                                 resolve();
                                 return;
                             }
                             const unsub = tui.store.subscribe(() => {
-                                if (tui.store.session.region !== null) {
+                                if (tui.store.session.introConcluded &&
+                                    tui.store.session.region !== null) {
                                     unsub();
                                     resolve();
                                 }
@@ -460,6 +513,8 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                             refreshToken: auth.refreshToken,
                             expiresAt: new Date(Date.now() + 3600 * 1000).toISOString(),
                         });
+                        // Populate user email for /whoami display
+                        session.userEmail = userInfo.email;
                         // Signal AuthScreen — triggers org/workspace/API key pickers
                         tui.store.setOAuthComplete({
                             accessToken: auth.accessToken,
@@ -564,6 +619,47 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                 // auth, data check, and any setup questions are all complete.
                 const { Screen } = await import('./src/ui/tui/router.js');
                 tui.store.onEnterScreen(Screen.Run, () => tui.store.completeSetup());
+                // Session checkpointing — save at key transitions so crash
+                // recovery can skip already-completed steps.
+                const { saveCheckpoint, clearCheckpoint } = await import('./src/lib/session-checkpoint.js');
+                // After auth completes (most expensive step to repeat)
+                tui.store.onEnterScreen(Screen.DataSetup, () => {
+                    saveCheckpoint(tui.store.session);
+                });
+                // Before agent starts (captures all setup state)
+                tui.store.onEnterScreen(Screen.Run, () => {
+                    saveCheckpoint(tui.store.session);
+                });
+                // Clear checkpoint only on successful completion — error/cancel
+                // should preserve the checkpoint so users can resume next run.
+                tui.store.onEnterScreen(Screen.Outro, () => {
+                    if (tui.store.session.outroData?.kind === 'success') {
+                        clearCheckpoint(tui.store.session.installDir);
+                    }
+                });
+                // Save checkpoint on unexpected termination (Ctrl+C).
+                // First Ctrl+C saves checkpoint and exits promptly.
+                // Second Ctrl+C within the grace window force-kills immediately.
+                let sigintReceived = false;
+                process.on('SIGINT', () => {
+                    if (sigintReceived) {
+                        // Second Ctrl+C — force-kill without waiting
+                        process.exit(130);
+                    }
+                    sigintReceived = true;
+                    // Force-kill after 1 second if checkpoint save hangs
+                    const forceTimer = setTimeout(() => process.exit(130), 1_000);
+                    // Unref so it doesn't keep the event loop alive
+                    if (forceTimer.unref)
+                        forceTimer.unref();
+                    try {
+                        saveCheckpoint(tui.store.session);
+                    }
+                    catch {
+                        // Best-effort — don't block exit
+                    }
+                    process.exit(130);
+                });
                 // Wait for auth and framework detection to finish concurrently.
                 await Promise.all([authTask, detectionTask]);
                 if (session.verbose || session.debug) {
@@ -589,14 +685,14 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     if (runWizardAnyway) {
                         log('[bin] user chose to run setup wizard despite pre-detection');
                         tui.store.resetForAgentAfterPreDetected();
-                        await (0, run_1.runWizard)(options, tui.store.session);
+                        await lazyRunWizard(options, tui.store.session);
                     }
                     else {
                         tui.store.setOutroData({ kind: OutroKind.Success });
                     }
                 }
                 else {
-                    await (0, run_1.runWizard)(options, tui.store.session);
+                    await lazyRunWizard(options, tui.store.session);
                 }
                 // Keep the outro screen visible — let process.exit() handle cleanup
             }
@@ -605,7 +701,7 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                 if (process.env.DEBUG || process.env.AMPLITUDE_WIZARD_DEBUG) {
                     console.error('TUI init failed:', err);
                 }
-                await (0, run_1.runWizard)(options);
+                await lazyRunWizard(options);
             }
         })();
     }
@@ -669,11 +765,13 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     void (async () => {
         const { getStoredUser, clearStoredCredentials } = await import('./src/utils/ampli-settings.js');
         const { clearApiKey } = await import('./src/utils/api-key-store.js');
+        const { clearCheckpoint } = await import('./src/lib/session-checkpoint.js');
         const installDir = argv.installDir ?? process.cwd();
         const user = getStoredUser();
         try {
             clearStoredCredentials();
             clearApiKey(installDir);
+            clearCheckpoint(installDir);
             if (user) {
                 console.log(chalk_1.default.green(`✔ Logged out ${user.email}`));
             }
@@ -703,7 +801,7 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         process.exit(0);
     })();
 })
-    .command('feedback', 'Send product feedback (Amplitude event: wizard: Feedback Submitted)', (yargs) => {
+    .command('feedback', 'Send product feedback', (yargs) => {
     return yargs.options({
         message: {
             alias: 'm',
@@ -734,39 +832,52 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         }
     })();
 })
-    .command('slack', 'Set up Amplitude Slack integration', (y) => y, (argv) => {
+    .command('slack', 'Set up Amplitude Slack integration', (y) => y, (_argv) => {
     void (async () => {
+        // Dynamic imports may land named exports on `.default` under tsx
+        // CJS/ESM interop. This helper normalises that.
+        const cjs = (mod) => (mod.default ?? mod);
         try {
-            const { startTUI } = await import('./src/ui/tui/start-tui.js');
-            const { buildSession } = await import('./src/lib/wizard-session.js');
-            const { Flow } = await import('./src/ui/tui/router.js');
-            const { getStoredUser, getStoredToken } = await import('./src/utils/ampli-settings.js');
-            const { getHostFromRegion } = await import('./src/utils/urls.js');
-            const session = buildSession({
-                debug: typeof argv['debug'] === 'boolean' ? argv['debug'] : undefined,
-            });
-            // Pre-populate credentials from ~/.ampli.json so SlackScreen can
-            // resolve the org name via fetchAmplitudeUser.
+            const { getStoredUser, getStoredToken } = cjs(await import('./src/utils/ampli-settings.js'));
+            const { readAmpliConfig } = cjs(await import('./src/lib/ampli-config.js'));
+            const { fetchSlackInstallUrl, fetchSlackConnectionStatus } = cjs(await import('./src/lib/api.js'));
+            const { OUTBOUND_URLS } = cjs(await import('./src/lib/constants.js'));
+            const opn = (await import('opn')).default;
             const storedUser = getStoredUser();
             const zone = storedUser?.zone ?? 'us';
             const storedToken = getStoredToken(storedUser?.id, zone);
-            if (storedToken) {
-                session.region = zone;
-                session.credentials = {
-                    accessToken: storedToken.idToken,
-                    projectApiKey: '',
-                    host: getHostFromRegion(zone),
-                    projectId: 0,
-                };
+            // Thunder validates access_tokens via Hydra, not id_tokens.
+            const accessToken = storedToken?.accessToken;
+            // Read orgId from project-level ampli.json
+            const ampliConfig = readAmpliConfig(process.cwd());
+            const orgId = ampliConfig.ok ? ampliConfig.config.OrgId : undefined;
+            if (!accessToken || !orgId) {
+                (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+                (0, ui_1.getUI)().log.info('No Amplitude session found. Run `npx @amplitude/wizard` first to log in and set up your project.');
+                process.exit(1);
+            }
+            // Check if Slack is already connected before prompting install.
+            const isConnected = await fetchSlackConnectionStatus(accessToken, zone, orgId);
+            if (isConnected) {
+                (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+                (0, ui_1.getUI)().log.info('Slack is already connected to your Amplitude workspace.');
+                process.exit(0);
             }
-            // Pass the pre-populated session so it's available before the first render.
-            startTUI(WIZARD_VERSION, Flow.SlackSetup, session);
+            const settingsUrl = OUTBOUND_URLS.slackSettings(zone, orgId);
+            let url = settingsUrl;
+            // Try to get the direct Slack OAuth URL from Thunder.
+            const directUrl = await fetchSlackInstallUrl(accessToken, zone, orgId, settingsUrl);
+            if (directUrl)
+                url = directUrl;
+            (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+            (0, ui_1.getUI)().log.info(`Opening Slack integration: ${url}`);
+            await opn(url, { wait: false });
         }
         catch {
             (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
-            const { getCloudUrlFromRegion } = await import('./src/utils/urls.js');
+            const { getCloudUrlFromRegion } = cjs(await import('./src/utils/urls.js'));
             const opn = (await import('opn')).default;
-            const url = `${getCloudUrlFromRegion('us')}/settings/profile`;
+            const url = `${getCloudUrlFromRegion('us')}/analytics/settings/profile`;
             (0, ui_1.getUI)().log.info(`Opening Amplitude Settings to connect Slack: ${url}`);
             await opn(url, { wait: false });
         }
@@ -791,7 +902,7 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
             const storedToken = getStoredToken(storedUser?.id, zone);
             if (storedToken) {
                 session.credentials = {
-                    accessToken: storedToken.idToken,
+                    accessToken: storedToken.accessToken,
                     projectApiKey: '',
                     host: getHostFromRegion(zone),
                     projectId: 0,
@@ -900,6 +1011,11 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     process.stdout.write(script + '\n');
     process.exit(0);
 })
+    .example('$0', 'Run the interactive setup wizard')
+    .example('$0 --ci --api-key <key> --install-dir .', 'Run in CI mode')
+    .example('$0 --agent --install-dir .', 'Run with structured JSON output for automation')
+    .epilogue('Docs: https://amplitude.com/docs/wizard\nFeedback: wizard@amplitude.com')
+    .recommendCommands()
     .help()
     .alias('help', 'h')
     .version()