@amplitude/wizard 1.0.0-beta.1 → 1.0.0-beta.5

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

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * Credential resolution — shared between TUI, agent, and CI modes.
+ *
+ * Reads stored OAuth tokens, refreshes them if needed, fetches the user's
+ * org/workspace/environment list, and populates session credentials when
+ * possible. When multiple environments exist, populates `pendingOrgs` so
+ * the caller (TUI AuthScreen or AgentUI NDJSON prompt) can handle selection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCredentials = resolveCredentials;
+exports.resolveEnvironmentSelection = resolveEnvironmentSelection;
+/**
+ * Resolve credentials from stored OAuth tokens and environment data.
+ *
+ * Mutates `session` in place:
+ * - Sets `session.credentials` when a single environment or local key is found
+ * - Sets `session.pendingOrgs` + `pendingAuthIdToken` + `pendingAuthAccessToken`
+ *   when multiple environments exist (caller must handle selection)
+ * - Sets `session.apiKeyNotice` when auto-fetch fails
+ *
+ * Skips entirely when `session.apiKey` is already set (--api-key flag) or
+ * `session.credentials` is already populated.
+ */
+async function resolveCredentials(session, options) {
+    // Already have credentials (e.g. from --api-key flag)
+    if (session.credentials || session.apiKey)
+        return;
+    const installDir = session.installDir;
+    const [{ getStoredUser, getStoredToken }, { readAmpliConfig }, { getAPIKey }, { getHostFromRegion }, { logToFile }, { persistApiKey, readApiKeyWithSource },] = await Promise.all([
+        import('../utils/ampli-settings.js'),
+        import('./ampli-config.js'),
+        import('../utils/get-api-key.js'),
+        import('../utils/urls.js'),
+        import('../utils/debug.js'),
+        import('../utils/api-key-store.js'),
+    ]);
+    // Resolve zone from stored user and project config
+    const storedUser = getStoredUser();
+    const realUser = storedUser && storedUser.id !== 'pending' ? storedUser : null;
+    if (realUser?.email) {
+        session.userEmail = realUser.email;
+    }
+    const projectConfig = readAmpliConfig(installDir);
+    const projectZone = projectConfig.ok ? projectConfig.config.Zone : undefined;
+    // Checkpoint region wins (user explicitly changed via /region),
+    // then project config, then global user zone.
+    const zone = (session._restoredFromCheckpoint ? session.region : null) ??
+        projectZone ??
+        realUser?.zone ??
+        null;
+    if (zone) {
+        session.region = zone;
+    }
+    // Try to resolve credentials from a stored OAuth token
+    if (zone) {
+        const storedToken = realUser
+            ? getStoredToken(realUser.id, realUser.zone)
+            : getStoredToken(undefined, zone);
+        if (storedToken) {
+            // Silent token refresh
+            const { tryRefreshToken } = await import('../utils/token-refresh.js');
+            const expiresAtMs = new Date(storedToken.expiresAt).getTime();
+            const refreshResult = await tryRefreshToken({
+                accessToken: storedToken.accessToken,
+                refreshToken: storedToken.refreshToken,
+                expiresAt: expiresAtMs,
+            }, zone);
+            if (refreshResult) {
+                const { storeToken } = await import('../utils/ampli-settings.js');
+                if (realUser) {
+                    storeToken(realUser, {
+                        ...storedToken,
+                        accessToken: refreshResult.accessToken,
+                        expiresAt: new Date(refreshResult.expiresAt).toISOString(),
+                        // Persist rotated refresh token if the server issued one
+                        ...(refreshResult.refreshToken
+                            ? { refreshToken: refreshResult.refreshToken }
+                            : {}),
+                    });
+                }
+                storedToken.accessToken = refreshResult.accessToken;
+                if (refreshResult.refreshToken) {
+                    storedToken.refreshToken = refreshResult.refreshToken;
+                }
+                logToFile('[credential-resolution] silently refreshed expired access token');
+            }
+            // Check local storage first — if a key is already persisted
+            // for this install dir, use it without fetching user data.
+            const localKey = readApiKeyWithSource(installDir);
+            if (localKey) {
+                logToFile('[credential-resolution] using locally stored API key');
+                session.credentials = {
+                    accessToken: storedToken.accessToken,
+                    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('./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 --env flag was provided, try to match across all orgs/workspaces
+                    if (options?.env) {
+                        const envMatch = options.env.toLowerCase();
+                        const orgFilter = options.org?.toLowerCase();
+                        for (const org of userInfo.orgs) {
+                            if (orgFilter && !org.name.toLowerCase().includes(orgFilter)) {
+                                continue;
+                            }
+                            for (const ws of org.workspaces) {
+                                const matchedEnv = (ws.environments ?? []).find((e) => e.app?.apiKey && e.name.toLowerCase() === envMatch);
+                                if (matchedEnv?.app?.apiKey) {
+                                    const apiKey = matchedEnv.app.apiKey;
+                                    session.selectedOrgId = org.id;
+                                    session.selectedOrgName = org.name;
+                                    session.selectedWorkspaceId = ws.id;
+                                    session.selectedWorkspaceName = ws.name;
+                                    session.selectedProjectName = matchedEnv.name;
+                                    if (!session.userEmail && userInfo.email) {
+                                        session.userEmail = userInfo.email;
+                                    }
+                                    logToFile(`[credential-resolution] --env matched: ${org.name} / ${ws.name} / ${matchedEnv.name}`);
+                                    persistApiKey(apiKey, installDir);
+                                    session.credentials = {
+                                        accessToken: storedToken.accessToken,
+                                        idToken: storedToken.idToken,
+                                        projectApiKey: apiKey,
+                                        host: getHostFromRegion(zone),
+                                        projectId: 0,
+                                    };
+                                    session.activationLevel = 'none';
+                                    session.projectHasData = false;
+                                    break;
+                                }
+                            }
+                            if (session.credentials)
+                                break;
+                        }
+                        if (!session.credentials) {
+                            logToFile(`[credential-resolution] --env "${options.env}" did not match any environment`);
+                        }
+                    }
+                    else if (envsWithKey.length === 1) {
+                        // Single environment — auto-select
+                        const apiKey = envsWithKey[0].app.apiKey;
+                        session.selectedProjectName = envsWithKey[0].name;
+                        // Populate org/workspace names
+                        for (const org of userInfo.orgs) {
+                            const ws = workspaceId
+                                ? org.workspaces.find((w) => w.id === workspaceId)
+                                : org.workspaces[0];
+                            if (ws?.environments?.some((e) => e.app?.apiKey === apiKey)) {
+                                session.selectedOrgId = org.id;
+                                session.selectedOrgName = org.name;
+                                session.selectedWorkspaceId = ws.id;
+                                session.selectedWorkspaceName = ws.name;
+                                break;
+                            }
+                        }
+                        if (!session.userEmail && userInfo.email) {
+                            session.userEmail = userInfo.email;
+                        }
+                        logToFile('[credential-resolution] single environment — auto-selecting API key');
+                        persistApiKey(apiKey, installDir);
+                        session.credentials = {
+                            accessToken: storedToken.accessToken,
+                            idToken: storedToken.idToken,
+                            projectApiKey: apiKey,
+                            host: getHostFromRegion(zone),
+                            projectId: 0,
+                        };
+                        session.activationLevel = 'none';
+                        session.projectHasData = false;
+                    }
+                    else if (envsWithKey.length > 1) {
+                        // Multiple environments — defer to caller for selection
+                        logToFile(`[credential-resolution] ${envsWithKey.length} environments found — deferring to project picker`);
+                        session.pendingOrgs = userInfo.orgs;
+                        session.pendingAuthIdToken = storedToken.idToken;
+                        session.pendingAuthAccessToken = storedToken.accessToken;
+                    }
+                    else {
+                        logToFile('[credential-resolution] 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(`[credential-resolution] fetchAmplitudeUser failed: ${err instanceof Error ? err.message : 'unknown'}`);
+                    // Fall back to getAPIKey for backward compatibility
+                    const projectApiKey = await getAPIKey({
+                        installDir,
+                        idToken: storedToken.idToken,
+                        zone: zone,
+                        workspaceId: session.selectedWorkspaceId ?? undefined,
+                    });
+                    if (projectApiKey) {
+                        persistApiKey(projectApiKey, installDir);
+                        session.credentials = {
+                            accessToken: storedToken.accessToken,
+                            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
+    // have the IDs they need even when the SUSI flow was skipped.
+    if (!session.selectedOrgId &&
+        projectConfig.ok &&
+        projectConfig.config.OrgId) {
+        session.selectedOrgId = String(projectConfig.config.OrgId);
+    }
+    if (!session.selectedWorkspaceId &&
+        projectConfig.ok &&
+        projectConfig.config.WorkspaceId) {
+        session.selectedWorkspaceId = projectConfig.config.WorkspaceId;
+    }
+    // Safety check: in TUI mode, clear credentials if no org/workspace ID
+    // so AuthScreen can force selection. In agent/CI mode, a local API key
+    // is sufficient — skip this check.
+    if (options?.requireOrgId !== false &&
+        session.credentials !== null &&
+        !session.selectedOrgId &&
+        !session.pendingOrgs) {
+        logToFile('[credential-resolution] credentials set but no org/workspace — clearing to force AuthScreen');
+        session.credentials = null;
+    }
+}
+/**
+ * Resolve environment selection from pendingOrgs.
+ *
+ * Given a selected org ID, workspace ID, and environment name,
+ * populates session.credentials from the matching environment.
+ * Returns true if credentials were populated.
+ */
+async function resolveEnvironmentSelection(session, selection) {
+    if (!session.pendingOrgs)
+        return false;
+    const { getHostFromRegion } = await import('../utils/urls.js');
+    const { persistApiKey } = await import('../utils/api-key-store.js');
+    const { logToFile } = await import('../utils/debug.js');
+    const org = session.pendingOrgs.find((o) => o.id === selection.orgId);
+    if (!org) {
+        logToFile(`[credential-resolution] org not found: ${selection.orgId}`);
+        return false;
+    }
+    const ws = org.workspaces.find((w) => w.id === selection.workspaceId);
+    if (!ws) {
+        logToFile(`[credential-resolution] workspace not found: ${selection.workspaceId}`);
+        return false;
+    }
+    const env = ws.environments?.find((e) => e.name.toLowerCase() === selection.env.toLowerCase());
+    if (!env?.app?.apiKey) {
+        logToFile(`[credential-resolution] environment not found or has no API key: ${selection.env}`);
+        return false;
+    }
+    const zone = (session.region ?? 'us');
+    const apiKey = env.app.apiKey;
+    session.selectedOrgId = org.id;
+    session.selectedOrgName = org.name;
+    session.selectedWorkspaceId = ws.id;
+    session.selectedWorkspaceName = ws.name;
+    session.selectedProjectName = env.name;
+    persistApiKey(apiKey, session.installDir);
+    session.credentials = {
+        accessToken: session.pendingAuthAccessToken ?? '',
+        idToken: session.pendingAuthIdToken ?? undefined,
+        projectApiKey: apiKey,
+        host: getHostFromRegion(zone),
+        projectId: 0,
+    };
+    session.activationLevel = 'none';
+    session.projectHasData = false;
+    logToFile(`[credential-resolution] resolved environment: ${org.name} / ${ws.name} / ${env.name}`);
+    return true;
+}

package/dist/src/lib/exit-codes.d.ts

@@ -0,0 +1,10 @@
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly INVALID_ARGS: 2;
+    readonly AUTH_REQUIRED: 3;
+    readonly NETWORK_ERROR: 4;
+    readonly AGENT_FAILED: 10;
+    readonly USER_CANCELLED: 130;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/src/lib/exit-codes.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExitCode = void 0;
+exports.ExitCode = {
+    SUCCESS: 0,
+    GENERAL_ERROR: 1,
+    INVALID_ARGS: 2,
+    AUTH_REQUIRED: 3,
+    NETWORK_ERROR: 4,
+    AGENT_FAILED: 10,
+    USER_CANCELLED: 130,
+};

package/dist/src/lib/feature-flags.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Feature flags powered by Amplitude Experiment (server-side local evaluation).
+ *
+ * Flags are fetched once at startup via `initFeatureFlags()` and evaluated
+ * synchronously thereafter — no per-check network calls.
+ */
+/** Gate for the LLM analytics additional-feature flow. */
+export declare const FLAG_LLM_ANALYTICS = "wizard-llm-analytics";
+/** Gate for agent-level analytics / telemetry instrumented by the wizard. */
+export declare const FLAG_AGENT_ANALYTICS = "wizard-agent-analytics";
+/**
+ * Initialize the Experiment local-evaluation client and pre-fetch flag configs.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ *
+ * @param userId  Optional user ID for targeted flag evaluation.
+ * @param deviceId  Optional device ID for targeted flag evaluation.
+ */
+export declare function initFeatureFlags(userId?: string, deviceId?: string): Promise<void>;
+/**
+ * Evaluate a single feature flag. Returns the string variant value,
+ * or `undefined` if the flag is not set / client not initialized.
+ */
+export declare function getFlag(flagKey: string): string | undefined;
+/**
+ * Check whether a flag is enabled (variant is `'on'` or `'true'`).
+ * Returns `false` when the flag is absent or the client is not initialized.
+ */
+export declare function isFlagEnabled(flagKey: string): boolean;
+/**
+ * Return a snapshot of all evaluated flags (key -> string value).
+ */
+export declare function getAllFlags(): Record<string, string>;
+/**
+ * Re-evaluate flags for a specific user (e.g. after login).
+ * Updates the cached flags in place.
+ */
+export declare function refreshFlags(userId?: string, deviceId?: string): Promise<void>;

package/dist/src/lib/feature-flags.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Feature flags powered by Amplitude Experiment (server-side local evaluation).
+ *
+ * Flags are fetched once at startup via `initFeatureFlags()` and evaluated
+ * synchronously thereafter — no per-check network calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLAG_AGENT_ANALYTICS = exports.FLAG_LLM_ANALYTICS = void 0;
+exports.initFeatureFlags = initFeatureFlags;
+exports.getFlag = getFlag;
+exports.isFlagEnabled = isFlagEnabled;
+exports.getAllFlags = getAllFlags;
+exports.refreshFlags = refreshFlags;
+const experiment_node_server_1 = require("@amplitude/experiment-node-server");
+const debug_1 = require("../utils/debug");
+// ── Flag keys ────────────────────────────────────────────────────────
+/** Gate for the LLM analytics additional-feature flow. */
+exports.FLAG_LLM_ANALYTICS = 'wizard-llm-analytics';
+/** Gate for agent-level analytics / telemetry instrumented by the wizard. */
+exports.FLAG_AGENT_ANALYTICS = 'wizard-agent-analytics';
+// ── Deployment key ───────────────────────────────────────────────────
+/**
+ * Server deployment key for local evaluation.
+ * Override with `AMPLITUDE_EXPERIMENT_DEPLOYMENT_KEY` env var.
+ */
+const DEFAULT_DEPLOYMENT_KEY = 'server-YOTsk4MS1RWzLyIf1DmvNDUsdOGqkRdM';
+function resolveDeploymentKey() {
+    const fromEnv = process.env.AMPLITUDE_EXPERIMENT_DEPLOYMENT_KEY;
+    return (fromEnv ?? DEFAULT_DEPLOYMENT_KEY).trim();
+}
+// ── Singleton client ─────────────────────────────────────────────────
+let client = null;
+let cachedFlags = {};
+/**
+ * Initialize the Experiment local-evaluation client and pre-fetch flag configs.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ *
+ * @param userId  Optional user ID for targeted flag evaluation.
+ * @param deviceId  Optional device ID for targeted flag evaluation.
+ */
+async function initFeatureFlags(userId, deviceId) {
+    if (client)
+        return; // already initialized
+    const deploymentKey = resolveDeploymentKey();
+    if (!deploymentKey) {
+        (0, debug_1.debug)('feature-flags: no deployment key — all flags default to off');
+        return;
+    }
+    try {
+        client = experiment_node_server_1.Experiment.initializeLocal(deploymentKey);
+        await client.start();
+        const user = {};
+        if (userId)
+            user.user_id = userId;
+        if (deviceId)
+            user.device_id = deviceId;
+        const variants = client.evaluateV2(user);
+        for (const [key, variant] of Object.entries(variants)) {
+            if (variant.value !== undefined && variant.value !== null) {
+                cachedFlags[key] = String(variant.value);
+            }
+        }
+        (0, debug_1.debug)('feature-flags: initialized with flags', cachedFlags);
+    }
+    catch (err) {
+        (0, debug_1.debug)('feature-flags: initialization failed, defaulting all flags off', err);
+        client = null;
+    }
+}
+/**
+ * Evaluate a single feature flag. Returns the string variant value,
+ * or `undefined` if the flag is not set / client not initialized.
+ */
+function getFlag(flagKey) {
+    return cachedFlags[flagKey];
+}
+/**
+ * Check whether a flag is enabled (variant is `'on'` or `'true'`).
+ * Returns `false` when the flag is absent or the client is not initialized.
+ */
+function isFlagEnabled(flagKey) {
+    const value = cachedFlags[flagKey];
+    return value === 'on' || value === 'true';
+}
+/**
+ * Return a snapshot of all evaluated flags (key -> string value).
+ */
+function getAllFlags() {
+    return { ...cachedFlags };
+}
+/**
+ * Re-evaluate flags for a specific user (e.g. after login).
+ * Updates the cached flags in place.
+ */
+async function refreshFlags(userId, deviceId) {
+    if (!client)
+        return;
+    try {
+        // Re-fetch flag configs in case they changed
+        await client.start();
+        const user = {};
+        if (userId)
+            user.user_id = userId;
+        if (deviceId)
+            user.device_id = deviceId;
+        const variants = client.evaluateV2(user);
+        cachedFlags = {};
+        for (const [key, variant] of Object.entries(variants)) {
+            if (variant.value !== undefined && variant.value !== null) {
+                cachedFlags[key] = String(variant.value);
+            }
+        }
+        (0, debug_1.debug)('feature-flags: refreshed flags', cachedFlags);
+    }
+    catch (err) {
+        (0, debug_1.debug)('feature-flags: refresh failed', err);
+    }
+}

package/dist/src/lib/health-checks/statuspage.d.ts

@@ -1,4 +1,5 @@
 import { type BaseHealthResult, type ComponentHealthResult } from './types';
+/** Model provider health — no-op, wizard uses Vertex AI via proxy. */
 export declare const checkAnthropicHealth: () => Promise<BaseHealthResult>;
 export declare const checkAmplitudeOverallHealth: () => Promise<BaseHealthResult>;
 export declare const checkAmplitudeComponentHealth: () => Promise<ComponentHealthResult>;

package/dist/src/lib/health-checks/statuspage.js

@@ -86,7 +86,11 @@ async function fetchStatuspageSummary(url, timeoutMs = 5000) {
 // ---------------------------------------------------------------------------
 // Individual statuspage-backed checks
 // ---------------------------------------------------------------------------
-const checkAnthropicHealth = () => fetchStatuspageIndicator('https://status.claude.com/api/v2/status.json');
+/** Model provider health — no-op, wizard uses Vertex AI via proxy. */
+const checkAnthropicHealth = () => Promise.resolve({
+    status: types_1.ServiceHealthStatus.Healthy,
+    pageUrl: '',
+});
 exports.checkAnthropicHealth = checkAnthropicHealth;
 const checkAmplitudeOverallHealth = () => fetchStatuspageIndicator('https://www.amplitudestatus.com/api/v2/status.json');
 exports.checkAmplitudeOverallHealth = checkAmplitudeOverallHealth;

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

@@ -0,0 +1,14 @@
+export type ExecutionMode = 'interactive' | 'ci' | 'agent';
+export interface ModeConfig {
+    mode: ExecutionMode;
+    autoApprove: boolean;
+    jsonOutput: boolean;
+    quiet: boolean;
+}
+export declare function resolveMode(opts: {
+    ci?: boolean;
+    yes?: boolean;
+    agent?: boolean;
+    json?: boolean;
+    isTTY: boolean;
+}): ModeConfig;

package/dist/src/lib/mode-config.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMode = resolveMode;
+function resolveMode(opts) {
+    const isAgent = Boolean(opts.agent);
+    const autoApprove = Boolean(opts.yes) || Boolean(opts.ci) || isAgent;
+    const isInteractive = !autoApprove && opts.isTTY;
+    return {
+        mode: isAgent ? 'agent' : isInteractive ? 'interactive' : 'ci',
+        autoApprove,
+        jsonOutput: opts.json ?? isAgent,
+        quiet: !opts.isTTY,
+    };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Session checkpointing — persist enough wizard state to resume after a crash.
+ *
+ * Saves a sanitized snapshot (no credentials/tokens) to a temp file.
+ * On restart the wizard can load it to skip already-completed setup steps
+ * (intro, region, auth selections) while still re-running the agent.
+ */
+import type { WizardSession } from './wizard-session';
+/**
+ * Write a sanitized session snapshot to disk.
+ * Strips credentials and any fields that should be re-evaluated on resume.
+ */
+export declare function saveCheckpoint(session: WizardSession): void;
+/**
+ * Load a checkpoint if one exists, is fresh, and matches the given install dir.
+ *
+ * Returns a partial session (only the checkpointed fields) or null when:
+ * - no checkpoint file exists
+ * - the checkpoint is older than 24 hours
+ * - the checkpoint belongs to a different project directory
+ * - the file is malformed or fails validation
+ */
+export declare function loadCheckpoint(installDir: string): Partial<WizardSession> | null;
+/**
+ * Delete the checkpoint file. Call on successful wizard completion.
+ */
+export declare function clearCheckpoint(installDir: string): void;