@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/dist/src/ui/tui/utils/classify-error.js

@@ -0,0 +1,90 @@
+/**
+ * Error classification for user-facing error messages.
+ *
+ * Transforms cryptic network errors and API failures into
+ * actionable messages with suggestions and docs links.
+ */
+/** Classify a caught error into a user-friendly message. */
+export function classifyError(err) {
+    if (!(err instanceof Error)) {
+        return {
+            message: String(err),
+            suggestion: 'An unexpected error occurred.',
+            retryable: false,
+        };
+    }
+    const msg = err.message;
+    // Network errors
+    if ('code' in err) {
+        const code = err.code;
+        switch (code) {
+            case 'ENOTFOUND':
+                return {
+                    message: 'Could not resolve hostname.',
+                    suggestion: 'Check your internet connection and DNS settings.',
+                    retryable: true,
+                };
+            case 'ECONNRESET':
+                return {
+                    message: 'Connection was reset by the server.',
+                    suggestion: 'This is usually temporary. Try again in a few seconds.',
+                    retryable: true,
+                };
+            case 'ECONNREFUSED':
+                return {
+                    message: 'Connection refused.',
+                    suggestion: 'The service may be down. Try again later.',
+                    retryable: true,
+                };
+            case 'ETIMEDOUT':
+                return {
+                    message: 'Request timed out.',
+                    suggestion: 'Check your network connection or try again later.',
+                    retryable: true,
+                };
+        }
+    }
+    // Timeout errors (from withTimeout utility)
+    if (err.name === 'TimeoutError') {
+        return {
+            message: msg,
+            suggestion: 'The operation took too long. Check your connection and retry.',
+            retryable: true,
+        };
+    }
+    // HTTP status errors — check structured status first, fall back to message
+    const errObj = err;
+    const responseObj = errObj.response;
+    const status = typeof errObj.status === 'number'
+        ? errObj.status
+        : typeof responseObj?.status === 'number'
+            ? responseObj.status
+            : null;
+    if (status === 401 || status === 403 || msg.includes('Unauthorized')) {
+        return {
+            message: 'Authentication failed.',
+            suggestion: 'Your session may have expired. Run /login to re-authenticate.',
+            retryable: false,
+        };
+    }
+    if (status === 429 || msg.includes('Too Many Requests')) {
+        return {
+            message: 'Rate limited by the API.',
+            suggestion: 'Wait a moment and try again.',
+            retryable: true,
+        };
+    }
+    if (status === 500 || status === 502 || status === 503) {
+        return {
+            message: 'Server error from Amplitude API.',
+            suggestion: 'This is temporary. Try again in a few seconds.',
+            retryable: true,
+        };
+    }
+    // Default
+    return {
+        message: msg,
+        suggestion: 'Run with --debug for more details, or /feedback to report this issue.',
+        retryable: false,
+    };
+}

package/dist/src/ui/tui/utils/diagnostics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Diagnostic snapshot for debugging flow issues.
+ *
+ * Produces a sanitized JSON object that shows exactly why the router
+ * picked the current screen — without leaking tokens or secrets.
+ *
+ * Used by the /debug slash command and crash report writer.
+ */
+import type { WizardSession } from '../../../lib/wizard-session.js';
+import type { WizardStore } from '../store.js';
+import { Flow } from '../flows.js';
+export interface FlowStepEvaluation {
+    screen: string;
+    visible: boolean;
+    complete: boolean;
+    active: boolean;
+}
+/** Walk the flow pipeline and explain each routing decision. */
+export declare function evaluateFlow(session: WizardSession, flow?: Flow): FlowStepEvaluation[];
+/** Create a sanitized diagnostic snapshot safe to share with support. */
+export declare function createDiagnosticSnapshot(store: WizardStore, version: string): object;

package/dist/src/ui/tui/utils/diagnostics.js

@@ -0,0 +1,72 @@
+/**
+ * Diagnostic snapshot for debugging flow issues.
+ *
+ * Produces a sanitized JSON object that shows exactly why the router
+ * picked the current screen — without leaking tokens or secrets.
+ *
+ * Used by the /debug slash command and crash report writer.
+ */
+import { FLOWS, Flow } from '../flows.js';
+/** Walk the flow pipeline and explain each routing decision. */
+export function evaluateFlow(session, flow = Flow.Wizard) {
+    const entries = FLOWS[flow];
+    if (!entries)
+        return [];
+    let foundActive = false;
+    return entries.map((entry) => {
+        const visible = entry.show ? entry.show(session) : true;
+        const complete = visible && entry.isComplete ? entry.isComplete(session) : false;
+        const active = visible && !complete && !foundActive;
+        if (active)
+            foundActive = true;
+        return { screen: entry.screen, visible, complete, active };
+    });
+}
+/** Create a sanitized diagnostic snapshot safe to share with support. */
+export function createDiagnosticSnapshot(store, version) {
+    const session = store.session;
+    return {
+        wizard_version: version,
+        node_version: process.version,
+        platform: `${process.platform}/${process.arch}`,
+        timestamp: new Date().toISOString(),
+        // Flow state — the "why did I see this screen?" answer
+        current_screen: store.currentScreen,
+        active_flow: store.router.activeFlow,
+        has_overlay: store.router.hasOverlay,
+        // Flow evaluation — shows every predicate result
+        flow_evaluation: evaluateFlow(session, store.router.activeFlow),
+        // Session state (secrets redacted, only structural/categorical data)
+        session: {
+            integration: session.integration,
+            detected_framework: session.detectedFrameworkLabel,
+            detection_complete: session.detectionComplete,
+            region: session.region,
+            region_forced: session.regionForced,
+            run_phase: session.runPhase,
+            activation_level: session.activationLevel,
+            project_has_data: session.projectHasData,
+            setup_confirmed: session.setupConfirmed,
+            intro_concluded: session.introConcluded,
+            mcp_complete: session.mcpComplete,
+            slack_complete: session.slackComplete,
+            data_ingestion_confirmed: session.dataIngestionConfirmed,
+            checklist_complete: session.checklistComplete,
+            checklist_chart_complete: session.checklistChartComplete,
+            checklist_dashboard_complete: session.checklistDashboardComplete,
+            discovered_features: session.discoveredFeatures,
+            additional_feature_queue: session.additionalFeatureQueue,
+            amplitude_pre_detected: session.amplitudePreDetected,
+            outro_kind: session.outroData?.kind ?? null,
+            // Redacted credential indicators
+            has_credentials: session.credentials !== null,
+            has_pending_orgs: session.pendingOrgs !== null,
+            selected_org: session.selectedOrgName,
+            selected_project: session.selectedProjectName,
+        },
+        // Counts
+        status_messages_count: store.statusMessages.length,
+        tasks_count: store.tasks.length,
+        event_plan_count: store.eventPlan.length,
+    };
+}

package/dist/src/ui/tui/utils/with-retry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Retry wrapper with exponential backoff.
+ *
+ * Retries transient failures (5xx, network errors) but bails immediately
+ * on client errors (4xx except 429) since retrying won't help.
+ */
+export interface RetryOptions {
+    retries?: number;
+    baseDelayMs?: number;
+    label?: string;
+}
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/src/ui/tui/utils/with-retry.js

@@ -0,0 +1,32 @@
+/**
+ * Retry wrapper with exponential backoff.
+ *
+ * Retries transient failures (5xx, network errors) but bails immediately
+ * on client errors (4xx except 429) since retrying won't help.
+ */
+export async function withRetry(fn, opts = {}) {
+    const { retries = 2, baseDelayMs = 1000, label = 'operation' } = opts;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            // Don't retry client errors (except rate limiting)
+            if (isClientError(err))
+                throw err;
+            if (attempt === retries)
+                throw err;
+            const delay = baseDelayMs * Math.pow(2, attempt);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw new Error(`${label}: unreachable`);
+}
+/** 4xx errors (except 429) are not retryable. */
+function isClientError(err) {
+    if (err && typeof err === 'object' && 'status' in err) {
+        const status = err.status;
+        return status >= 400 && status < 500 && status !== 429;
+    }
+    return false;
+}

package/dist/src/ui/tui/utils/with-timeout.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Timeout wrapper for async operations.
+ *
+ * Prevents stuck states when API calls hang due to network issues.
+ * Every API call in screens should be wrapped in this.
+ */
+export declare class TimeoutError extends Error {
+    constructor(label: string, ms: number);
+}
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;

package/dist/src/ui/tui/utils/with-timeout.js

@@ -0,0 +1,24 @@
+/**
+ * Timeout wrapper for async operations.
+ *
+ * Prevents stuck states when API calls hang due to network issues.
+ * Every API call in screens should be wrapped in this.
+ */
+export class TimeoutError extends Error {
+    constructor(label, ms) {
+        super(`${label} timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+export async function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new TimeoutError(label, ms)), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/utils/ampli-settings.d.ts

@@ -22,7 +22,7 @@ export interface StoredUser {
     email: string;
     zone: AmplitudeZone;
 }
-/** Returns the first stored user, or undefined if none. */
+/** Returns the first real (non-pending) stored user, or undefined if none. */
 export declare function getStoredUser(configPath?: string): StoredUser | undefined;
 /** Returns a valid (non-expired) stored token, or undefined. */
 export declare function getStoredToken(userId?: string, zone?: AmplitudeZone, configPath?: string): StoredOAuthToken | undefined;

package/dist/src/utils/ampli-settings.js

@@ -53,6 +53,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const zod_1 = require("zod");
 const constants_js_1 = require("../lib/constants.js");
+const atomic_write_js_1 = require("./atomic-write.js");
 exports.AMPLI_CONFIG_PATH = path.join(os.homedir(), '.ampli.json');
 const AmpliSettingsFileSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
 function readConfig(configPath = exports.AMPLI_CONFIG_PATH) {
@@ -66,7 +67,8 @@ function readConfig(configPath = exports.AMPLI_CONFIG_PATH) {
     }
 }
 function writeConfig(data, configPath = exports.AMPLI_CONFIG_PATH) {
-    fs.writeFileSync(configPath, JSON.stringify(data, null, 2), 'utf-8');
+    // Atomic write: temp file + rename prevents corruption if process dies mid-write
+    (0, atomic_write_js_1.atomicWriteJSON)(configPath, data, 0o600);
 }
 function userKey(userId, zone) {
     const safeId = userId.replace(/\./g, '-');
@@ -86,17 +88,25 @@ const UserEntrySchema = zod_1.z
     User: StoredUserSchema.optional(),
 })
     .passthrough();
-/** Returns the first stored user, or undefined if none. */
+/** Returns the first real (non-pending) stored user, or undefined if none. */
 function getStoredUser(configPath) {
     const config = readConfig(configPath);
+    let fallback;
     for (const [key, value] of Object.entries(config)) {
         if (!key.startsWith('User-') && !key.startsWith('User['))
             continue;
         const entry = UserEntrySchema.safeParse(value);
-        if (entry.success && entry.data.User)
-            return entry.data.User;
+        if (!entry.success || !entry.data.User)
+            continue;
+        const user = entry.data.User;
+        // Skip the "pending" placeholder — prefer a real user with an actual ID
+        if (user.id === 'pending') {
+            fallback = fallback ?? user;
+            continue;
+        }
+        return user;
     }
-    return undefined;
+    return fallback;
 }
 /** Returns a valid (non-expired) stored token, or undefined. */
 function getStoredToken(userId, zone = constants_js_1.DEFAULT_AMPLITUDE_ZONE, configPath) {

package/dist/src/utils/api-key-store.js

@@ -164,13 +164,13 @@ function readApiKeyWithSource(installDir) {
         if (key)
             return { key, source: 'keychain' };
     }
-    // .env.local in the project directory
+    // .env.local in the project directory (project-scoped, safe)
     const envKey = envRead(installDir);
     if (envKey)
         return { key: envKey, source: 'env' };
-    // Also honour AMPLITUDE_API_KEY from the environment (e.g. already in .env)
-    const envVar = process.env.AMPLITUDE_API_KEY;
-    if (envVar)
-        return { key: envVar, source: 'env' };
+    // NOTE: We intentionally do NOT fall back to process.env.AMPLITUDE_API_KEY.
+    // A shell-level env var would leak across projects — if a user sets it in
+    // their .bashrc, every project on the machine would silently use it.
+    // Users should use .env.local (project-scoped) or --api-key (explicit).
     return null;
 }

package/dist/src/utils/atomic-write.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Atomic JSON file writes via temp-file + rename.
+ *
+ * writeFileSync is atomic for small files on POSIX, but NOT on Windows.
+ * This utility ensures crash-safety on all platforms: if the process dies
+ * mid-write, the original file is untouched (the temp file is orphaned).
+ */
+/**
+ * Write a JSON object to a file atomically.
+ *
+ * 1. Writes to a temp file (same directory, PID-suffixed)
+ * 2. Renames temp → target (atomic on all OSes)
+ * 3. Cleans up temp on failure
+ */
+export declare function atomicWriteJSON(filePath: string, data: unknown, mode?: number): void;

package/dist/src/utils/atomic-write.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Atomic JSON file writes via temp-file + rename.
+ *
+ * writeFileSync is atomic for small files on POSIX, but NOT on Windows.
+ * This utility ensures crash-safety on all platforms: if the process dies
+ * mid-write, the original file is untouched (the temp file is orphaned).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomicWriteJSON = atomicWriteJSON;
+const fs_1 = require("fs");
+/**
+ * Write a JSON object to a file atomically.
+ *
+ * 1. Writes to a temp file (same directory, PID-suffixed)
+ * 2. Renames temp → target (atomic on all OSes)
+ * 3. Cleans up temp on failure
+ */
+function atomicWriteJSON(filePath, data, mode = 0o644) {
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    try {
+        (0, fs_1.writeFileSync)(tmp, JSON.stringify(data, null, 2) + '\n', { mode });
+        (0, fs_1.renameSync)(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            (0, fs_1.unlinkSync)(tmp);
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        throw err;
+    }
+}

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

@@ -284,7 +284,7 @@ async function tryResolveCredentialsForCi(installDir) {
     return {
         host: getHostFromRegion(cloudRegion),
         projectApiKey,
-        accessToken: storedToken.idToken,
+        accessToken: storedToken.accessToken,
         cloudRegion,
     };
 }
@@ -482,7 +482,7 @@ async function askForWizardLogin(opts = {}) {
         projectApiKey = await askForAmplitudeApiKey(opts.installDir);
     }
     return {
-        accessToken: auth.idToken,
+        accessToken: auth.accessToken,
         projectApiKey,
         host: constants_1.DEFAULT_HOST_URL,
         distinctId: userInfo?.id ?? 'unknown',

package/dist/src/utils/token-refresh.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Silent OAuth token refresh — lightweight utility that exchanges an expired
+ * access token for a new one using a stored refresh token, without opening
+ * the browser or importing heavy dependencies.
+ *
+ * Returns null on any failure so the caller can fall back to full browser auth.
+ */
+import { type AmplitudeZone } from '../lib/constants.js';
+/**
+ * Attempts a silent OAuth token refresh if the access token is expired or
+ * expiring within 5 minutes. Returns new token data on success, or null if
+ * refresh is not needed, not possible, or fails.
+ */
+export declare function tryRefreshToken(storedEntry: {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+}, zone?: AmplitudeZone): Promise<{
+    accessToken: string;
+    expiresAt: number;
+    refreshToken?: string;
+} | null>;

package/dist/src/utils/token-refresh.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Silent OAuth token refresh — lightweight utility that exchanges an expired
+ * access token for a new one using a stored refresh token, without opening
+ * the browser or importing heavy dependencies.
+ *
+ * Returns null on any failure so the caller can fall back to full browser auth.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryRefreshToken = tryRefreshToken;
+const constants_js_1 = require("../lib/constants.js");
+const debug_js_1 = require("./debug.js");
+/** Five minutes in milliseconds — refresh proactively before actual expiry. */
+const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+/**
+ * Attempts a silent OAuth token refresh if the access token is expired or
+ * expiring within 5 minutes. Returns new token data on success, or null if
+ * refresh is not needed, not possible, or fails.
+ */
+async function tryRefreshToken(storedEntry, zone = constants_js_1.DEFAULT_AMPLITUDE_ZONE) {
+    // 1. Check whether the token actually needs refreshing
+    const now = Date.now();
+    if (storedEntry.expiresAt - now > EXPIRY_BUFFER_MS) {
+        // Token is still valid — no refresh needed
+        return null;
+    }
+    // 2. A refresh token is required
+    if (!storedEntry.refreshToken) {
+        (0, debug_js_1.logToFile)('[token-refresh] access token expired but no refresh token stored');
+        return null;
+    }
+    (0, debug_js_1.logToFile)('[token-refresh] access token expired or expiring soon, attempting silent refresh', {
+        expiresAt: new Date(storedEntry.expiresAt).toISOString(),
+        zone,
+    });
+    // 3. Exchange the refresh token for a new access token
+    try {
+        const { oAuthHost, oAuthClientId } = constants_js_1.AMPLITUDE_ZONE_SETTINGS[zone];
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: storedEntry.refreshToken,
+            client_id: oAuthClientId,
+        });
+        const response = await fetch(`${oAuthHost}/oauth2/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            (0, debug_js_1.logToFile)('[token-refresh] refresh request failed', {
+                status: response.status,
+                statusText: response.statusText,
+            });
+            return null;
+        }
+        const data = (await response.json());
+        const accessToken = data.access_token;
+        const expiresIn = data.expires_in;
+        if (typeof accessToken !== 'string' || typeof expiresIn !== 'number') {
+            (0, debug_js_1.logToFile)('[token-refresh] unexpected response shape', {
+                hasAccessToken: typeof accessToken,
+                hasExpiresIn: typeof expiresIn,
+            });
+            return null;
+        }
+        const expiresAt = now + expiresIn * 1000;
+        // Persist rotated refresh token if the server issued a new one
+        const newRefreshToken = typeof data.refresh_token === 'string' ? data.refresh_token : undefined;
+        (0, debug_js_1.logToFile)('[token-refresh] silent refresh succeeded', {
+            expiresAt: new Date(expiresAt).toISOString(),
+            rotatedRefreshToken: !!newRefreshToken,
+        });
+        return { accessToken, expiresAt, refreshToken: newRefreshToken };
+    }
+    catch (err) {
+        (0, debug_js_1.logToFile)('[token-refresh] refresh failed', err instanceof Error ? err.message : 'unknown error');
+        return null;
+    }
+}

package/dist/src/utils/wizard-abort.js

@@ -52,5 +52,10 @@ async function wizardAbort(options) {
     // 4. Display message to user
     (0, ui_1.getUI)().cancel(message);
     // 5. Exit (fires 'exit' event so TUI cleanup runs)
-    return process.exit(exitCode);
+    // In agent mode, always exit 0 — errors are communicated via NDJSON output,
+    // not exit codes. A non-zero exit makes callers (like Claude Code) show
+    // ugly red error banners when the error is already reported in the output.
+    const isAgentMode = process.env.AMPLITUDE_WIZARD_AGENT === '1' ||
+        process.argv.includes('--agent');
+    return process.exit(isAgentMode ? 0 : exitCode);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplitude/wizard",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0",
   "homepage": "https://github.com/amplitude/wizard",
   "repository": "https://github.com/amplitude/wizard",
   "description": "The Amplitude wizard helps you to configure your project",
@@ -27,6 +27,7 @@
     "dist/bin.*",
     "dist/src",
     "man/",
+    "skills/",
     "package.json",
     "README.md"
   ],
@@ -47,7 +48,6 @@
     "axios": "1.13.5",
     "chalk": "^2.4.1",
     "client-oauth2": "^4.3.3",
-    "conf": "^15.1.0",
     "dotenv": "^16.4.7",
     "fast-glob": "^3.3.3",
     "glob": "9.3.5",
@@ -66,7 +66,6 @@
     "semver": "^7.5.3",
     "uuid": "^11.1.0",
     "xcode": "3.0.1",
-    "xml-js": "^1.6.11",
     "yargs": "^16.2.0",
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.1"
@@ -88,6 +87,7 @@
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^9.1.2",
+    "fast-check": "^4.6.0",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
     "lint-staged": "^15.5.1",
@@ -115,11 +115,11 @@
   },
   "scripts": {
     "clean": "rm -rf ./dist",
-    "prebuild": "pnpm clean",
+    "prebuild": "pnpm clean && node scripts/sync-version.mjs",
     "build:watch": "pnpm tsc -w",
     "build": "pnpm tsc",
     "postbuild": "chmod +x ./dist/bin.js && pnpm test:smoke",
-    "test:smoke": "node -e \"require('./dist/bin.js')\" 2>&1 | head -5 | grep -q 'Amplitude Wizard' || (echo 'Smoke test failed: compiled binary crashed on load' && exit 1)",
+    "test:smoke": "node ./dist/bin.js --help 2>&1 | head -5 | grep -q 'Amplitude' || (echo 'Smoke test failed: compiled binary crashed on load' && exit 1)",
     "lint": "pnpm lint:prettier && pnpm lint:eslint",
     "lint:prettier": "prettier --check \"{lib,src,test}/**/*.ts\"",
     "lint:eslint": "eslint . --cache --format stylish",
@@ -129,7 +129,7 @@
     "test": "vitest run",
     "test:e2e": "pnpm build && ./e2e-tests/run.sh",
     "test:e2e-record": "export RECORD_FIXTURES=true && pnpm build && ./e2e-tests/run.sh",
-    "try": "tsx bin.ts",
+    "try": "pnpm build && node dist/bin.js",
     "proxy": "cd \"${JS_REPO:-../javascript}\"/server/packages/thunder && aws-sso exec --profile us-prod-dev -- pnpm debug",
     "proxy:bypass": "cd \"${JS_REPO:-../javascript}\"/server/packages/thunder && WIZARD_PROXY_DEV_BYPASS=1 aws-sso exec --profile us-prod-dev -- pnpm debug",
     "dev": "pnpm build && pnpm link --global && (trap 'kill 0' EXIT; pnpm proxy & pnpm build:watch)",