@amplitude/wizard 1.1.0 → 1.2.0

package/dist/src/lib/api.js

@@ -4,11 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiProjectSchema = exports.ApiUserSchema = void 0;
+exports.extractProjectId = extractProjectId;
 exports.fetchAmplitudeUser = fetchAmplitudeUser;
 exports.fetchBranches = fetchBranches;
 exports.fetchWorkspaceEventTypes = fetchWorkspaceEventTypes;
 exports.fetchOwnedDashboards = fetchOwnedDashboards;
 exports.fetchSources = fetchSources;
+exports.fetchHasAnyEventsMcp = fetchHasAnyEventsMcp;
 exports.fetchProjectActivationStatus = fetchProjectActivationStatus;
 exports.fetchSlackInstallUrl = fetchSlackInstallUrl;
 exports.fetchSlackConnectionStatus = fetchSlackConnectionStatus;
@@ -19,6 +21,7 @@ const zod_1 = require("zod");
 const analytics_js_1 = require("../utils/analytics.js");
 const debug_js_1 = require("../utils/debug.js");
 const constants_js_1 = require("./constants.js");
+const mcp_with_fallback_js_1 = require("./mcp-with-fallback.js");
 // ── Thunder URL helper ────────────────────────────────────────────────
 /**
  * Builds the Thunder GraphQL endpoint for the given zone and orgId.
@@ -68,6 +71,17 @@ const AmplitudeUserSchema = zod_1.z.object({
         })),
     }),
 });
+/**
+ * Extract the primary analytics project ID from a workspace.
+ * Picks the lowest-rank environment that has an app ID.
+ * Returns null if no such environment exists.
+ */
+function extractProjectId(ws) {
+    return ((ws.environments ?? [])
+        .slice()
+        .sort((a, b) => a.rank - b.rank)
+        .find((e) => e.app?.id)?.app?.id ?? null);
+}
 const ORGS_QUERY = `
 query orgs {
   orgs {
@@ -369,6 +383,110 @@ async function fetchSources(idToken, zone, orgId, workspaceId, branchId, version
         throw apiError;
     }
 }
+/**
+ * Checks whether the project has received any events via the Amplitude MCP server.
+ * Uses get_users with `_all` as the primary signal (userCount > 0 → events exist),
+ * then fetches get_events for display names.
+ *
+ * Falls back to a Claude agent with the Amplitude MCP configured if the direct
+ * HTTP call fails, so the check survives MCP API drift.
+ *
+ * Requires the numeric analytics project ID (from workspace.environments[].app.id),
+ * not the workspace UUID. Returns false on any error so callers can fall through.
+ */
+async function fetchHasAnyEventsMcp(accessToken, projectId) {
+    const NONE = {
+        hasEvents: false,
+        csvRows: [],
+        activeEventNames: [],
+        activeUsers: [],
+    };
+    const result = await (0, mcp_with_fallback_js_1.callAmplitudeMcp)({
+        accessToken,
+        label: 'fetchHasAnyEventsMcp',
+        direct: async (callTool) => {
+            // get_users with _all — primary signal for whether any events have been received.
+            // '_all' covers every event type without requiring taxonomy setup.
+            // metadata.userCount > 0 means at least one device has sent events to this project.
+            const usersText = await callTool(1, 'get_users', {
+                projectId,
+                event: { event_type: '_all', filters: [] },
+                limit: 5,
+            });
+            if (!usersText) {
+                (0, debug_js_1.logToFile)('[MCP] get_users: no text in response');
+                return null;
+            }
+            let activeUsers;
+            let hasEvents;
+            try {
+                const parsed = JSON.parse(usersText);
+                const userCount = parsed.metadata?.userCount ?? parsed.users?.length ?? 0;
+                hasEvents = userCount > 0;
+                activeUsers = (parsed.users ?? [])
+                    .filter((u) => u.amplitudeId ?? u.amplitude_id)
+                    .map((u) => ({
+                    amplitudeId: (u.amplitudeId ?? u.amplitude_id),
+                    userId: u.user_id ?? null,
+                }))
+                    .slice(0, 5);
+                (0, debug_js_1.logToFile)(`[MCP] get_users: userCount=${userCount}, hasEvents=${hasEvents}`);
+            }
+            catch (parseErr) {
+                (0, debug_js_1.logToFile)(`[MCP] get_users parse error: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+                return null;
+            }
+            if (!hasEvents)
+                return NONE;
+            // get_events — fetch active event names for the celebration display.
+            // isActive=true means events arrived within ~30 days.
+            const eventsText = await callTool(2, 'get_events', {
+                projectId,
+                limit: 10,
+            });
+            let activeEventNames = [];
+            if (eventsText) {
+                try {
+                    const parsed = JSON.parse(eventsText);
+                    activeEventNames = (parsed.events ?? [])
+                        .filter((e) => e.isActive && !e.isHidden && !e.isDeleted && e.name)
+                        .map((e) => e.name)
+                        .slice(0, 10);
+                    (0, debug_js_1.logToFile)(`[MCP] get_events: ${activeEventNames.length} active events`);
+                }
+                catch (parseErr) {
+                    (0, debug_js_1.logToFile)(`[MCP] get_events parse error: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+                }
+            }
+            return { hasEvents: true, csvRows: [], activeEventNames, activeUsers };
+        },
+        agentPrompt: `Use the Amplitude MCP to check whether project ${projectId} has received any events.
+Call get_users with event_type "_all" and limit 5. If userCount > 0, also call get_events with limit 10.
+Respond with JSON only — no prose, no markdown fences:
+{"hasEvents":true/false,"activeEventNames":["..."],"activeUsers":[{"amplitudeId":"...","userId":"..."}]}`,
+        parseAgent: (text) => {
+            const match = text.match(/\{[\s\S]*\}/);
+            if (!match)
+                return null;
+            try {
+                const parsed = JSON.parse(match[0]);
+                return {
+                    hasEvents: parsed.hasEvents ?? false,
+                    csvRows: [],
+                    activeEventNames: parsed.activeEventNames ?? [],
+                    activeUsers: (parsed.activeUsers ?? []).map((u) => ({
+                        amplitudeId: u.amplitudeId ?? '',
+                        userId: u.userId ?? null,
+                    })),
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+    });
+    return result ?? NONE;
+}
 // ── Project activation status ──────────────────────────────────────────────
 const ActivationStatusSchema = zod_1.z.object({
     data: zod_1.z.object({

package/dist/src/lib/commandments.js

@@ -26,6 +26,7 @@ CRITICAL — confirm_event_plan format:
   WRONG name: "Fires on the product detail page after product data loads"
   RIGHT name: "product viewed"
   Names longer than 50 characters will be automatically truncated.`,
+    `After all event and identity instrumentation is complete, you MUST create a dashboard via the Amplitude MCP. This is a hard requirement — do not skip it. Load the amplitude-chart-dashboard-plan skill (taxonomy category via wizard-tools) and follow it exactly. The dashboard is a first-class deliverable.`,
     ...(constants_js_1.DEMO_MODE
         ? [
             'DEMO MODE: This is a demo run. Limit the instrumentation plan to at most 5 events. Pick the 5 most impactful, representative events for the project. Be concise and fast — skip non-essential analysis.',

package/dist/src/lib/constants.d.ts

@@ -113,7 +113,7 @@ export declare const WIZARD_VARIANT_FLAG_KEY = "wizard-variant";
 /** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */
 export declare const WIZARD_VARIANTS: Record<string, Record<string, string>>;
 /** User-Agent for wizard HTTP requests and MCP server identification. */
-export declare const WIZARD_USER_AGENT = "amplitude/wizard; version: 1.1.0";
+export declare const WIZARD_USER_AGENT = "amplitude/wizard; version: 1.2.0";
 /** Header prefix for Amplitude properties. */
 export declare const AMPLITUDE_PROPERTY_HEADER_PREFIX = "X-AMPLITUDE-PROPERTY-";
 /** Header prefix for Amplitude feature flags. */

package/dist/src/lib/constants.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DETECTION_TIMEOUT_MS = exports.AMPLITUDE_FLAG_HEADER_PREFIX = exports.AMPLITUDE_PROPERTY_HEADER_PREFIX = exports.WIZARD_USER_AGENT = exports.WIZARD_VARIANTS = exports.WIZARD_VARIANT_FLAG_KEY = exports.DUMMY_PROJECT_API_KEY = exports.OUTBOUND_URLS = exports.DEFAULT_AMPLITUDE_ZONE = exports.AMPLITUDE_ZONE_SETTINGS = exports.OAUTH_PORT = exports.ANALYTICS_TEAM_TAG = exports.ANALYTICS_HOST_URL = exports.ANALYTICS_AMPLITUDE_PUBLIC_PROJECT_WRITE_KEY = exports.DEFAULT_HOST_URL = exports.DEFAULT_URL = exports.DEMO_MODE = exports.DEBUG = exports.IS_DEV = exports.Integration = void 0;
 // Kept in sync by release-please (x-release-please-version marker).
 // The prebuild script (sync-version.mjs) acts as a safety net.
-const VERSION = '1.1.0'; // x-release-please-version
+const VERSION = '1.2.0'; // x-release-please-version
 // ── Integration / CLI ───────────────────────────────────────────────
 /**
  * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks.

package/dist/src/lib/credential-resolution.js

@@ -10,6 +10,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCredentials = resolveCredentials;
 exports.resolveEnvironmentSelection = resolveEnvironmentSelection;
+const api_1 = require("./api");
+const analytics_1 = require("../utils/analytics");
 /**
  * Resolve credentials from stored OAuth tokens and environment data.
  *
@@ -105,6 +107,8 @@ async function resolveCredentials(session, options) {
                 const { fetchAmplitudeUser } = await import('./api.js');
                 try {
                     const userInfo = await fetchAmplitudeUser(storedToken.idToken, zone);
+                    analytics_1.analytics.setDistinctId(userInfo.email);
+                    analytics_1.analytics.identifyUser({ email: userInfo.email });
                     const workspaceId = session.selectedWorkspaceId ?? undefined;
                     // Find the relevant workspace and its environments
                     let envsWithKey = [];
@@ -296,6 +300,9 @@ async function resolveEnvironmentSelection(session, selection) {
     session.selectedWorkspaceId = ws.id;
     session.selectedWorkspaceName = ws.name;
     session.selectedProjectName = env.name;
+    // Extract the numeric analytics project ID for MCP-based event detection.
+    const projectId = (0, api_1.extractProjectId)(ws);
+    session.selectedProjectId = projectId;
     persistApiKey(apiKey, session.installDir);
     session.credentials = {
         accessToken: session.pendingAuthAccessToken ?? '',

package/dist/src/lib/framework-config.d.ts

@@ -95,6 +95,15 @@ export interface FrameworkDetection {
     minimumVersion?: string;
     /** Get the currently installed version. Called by runner for version check. */
     getInstalledVersion?: (options: WizardOptions) => Promise<string | undefined>;
+    /**
+     * Optional: Return dynamic version-check metadata when a framework can be
+     * backed by multiple packages with different minimum versions.
+     */
+    getVersionCheckInfo?: (options: WizardOptions) => Promise<{
+        version?: string;
+        minimumVersion?: string;
+        packageDisplayName?: string;
+    }>;
     /** Detect whether this framework is present in the project. */
     detect: (options: Pick<WizardOptions, 'installDir'>) => Promise<boolean>;
     /** Detect the project's package manager(s). Used by the in-process MCP tool. */

package/dist/src/lib/mcp-with-fallback.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Utility for making authenticated calls to the Amplitude MCP server with
+ * automatic Claude agent fallback.
+ *
+ * When the direct HTTP call fails (tool removed, auth error, parse failure,
+ * etc.) the function re-runs the same query via a minimal Claude agent that
+ * has only the Amplitude MCP server configured. This insulates callers from
+ * MCP API drift without requiring them to write two code paths.
+ */
+export declare const AMPLITUDE_MCP_URL: string;
+export type CallToolFn = (id: number, name: string, args: unknown) => Promise<string | null>;
+export interface CallAmplitudeMcpOptions<T> {
+    accessToken: string;
+    mcpUrl?: string;
+    /**
+     * The direct MCP call path. Receives a `callTool` helper bound to an open
+     * session. Return `null` to trigger the agent fallback.
+     */
+    direct: (callTool: CallToolFn) => Promise<T | null>;
+    /** Prompt sent to the Claude agent when the direct path returns null or throws. */
+    agentPrompt: string;
+    /** Extract the result from the agent's collected text output. Return null if unparseable. */
+    parseAgent: (text: string) => T | null;
+    label?: string;
+    agentTimeoutMs?: number;
+    /**
+     * Optional signal from the caller's AbortController. When aborted, in-flight
+     * fetch requests and the agent fallback subprocess are cancelled immediately.
+     * The top-level application should wire this to its exit / cleanup handler.
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Make an authenticated call to the Amplitude MCP server.
+ *
+ * 1. Opens an MCP session and calls `opts.direct(callTool)`.
+ * 2. If the direct call returns `null` or throws, falls back to a minimal
+ *    Claude agent with only the Amplitude MCP configured.
+ * 3. Passes the agent's text output to `opts.parseAgent` and returns the result.
+ *
+ * Returns `null` if both paths fail.
+ */
+export declare function callAmplitudeMcp<T>(opts: CallAmplitudeMcpOptions<T>): Promise<T | null>;

package/dist/src/lib/mcp-with-fallback.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Utility for making authenticated calls to the Amplitude MCP server with
+ * automatic Claude agent fallback.
+ *
+ * When the direct HTTP call fails (tool removed, auth error, parse failure,
+ * etc.) the function re-runs the same query via a minimal Claude agent that
+ * has only the Amplitude MCP server configured. This insulates callers from
+ * MCP API drift without requiring them to write two code paths.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AMPLITUDE_MCP_URL = void 0;
+exports.callAmplitudeMcp = callAmplitudeMcp;
+const path_1 = __importDefault(require("path"));
+const debug_js_1 = require("../utils/debug.js");
+const constants_js_1 = require("./constants.js");
+const schemas_js_1 = require("./middleware/schemas.js");
+exports.AMPLITUDE_MCP_URL = process.env.MCP_URL ?? 'https://mcp.amplitude.com/mcp';
+let _sdkModule = null;
+async function getSDKModule() {
+    if (!_sdkModule) {
+        const mod = await import('@anthropic-ai/claude-agent-sdk');
+        _sdkModule = { query: mod.query };
+    }
+    return _sdkModule;
+}
+function getClaudeCodeExecutablePath() {
+    const sdkPackagePath = require.resolve('@anthropic-ai/claude-agent-sdk');
+    return path_1.default.join(path_1.default.dirname(sdkPackagePath), 'cli.js');
+}
+// ── MCP session helpers ───────────────────────────────────────────────────────
+/**
+ * Open an MCP session and return a `callTool` helper bound to that session.
+ * Returns null if the session cannot be established.
+ */
+async function openMcpSession(accessToken, mcpUrl, signal) {
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+        'User-Agent': constants_js_1.WIZARD_USER_AGENT,
+    };
+    let sessionId;
+    try {
+        const initRes = await fetch(mcpUrl, {
+            method: 'POST',
+            headers: { ...headers, Accept: 'application/json, text/event-stream' },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 0,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: { name: 'amplitude-wizard', version: '1.0.0' },
+                },
+            }),
+            signal,
+        });
+        sessionId = initRes.headers.get('mcp-session-id') ?? undefined;
+        await initRes.body?.cancel().catch(() => undefined);
+    }
+    catch (err) {
+        (0, debug_js_1.logToFile)(`[MCP] initialize failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (!sessionId)
+        return null;
+    try {
+        const notifRes = await fetch(mcpUrl, {
+            method: 'POST',
+            headers: { ...headers, 'Mcp-Session-Id': sessionId },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                method: 'notifications/initialized',
+            }),
+            signal,
+        });
+        await notifRes.body?.cancel().catch(() => undefined);
+    }
+    catch {
+        (0, debug_js_1.logToFile)('[MCP] notifications/initialized failed (continuing)');
+    }
+    return async (id, name, args) => {
+        try {
+            const res = await fetch(mcpUrl, {
+                method: 'POST',
+                headers: {
+                    ...headers,
+                    'Mcp-Session-Id': sessionId,
+                    Accept: 'application/json, text/event-stream',
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id,
+                    method: 'tools/call',
+                    params: { name, arguments: args },
+                }),
+                signal,
+            });
+            const body = await res.text();
+            const sseData = body.match(/^data: (.+)$/m)?.[1] ?? '';
+            const rpc = JSON.parse(sseData);
+            if (rpc.error) {
+                (0, debug_js_1.logToFile)(`[MCP] ${name} rpc error: ${JSON.stringify(rpc.error)}`);
+                return null;
+            }
+            return rpc.result?.content?.[0]?.text ?? null;
+        }
+        catch (err) {
+            (0, debug_js_1.logToFile)(`[MCP] ${name} error: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    };
+}
+// ── Agent fallback ────────────────────────────────────────────────────────────
+const AGENT_FALLBACK_TIMEOUT_MS = 30_000;
+async function runAgentFallback(accessToken, mcpUrl, agentPrompt, timeoutMs, externalSignal) {
+    const { query } = await getSDKModule();
+    const cliPath = getClaudeCodeExecutablePath();
+    // Combine the timeout with any external abort signal.
+    // AbortSignal.any() requires Node 20.3+; we support 18.17+, so we wire it manually.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const onExternalAbort = () => controller.abort();
+    externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
+    const collectedText = [];
+    try {
+        const response = query({
+            prompt: agentPrompt,
+            options: {
+                claudeCodePath: cliPath,
+                permissionMode: 'bypassPermissions',
+                allowedTools: [],
+                mcpServers: {
+                    amplitude: {
+                        type: 'http',
+                        url: mcpUrl,
+                        headers: { Authorization: `Bearer ${accessToken}` },
+                    },
+                },
+                abortSignal: controller.signal,
+            },
+        });
+        for await (const rawMessage of response) {
+            const parsed = (0, schemas_js_1.safeParseSDKMessage)(rawMessage);
+            if (!parsed.ok)
+                continue;
+            const message = parsed.message;
+            if (message.type === 'assistant') {
+                const content = message.message?.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (block.type === 'text' && typeof block.text === 'string') {
+                            collectedText.push(block.text);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        (0, debug_js_1.logToFile)(`[MCP-fallback] agent error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+        externalSignal?.removeEventListener('abort', onExternalAbort);
+    }
+    return collectedText.join('');
+}
+/**
+ * Make an authenticated call to the Amplitude MCP server.
+ *
+ * 1. Opens an MCP session and calls `opts.direct(callTool)`.
+ * 2. If the direct call returns `null` or throws, falls back to a minimal
+ *    Claude agent with only the Amplitude MCP configured.
+ * 3. Passes the agent's text output to `opts.parseAgent` and returns the result.
+ *
+ * Returns `null` if both paths fail.
+ */
+async function callAmplitudeMcp(opts) {
+    const { accessToken, mcpUrl = exports.AMPLITUDE_MCP_URL, direct, agentPrompt, parseAgent, label = 'callAmplitudeMcp', agentTimeoutMs = AGENT_FALLBACK_TIMEOUT_MS, abortSignal, } = opts;
+    // ── Direct path ────────────────────────────────────────────────────────────
+    let directResult = null;
+    let useFallback = false;
+    const callTool = await openMcpSession(accessToken, mcpUrl, abortSignal);
+    if (callTool) {
+        try {
+            directResult = await direct(callTool);
+            if (directResult === null) {
+                (0, debug_js_1.logToFile)(`[${label}] direct returned null — trying agent fallback`);
+                useFallback = true;
+            }
+        }
+        catch (err) {
+            (0, debug_js_1.logToFile)(`[${label}] direct threw — trying agent fallback: ${err instanceof Error ? err.message : String(err)}`);
+            useFallback = true;
+        }
+    }
+    else {
+        (0, debug_js_1.logToFile)(`[${label}] MCP session failed — trying agent fallback`);
+        useFallback = true;
+    }
+    if (!useFallback)
+        return directResult;
+    // ── Agent fallback ────────────────────────────────────────────────────────
+    (0, debug_js_1.logToFile)(`[${label}] running agent fallback`);
+    const agentText = await runAgentFallback(accessToken, mcpUrl, agentPrompt, agentTimeoutMs, abortSignal);
+    if (!agentText) {
+        (0, debug_js_1.logToFile)(`[${label}] agent fallback produced no output`);
+        return null;
+    }
+    const parsed = parseAgent(agentText);
+    if (parsed === null) {
+        (0, debug_js_1.logToFile)(`[${label}] parseAgent returned null`);
+    }
+    return parsed;
+}

package/dist/src/lib/version-check.d.ts

@@ -0,0 +1,17 @@
+import type { FrameworkDetection } from './framework-config';
+import type { WizardOptions } from '../utils/types';
+export interface VersionCheckInfo {
+    version?: string;
+    minimumVersion?: string;
+    packageDisplayName?: string;
+}
+type VersionWarningOptions = {
+    coerceVersion?: boolean;
+};
+/**
+ * Resolve version-check metadata for frameworks that either rely on a single
+ * package (minimumVersion + getInstalledVersion) or multiple package backends.
+ */
+export declare function getVersionCheckInfo(detection: FrameworkDetection, options: WizardOptions): Promise<VersionCheckInfo>;
+export declare function getVersionWarning({ version, minimumVersion, packageDisplayName }: VersionCheckInfo, options?: VersionWarningOptions): string | undefined;
+export {};

package/dist/src/lib/version-check.js

@@ -0,0 +1,72 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVersionCheckInfo = getVersionCheckInfo;
+exports.getVersionWarning = getVersionWarning;
+const semver = __importStar(require("semver"));
+/**
+ * Resolve version-check metadata for frameworks that either rely on a single
+ * package (minimumVersion + getInstalledVersion) or multiple package backends.
+ */
+async function getVersionCheckInfo(detection, options) {
+    if (detection.getVersionCheckInfo) {
+        const info = await detection.getVersionCheckInfo(options);
+        return {
+            version: info.version,
+            minimumVersion: info.minimumVersion ?? detection.minimumVersion,
+            packageDisplayName: info.packageDisplayName ?? detection.packageDisplayName,
+        };
+    }
+    if (!detection.getInstalledVersion) {
+        return {};
+    }
+    return {
+        version: await detection.getInstalledVersion(options),
+        minimumVersion: detection.minimumVersion,
+        packageDisplayName: detection.packageDisplayName,
+    };
+}
+function getVersionWarning({ version, minimumVersion, packageDisplayName }, options = {}) {
+    if (!version || !minimumVersion || !packageDisplayName) {
+        return undefined;
+    }
+    const normalizedVersion = options.coerceVersion
+        ? semver.coerce(version)?.version
+        : semver.valid(version);
+    if (!normalizedVersion || !semver.lt(normalizedVersion, minimumVersion)) {
+        return undefined;
+    }
+    return `${packageDisplayName} ${version} is below minimum ${minimumVersion}`;
+}

package/dist/src/lib/wizard-session.d.ts

@@ -23,6 +23,7 @@ export declare const CliArgsSchema: z.ZodObject<{
     debug: z.ZodDefault<z.ZodBoolean>;
     verbose: z.ZodDefault<z.ZodBoolean>;
     ci: z.ZodDefault<z.ZodBoolean>;
+    agent: z.ZodDefault<z.ZodBoolean>;
     forceInstall: z.ZodDefault<z.ZodBoolean>;
     signup: z.ZodDefault<z.ZodBoolean>;
     localMcp: z.ZodDefault<z.ZodBoolean>;
@@ -110,6 +111,7 @@ export interface WizardSession {
     forceInstall: boolean;
     installDir: string;
     ci: boolean;
+    agent: boolean;
     signup: boolean;
     localMcp: boolean;
     apiKey?: string;
@@ -124,6 +126,15 @@ export interface WizardSession {
     detectedFrameworkLabel: string | null;
     /** True once framework detection has run (whether it found something or not) */
     detectionComplete: boolean;
+    /** Full results from parallel detection (all frameworks). Available for diagnostics. */
+    detectionResults: Array<{
+        integration: Integration;
+        detected: boolean;
+        durationMs: number;
+        timedOut: boolean;
+        error?: string;
+        version?: string;
+    }> | null;
     /**
      * Whether the currently selected project has existing event data.
      * null = not yet checked (shown as DataSetup screen)
@@ -191,6 +202,12 @@ export interface WizardSession {
     selectedWorkspaceName: string | null;
     /** Project/environment selected during SUSI (displayed in TitleBar). */
     selectedProjectName: string | null;
+    /**
+     * Numeric analytics project ID for the selected workspace (e.g. "769610").
+     * Sourced from workspace.environments[*].app.id at project selection time.
+     * Used by DataIngestionCheckScreen to call query_dataset via MCP.
+     */
+    selectedProjectId: string | null;
     /**
      * Notice shown on the API key entry step of AuthScreen.
      * Set when auto-fetch fails (e.g. user is not an org admin) so the user
@@ -242,15 +259,13 @@ export interface WizardSession {
      * the DataIngestionCheckScreen detects events via the API.
      */
     dataIngestionConfirmed: boolean;
-    /** Checklist item: whether the user's first chart has been created. */
-    checklistChartComplete: boolean;
-    /** Checklist item: whether the user's first dashboard has been created. */
-    checklistDashboardComplete: boolean;
     /**
-     * True once the user has dismissed the checklist (either all items done,
-     * or they chose to continue without completing everything).
+     * URL of the dashboard created by the agent during the conclude phase.
+     * Set when the agent writes .amplitude-dashboard.json and the watcher
+     * picks it up. Shown in OutroScreen as a direct link.
+     * Null until the agent creates a dashboard.
      */
-    checklistComplete: boolean;
+    checklistDashboardUrl: string | null;
     /** Email address of the authenticated user (from ~/.ampli.json stored profile). */
     userEmail: string | null;
     /**