@amplitude/wizard 1.0.0-beta.0

package/dist/src/lib/wizard-tools.js

@@ -0,0 +1,499 @@
+"use strict";
+/**
+ * Unified in-process MCP server for the Amplitude wizard.
+ *
+ * Provides tools that run locally (secret values never leave the machine):
+ * - check_env_keys: Check which env var keys exist in a .env file
+ * - set_env_values: Create/update env vars in a .env file
+ * - detect_package_manager: Detect the project's package manager(s)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WIZARD_TOOL_NAMES = void 0;
+exports.fetchSkillMenu = fetchSkillMenu;
+exports.downloadSkill = downloadSkill;
+exports.loadBundledSkillMenu = loadBundledSkillMenu;
+exports.installBundledSkill = installBundledSkill;
+exports.resolveEnvPath = resolveEnvPath;
+exports.ensureGitignoreCoverage = ensureGitignoreCoverage;
+exports.parseEnvKeys = parseEnvKeys;
+exports.mergeEnvValues = mergeEnvValues;
+exports.createWizardToolsServer = createWizardToolsServer;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const zod_1 = require("zod");
+const debug_1 = require("../utils/debug");
+const ui_1 = require("../ui");
+// ---------------------------------------------------------------------------
+// Remote skill helpers — for future use with amplitude/context-hub releases.
+// Currently unused; skills are bundled locally. Enable by setting SKILLS_URL
+// env var (e.g. https://github.com/amplitude/context-hub/releases/latest/download).
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the skill menu from a remote skills server (GitHub Releases).
+ * Returns parsed data on success, `null` on failure.
+ */
+async function fetchSkillMenu(skillsBaseUrl) {
+    try {
+        const menuUrl = `${skillsBaseUrl}/skill-menu.json`;
+        (0, debug_1.logToFile)(`fetchSkillMenu: fetching from ${menuUrl}`);
+        const resp = await fetch(menuUrl);
+        if (resp.ok) {
+            const data = (await resp.json());
+            (0, debug_1.logToFile)(`fetchSkillMenu: loaded (${Object.keys(data.categories).length} categories)`);
+            return data;
+        }
+        (0, debug_1.logToFile)(`fetchSkillMenu: failed with HTTP ${resp.status}`);
+        return null;
+    }
+    catch (err) {
+        (0, debug_1.logToFile)(`fetchSkillMenu: error: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Download and extract a skill from a remote URL.
+ * Installs to `<installDir>/.claude/skills/<id>/`.
+ */
+function downloadSkill(skillEntry, installDir) {
+    const { execFileSync } = require('child_process');
+    const skillDir = path_1.default.join(installDir, '.claude', 'skills', skillEntry.id);
+    const tmpFile = `/tmp/amplitude-skill-${skillEntry.id}.zip`;
+    try {
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        execFileSync('curl', ['-sL', skillEntry.downloadUrl, '-o', tmpFile], {
+            timeout: 30000,
+        });
+        execFileSync('unzip', ['-o', tmpFile, '-d', skillDir], {
+            timeout: 30000,
+        });
+        try {
+            fs_1.default.unlinkSync(tmpFile);
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+        (0, debug_1.logToFile)(`downloadSkill: installed ${skillEntry.id} from ${skillEntry.downloadUrl}`);
+        return { success: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        (0, debug_1.logToFile)(`downloadSkill: error: ${msg}`);
+        return { success: false, error: msg };
+    }
+}
+// ---------------------------------------------------------------------------
+// Bundled skill helpers — reads skills from wizard/skills/integration/
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the bundled skills root directory.
+ * Skills are shipped in `<wizardRoot>/skills/<category>/` subdirectories.
+ */
+function getSkillsRootDir() {
+    // Walk up from this file to find the wizard repo root (where skills/ lives)
+    let dir = __dirname;
+    for (let i = 0; i < 5; i++) {
+        if (fs_1.default.existsSync(path_1.default.join(dir, 'skills'))) {
+            return path_1.default.join(dir, 'skills');
+        }
+        dir = path_1.default.dirname(dir);
+    }
+    // Fallback: relative to cwd
+    return path_1.default.join(process.cwd(), 'skills');
+}
+/**
+ * Build skill menu from bundled skill directories.
+ * Scans skills/<category>/ subdirectories for folders containing SKILL.md.
+ * Each subdirectory of skills/ becomes a category (e.g. integration, instrumentation).
+ */
+function loadBundledSkillMenu() {
+    const skillsRoot = getSkillsRootDir();
+    (0, debug_1.logToFile)(`loadBundledSkillMenu: scanning ${skillsRoot}`);
+    const categories = {};
+    try {
+        for (const category of fs_1.default.readdirSync(skillsRoot)) {
+            const categoryPath = path_1.default.join(skillsRoot, category);
+            if (!fs_1.default.statSync(categoryPath).isDirectory())
+                continue;
+            const entries = [];
+            for (const name of fs_1.default.readdirSync(categoryPath)) {
+                const skillPath = path_1.default.join(categoryPath, name);
+                const skillMd = path_1.default.join(skillPath, 'SKILL.md');
+                if (fs_1.default.statSync(skillPath).isDirectory() && fs_1.default.existsSync(skillMd)) {
+                    // Extract display name from SKILL.md frontmatter
+                    const content = fs_1.default.readFileSync(skillMd, 'utf8');
+                    const descMatch = content.match(/^description:\s*>-?\s*\n\s+(.+)/m);
+                    const fallbackName = name
+                        .replace(new RegExp(`^${category}-`), '')
+                        .replace(/-/g, ' ');
+                    const displayName = descMatch ? descMatch[1].trim() : fallbackName;
+                    entries.push({ id: name, name: displayName, downloadUrl: '' });
+                }
+            }
+            if (entries.length > 0) {
+                categories[category] = entries;
+            }
+        }
+    }
+    catch (err) {
+        (0, debug_1.logToFile)(`loadBundledSkillMenu: error scanning: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const total = Object.values(categories).reduce((sum, entries) => sum + entries.length, 0);
+    (0, debug_1.logToFile)(`loadBundledSkillMenu: found ${total} skills across ${Object.keys(categories).length} categories`);
+    return { categories };
+}
+/**
+ * Install a bundled skill by copying it to the project's .claude/skills/ dir.
+ * Searches across all category subdirectories under skills/.
+ */
+function installBundledSkill(skillId, installDir) {
+    const skillsRoot = getSkillsRootDir();
+    const dest = path_1.default.join(installDir, '.claude', 'skills', skillId);
+    try {
+        for (const category of fs_1.default.readdirSync(skillsRoot)) {
+            const src = path_1.default.join(skillsRoot, category, skillId);
+            if (fs_1.default.existsSync(src) && fs_1.default.statSync(src).isDirectory()) {
+                fs_1.default.cpSync(src, dest, { recursive: true });
+                (0, debug_1.logToFile)(`installBundledSkill: copied ${skillId} from ${src} to ${dest}`);
+                return { success: true };
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        (0, debug_1.logToFile)(`installBundledSkill: error: ${msg}`);
+        return { success: false, error: msg };
+    }
+    return { success: false, error: `Bundled skill "${skillId}" not found` };
+}
+let _sdkModule = null;
+async function getSDKModule() {
+    if (!_sdkModule) {
+        _sdkModule = (await import('@anthropic-ai/claude-agent-sdk'));
+    }
+    return _sdkModule;
+}
+// ---------------------------------------------------------------------------
+// Env file helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve filePath relative to workingDirectory, rejecting path traversal.
+ */
+function resolveEnvPath(workingDirectory, filePath) {
+    const resolved = path_1.default.resolve(workingDirectory, filePath);
+    if (!resolved.startsWith(workingDirectory + path_1.default.sep) &&
+        resolved !== workingDirectory) {
+        throw new Error(`Path traversal rejected: "${filePath}" resolves outside working directory`);
+    }
+    return resolved;
+}
+/**
+ * Ensure the given env file basename is covered by .gitignore in the working directory.
+ * Creates .gitignore if it doesn't exist; appends the entry if missing.
+ */
+function ensureGitignoreCoverage(workingDirectory, envFileName) {
+    const gitignorePath = path_1.default.join(workingDirectory, '.gitignore');
+    if (fs_1.default.existsSync(gitignorePath)) {
+        const content = fs_1.default.readFileSync(gitignorePath, 'utf8');
+        // Check if the file (or a glob covering it) is already listed
+        if (content.split('\n').some((line) => line.trim() === envFileName)) {
+            return;
+        }
+        const newContent = content.endsWith('\n')
+            ? `${content}${envFileName}\n`
+            : `${content}\n${envFileName}\n`;
+        fs_1.default.writeFileSync(gitignorePath, newContent, 'utf8');
+    }
+    else {
+        fs_1.default.writeFileSync(gitignorePath, `${envFileName}\n`, 'utf8');
+    }
+}
+/**
+ * Parse a .env file's content and return the set of defined key names.
+ */
+function parseEnvKeys(content) {
+    const keys = new Set();
+    for (const line of content.split('\n')) {
+        const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (match) {
+            keys.add(match[1]);
+        }
+    }
+    return keys;
+}
+/**
+ * Merge key-value pairs into existing .env content.
+ * Updates existing keys in-place, appends new keys at the end.
+ */
+function mergeEnvValues(content, values) {
+    let result = content;
+    const updatedKeys = new Set();
+    for (const [key, value] of Object.entries(values)) {
+        const regex = new RegExp(`^(\\s*${key}\\s*=).*$`, 'm');
+        if (regex.test(result)) {
+            result = result.replace(regex, `$1${value}`);
+            updatedKeys.add(key);
+        }
+    }
+    const newKeys = Object.entries(values).filter(([key]) => !updatedKeys.has(key));
+    if (newKeys.length > 0) {
+        if (result.length > 0 && !result.endsWith('\n')) {
+            result += '\n';
+        }
+        for (const [key, value] of newKeys) {
+            result += `${key}=${value}\n`;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+const SERVER_NAME = 'wizard-tools';
+/**
+ * Create the unified in-process MCP server with all wizard tools.
+ * Must be called asynchronously because the SDK is an ESM module loaded via dynamic import.
+ */
+async function createWizardToolsServer(options) {
+    const { workingDirectory, detectPackageManager, skillsBaseUrl } = options;
+    const { tool, createSdkMcpServer } = await getSDKModule();
+    // Load skill menu: try remote first, fall back to bundled
+    const menu = skillsBaseUrl
+        ? (await fetchSkillMenu(skillsBaseUrl)) ?? loadBundledSkillMenu()
+        : loadBundledSkillMenu();
+    const cachedSkillMenu = menu?.categories ?? {};
+    const keys = Object.keys(cachedSkillMenu);
+    const categoryNames = keys.length > 0 ? keys : ['integration'];
+    // -- check_env_keys -------------------------------------------------------
+    const checkEnvKeys = tool('check_env_keys', 'Check which environment variable keys are present or missing in a .env file. Never reveals values.', {
+        filePath: zod_1.z
+            .string()
+            .describe('Path to the .env file, relative to the project root'),
+        keys: zod_1.z
+            .array(zod_1.z.string())
+            .describe('Environment variable key names to check'),
+    }, (args) => {
+        const resolved = resolveEnvPath(workingDirectory, args.filePath);
+        (0, debug_1.logToFile)(`check_env_keys: ${resolved}, keys: ${args.keys.join(', ')}`);
+        const existingKeys = fs_1.default.existsSync(resolved)
+            ? parseEnvKeys(fs_1.default.readFileSync(resolved, 'utf8'))
+            : new Set();
+        const results = {};
+        for (const key of args.keys) {
+            results[key] = existingKeys.has(key) ? 'present' : 'missing';
+        }
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(results, null, 2) },
+            ],
+        };
+    });
+    // -- set_env_values -------------------------------------------------------
+    const setEnvValues = tool('set_env_values', 'Create or update environment variable keys in a .env file. Creates the file if it does not exist. Ensures .gitignore coverage.', {
+        filePath: zod_1.z
+            .string()
+            .describe('Path to the .env file, relative to the project root'),
+        values: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.string())
+            .describe('Key-value pairs to set'),
+    }, (args) => {
+        const resolved = resolveEnvPath(workingDirectory, args.filePath);
+        (0, debug_1.logToFile)(`set_env_values: ${resolved}, keys: ${Object.keys(args.values).join(', ')}`);
+        const existing = fs_1.default.existsSync(resolved)
+            ? fs_1.default.readFileSync(resolved, 'utf8')
+            : '';
+        const content = mergeEnvValues(existing, args.values);
+        // Ensure parent directory exists
+        const dir = path_1.default.dirname(resolved);
+        if (!fs_1.default.existsSync(dir)) {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+        fs_1.default.writeFileSync(resolved, content, 'utf8');
+        // Ensure .gitignore coverage for this env file
+        const envFileName = path_1.default.basename(resolved);
+        ensureGitignoreCoverage(workingDirectory, envFileName);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Updated ${Object.keys(args.values).length} key(s) in ${args.filePath}`,
+                },
+            ],
+        };
+    });
+    // -- detect_package_manager -----------------------------------------------
+    const detectPM = tool('detect_package_manager', 'Detect which package manager(s) the project uses. Returns the name, install command, and run command for each detected package manager. Call this before running any install commands.', {}, async () => {
+        (0, debug_1.logToFile)(`detect_package_manager: scanning ${workingDirectory}`);
+        const result = await detectPackageManager(workingDirectory);
+        (0, debug_1.logToFile)(`detect_package_manager: detected ${result.detected.length} package manager(s)`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    // -- load_skill_menu ------------------------------------------------------
+    const loadSkillMenu = tool('load_skill_menu', 'Load available Amplitude skills for a category. Returns skill IDs and names. Call this first, then use install_skill with the chosen ID.', {
+        category: zod_1.z.enum(categoryNames).describe('Skill category'),
+    }, (args) => {
+        const skills = cachedSkillMenu[args.category];
+        if (!skills || skills.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No skills found for category "${args.category}".`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const menuText = skills.map((s) => `- ${s.id}: ${s.name}`).join('\n');
+        (0, debug_1.logToFile)(`load_skill_menu: returning ${skills.length} skills for "${args.category}"`);
+        return {
+            content: [{ type: 'text', text: menuText }],
+        };
+    });
+    // -- install_skill --------------------------------------------------------
+    const installSkill = tool('install_skill', 'Download and install an Amplitude skill by ID. Call load_skill_menu first to see available skills. Extracts the skill to .claude/skills/<skillId>/.', {
+        skillId: zod_1.z
+            .string()
+            .describe('Skill ID from the skill menu (e.g., "integration-nextjs-app-router")'),
+    }, (args) => {
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(args.skillId)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error: skillId must be lowercase alphanumeric with hyphens.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Look up download URL from cached menu
+        const allSkills = Object.values(cachedSkillMenu).flat();
+        const skill = allSkills.find((s) => s.id === args.skillId);
+        if (!skill) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: skill "${args.skillId}" not found. Use load_skill_menu to see available skills.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Try remote download if URL available, otherwise use bundled copy
+        const result = skill.downloadUrl
+            ? downloadSkill(skill, workingDirectory)
+            : installBundledSkill(args.skillId, workingDirectory);
+        if (result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Skill installed to .claude/skills/${args.skillId}/`,
+                    },
+                ],
+            };
+        }
+        else {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error installing skill: ${result.error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -- confirm --------------------------------------------------------------
+    const confirm = tool('confirm', 'Ask the user a yes/no question and wait for their answer. Returns true if confirmed, false if declined or skipped.', {
+        message: zod_1.z
+            .string()
+            .describe('The confirmation question to show the user'),
+    }, async (args) => {
+        (0, debug_1.logToFile)(`confirm: ${args.message}`);
+        const answer = await (0, ui_1.getUI)().promptConfirm(args.message);
+        return {
+            content: [{ type: 'text', text: answer ? 'true' : 'false' }],
+        };
+    });
+    // -- choose ---------------------------------------------------------------
+    const choose = tool('choose', 'Present the user with a list of options and wait for their selection. Returns the chosen option, or an empty string if skipped.', {
+        message: zod_1.z.string().describe('The prompt to show above the options'),
+        options: zod_1.z
+            .array(zod_1.z.string())
+            .min(2)
+            .describe('The list of choices to present'),
+    }, async (args) => {
+        (0, debug_1.logToFile)(`choose: ${args.message}, options: ${args.options.join(', ')}`);
+        const answer = await (0, ui_1.getUI)().promptChoice(args.message, args.options);
+        return {
+            content: [{ type: 'text', text: answer }],
+        };
+    });
+    // -- confirm_event_plan ---------------------------------------------------
+    const confirmEventPlan = tool('confirm_event_plan', `Present the proposed instrumentation plan to the user for review BEFORE instrumenting any events.
+Call this tool AFTER installing the SDK and adding initialization code, but BEFORE writing any track() calls.
+The user can approve the plan, skip the review, or give feedback.
+If the user gives feedback, revise your plan and call this tool again — loop until approved or skipped.
+Returns: "approved", "skipped", or "feedback: <user message>"`, {
+        events: zod_1.z
+            .array(zod_1.z.object({
+            name: zod_1.z.string().describe('Event name, e.g. "Button Clicked"'),
+            description: zod_1.z
+                .string()
+                .describe('When this event fires and what it tracks'),
+        }))
+            .min(1)
+            .describe('The list of events you plan to instrument'),
+    }, async (args) => {
+        (0, debug_1.logToFile)(`confirm_event_plan: ${args.events.length} events`);
+        const decision = await (0, ui_1.getUI)().promptEventPlan(args.events);
+        let text;
+        if (decision.decision === 'revised') {
+            text = `feedback: ${decision.feedback}`;
+        }
+        else {
+            text = decision.decision; // 'approved' or 'skipped'
+        }
+        (0, debug_1.logToFile)(`confirm_event_plan result: ${text}`);
+        return { content: [{ type: 'text', text }] };
+    });
+    // -- Assemble server ------------------------------------------------------
+    return createSdkMcpServer({
+        name: SERVER_NAME,
+        version: '1.0.0',
+        tools: [
+            checkEnvKeys,
+            setEnvValues,
+            detectPM,
+            loadSkillMenu,
+            installSkill,
+            confirm,
+            choose,
+            confirmEventPlan,
+        ],
+    });
+}
+/** Tool names exposed by the wizard-tools server, for use in allowedTools */
+exports.WIZARD_TOOL_NAMES = [
+    `${SERVER_NAME}:check_env_keys`,
+    `${SERVER_NAME}:set_env_values`,
+    `${SERVER_NAME}:detect_package_manager`,
+    `${SERVER_NAME}:load_skill_menu`,
+    `${SERVER_NAME}:install_skill`,
+    `${SERVER_NAME}:confirm`,
+    `${SERVER_NAME}:choose`,
+    `${SERVER_NAME}:confirm_event_plan`,
+];

package/dist/src/run.d.ts

@@ -0,0 +1,19 @@
+import { type WizardSession } from './lib/wizard-session';
+import { Integration } from './lib/constants';
+type Args = {
+    integration?: Integration;
+    debug?: boolean;
+    forceInstall?: boolean;
+    installDir?: string;
+    default?: boolean;
+    signup?: boolean;
+    localMcp?: boolean;
+    ci?: boolean;
+    apiKey?: string;
+    projectId?: string;
+    menu?: boolean;
+    benchmark?: boolean;
+};
+export declare function runWizard(argv: Args, session?: WizardSession): Promise<void>;
+export declare function detectIntegration(installDir: string): Promise<Integration | undefined>;
+export {};

package/dist/src/run.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWizard = runWizard;
+exports.detectIntegration = detectIntegration;
+const wizard_session_1 = require("./lib/wizard-session");
+const constants_1 = require("./lib/constants");
+const environment_1 = require("./utils/environment");
+const ui_1 = require("./ui");
+const path_1 = __importDefault(require("path"));
+const registry_1 = require("./lib/registry");
+const analytics_1 = require("./utils/analytics");
+const agent_runner_1 = require("./lib/agent-runner");
+const events_1 = require("events");
+const chalk_1 = __importDefault(require("chalk"));
+const debug_1 = require("./utils/debug");
+const wizard_abort_1 = require("./utils/wizard-abort");
+events_1.EventEmitter.defaultMaxListeners = 50;
+async function runWizard(argv, session) {
+    const finalArgs = {
+        ...argv,
+        ...(0, environment_1.readEnvironment)(),
+    };
+    let resolvedInstallDir;
+    if (finalArgs.installDir) {
+        if (path_1.default.isAbsolute(finalArgs.installDir)) {
+            resolvedInstallDir = finalArgs.installDir;
+        }
+        else {
+            resolvedInstallDir = path_1.default.join(process.cwd(), finalArgs.installDir);
+        }
+    }
+    else {
+        resolvedInstallDir = process.cwd();
+    }
+    // Build session if not provided (CI mode passes one pre-built)
+    if (!session) {
+        session = (0, wizard_session_1.buildSession)({
+            debug: finalArgs.debug,
+            forceInstall: finalArgs.forceInstall,
+            installDir: resolvedInstallDir,
+            ci: finalArgs.ci,
+            signup: finalArgs.signup,
+            localMcp: finalArgs.localMcp,
+            apiKey: finalArgs.apiKey,
+            menu: finalArgs.menu,
+            integration: finalArgs.integration,
+            benchmark: finalArgs.benchmark,
+            projectId: finalArgs.projectId,
+        });
+    }
+    session.installDir = resolvedInstallDir;
+    (0, ui_1.getUI)().intro(`Welcome to the Amplitude setup wizard`);
+    if (session.ci) {
+        (0, ui_1.getUI)().log.info(chalk_1.default.dim('Running in CI mode'));
+    }
+    const integration = session.integration ?? (await detectAndResolveIntegration(session));
+    session.integration = integration;
+    analytics_1.analytics.setTag('integration', integration);
+    analytics_1.analytics.wizardCapture('session started', {
+        integration,
+        ci: session.ci ?? false,
+    });
+    const config = registry_1.FRAMEWORK_REGISTRY[integration];
+    session.frameworkConfig = config;
+    // Run gatherContext if the framework has it and it hasn't already run
+    // (bin.ts runs it early so IntroScreen can show the friendly label)
+    const contextAlreadyGathered = Object.keys(session.frameworkContext).length > 0;
+    if (config.metadata.gatherContext && !contextAlreadyGathered) {
+        try {
+            const context = await config.metadata.gatherContext({
+                installDir: session.installDir,
+                debug: session.debug,
+                forceInstall: session.forceInstall,
+                default: false,
+                signup: session.signup,
+                localMcp: session.localMcp,
+                ci: session.ci,
+                menu: session.menu,
+                benchmark: session.benchmark,
+            });
+            for (const [key, value] of Object.entries(context)) {
+                if (!(key in session.frameworkContext)) {
+                    session.frameworkContext[key] = value;
+                }
+            }
+        }
+        catch {
+            // Detection failed — SetupScreen or agent will handle it
+        }
+    }
+    let retry = true;
+    while (retry) {
+        try {
+            await (0, agent_runner_1.runAgentWizard)(config, session);
+            retry = false;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error && error.stack ? error.stack : undefined;
+            (0, debug_1.logToFile)(`[Wizard run.ts] ERROR MESSAGE: ${errorMessage} `);
+            if (errorStack) {
+                (0, debug_1.logToFile)(`[Wizard run.ts] ERROR STACK: ${errorStack}`);
+            }
+            const debugInfo = session.debug && errorStack ? `\n\n${errorStack}` : '';
+            retry = await (0, ui_1.getUI)().setRunError(error);
+            if (!retry) {
+                await (0, wizard_abort_1.wizardAbort)({
+                    message: `Something went wrong: ${errorMessage}\n\nYou can read the documentation at ${config.metadata.docsUrl} to set up Amplitude manually.${debugInfo}`,
+                    error: error,
+                });
+            }
+        }
+    }
+}
+async function detectIntegration(installDir) {
+    for (const integration of Object.values(constants_1.Integration)) {
+        const config = registry_1.FRAMEWORK_REGISTRY[integration];
+        try {
+            const detected = await Promise.race([
+                config.detection.detect({ installDir }),
+                new Promise((resolve) => setTimeout(() => resolve(false), constants_1.DETECTION_TIMEOUT_MS)),
+            ]);
+            if (detected) {
+                return integration;
+            }
+        }
+        catch {
+            // Skip frameworks whose detection throws
+        }
+    }
+}
+async function detectAndResolveIntegration(session) {
+    if (!session.menu) {
+        const detectedIntegration = await detectIntegration(session.installDir);
+        if (detectedIntegration) {
+            (0, ui_1.getUI)().setDetectedFramework(registry_1.FRAMEWORK_REGISTRY[detectedIntegration].metadata.name);
+            return detectedIntegration;
+        }
+        // Framework not detected — fall back to generic Amplitude quickstart.
+        (0, ui_1.getUI)().log.warn("Couldn't detect your framework. Falling back to the Amplitude quickstart guide.");
+        return constants_1.Integration.generic;
+    }
+    // Fallback: in TUI mode the IntroScreen would handle this,
+    // but for CI mode or when detection fails, abort with guidance.
+    return (0, wizard_abort_1.wizardAbort)({
+        message: 'Could not auto-detect your framework. Please specify --integration on the command line.',
+    });
+}