better-gemini-mcp 1.0.0

package/dist/constants.js

@@ -0,0 +1,295 @@
+/**
+ * Constants for Better Gemini MCP Server
+ * Error codes, model configurations, system prompt, and protocol constants
+ */
+// ============================================================================
+// Logging
+// ============================================================================
+export const LOG_PREFIX = "[BGMCP]";
+// ============================================================================
+// Error Codes (Appendix B from PRD)
+// ============================================================================
+export const ERROR_CODES = {
+    /** Tool called with invalid parameters */
+    INVALID_ARGUMENT: "INVALID_ARGUMENT",
+    /** Path is outside project root */
+    PATH_NOT_ALLOWED: "PATH_NOT_ALLOWED",
+    /** gemini binary not on PATH */
+    GEMINI_CLI_NOT_FOUND: "GEMINI_CLI_NOT_FOUND",
+    /** Gemini CLI execution failed */
+    GEMINI_CLI_ERROR: "GEMINI_CLI_ERROR",
+    /** Gemini CLI authentication not configured */
+    AUTH_MISSING: "AUTH_MISSING",
+    /** Gemini API quota exhausted (after fallback) */
+    QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
+    /** Chunk cache key not found or expired */
+    CACHE_EXPIRED: "CACHE_EXPIRED",
+    /** Requested chunk index out of range */
+    INVALID_CHUNK_INDEX: "INVALID_CHUNK_INDEX",
+    /** Unexpected server error */
+    INTERNAL: "INTERNAL",
+};
+// ============================================================================
+// Error Messages
+// ============================================================================
+export const ERROR_MESSAGES = {
+    QUOTA_EXCEEDED: "Quota exceeded for quota metric",
+    QUOTA_EXCEEDED_SHORT: "⚠️ Gemini API quota exceeded. Falling back to alternative model...",
+    TOOL_NOT_FOUND: "not found in registry",
+    NO_PROMPT_PROVIDED: "Please provide a prompt for analysis. Use @ syntax to include files (e.g., '@src/auth.ts explain what this does') or ask general questions",
+    GEMINI_CLI_NOT_FOUND: "Gemini CLI not found on PATH. Install with: npm install -g @google/gemini-cli",
+    AUTH_MISSING: "Gemini CLI authentication not configured. Run 'gemini' and select 'Login with Google', or set GEMINI_API_KEY environment variable.",
+    PATH_NOT_ALLOWED: "Path is outside project root",
+    CACHE_EXPIRED: "Cache key not found or expired. Re-run original query to regenerate response.",
+    INVALID_CHUNK_INDEX: "Requested chunk index out of range",
+};
+// ============================================================================
+// Status Messages
+// ============================================================================
+export const STATUS_MESSAGES = {
+    QUOTA_SWITCHING: "🚫 Primary model quota exceeded, switching to fallback model...",
+    FALLBACK_RETRY: "⚡ Retrying with fallback model...",
+    FALLBACK_SUCCESS: "✅ Fallback model completed successfully",
+    AUTO_SELECT_RETRY: "🔄 Retrying with auto-selected model...",
+    PROCESSING_START: "🔍 Starting analysis (may take 5-15 minutes for large codebases)",
+    PROCESSING_CONTINUE: "⏳ Still processing... Gemini is working on your request",
+    PROCESSING_COMPLETE: "✅ Analysis completed successfully",
+};
+// ============================================================================
+// Model Configuration (Appendix A from PRD)
+// ============================================================================
+export const MODELS = {
+    // Tier 1: Default models (Gemini 3 - requires Preview Features)
+    FLASH_DEFAULT: "gemini-3-flash-preview",
+    PRO_DEFAULT: "gemini-3-pro-preview",
+    // Tier 2: Fallback models (Gemini 2.5)
+    FLASH_FALLBACK: "gemini-2.5-flash",
+    PRO_FALLBACK: "gemini-2.5-pro",
+    // Tier 3: Auto-select (no -m flag, let Gemini CLI choose)
+    AUTO_SELECT: null,
+};
+/**
+ * Model selection configuration per tool
+ */
+export const MODEL_TIERS = {
+    quick_query: {
+        tier1: MODELS.FLASH_DEFAULT,
+        tier2: MODELS.FLASH_FALLBACK,
+        tier3: MODELS.AUTO_SELECT,
+    },
+    deep_research: {
+        tier1: MODELS.PRO_DEFAULT,
+        tier2: MODELS.PRO_FALLBACK,
+        tier3: MODELS.AUTO_SELECT,
+    },
+    analyze_directory: {
+        tier1: MODELS.FLASH_DEFAULT,
+        tier2: MODELS.FLASH_FALLBACK,
+        tier3: MODELS.AUTO_SELECT,
+    },
+};
+// ============================================================================
+// MCP Protocol Constants
+// ============================================================================
+export const PROTOCOL = {
+    // Message roles
+    ROLES: {
+        USER: "user",
+        ASSISTANT: "assistant",
+    },
+    // Content types
+    CONTENT_TYPES: {
+        TEXT: "text",
+    },
+    // Status codes
+    STATUS: {
+        SUCCESS: "success",
+        ERROR: "error",
+        FAILED: "failed",
+    },
+    // Notification methods
+    NOTIFICATIONS: {
+        PROGRESS: "notifications/progress",
+    },
+    // Timeout prevention - keep client alive with periodic updates
+    KEEPALIVE_INTERVAL: 25000, // 25 seconds
+};
+// ============================================================================
+// CLI Constants
+// ============================================================================
+export const CLI = {
+    // Command names
+    COMMANDS: {
+        GEMINI: "gemini",
+        WHICH: "which",
+        WHERE: "where", // Windows
+    },
+    // Command flags
+    FLAGS: {
+        MODEL: "-m",
+        PROMPT: "-p",
+        YES: "-y", // Auto-approve file reads
+        OUTPUT_FORMAT: "--output-format",
+        VERSION: "--version",
+        HELP: "--help",
+    },
+    // Output formats
+    OUTPUT_FORMATS: {
+        JSON: "json",
+        STREAM_JSON: "stream-json",
+    },
+};
+// ============================================================================
+// Default Configuration
+// ============================================================================
+export const DEFAULTS = {
+    /** Maximum files to enumerate in analyze_directory */
+    MAX_FILES: 500,
+    /** Response chunk size in KB (for chunking large responses) */
+    RESPONSE_CHUNK_SIZE_KB: 10,
+    /** Cache TTL in milliseconds (1 hour) */
+    CACHE_TTL_MS: 3600000,
+    /** Maximum response size before truncation (50KB) */
+    MAX_RESPONSE_SIZE: 50 * 1024,
+};
+// ============================================================================
+// Ignore Patterns (for analyze_directory)
+// ============================================================================
+export const DEFAULT_IGNORE_PATTERNS = [
+    ".git/",
+    "node_modules/",
+    "dist/",
+    "build/",
+    "out/",
+    ".next/",
+    "coverage/",
+    ".venv/",
+    "venv/",
+    "__pycache__/",
+];
+// ============================================================================
+// System Prompt (PRD §7.5)
+// ============================================================================
+export const SYSTEM_PROMPT = `
+You are analyzing a codebase on behalf of an AI coding agent.
+
+WHEN TO USE THIS TOOL:
+- The calling agent should use MCP tools (quick_query, deep_research, analyze_directory) FIRST when questions involve repository files or code analysis
+- This reduces the calling agent's context and model usage by offloading heavy reading/analysis to Gemini CLI's large context window
+- Prefer using tools over asking the agent to read files directly
+
+CRITICAL CONSTRAINTS:
+- Read-only analysis ONLY (no write/edit tools available without --yolo flag)
+- Do NOT suggest code changes, patches, or file modifications
+- Do NOT attempt to use run_shell_command or write_file (not available)
+
+OPTIMIZATION FOR TOKEN EFFICIENCY:
+- The calling agent has limited context - be concise but thorough
+- Prioritize KEY findings over exhaustive details
+- Include file paths for all referenced code
+- Use bullet points and structured formatting for clarity
+- If asked about security/architecture/performance, focus ONLY on that dimension
+
+OUTPUT FORMAT:
+- Start with a 2-3 sentence executive summary
+- Provide detailed findings with file path references
+- End with a "## Files Referenced" section listing all paths examined
+`;
+// ============================================================================
+// Server Info
+// ============================================================================
+export const SERVER_INFO = {
+    NAME: "better-gemini-mcp",
+    VERSION: "1.0.0",
+    DESCRIPTION: "Stateless MCP server that proxies research queries to Gemini CLI",
+};
+// ============================================================================
+// Setup Wizard Messages
+// ============================================================================
+export const WIZARD_MESSAGES = {
+    HEADER: `
+Better Gemini MCP — Setup Wizard
+================================
+`,
+    SUCCESS_HEADER: `
+Setup Complete! 🎉
+==================
+`,
+    STEP_GEMINI_INSTALL: "[1/2] Checking Gemini CLI installation...",
+    STEP_AUTH: "[2/3] Checking authentication...", // Deprecated - no longer used
+    STEP_TEST: "[2/2] Testing Gemini CLI...",
+    GEMINI_FOUND: (path, version) => `  ✓ Gemini CLI found at ${path} (version ${version})`,
+    GEMINI_NOT_FOUND: `  ✗ Gemini CLI not found
+
+  Install Gemini CLI:
+    npm install -g @google/gemini-cli
+  
+  Documentation:
+    https://github.com/google-gemini/gemini-cli`,
+    AUTH_GOOGLE: "  ✓ Authenticated session detected (Login with Google)",
+    AUTH_API_KEY: "  ✓ GEMINI_API_KEY environment variable set",
+    AUTH_VERTEX: "  ✓ Vertex AI credentials detected",
+    AUTH_NOT_FOUND: `  ✗ No authentication configured
+
+  Option 1: Login with Google (Recommended)
+    - Run: gemini
+    - Select "Login with Google" and follow prompts
+    - Your credentials will be cached for future sessions
+    - Works seamlessly in headless mode after initial setup
+
+  Option 2: Use Gemini API Key (Alternative for automation)
+    - Get API key: https://aistudio.google.com/app/apikey
+    - Set in terminal: export GEMINI_API_KEY="your-key-here"
+    - Make persistent: Add to ~/.bashrc or ~/.zshrc
+
+  Option 3: Vertex AI (For enterprise users)
+    - See: https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.md#vertex-ai`,
+    TEST_SUCCESS: "  ✓ Test invocation successful",
+    TEST_FAILED: (error) => `  ✗ Test invocation failed: ${error}`,
+    NEXT_STEPS: `
+Next steps:
+1. Configure your MCP client (Claude Desktop, VS Code)
+2. Add this server to your MCP config:
+
+   For Claude Desktop (~/.config/Claude/claude_desktop_config.json):
+   {
+     "mcpServers": {
+       "better-gemini-mcp": {
+         "command": "npx",
+         "args": ["better-gemini-mcp"]
+       }
+     }
+   }
+
+   For VS Code (settings.json or mcp-settings.json):
+   {
+     "mcp.servers": {
+       "better-gemini-mcp": {
+         "command": "npx",
+         "args": ["better-gemini-mcp"]
+       }
+     }
+   }
+
+3. Restart your MCP client
+4. Test with: "Can you list your available tools?"
+
+Documentation: https://github.com/YOUR_ORG/better-gemini-mcp
+`,
+    FIX_ISSUES: `
+Please fix the issues above and run 'npx better-gemini-mcp init' again.
+`,
+    // Startup validation messages
+    STARTUP_SUCCESS: "✅ All checks passed! Server starting...",
+    STARTUP_GEMINI_NOT_FOUND: `❌ Gemini CLI not found on PATH
+→ Install: npm install -g @google/gemini-cli
+→ Docs: https://github.com/google-gemini/gemini-cli
+→ Run 'npx better-gemini-mcp init' for guided setup`,
+    STARTUP_AUTH_MISSING: `❌ Gemini CLI authentication not configured
+→ Recommended: Run 'gemini' and select "Login with Google"
+→ Alternative: Set GEMINI_API_KEY environment variable
+   - Get API key: https://aistudio.google.com/app/apikey
+   - Set in terminal: export GEMINI_API_KEY="your-key-here"
+→ Run 'npx better-gemini-mcp init' for guided setup`,
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Better Gemini MCP Server
+ *
+ * A stateless MCP server that proxies research queries to Gemini CLI,
+ * reducing agent context/model usage.
+ *
+ * @see docs/project-overview-PRD.md for full specification
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/dist/index.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * Better Gemini MCP Server
+ *
+ * A stateless MCP server that proxies research queries to Gemini CLI,
+ * reducing agent context/model usage.
+ *
+ * @see docs/project-overview-PRD.md for full specification
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { PROTOCOL, SERVER_INFO, LOG_PREFIX, WIZARD_MESSAGES } from "./constants.js";
+import { getToolDefinitions, executeTool, toolExists } from "./tools/index.js";
+import { runSetupWizard, validateEnvironment } from "./setup/index.js";
+// ============================================================================
+// Server Instance
+// ============================================================================
+const server = new Server({
+    name: SERVER_INFO.NAME,
+    version: SERVER_INFO.VERSION,
+}, {
+    capabilities: {
+        tools: {},
+        notifications: {},
+        logging: {},
+    },
+});
+// ============================================================================
+// Progress Tracking State
+// ============================================================================
+let isProcessing = false;
+let currentOperationName = "";
+let latestOutput = "";
+// ============================================================================
+// Notification Helpers
+// ============================================================================
+/**
+ * Send a notification to the client
+ */
+async function sendNotification(method, params) {
+    try {
+        await server.notification({ method, params });
+    }
+    catch (error) {
+        logError("notification failed:", error);
+    }
+}
+/**
+ * Send a progress notification to the client
+ * @param progressToken - The progress token provided by the client
+ * @param progress - The current progress value
+ * @param total - Optional total value (for determinate progress)
+ * @param message - Optional status message
+ */
+async function sendProgressNotification(progressToken, progress, total, message) {
+    // Only send if client requested progress updates
+    if (!progressToken)
+        return;
+    try {
+        const params = {
+            progressToken,
+            progress,
+        };
+        if (total !== undefined)
+            params.total = total;
+        if (message)
+            params.message = message;
+        await server.notification({
+            method: PROTOCOL.NOTIFICATIONS.PROGRESS,
+            params,
+        });
+    }
+    catch (error) {
+        logError("Failed to send progress notification:", error);
+    }
+}
+/**
+ * Start periodic progress updates for long-running operations
+ */
+function startProgressUpdates(operationName, progressToken) {
+    isProcessing = true;
+    currentOperationName = operationName;
+    latestOutput = "";
+    const progressMessages = [
+        `${operationName} - Gemini is analyzing your request...`,
+        `${operationName} - Processing files and generating insights...`,
+        `${operationName} - Creating structured response for your review...`,
+        `${operationName} - Large analysis in progress (this is normal for big requests)...`,
+        `${operationName} - Still working... Gemini takes time for quality results...`,
+    ];
+    let messageIndex = 0;
+    let progress = 0;
+    // Send immediate acknowledgment if progress requested
+    if (progressToken) {
+        sendProgressNotification(progressToken, 0, undefined, // No total - indeterminate progress
+        `Starting ${operationName}`);
+    }
+    // Keep client alive with periodic updates
+    const progressInterval = setInterval(async () => {
+        if (isProcessing && progressToken) {
+            progress += 1;
+            // Include latest output preview if available
+            const baseMessage = progressMessages[messageIndex % progressMessages.length];
+            const outputPreview = latestOutput.slice(-150).trim();
+            const message = outputPreview
+                ? `${baseMessage}\nOutput: ...${outputPreview}`
+                : baseMessage;
+            await sendProgressNotification(progressToken, progress, undefined, // No total - indeterminate progress
+            message);
+            messageIndex++;
+        }
+        else if (!isProcessing) {
+            clearInterval(progressInterval);
+        }
+    }, PROTOCOL.KEEPALIVE_INTERVAL);
+    return { interval: progressInterval, progressToken };
+}
+/**
+ * Stop progress updates and send final notification
+ */
+function stopProgressUpdates(progressData, success = true) {
+    const operationName = currentOperationName;
+    isProcessing = false;
+    currentOperationName = "";
+    clearInterval(progressData.interval);
+    // Send final progress notification if client requested progress
+    if (progressData.progressToken) {
+        sendProgressNotification(progressData.progressToken, 100, 100, success
+            ? `✅ ${operationName} completed successfully`
+            : `❌ ${operationName} failed`);
+    }
+}
+// ============================================================================
+// Logging Helpers
+// ============================================================================
+/**
+ * Log debug message to stderr (stdout reserved for MCP protocol)
+ */
+function logDebug(message, ...args) {
+    if (process.env.DEBUG) {
+        console.error(`${LOG_PREFIX} [DEBUG]`, message, ...args);
+    }
+}
+/**
+ * Log info message to stderr
+ */
+function logInfo(message, ...args) {
+    console.error(`${LOG_PREFIX} [INFO]`, message, ...args);
+}
+/**
+ * Log error message to stderr
+ */
+function logError(message, ...args) {
+    console.error(`${LOG_PREFIX} [ERROR]`, message, ...args);
+}
+/**
+ * Log tool invocation for debugging
+ */
+function logToolInvocation(toolName, args) {
+    logDebug(`Tool invoked: ${toolName}`, JSON.stringify(args, null, 2));
+}
+// ============================================================================
+// Request Handlers
+// ============================================================================
+/**
+ * Handle tools/list request
+ * Returns the list of available tools with their schemas
+ */
+server.setRequestHandler(ListToolsRequestSchema, async (_request) => {
+    logDebug("tools/list request received");
+    return { tools: getToolDefinitions() };
+});
+/**
+ * Handle tools/call request
+ * Executes the requested tool and returns the result
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    logDebug(`tools/call request received for: ${toolName}`);
+    if (!toolExists(toolName)) {
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+    // Check if client requested progress updates
+    const progressToken = request.params
+        ._meta?.progressToken;
+    // Start progress updates if client requested them
+    const progressData = startProgressUpdates(toolName, progressToken);
+    try {
+        // Get arguments from request
+        const args = request.params.arguments || {};
+        logToolInvocation(toolName, request.params.arguments);
+        // Execute the tool with progress callback
+        const result = await executeTool(toolName, args, (newOutput) => {
+            latestOutput = newOutput;
+        });
+        // Stop progress updates on success
+        stopProgressUpdates(progressData, true);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        // Stop progress updates on error
+        stopProgressUpdates(progressData, false);
+        logError(`Error in tool '${toolName}':`, error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: {
+                            code: "INTERNAL",
+                            message: `Error executing ${toolName}: ${errorMessage}`,
+                        },
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Server Startup
+// ============================================================================
+/**
+ * Handle the 'init' command (setup wizard)
+ */
+async function handleInitCommand() {
+    const success = await runSetupWizard();
+    process.exit(success ? 0 : 1);
+}
+/**
+ * Perform startup validation
+ * Checks that Gemini CLI is installed and authentication is configured
+ */
+async function performStartupValidation() {
+    const result = await validateEnvironment();
+    if (!result.valid) {
+        console.error(result.error);
+        return false;
+    }
+    logInfo(WIZARD_MESSAGES.STARTUP_SUCCESS);
+    return true;
+}
+/**
+ * Main entry point
+ * Initializes the MCP server with stdio transport
+ */
+async function main() {
+    // Check for 'init' command
+    if (process.argv.includes("init")) {
+        await handleInitCommand();
+        return;
+    }
+    // Perform startup validation
+    const isValid = await performStartupValidation();
+    if (!isValid) {
+        process.exit(1);
+    }
+    logInfo(`Initializing ${SERVER_INFO.NAME} v${SERVER_INFO.VERSION}`);
+    // Create stdio transport
+    const transport = new StdioServerTransport();
+    // Connect server to transport
+    await server.connect(transport);
+    logInfo(`${SERVER_INFO.NAME} listening on stdio`);
+}
+// Start the server
+main().catch((error) => {
+    logError("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/setup/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Setup module barrel export
+ * Exports the setup wizard functionality
+ */
+export { runSetupWizard, validateEnvironment } from "./wizard.js";
+export type { ValidationResult, GeminiInstallCheck, } from "./wizard.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/setup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/setup/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC"}

package/dist/setup/index.js

@@ -0,0 +1,6 @@
+/**
+ * Setup module barrel export
+ * Exports the setup wizard functionality
+ */
+export { runSetupWizard, validateEnvironment } from "./wizard.js";
+//# sourceMappingURL=index.js.map

package/dist/setup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/setup/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/setup/wizard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Setup Wizard for Better Gemini MCP Server
+ * Guides first-time users through validating their environment
+ * and configuring Gemini CLI authentication.
+ */
+export interface ValidationResult {
+    success: boolean;
+    message?: string;
+    details?: Record<string, unknown>;
+    isAuthError?: boolean;
+}
+export interface GeminiInstallCheck {
+    installed: boolean;
+    path: string | null;
+    version: string | null;
+}
+/**
+ * Step 1: Check if Gemini CLI is installed
+ */
+export declare function checkGeminiInstallation(): Promise<GeminiInstallCheck>;
+/**
+ * Step 2: Test Gemini CLI invocation
+ * This also validates authentication - if auth is missing, command will fail
+ */
+export declare function testGeminiInvocation(): Promise<ValidationResult>;
+/**
+ * Run the complete setup wizard
+ * Performs all validation steps and displays results to the user
+ */
+export declare function runSetupWizard(): Promise<boolean>;
+/**
+ * Validate environment at startup (quick validation, no user interaction)
+ * Returns true if environment is valid, false otherwise
+ */
+export declare function validateEnvironment(): Promise<{
+    valid: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=wizard.d.ts.map