@amplitude/wizard 1.0.0-beta.0

package/dist/src/ui/tui/store.js

@@ -0,0 +1,568 @@
+/**
+ * WizardStore — Nanostore-backed reactive store for the TUI.
+ * React components subscribe via useSyncExternalStore.
+ *
+ * Navigation is delegated to WizardRouter.
+ * The active screen is derived from session state — not imperatively set.
+ * Overlays (outage, etc.) are the only imperative navigation.
+ *
+ * All session mutations that affect screen resolution go through
+ * explicit setters so emitChange() is always called.
+ */
+import { atom, map } from 'nanostores';
+import { TaskStatus } from '../wizard-ui.js';
+import { AdditionalFeature, McpOutcome, SlackOutcome, RunPhase, buildSession, } from '../../lib/wizard-session.js';
+import { WizardRouter, Screen, Overlay, Flow, } from './router.js';
+import { analytics, sessionProperties } from '../../utils/analytics.js';
+export { TaskStatus, Screen, Overlay, Flow, RunPhase, McpOutcome, SlackOutcome, };
+export class WizardStore {
+    // ── Internal nanostore atoms ─────────────────────────────────────
+    $session = map(buildSession({}));
+    $statusMessages = atom([]);
+    $tasks = atom([]);
+    $eventPlan = atom([]);
+    $version = atom(0);
+    /** True while the user is typing a slash command in the command bar. */
+    $commandMode = atom(false);
+    /** Transient feedback message shown in the command bar after a command runs. */
+    $commandFeedback = atom(null);
+    /** Error caught by the app error boundary — shown in ConsoleView. */
+    $screenError = atom(null);
+    $screenErrorRetry = atom(0);
+    /** Tab id to switch to imperatively (e.g. from a slash command). */
+    $requestedTab = atom(null);
+    /** Last screen seen — used to detect screen transitions for analytics. */
+    _lastScreen = null;
+    /** Hooks run when transitioning onto a screen. */
+    _enterScreenHooks = new Map();
+    version = '';
+    /** Navigation router — resolves active screen from session state. */
+    router;
+    /**
+     * Setup promise — IntroScreen resolves this when the user confirms.
+     * bin.ts awaits it before calling runWizard.
+     */
+    _resolveSetup;
+    setupComplete = new Promise((resolve) => {
+        this._resolveSetup = resolve;
+    });
+    /** Blocks agent execution until the settings-override overlay is dismissed. */
+    _resolveSettingsOverride = null;
+    _backupAndFixSettings = null;
+    /** Pending confirmation or choice prompt from the agent. */
+    $pendingPrompt = atom(null);
+    constructor(flow = Flow.Wizard) {
+        this.router = new WizardRouter(flow);
+    }
+    // ── State accessors (read from atoms) ────────────────────────────
+    get session() {
+        return this.$session.get();
+    }
+    set session(value) {
+        this.$session.set(value);
+    }
+    get commandMode() {
+        return this.$commandMode.get();
+    }
+    get commandFeedback() {
+        return this.$commandFeedback.get();
+    }
+    get screenError() {
+        return this.$screenError.get();
+    }
+    get screenErrorRetry() {
+        return this.$screenErrorRetry.get();
+    }
+    get requestedTab() {
+        return this.$requestedTab.get();
+    }
+    get statusMessages() {
+        return this.$statusMessages.get();
+    }
+    get tasks() {
+        return this.$tasks.get();
+    }
+    get eventPlan() {
+        return this.$eventPlan.get();
+    }
+    get pendingPrompt() {
+        return this.$pendingPrompt.get();
+    }
+    // ── Session setters ─────────────────────────────────────────────
+    // Every setter that affects screen resolution calls emitChange().
+    // Business logic calls these instead of mutating session directly.
+    /** Advances the flow past IntroScreen. Does not start the agent. */
+    concludeIntro() {
+        this.$session.setKey('introConcluded', true);
+        this.emitChange();
+    }
+    /**
+     * Unblocks bin.ts via the setupComplete promise, signalling that the agent
+     * can start. Called by bin.ts via onEnterScreen(Screen.Run) so it fires at
+     * the right point in the flow — after auth, data check, and setup questions.
+     */
+    completeSetup() {
+        this.$session.setKey('setupConfirmed', true);
+        analytics.wizardCapture('setup confirmed', sessionProperties(this.session));
+        this._resolveSetup();
+        this.emitChange();
+    }
+    setRunPhase(phase) {
+        this.$session.setKey('runPhase', phase);
+        this.emitChange();
+    }
+    setCredentials(credentials) {
+        this.$session.setKey('credentials', credentials);
+        if (credentials?.projectId) {
+            analytics.setDistinctId(String(credentials.projectId));
+        }
+        analytics.wizardCapture('auth complete', {
+            project_id: credentials?.projectId,
+        });
+        analytics.wizardCapture('credentials updated', {
+            project_id: credentials?.projectId,
+            region: this.session.region,
+        });
+        this.emitChange();
+    }
+    setFrameworkConfig(integration, config) {
+        this.$session.setKey('integration', integration);
+        this.$session.setKey('frameworkConfig', config);
+        this.emitChange();
+    }
+    setDetectionComplete() {
+        this.$session.setKey('detectionComplete', true);
+        this.emitChange();
+    }
+    setDetectedFramework(label) {
+        this.$session.setKey('detectedFrameworkLabel', label);
+        this.emitChange();
+    }
+    setLoginUrl(url) {
+        this.$session.setKey('loginUrl', url);
+        this.emitChange();
+    }
+    setRegion(region) {
+        this.$session.setKey('region', region);
+        this.$session.setKey('regionForced', false);
+        this.emitChange();
+    }
+    /** Force the RegionSelect screen to re-appear (/region command). */
+    setRegionForced() {
+        this.$session.setKey('regionForced', true);
+        // Reset data check so it re-runs after region changes
+        this.$session.setKey('projectHasData', null);
+        this.emitChange();
+    }
+    _retryResolve = null;
+    setScreenError(error) {
+        this.$screenError.set(error);
+        this.$version.set(this.$version.get() + 1);
+    }
+    clearScreenError() {
+        this.$screenError.set(null);
+        this.$screenErrorRetry.set(this.$screenErrorRetry.get() + 1);
+        this.$version.set(this.$version.get() + 1);
+        this._retryResolve?.();
+        this._retryResolve = null;
+    }
+    /**
+     * Returns a Promise that resolves the next time clearScreenError() is called
+     * (i.e. the user presses R). Used by InkUI.setRunError to block until retry.
+     */
+    waitForRetry() {
+        return new Promise((resolve) => {
+            this._retryResolve = resolve;
+        });
+    }
+    /** Show a confirmation prompt. Resolves with true (yes) or false (no / skipped). */
+    promptConfirm(message) {
+        return new Promise((resolve) => {
+            this.$pendingPrompt.set({ kind: 'confirm', message, resolve });
+            this.$version.set(this.$version.get() + 1);
+        });
+    }
+    /** Show a multiple-choice prompt. Resolves with the chosen option or empty string if skipped. */
+    promptChoice(message, options) {
+        return new Promise((resolve) => {
+            this.$pendingPrompt.set({ kind: 'choice', message, options, resolve });
+            this.$version.set(this.$version.get() + 1);
+        });
+    }
+    /** Resolve a confirm or choice pending prompt. */
+    resolvePrompt(answer) {
+        const prompt = this.$pendingPrompt.get();
+        if (!prompt || prompt.kind === 'event-plan')
+            return;
+        analytics.wizardCapture('prompt response', {
+            prompt_kind: prompt.kind,
+            response: String(answer),
+        });
+        this.$pendingPrompt.set(null);
+        this.$version.set(this.$version.get() + 1);
+        if (prompt.kind === 'confirm') {
+            prompt.resolve(answer);
+        }
+        else {
+            prompt.resolve(answer);
+        }
+    }
+    /** Show an event-plan confirmation. Resolves when the user approves, skips, or gives feedback. */
+    promptEventPlan(events) {
+        return new Promise((resolve) => {
+            this.$pendingPrompt.set({ kind: 'event-plan', events, resolve });
+            this.$version.set(this.$version.get() + 1);
+        });
+    }
+    /** Resolve the pending event-plan prompt. */
+    resolveEventPlan(decision) {
+        const prompt = this.$pendingPrompt.get();
+        if (!prompt || prompt.kind !== 'event-plan')
+            return;
+        analytics.wizardCapture('prompt response', {
+            prompt_kind: 'event-plan',
+            response: typeof decision === 'object' ? 'feedback' : String(decision),
+        });
+        this.$pendingPrompt.set(null);
+        this.$version.set(this.$version.get() + 1);
+        prompt.resolve(decision);
+    }
+    /** Enter or exit slash command mode. */
+    setCommandMode(active) {
+        this.$commandMode.set(active);
+        this.$version.set(this.$version.get() + 1);
+    }
+    showSnakeOverlay() {
+        this.pushOverlay(Overlay.Snake);
+    }
+    hideSnakeOverlay() {
+        this.popOverlay();
+    }
+    showMcpOverlay() {
+        this.pushOverlay(Overlay.Mcp);
+    }
+    hideMcpOverlay() {
+        this.popOverlay();
+    }
+    showSlackOverlay() {
+        this.pushOverlay(Overlay.Slack);
+    }
+    hideSlackOverlay() {
+        this.popOverlay();
+    }
+    showLogoutOverlay() {
+        this.pushOverlay(Overlay.Logout);
+    }
+    hideLogoutOverlay() {
+        this.popOverlay();
+    }
+    showLoginOverlay() {
+        this.pushOverlay(Overlay.Login);
+    }
+    hideLoginOverlay() {
+        this.popOverlay();
+    }
+    /** Update just the access token in credentials without triggering auth analytics. */
+    updateAccessToken(accessToken) {
+        const creds = this.$session.get().credentials;
+        if (!creds)
+            return;
+        this.$session.setKey('credentials', { ...creds, accessToken });
+        this.$version.set(this.$version.get() + 1);
+    }
+    /** Request the TabContainer to switch to a tab by id. Clears after consumption. */
+    setRequestedTab(id) {
+        this.$requestedTab.set(id);
+        this.$version.set(this.$version.get() + 1);
+    }
+    clearRequestedTab() {
+        this.$requestedTab.set(null);
+    }
+    /** Show a transient feedback message in the command bar. Clears after ms. */
+    setCommandFeedback(message, ms = 3000) {
+        this.$commandFeedback.set(message);
+        this.$version.set(this.$version.get() + 1);
+        setTimeout(() => {
+            this.$commandFeedback.set(null);
+            this.$version.set(this.$version.get() + 1);
+        }, ms);
+    }
+    setProjectHasData(value) {
+        this.$session.setKey('projectHasData', value);
+        this.emitChange();
+    }
+    setActivationLevel(level) {
+        this.$session.setKey('activationLevel', level);
+        // Keep projectHasData in sync so existing routing still works
+        this.$session.setKey('projectHasData', level === 'full' ? true : false);
+        this.emitChange();
+    }
+    setSnippetConfigured(value) {
+        this.$session.setKey('snippetConfigured', value);
+        this.emitChange();
+    }
+    setDataIngestionConfirmed() {
+        this.$session.setKey('dataIngestionConfirmed', true);
+        analytics.wizardCapture('data ingestion confirmed', sessionProperties(this.session));
+        this.emitChange();
+    }
+    setChecklistChartComplete() {
+        this.$session.setKey('checklistChartComplete', true);
+        this.emitChange();
+    }
+    setChecklistDashboardComplete() {
+        this.$session.setKey('checklistDashboardComplete', true);
+        this.emitChange();
+    }
+    setChecklistComplete() {
+        this.$session.setKey('checklistComplete', true);
+        analytics.wizardCapture('checklist completed', {
+            chart_complete: this.session.checklistChartComplete,
+            dashboard_complete: this.session.checklistDashboardComplete,
+            ...sessionProperties(this.session),
+        });
+        this.emitChange();
+    }
+    setActivationOptionsComplete() {
+        this.$session.setKey('activationOptionsComplete', true);
+        this.emitChange();
+    }
+    /**
+     * Called from bin.ts when OAuth completes (browser redirect done).
+     * Stores auth tokens + org list so AuthScreen can show the SUSI pickers.
+     * Also sets region from the detected cloud zone.
+     */
+    setOAuthComplete(data) {
+        this.$session.setKey('pendingAuthAccessToken', data.accessToken);
+        this.$session.setKey('pendingAuthIdToken', data.idToken);
+        this.$session.setKey('pendingAuthCloudRegion', data.cloudRegion);
+        this.$session.setKey('pendingOrgs', data.orgs);
+        // Auto-set region — skips RegionSelect for users whose zone is detected.
+        if (data.cloudRegion) {
+            this.$session.setKey('region', data.cloudRegion);
+        }
+        this.emitChange();
+    }
+    /**
+     * Called from AuthScreen when the user finishes org + workspace selection.
+     * Writes ampli.json and records org/workspace on the session.
+     */
+    setOrgAndWorkspace(org, workspace, installDir) {
+        this.$session.setKey('selectedOrgId', org.id);
+        this.$session.setKey('selectedOrgName', org.name);
+        this.$session.setKey('selectedWorkspaceId', workspace.id);
+        this.$session.setKey('selectedWorkspaceName', workspace.name);
+        // Write ampli.json to the project directory
+        void import('../../lib/ampli-config.js').then(({ writeAmpliConfig }) => {
+            const zone = this.$session.get().pendingAuthCloudRegion ?? 'us';
+            writeAmpliConfig(installDir, {
+                OrgId: org.id,
+                WorkspaceId: workspace.id,
+                Zone: zone,
+            });
+        });
+        this.emitChange();
+    }
+    setServiceStatus(status) {
+        this.$session.setKey('serviceStatus', status);
+        this.emitChange();
+    }
+    /**
+     * Push the settings-override overlay and return a promise that blocks
+     * until the user dismisses it via backupAndFixSettingsOverride().
+     */
+    showSettingsOverride(keys, backupAndFix) {
+        this.$session.setKey('settingsOverrideKeys', keys);
+        this._backupAndFixSettings = backupAndFix;
+        this.pushOverlay(Overlay.SettingsOverride);
+        return new Promise((resolve) => {
+            this._resolveSettingsOverride = resolve;
+        });
+    }
+    /**
+     * Back up .claude/settings.json. Dismisses the overlay on success.
+     */
+    backupAndFixSettingsOverride() {
+        const ok = this._backupAndFixSettings?.() ?? false;
+        if (ok) {
+            this.$session.setKey('settingsOverrideKeys', null);
+            this.popOverlay();
+            this._resolveSettingsOverride?.();
+            this._resolveSettingsOverride = null;
+            this._backupAndFixSettings = null;
+        }
+        return ok;
+    }
+    addDiscoveredFeature(feature) {
+        if (!this.session.discoveredFeatures.includes(feature)) {
+            this.session.discoveredFeatures.push(feature);
+            this.emitChange();
+        }
+    }
+    /**
+     * Enable an additional feature: enqueue it for the stop hook
+     * and set any feature-specific session flags.
+     */
+    enableFeature(feature) {
+        if (!this.session.additionalFeatureQueue.includes(feature)) {
+            this.session.additionalFeatureQueue.push(feature);
+        }
+        // Feature-specific flags
+        if (feature === AdditionalFeature.LLM) {
+            this.session.llmOptIn = true;
+        }
+        analytics.wizardCapture('feature enabled', { feature });
+        this.emitChange();
+    }
+    setAmplitudePreDetected() {
+        this.$session.setKey('amplitudePreDetected', true);
+        this.emitChange();
+    }
+    setMcpComplete(outcome = McpOutcome.Skipped, installedClients = []) {
+        this.$session.setKey('mcpComplete', true);
+        this.$session.setKey('mcpOutcome', outcome);
+        this.$session.setKey('mcpInstalledClients', installedClients);
+        analytics.wizardCapture('mcp complete', {
+            mcp_outcome: outcome,
+            mcp_installed_clients: installedClients,
+            ...sessionProperties(this.session),
+        });
+        this.emitChange();
+    }
+    setSlackComplete(outcome = SlackOutcome.Skipped) {
+        this.$session.setKey('slackComplete', true);
+        this.$session.setKey('slackOutcome', outcome);
+        analytics.wizardCapture('slack complete', {
+            slack_outcome: outcome,
+            ...sessionProperties(this.session),
+        });
+        this.emitChange();
+    }
+    setOutroData(data) {
+        this.$session.setKey('outroData', data);
+        this.emitChange();
+    }
+    setFrameworkContext(key, value) {
+        const ctx = { ...this.$session.get().frameworkContext, [key]: value };
+        this.$session.setKey('frameworkContext', ctx);
+        this.emitChange();
+    }
+    // ── Derived state ───────────────────────────────────────────────
+    /**
+     * The screen that should be rendered right now.
+     * Derived from session state via the router.
+     */
+    get currentScreen() {
+        return this.router.resolve(this.session);
+    }
+    /** Direction hint for screen transitions. */
+    get lastNavDirection() {
+        return this.router.lastNavDirection;
+    }
+    // ── Change notification ─────────────────────────────────────────
+    getVersion() {
+        return this.$version.get();
+    }
+    /**
+     * Notify React that state has changed.
+     * The router re-resolves the active screen on next render.
+     */
+    emitChange() {
+        this.router._setDirection('push');
+        this.$version.set(this.$version.get() + 1);
+        this._detectTransition();
+    }
+    // ── Overlay navigation ──────────────────────────────────────────
+    pushOverlay(overlay) {
+        this.router._setDirection('push');
+        this.router.pushOverlay(overlay);
+        this.$version.set(this.$version.get() + 1);
+        this._detectTransition();
+    }
+    popOverlay() {
+        this.router._setDirection('pop');
+        this.router.popOverlay();
+        this.$version.set(this.$version.get() + 1);
+        this._detectTransition();
+    }
+    // ── Screen transition analytics ─────────────────────────────────
+    /**
+     * Register a callback to run when transitioning onto the given screen.
+     * Fires after every transition that lands on this screen.
+     */
+    onEnterScreen(screen, fn) {
+        const list = this._enterScreenHooks.get(screen) ?? [];
+        list.push(fn);
+        this._enterScreenHooks.set(screen, list);
+    }
+    /**
+     * Detect screen transitions, run enter-screen hooks, and fire analytics.
+     * Called at the end of emitChange/pushOverlay/popOverlay.
+     */
+    _detectTransition() {
+        const next = this.router.resolve(this.session);
+        const prev = this._lastScreen;
+        // Update _lastScreen before invoking hooks so re-entrant emitChange calls
+        // (e.g. completeSetup inside an onEnterScreen hook) see prev === next and
+        // don't re-fire the same hooks, preventing infinite recursion.
+        this._lastScreen = next;
+        if (prev !== null && next !== prev) {
+            const hooks = this._enterScreenHooks.get(next);
+            if (hooks) {
+                for (const fn of hooks)
+                    fn();
+            }
+            analytics.wizardCapture(`screen ${next}`, {
+                from_screen: prev,
+                ...sessionProperties(this.session),
+            });
+        }
+    }
+    // ── Agent observation state ─────────────────────────────────────
+    pushStatus(message) {
+        this.$statusMessages.set([...this.$statusMessages.get(), message]);
+        this.emitChange();
+    }
+    setTasks(tasks) {
+        this.$tasks.set(tasks);
+        this.emitChange();
+    }
+    updateTask(index, done) {
+        const tasks = this.$tasks.get();
+        if (tasks[index]) {
+            const updated = [...tasks];
+            updated[index] = {
+                ...updated[index],
+                done,
+                status: done ? TaskStatus.Completed : TaskStatus.Pending,
+            };
+            this.$tasks.set(updated);
+            this.emitChange();
+        }
+    }
+    setEventPlan(events) {
+        this.$eventPlan.set(events);
+        this.emitChange();
+    }
+    syncTodos(todos) {
+        const incoming = todos.map((t) => ({
+            label: t.content,
+            activeForm: t.activeForm,
+            status: t.status || TaskStatus.Pending,
+            done: t.status === TaskStatus.Completed,
+        }));
+        const incomingLabels = new Set(incoming.map((t) => t.label));
+        const retained = this.$tasks
+            .get()
+            .filter((t) => t.done && !incomingLabels.has(t.label));
+        this.$tasks.set([...retained, ...incoming]);
+        this.emitChange();
+    }
+    // ── React integration ───────────────────────────────────────────
+    subscribe(callback) {
+        return this.$version.listen(() => callback());
+    }
+    getSnapshot() {
+        return this.$version.get();
+    }
+}

package/dist/src/ui/tui/styles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared style constants for TUI layout primitives.
+ */
+export declare enum HAlign {
+    Left = "flex-start",
+    Center = "center",
+    Right = "flex-end"
+}
+export declare enum VAlign {
+    Top = "flex-start",
+    Center = "center",
+    Bottom = "flex-end"
+}
+export declare const Colors: {
+    readonly primary: "#1e61f0";
+    readonly accent: "#1e61f0";
+    readonly success: "green";
+    readonly error: "red";
+    readonly muted: "#cccccc";
+};
+export declare const Icons: {
+    readonly diamond: "◆";
+    readonly diamondOpen: "◇";
+    readonly check: "✔";
+    readonly warning: "⚠";
+    readonly squareFilled: "◼";
+    readonly squareOpen: "◻";
+    readonly triangleRight: "▶";
+    readonly triangleSmallRight: "▸";
+    readonly bullet: "•";
+};

package/dist/src/ui/tui/styles.js

@@ -0,0 +1,33 @@
+/**
+ * Shared style constants for TUI layout primitives.
+ */
+export var HAlign;
+(function (HAlign) {
+    HAlign["Left"] = "flex-start";
+    HAlign["Center"] = "center";
+    HAlign["Right"] = "flex-end";
+})(HAlign || (HAlign = {}));
+export var VAlign;
+(function (VAlign) {
+    VAlign["Top"] = "flex-start";
+    VAlign["Center"] = "center";
+    VAlign["Bottom"] = "flex-end";
+})(VAlign || (VAlign = {}));
+export const Colors = {
+    primary: '#1e61f0',
+    accent: '#1e61f0',
+    success: 'green',
+    error: 'red',
+    muted: '#cccccc',
+};
+export const Icons = {
+    diamond: '\u25C6',
+    diamondOpen: '\u25C7',
+    check: '\u2714',
+    warning: '\u26A0',
+    squareFilled: '\u25FC',
+    squareOpen: '\u25FB',
+    triangleRight: '\u25B6',
+    triangleSmallRight: '\u25B8',
+    bullet: '\u2022',
+};