@oobe-protocol-labs/sap-mcp-server 0.1.0

package/dist/config/wizard.js

@@ -0,0 +1,1176 @@
+#!/usr/bin/env node
+/**
+ * SAP MCP Server - Configuration Wizard
+ *
+ * Interactive wizard for initial configuration setup.
+ * Guides users through secure configuration with explanations.
+ *
+ * Usage:
+ *   npx sap-mcp-config wizard
+ */
+import { existsSync, readFileSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import readline from 'readline';
+import { Keypair } from '@solana/web3.js';
+import { defaults } from './defaults.js';
+import { defaultGeneratedWalletPath } from './paths.js';
+import { saveWizardSetup } from './setup.js';
+import { applyMcpClientInjection, createCanonicalServerConfig, createManualMcpJsonSnippets, discoverMcpClientTargets, planMcpClientInjection, } from './mcp-client-injection.js';
+class WizardCancelled extends Error {
+    constructor() {
+        super('Wizard cancelled');
+        this.name = 'WizardCancelled';
+    }
+}
+const EXIT_COMMANDS = new Set(['exit', 'quit', 'cancel', 'q', ':q', '/exit', '/quit', '/cancel']);
+const HELP_COMMANDS = new Set(['?', 'help', '/help']);
+const WIZARD_WIDTH = 72;
+const COLOR_ENABLED = process.env.NO_COLOR !== '1' && process.env.SAP_MCP_NO_COLOR !== 'true';
+const color = {
+    aqua: '\x1b[36m',
+    blue: '\x1b[34m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    magenta: '\x1b[35m',
+    gray: '\x1b[90m',
+    bold: '\x1b[1m',
+    reset: '\x1b[0m',
+};
+/**
+ * @name paint
+ * @description Applies ANSI color only when terminal color output is enabled.
+ */
+function paint(value, ...colors) {
+    if (!COLOR_ENABLED) {
+        return value;
+    }
+    return `${colors.map((name) => color[name]).join('')}${value}${color.reset}`;
+}
+// ============================================================================
+// Interactive CLI Helper
+// ============================================================================
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+process.once('SIGINT', () => {
+    console.log(`\n${paint('Wizard cancelled. No configuration was saved.', 'yellow')}`);
+    rl.close();
+    process.exit(130);
+});
+/**
+ * Returns true when the user requested wizard cancellation.
+ */
+function isExitCommand(value) {
+    return EXIT_COMMANDS.has(value.trim().toLowerCase());
+}
+/**
+ * Returns true when the user requested contextual help.
+ */
+function isHelpCommand(value) {
+    return HELP_COMMANDS.has(value.trim().toLowerCase());
+}
+/**
+ * Prints contextual help for a prompt.
+ */
+function printPromptHelp(lines) {
+    console.log('');
+    console.log(paint('Help', 'aqua', 'bold'));
+    for (const line of lines ?? ['Enter a value, or type /exit to cancel the wizard.']) {
+        console.log(`  ${line}`);
+    }
+    console.log('');
+}
+/**
+ * Prints the common wizard control hints.
+ */
+function printControlHints() {
+    console.log(paint('Controls: type ? for help, /exit to cancel, Ctrl+C to abort.', 'gray'));
+}
+/**
+ * Builds a user-friendly prompt string with default values.
+ */
+function formatPrompt(question, defaultValue) {
+    return defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+}
+/**
+ * Formats a selectable option label, preserving labels that already include ANSI styling.
+ */
+function formatChoiceLabel(choice) {
+    return choice.includes('\x1b[') ? choice : paint(choice, 'aqua');
+}
+/**
+ * Internal helper for the ask question operation.
+ */
+function askQuestion(question, defaultValueOrOptions) {
+    const options = typeof defaultValueOrOptions === 'string'
+        ? { defaultValue: defaultValueOrOptions }
+        : defaultValueOrOptions ?? {};
+    return new Promise((resolve, reject) => {
+        const ask = () => {
+            rl.question(formatPrompt(question, options.defaultValue), (answer) => {
+                const raw = answer.trim();
+                if (isExitCommand(raw)) {
+                    reject(new WizardCancelled());
+                    return;
+                }
+                if (isHelpCommand(raw)) {
+                    printPromptHelp(options.help);
+                    ask();
+                    return;
+                }
+                const candidate = raw || options.defaultValue || '';
+                const value = options.transform ? options.transform(candidate) : candidate;
+                if (options.required && !value) {
+                    printError('This field is required.');
+                    ask();
+                    return;
+                }
+                const validationError = options.validate?.(value);
+                if (validationError) {
+                    printError(validationError);
+                    ask();
+                    return;
+                }
+                resolve(value);
+            });
+        };
+        ask();
+    });
+}
+/**
+ * Internal helper for the ask choice operation.
+ */
+function askChoice(question, choices, defaultIndex = 0, help) {
+    return new Promise((resolve, reject) => {
+        const ask = () => {
+            console.log(question);
+            choices.forEach((choice, i) => {
+                const marker = i === defaultIndex ? ' (recommended)' : '';
+                console.log(`  ${paint(`${i + 1})`, 'gray')} ${formatChoiceLabel(choice)}${paint(marker, 'green')}`);
+            });
+            const prompt = `Enter choice (1-${choices.length})`;
+            const defaultChoice = defaultIndex + 1;
+            rl.question(`${paint(`${prompt} [${defaultChoice}]:`, 'gray')} `, (answer) => {
+                const raw = answer.trim();
+                if (isExitCommand(raw)) {
+                    reject(new WizardCancelled());
+                    return;
+                }
+                if (isHelpCommand(raw)) {
+                    printPromptHelp(help);
+                    ask();
+                    return;
+                }
+                if (!raw) {
+                    resolve(defaultIndex);
+                    return;
+                }
+                const num = parseInt(raw, 10);
+                if (isNaN(num) || num < 1 || num > choices.length) {
+                    printError(`Choose a number between 1 and ${choices.length}.`);
+                    ask();
+                    return;
+                }
+                resolve(num - 1);
+            });
+        };
+        ask();
+    });
+}
+/**
+ * Internal helper for selecting multiple numbered options in one prompt.
+ */
+function askMultiChoice(question, choices, defaultIndexes = [], help) {
+    return new Promise((resolve, reject) => {
+        const ask = () => {
+            console.log(question);
+            choices.forEach((choice, i) => {
+                const marker = defaultIndexes.includes(i) ? ' (default)' : '';
+                console.log(`  ${paint(`${i + 1})`, 'gray')} ${formatChoiceLabel(choice)}${paint(marker, 'green')}`);
+            });
+            const defaultValue = defaultIndexes.length > 0
+                ? defaultIndexes.map((index) => String(index + 1)).join(',')
+                : 'none';
+            rl.question(`${paint(`Enter choices as comma-separated numbers, "all", or "none" [${defaultValue}]:`, 'gray')} `, (answer) => {
+                const raw = answer.trim().toLowerCase();
+                if (isExitCommand(raw)) {
+                    reject(new WizardCancelled());
+                    return;
+                }
+                if (isHelpCommand(raw)) {
+                    printPromptHelp(help);
+                    ask();
+                    return;
+                }
+                const value = raw || defaultValue;
+                if (value === 'none' || value === 'no' || value === 'skip') {
+                    resolve([]);
+                    return;
+                }
+                if (value === 'all') {
+                    resolve(choices.map((_, index) => index));
+                    return;
+                }
+                const indexes = value
+                    .split(',')
+                    .map((item) => Number(item.trim()))
+                    .filter((item) => Number.isInteger(item));
+                if (indexes.length === 0 || indexes.some((item) => item < 1 || item > choices.length)) {
+                    printError(`Choose numbers between 1 and ${choices.length}, "all", or "none".`);
+                    ask();
+                    return;
+                }
+                resolve(Array.from(new Set(indexes.map((item) => item - 1))));
+            });
+        };
+        ask();
+    });
+}
+/**
+ * Internal helper for the ask confirm operation.
+ */
+function askConfirm(question, defaultYes = false, help) {
+    return new Promise((resolve, reject) => {
+        const ask = () => {
+            const suffix = defaultYes ? ' (Y/n)' : ' (y/N)';
+            rl.question(`${question}${suffix}: `, (answer) => {
+                const lower = answer.toLowerCase().trim();
+                if (isExitCommand(lower)) {
+                    reject(new WizardCancelled());
+                    return;
+                }
+                if (isHelpCommand(lower)) {
+                    printPromptHelp(help);
+                    ask();
+                    return;
+                }
+                if (lower === '') {
+                    resolve(defaultYes);
+                    return;
+                }
+                if (lower === 'y' || lower === 'yes') {
+                    resolve(true);
+                    return;
+                }
+                if (lower === 'n' || lower === 'no') {
+                    resolve(false);
+                    return;
+                }
+                printError('Answer yes or no.');
+                ask();
+            });
+        };
+        ask();
+    });
+}
+/**
+ * Internal helper for the clear console operation.
+ */
+function clearConsole() {
+    console.clear();
+}
+/**
+ * Internal helper for the print header operation.
+ */
+function printHeader(title, subtitle) {
+    const width = WIZARD_WIDTH;
+    const line = '═'.repeat(width);
+    const space = ' '.repeat(width);
+    console.log('');
+    console.log(paint('╔' + line + '╗', 'aqua'));
+    console.log(paint('║', 'aqua') + space + paint('║', 'aqua'));
+    const titlePadding = Math.floor((width - title.length) / 2);
+    const titleLine = ' '.repeat(titlePadding) + title + ' '.repeat(width - titlePadding - title.length);
+    console.log(paint('║', 'aqua') + paint(titleLine, 'bold') + paint('║', 'aqua'));
+    if (subtitle) {
+        const subPadding = Math.floor((width - subtitle.length) / 2);
+        const subLine = ' '.repeat(subPadding) + subtitle + ' '.repeat(width - subPadding - subtitle.length);
+        console.log(paint('║', 'aqua') + paint(subLine, 'gray') + paint('║', 'aqua'));
+    }
+    console.log(paint('║', 'aqua') + space + paint('║', 'aqua'));
+    console.log(paint('╚' + line + '╝', 'aqua'));
+    console.log('');
+}
+/**
+ * Print SAP ASCII art logo
+ */
+function printSapLogo() {
+    const logo = [
+        '  ███████╗ █████╗ ██████╗     ███╗   ███╗ ██████╗██████╗ ',
+        '  ██╔════╝██╔══██╗██╔══██╗════████╗ ████║██╔════╝██╔══██╗',
+        '  ███████╗███████║██████╔╝════██╔████╔██║██║     ██████╔╝',
+        '  ╚════██║██╔══██║██╔═══╝     ██║╚██╔╝██║██║     ██╔═══╝ ',
+        '  ███████║██║  ██║██║         ██║ ╚═╝ ██║╚██████╗██║     ',
+        '  ╚══════╝╚═╝  ╚═╝╚═╝         ╚═╝     ╚═╝ ╚═════╝╚═╝     ',
+        '',
+        '  ┌─────────────────────────────────────┐',
+        '  │  Synapse Agent Protocol  │  MCP     │',
+        '  └─────────────────────────────────────┘',
+    ];
+    console.log(logo.map((line) => paint(line, 'aqua')).join('\n'));
+    console.log('');
+}
+/**
+ * Internal helper for the print section operation.
+ */
+function printSection(title) {
+    console.log(`\n${paint('─'.repeat(WIZARD_WIDTH), 'aqua')}`);
+    console.log(`  ${paint(title, 'aqua', 'bold')}`);
+    console.log(`${paint('─'.repeat(WIZARD_WIDTH), 'aqua')}\n`);
+}
+/**
+ * Internal helper for the print success operation.
+ */
+function printSuccess(message) {
+    console.log(paint(`OK: ${message}`, 'green'));
+}
+/**
+ * Internal helper for the print info operation.
+ */
+function printInfo(message) {
+    console.log(paint(`Info: ${message}`, 'aqua'));
+}
+/**
+ * Prints a warning message.
+ */
+function printWarning(message) {
+    console.log(paint(`Warning: ${message}`, 'yellow'));
+}
+/**
+ * Prints an error message with a text prefix that remains meaningful without color.
+ */
+function printError(message) {
+    console.log(paint(`Error: ${message}`, 'red'));
+}
+/**
+ * Prints a descriptive lead paragraph for the current wizard step.
+ */
+function printLead(message) {
+    console.log(paint(message, 'aqua'));
+}
+/**
+ * Prints a section label in the wizard's primary color.
+ */
+function printLabel(label) {
+    console.log(paint(label, 'aqua', 'bold'));
+}
+/**
+ * Prints one accessible bullet line.
+ */
+function printBullet(message) {
+    console.log(`  - ${message}`);
+}
+/**
+ * Prints a key/value summary row.
+ */
+function printField(label, value) {
+    console.log(`  ${paint(`${label}:`, 'aqua')} ${value}`);
+}
+/**
+ * Expands a shell-style home directory prefix for local file inputs.
+ */
+function expandHomePath(path) {
+    if (path === '~') {
+        return homedir();
+    }
+    if (path.startsWith('~/')) {
+        return join(homedir(), path.slice(2));
+    }
+    return path;
+}
+/**
+ * Validates profile names used as config and wallet filename components.
+ */
+function validateProfileName(value) {
+    if (value === 'default') {
+        return 'Use a named profile instead of "default" so wallets and configs stay explicit.';
+    }
+    if (value.length < 3 || value.length > 48) {
+        return 'Profile names must be between 3 and 48 characters.';
+    }
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)) {
+        return 'Use lowercase letters, numbers, and single hyphens between words.';
+    }
+    return undefined;
+}
+/**
+ * Validates HTTP(S) URLs.
+ */
+function validateHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return 'URL must start with http:// or https://.';
+        }
+        if (!url.hostname) {
+            return 'URL must include a hostname.';
+        }
+        return undefined;
+    }
+    catch {
+        return 'Enter a valid URL, for example https://api.mainnet-beta.solana.com.';
+    }
+}
+/**
+ * Validates a Solana keypair JSON file without exposing the secret bytes.
+ */
+function validateWalletFile(value) {
+    const walletPath = expandHomePath(value);
+    if (!existsSync(walletPath)) {
+        return 'Wallet file does not exist.';
+    }
+    try {
+        const stat = statSync(walletPath);
+        if (!stat.isFile()) {
+            return 'Wallet path must point to a JSON file.';
+        }
+        const parsed = JSON.parse(readFileSync(walletPath, 'utf-8'));
+        if (!Array.isArray(parsed) || parsed.length !== 64) {
+            return 'Wallet JSON must be a Solana keypair array with 64 bytes.';
+        }
+        const bytes = parsed;
+        if (!bytes.every((item) => Number.isInteger(item) && Number(item) >= 0 && Number(item) <= 255)) {
+            return 'Wallet JSON contains invalid byte values.';
+        }
+        Keypair.fromSecretKey(Uint8Array.from(bytes));
+        return undefined;
+    }
+    catch {
+        return 'Wallet file is not a valid Solana keypair JSON.';
+    }
+}
+/**
+ * Creates a validator for positive SOL amount inputs.
+ */
+function validateSolAmount(label, options = {}) {
+    return (value) => {
+        const amount = Number(value);
+        const minimum = options.min ?? 0;
+        const maximum = options.max ?? 1_000_000;
+        if (!Number.isFinite(amount)) {
+            return `${label} must be a number.`;
+        }
+        if (!options.allowZero && amount <= 0) {
+            return `${label} must be greater than 0 SOL.`;
+        }
+        if (amount < minimum) {
+            return `${label} must be at least ${minimum} SOL.`;
+        }
+        if (amount > maximum) {
+            return `${label} is too high; choose a value below ${maximum} SOL.`;
+        }
+        return undefined;
+    };
+}
+/**
+ * Validates that a daily spending limit can contain the per-transaction limit.
+ */
+function validateDailyLimit(maxTxValueSol) {
+    return (value) => {
+        const amountError = validateSolAmount('Daily spending limit', { allowZero: false })(value);
+        if (amountError) {
+            return amountError;
+        }
+        if (Number(value) < maxTxValueSol) {
+            return 'Daily spending limit must be greater than or equal to the maximum transaction value.';
+        }
+        return undefined;
+    };
+}
+/**
+ * Validates TCP port numbers.
+ */
+function validatePort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        return 'Port must be an integer between 1 and 65535.';
+    }
+    return undefined;
+}
+// ============================================================================
+// Wizard Steps
+// ============================================================================
+/**
+ * Internal helper for the wizard welcome operation.
+ */
+async function wizardWelcome() {
+    clearConsole();
+    printSapLogo();
+    printHeader('SAP MCP Configuration Wizard', 'Secure setup for AI agent access to SAP Protocol');
+    printLead('This guided setup creates a named SAP MCP profile, isolates its wallet, and prepares MCP clients to load the active profile safely.');
+    printLead('You can review everything before saving. Secret key bytes are never printed or injected into client configs.');
+    printControlHints();
+    console.log('');
+    printLabel('What this wizard configures');
+    printBullet('A named profile under ~/.config/mcp-sap/config-<profile>.json.');
+    printBullet('A dedicated wallet path under ~/.config/mcp-sap/keypairs/ when signing is enabled.');
+    printBullet('Policy limits for transaction value, daily spending, and optional Bento Guard checks.');
+    printBullet('Optional MCP client config injection for Claude, Hermes, OpenClaw, and Codex.');
+    console.log('');
+    printLabel('What this wizard will not do');
+    printBullet('It will not modify ~/.config/solana/id.json.');
+    printBullet('It will not print, log, or copy keypair bytes.');
+    printBullet('It will not write anything until the final confirmation step.');
+    console.log('');
+    const continueResult = await askConfirm('Continue?', true, [
+        'Choose yes to create/update a named SAP MCP profile.',
+        'Type /exit at any prompt to leave without saving.',
+    ]);
+    if (!continueResult) {
+        throw new WizardCancelled();
+    }
+}
+/**
+ * Internal helper for the wizard profile operation.
+ */
+async function wizardProfile() {
+    while (true) {
+        clearConsole();
+        printSapLogo();
+        printHeader('Step 1: Agent Profile', 'Create or select agent identity');
+        printLead('Choose a stable profile name for this agent or operator identity.');
+        printControlHints();
+        console.log('');
+        printLabel('Profile naming convention');
+        printBullet('Use a descriptive name such as merchant-lexus-sap.');
+        printBullet('Include the agent purpose, environment, or business role.');
+        printBullet('Use lowercase letters, numbers, and hyphens only.');
+        printBullet('The name controls config and wallet isolation.');
+        console.log('');
+        printLabel('Examples');
+        printBullet('merchant-lexus-sap');
+        printBullet('gianni-market-nft-agent');
+        printBullet('dev-testing-mainnet');
+        printBullet('citizen-support-bot');
+        console.log('');
+        const profileName = await askQuestion('Profile name', {
+            required: true,
+            transform: (value) => value.trim().toLowerCase(),
+            validate: validateProfileName,
+            help: [
+                'Use the real agent identity, for example gianni-market-nft-agent.',
+                'The wizard reserves "default" to prevent accidental profile ambiguity.',
+                'This name becomes config-<profile>.json and <profile>-keypair.json.',
+            ],
+        });
+        return profileName;
+    }
+}
+/**
+ * Internal helper for the wizard mode operation.
+ */
+async function wizardMode() {
+    clearConsole();
+    printSapLogo();
+    printHeader('Step 2: Server Mode', 'How will the MCP server run?');
+    printLead('Choose the trust model for this profile. This controls whether SAP MCP can only read data, prepare transactions, or request signatures.');
+    console.log('');
+    printLabel('Mode guidance');
+    printBullet('Choose readonly if the agent only needs discovery, analytics, profile context, or registry reads.');
+    printBullet('Choose external-signer for production signing, hardware wallets, custody systems, or the local signing proxy.');
+    printBullet('Choose local-dev-keypair only when this machine should hold the dedicated SAP MCP wallet file.');
+    printBullet('Choose hosted-api when deploying the MCP server for remote clients behind HTTPS.');
+    console.log('');
+    printControlHints();
+    console.log('');
+    const choices = [
+        `${paint('readonly', 'aqua', 'bold')} ${paint('[safest]', 'green')} - Read tools only; no transaction signing.`,
+        `${paint('local-dev-keypair', 'aqua', 'bold')} ${paint('[local wallet]', 'yellow')} - Signs with this profile's dedicated keypair file.`,
+        `${paint('external-signer', 'aqua', 'bold')} ${paint('[production]', 'green')} - Sends signing requests to Ledger, Fireblocks, or signing proxy.`,
+        `${paint('delegated-session', 'aqua', 'bold')} ${paint('[limited session]', 'blue')} - Uses session-scoped permissions and spending limits.`,
+        `${paint('hosted-api', 'aqua', 'bold')} ${paint('[remote HTTP]', 'magenta')} - Runs Streamable HTTP MCP for VPS/client access.`,
+    ];
+    const index = await askChoice(paint('Select operating mode:', 'aqua', 'bold'), choices, 0, [
+        'readonly is recommended when you only need discovery and read tools.',
+        'local-dev-keypair signs with the dedicated profile wallet, never Solana CLI id.json.',
+        'external-signer is preferred for production signing.',
+        'hosted-api enables remote MCP over HTTP and should be deployed behind TLS.',
+    ]);
+    const modes = ['readonly', 'local-dev-keypair', 'external-signer', 'delegated-session', 'hosted-api'];
+    return modes[index];
+}
+/**
+ * Internal helper for the wizard rpc url operation.
+ */
+async function wizardRpcUrl(mode) {
+    clearConsole();
+    printSapLogo();
+    printHeader('Step 3: Solana RPC', 'Blockchain connection settings');
+    const isDev = mode === 'local-dev-keypair';
+    const defaultRpc = isDev
+        ? 'https://api.devnet.solana.com'
+        : 'https://api.mainnet-beta.solana.com';
+    printLead('Select the Solana network and RPC endpoint this profile will use. Tools will report and execute against this configured network.');
+    printControlHints();
+    console.log('');
+    printLabel('Common endpoints');
+    printField('Mainnet', paint('https://api.mainnet-beta.solana.com', 'green'));
+    printField('Devnet', paint('https://api.devnet.solana.com', 'yellow'));
+    printField('Testnet', paint('https://api.testnet.solana.com', 'blue'));
+    printField('Custom', 'Your own RPC endpoint');
+    console.log('');
+    const rpcUrl = await askQuestion('RPC URL', {
+        defaultValue: defaultRpc,
+        required: true,
+        validate: validateHttpUrl,
+        help: [
+            'Use devnet for disposable test wallets and faucet workflows.',
+            'Use mainnet-beta only when the profile wallet is intended for production assets.',
+            'Custom RPC endpoints are allowed if they use http:// or https://.',
+        ],
+    });
+    return rpcUrl;
+}
+/**
+ * Internal helper for the wizard signer config operation.
+ */
+async function wizardSignerConfig(mode, profileName) {
+    if (mode === 'readonly') {
+        return {};
+    }
+    if (mode === 'local-dev-keypair') {
+        clearConsole();
+        printSapLogo();
+        printHeader('Step 4: Wallet Configuration', 'Local keypair setup');
+        printLead('Choose the wallet that will sign transactions for this profile. A new dedicated wallet is safest for first-time setup.');
+        printControlHints();
+        console.log('');
+        printField('Profile', profileName);
+        printField('Default wallet', `~/.config/mcp-sap/keypairs/${profileName}-keypair.json`);
+        printWarning('The wizard never modifies ~/.config/solana/id.json and never asks you to paste secret key bytes.');
+        console.log('');
+        const useExisting = await askChoice('Choose option:', [
+            'Use existing wallet file',
+            `Create new wallet for "${profileName}"`,
+        ], 1, [
+            'Creating a wallet is safest for new agents because it isolates funds and permissions.',
+            'Using an existing wallet validates the JSON keypair file and stores only its path.',
+            'Do not paste keypair bytes into the terminal.',
+        ]);
+        if (useExisting === 0) {
+            // Use existing wallet
+            console.log('');
+            printLead('Enter the path to a Solana keypair JSON file. The wizard validates the file and stores only the path.');
+            printLabel('Examples');
+            printBullet(`~/.config/mcp-sap/keypairs/${profileName}-keypair.json`);
+            printBullet('/path/to/wallet.json');
+            console.log('');
+            const defaultPath = defaultGeneratedWalletPath(profileName);
+            const walletPath = await askQuestion('Wallet path', {
+                defaultValue: defaultPath,
+                required: true,
+                transform: expandHomePath,
+                validate: validateWalletFile,
+                help: [
+                    'Enter the path to a Solana keypair JSON file.',
+                    'The wizard validates the file and stores the path, not the secret bytes.',
+                    'Use a dedicated SAP MCP wallet, not your Solana CLI id.json.',
+                ],
+            });
+            return { walletPath, createNewWallet: false };
+        }
+        else {
+            // Create new wallet
+            const walletFileName = `${profileName}-keypair.json`;
+            console.log('');
+            printSuccess(`Will create a new dedicated wallet for profile "${profileName}".`);
+            printField('Wallet path', `~/.config/mcp-sap/keypairs/${walletFileName}`);
+            printInfo('This wallet is isolated from the Solana CLI keypair.');
+            printWarning('Back up this keypair after creation; it controls funds for this SAP MCP profile.');
+            console.log('');
+            return { createNewWallet: true };
+        }
+    }
+    if (mode === 'external-signer') {
+        clearConsole();
+        printSapLogo();
+        printHeader('Step 4: External Signer', 'Signing service configuration');
+        printLead('Enter the URL of the service that will sign transactions without exposing key material to the MCP server.');
+        printControlHints();
+        console.log('');
+        printLabel('Examples');
+        printBullet('http://localhost:8080/sign');
+        printBullet('https://fireblocks.example.com/api/v1/sign');
+        console.log('');
+        const externalSignerUrl = await askQuestion('External signer URL', {
+            defaultValue: 'http://localhost:8080/sign',
+            required: true,
+            validate: validateHttpUrl,
+            help: [
+                'The signer service must expose the SAP MCP signing protocol.',
+                'Use HTTPS for remote signer services.',
+                'Localhost HTTP is acceptable for local development only.',
+            ],
+        });
+        return { externalSignerUrl };
+    }
+    return {};
+}
+/**
+ * Internal helper for the wizard security limits operation.
+ */
+async function wizardSecurityLimits(mode) {
+    if (mode === 'readonly') {
+        return { maxTxValueSol: 0, dailyLimitSol: 0 };
+    }
+    clearConsole();
+    printSapLogo();
+    printHeader('Step 5: Security Limits', 'Transaction spending controls');
+    printLead('Set guardrails before this profile can sign or submit transactions. These limits are enforced before signing.');
+    printControlHints();
+    console.log('');
+    const maxTxValueSol = await askQuestion(paint('Maximum transaction value (SOL)', 'aqua'), {
+        defaultValue: defaults.maxTxValueSol.toString(),
+        required: true,
+        validate: validateSolAmount('Maximum transaction value', { allowZero: false }),
+        help: [
+            'This is a hard per-transaction ceiling enforced before signing.',
+            'For test/dev profiles, 1 SOL or less is usually enough.',
+        ],
+    });
+    const dailyLimitSol = await askQuestion(paint('Daily spending limit (SOL)', 'aqua'), {
+        defaultValue: defaults.dailyLimitSol.toString(),
+        required: true,
+        validate: validateDailyLimit(Number(maxTxValueSol)),
+        help: [
+            'This is the total native SOL value allowed per day.',
+            'It must be greater than or equal to the per-transaction maximum.',
+        ],
+    });
+    return {
+        maxTxValueSol: parseFloat(maxTxValueSol) || defaults.maxTxValueSol,
+        dailyLimitSol: parseFloat(dailyLimitSol) || defaults.dailyLimitSol,
+    };
+}
+/**
+ * Internal helper for the wizard bento integration operation.
+ */
+async function wizardBentoIntegration() {
+    clearConsole();
+    printSapLogo();
+    printHeader('Step 6: Bento Guard Integration', 'Optional AI-powered security layer');
+    printLead('Bento Guard is optional. When enabled, local deterministic policy still runs and Bento adds AI-assisted intent scoring.');
+    printControlHints();
+    console.log('');
+    printWarning('This step is optional. Choose no to use local policy enforcement only.');
+    console.log('');
+    printLabel('If enabled');
+    printBullet('Tool calls are scored for intent and policy risk.');
+    printBullet('Suspicious actions can be escalated or blocked.');
+    printBullet('Bento outages follow your configured fail-open/fail-closed policy.');
+    printBullet('API keys are redacted in summaries.');
+    console.log('');
+    const enableBento = await askConfirm('Enable Bento Guard integration?', false, [
+        'Choose no for local-only policy enforcement.',
+        'Choose yes when you have Bento credentials and want hybrid policy checks.',
+    ]);
+    if (!enableBento) {
+        console.log('');
+        printInfo('Skipping Bento. This profile will use local policy enforcement only.');
+        printLabel('Enable later with');
+        printBullet('SAP_MCP_BENTO_API_KEY');
+        printBullet('SAP_MCP_BENTO_AGENT_ID');
+        console.log('');
+        return { enableBento: false };
+    }
+    console.log('');
+    printLead('Enter your Bento Guard credentials.');
+    printField('Dashboard', 'https://app.bentoguard.xyz');
+    console.log('');
+    const bentoApiKey = await askQuestion(paint('Bento API Key', 'aqua'), {
+        required: true,
+        help: [
+            'Paste only the Bento API key here.',
+            'It is redacted in the summary and can be rotated later.',
+        ],
+    });
+    const bentoAgentId = await askQuestion(paint('Bento Agent ID', 'aqua'), {
+        defaultValue: 'sap-mcp-server-' + Math.random().toString(36).substring(2, 8),
+        required: true,
+        validate: (value) => /^[a-zA-Z0-9_.:-]+$/.test(value)
+            ? undefined
+            : 'Bento Agent ID may contain letters, numbers, dot, underscore, colon, or hyphen.',
+        help: [
+            'This identifies this SAP MCP server inside Bento policy logs.',
+        ],
+    });
+    console.log('');
+    printSuccess('Bento Guard will be used for policy enforcement.');
+    printInfo('Local policies still run as deterministic guardrails.');
+    console.log('');
+    return {
+        enableBento: true,
+        bentoApiKey,
+        bentoAgentId,
+    };
+}
+/**
+ * Internal helper for the wizard http transport operation.
+ */
+async function wizardHttpTransport(mode) {
+    if (mode !== 'hosted-api') {
+        return { enableHttp: false, httpPort: defaults.httpPort };
+    }
+    clearConsole();
+    printSapLogo();
+    printHeader('Step 7: HTTP Transport', 'API server configuration');
+    printLead('HTTP mode exposes MCP over Streamable HTTP for remote clients. Use this for VPS deployments and hosted agent workflows.');
+    printControlHints();
+    console.log('');
+    printWarning('Production HTTP deployments must sit behind HTTPS/TLS and operational monitoring.');
+    console.log('');
+    const enableHttp = await askConfirm('Enable HTTP API server?', true, [
+        'HTTP mode is for remote MCP clients and VPS deployment.',
+        'Use a reverse proxy such as Caddy or nginx for HTTPS/TLS.',
+    ]);
+    if (!enableHttp) {
+        return { enableHttp: false, httpPort: defaults.httpPort };
+    }
+    const httpPort = await askQuestion(paint('HTTP port', 'aqua'), {
+        defaultValue: defaults.httpPort.toString(),
+        required: true,
+        validate: validatePort,
+        help: [
+            'Use 8787 locally unless another service already uses it.',
+            'In production, expose HTTPS via a reverse proxy and forward to this port.',
+        ],
+    });
+    return {
+        enableHttp: true,
+        httpPort: parseInt(httpPort, 10) || defaults.httpPort,
+    };
+}
+/**
+ * Internal helper for the wizard logging operation.
+ */
+async function wizardLogging() {
+    clearConsole();
+    printSapLogo();
+    printHeader('Step 8: Logging & Observability', 'Debugging and monitoring');
+    printLead('Choose how much operational detail SAP MCP should write to logs.');
+    printControlHints();
+    console.log('');
+    const logChoices = ['debug', 'info', 'warn', 'error'];
+    const logIndex = await askChoice('Log level:', logChoices.map((level, i) => {
+        const colors = ['blue', 'aqua', 'yellow', 'red'];
+        return paint(level, colors[i]);
+    }), 1, [
+        'info is recommended for normal use.',
+        'debug is useful while integrating Hermes, Claude, Codex, or OpenClaw.',
+        'error is quietest and best for stable production logs.',
+    ]);
+    const enableMetrics = await askConfirm('Enable Prometheus metrics?', false, [
+        'Metrics expose operational counters for monitoring.',
+        'Enable when deploying behind a trusted network or protected reverse proxy.',
+    ]);
+    return {
+        logLevel: logChoices[logIndex],
+        enableMetrics,
+    };
+}
+/**
+ * Formats a discovered MCP client target for selector output.
+ */
+function formatMcpClientTarget(target) {
+    const state = target.exists ? 'found' : 'will create';
+    const profile = target.profileName ? ` (${target.profileName})` : '';
+    return `${target.label}${profile} - ${state} - ${target.path}`;
+}
+/**
+ * Prints copy/paste JSON snippets for manual MCP client setup.
+ */
+function printManualMcpJsonSnippets(canonical = createCanonicalServerConfig(process.cwd())) {
+    const snippets = createManualMcpJsonSnippets(canonical);
+    console.log('');
+    printSection('Manual MCP Client Configuration');
+    printLead('Paste one of these JSON snippets into the MCP config for Claude, Hermes, OpenClaw, Codex, or another MCP-capable agent.');
+    printWarning('Do not add wallet paths, RPC overrides, profile names, or keypair bytes to client config.');
+    console.log('');
+    for (const snippet of snippets) {
+        printLabel(snippet.title);
+        printBullet(snippet.description);
+        console.log('');
+        console.log(snippet.content.trimEnd());
+        console.log('');
+    }
+}
+/**
+ * Prints the recommended hosted MCP client configuration.
+ */
+function printHostedMcpJsonSnippet(canonical = createCanonicalServerConfig(process.cwd())) {
+    const hostedSnippet = createManualMcpJsonSnippets(canonical)
+        .find((snippet) => snippet.title === 'Hosted SAP MCP JSON');
+    if (!hostedSnippet) {
+        printError('Hosted SAP MCP snippet is not available.');
+        return;
+    }
+    console.log('');
+    printSection('Hosted SAP MCP Configuration');
+    printLead('Use this for agents that should connect to the OOBE hosted MCP server.');
+    printInfo('Hosted mode uses the remote MCP transport, but the user SAP profile and signer are still created locally by this wizard.');
+    printInfo('The local wallet or external signer is what authorizes x402, pay.sh, and any value-moving tool transaction.');
+    console.log('');
+    printField('Hosted MCP URL', 'https://mcp.sap.oobeprotocol.ai/mcp');
+    printWarning('Do not paste keypair bytes into hosted client config. Keep wallet material in ~/.config/mcp-sap or an external signer.');
+    printWarning('Do not add stale SAP_MCP_RPC_URL or SAP_WALLET_PATH overrides to the hosted MCP block.');
+    console.log('');
+    printLabel(`${hostedSnippet.title} ${paint('[RECOMMENDED]', 'green', 'bold')}`);
+    printBullet(hostedSnippet.description);
+    printBullet('Run the wizard first to create the user SAP profile, wallet path, policy limits, and signing preferences.');
+    printBullet('For signing flows, the agent must use the configured local wallet/external signer rather than expecting the hosted server to hold private keys.');
+    console.log('');
+    console.log(hostedSnippet.content.trimEnd());
+    console.log('');
+}
+/**
+ * Runs the optional MCP client injection step after profile config has been saved.
+ */
+async function wizardMcpClientInjection(result) {
+    clearConsole();
+    printSapLogo();
+    printHeader('Optional MCP Client Setup', 'Connect agents to hosted or local SAP MCP');
+    printLead('Choose how Claude, Hermes, OpenClaw, Codex, or another MCP client should reach SAP MCP.');
+    printInfo('For most users, run this wizard to create the SAP profile/signer, then connect the agent to https://mcp.sap.oobeprotocol.ai/mcp.');
+    printInfo('Injected client config does not pin wallet paths, RPC overrides, profile names, or keypair bytes.');
+    console.log('');
+    printField('Agent public key', result.config.agentPubkey ?? 'not configured');
+    printField('Config path', result.configPath);
+    printField('Hosted MCP URL', 'https://mcp.sap.oobeprotocol.ai/mcp');
+    printControlHints();
+    console.log('');
+    const setupMode = await askChoice('How do you want to configure MCP clients?', [
+        `${paint('Connect to hosted SAP MCP at https://mcp.sap.oobeprotocol.ai/mcp', 'aqua', 'bold')} ${paint('[RECOMMENDED]', 'green', 'bold')}`,
+        'Print manual JSON snippets for hosted and local setup',
+        'Automatically inject local active-profile config into detected client files',
+        'Skip MCP client configuration',
+    ], 0, [
+        'Hosted agents should use https://mcp.sap.oobeprotocol.ai/mcp, but signing still requires the wizard-created user SAP profile.',
+        'Manual snippets are useful when configuring an unknown client or comparing hosted and local setup.',
+        'Automatic injection updates known local config files after preview and confirmation.',
+    ]);
+    const canonical = createCanonicalServerConfig(process.cwd());
+    if (setupMode === 0) {
+        printHostedMcpJsonSnippet(canonical);
+        return;
+    }
+    if (setupMode === 1) {
+        printManualMcpJsonSnippets(canonical);
+        return;
+    }
+    if (setupMode === 3) {
+        printInfo('Skipped MCP client injection.');
+        return;
+    }
+    const targets = discoverMcpClientTargets();
+    if (targets.length === 0) {
+        printWarning('No known MCP client config paths were found.');
+        return;
+    }
+    const selectedIndexes = await askMultiChoice('Select client configs to update:', targets.map(formatMcpClientTarget), [], [
+        'Use "all" to select every discovered config.',
+        'The wizard previews every change and asks again before writing.',
+        'Existing SAP MCP entries trigger merge/override/skip choices.',
+    ]);
+    if (selectedIndexes.length === 0) {
+        printInfo('No MCP client configs selected.');
+        return;
+    }
+    const applied = [];
+    for (const index of selectedIndexes) {
+        const target = targets[index];
+        const previewPlan = planMcpClientInjection(target, canonical, 'merge');
+        console.log('');
+        printSection(target.label);
+        printField('Path', target.path);
+        printField('Current', previewPlan.beforeSummary);
+        printField('Result', previewPlan.afterSummary);
+        if (previewPlan.legacyFindings.length > 0) {
+            printWarning('Existing config contains SAP MCP related entries:');
+            for (const finding of previewPlan.legacyFindings) {
+                printBullet(finding);
+            }
+        }
+        let mode = 'merge';
+        if (previewPlan.hadSapConfig || previewPlan.legacyFindings.length > 0) {
+            const choice = await askChoice('How should this SAP MCP config be updated?', [
+                'Merge and clean stale SAP env overrides',
+                'Override the SAP MCP block completely',
+                'Skip this client config',
+            ], 0, [
+                'Merge preserves unrelated environment values and removes wallet/RPC/profile overrides.',
+                'Override replaces only the SAP MCP server entry/block.',
+                'Skip leaves this file unchanged.',
+            ]);
+            if (choice === 2) {
+                printInfo(`Skipped ${target.label}.`);
+                continue;
+            }
+            mode = choice === 1 ? 'override' : 'merge';
+        }
+        const plan = planMcpClientInjection(target, canonical, mode);
+        const shouldApply = await askConfirm(`Apply ${mode} to ${target.label}?`, true, [
+            `Backup will be created when the file already exists: ${plan.backupPath ?? 'not needed for new file'}`,
+            'The injected SAP MCP entry follows the active profile manager and does not include wallet paths or keypair bytes.',
+        ]);
+        if (!shouldApply) {
+            printInfo(`Skipped ${target.label}.`);
+            continue;
+        }
+        const writeResult = applyMcpClientInjection(plan);
+        applied.push(`${writeResult.message}${writeResult.backupPath ? ` (backup: ${writeResult.backupPath})` : ''}`);
+        printSuccess(writeResult.message);
+    }
+    console.log('');
+    if (applied.length === 0) {
+        printInfo('No MCP client config files were changed.');
+        return;
+    }
+    printSuccess('MCP client injection complete.');
+    for (const item of applied) {
+        console.log(`  - ${item}`);
+    }
+}
+/**
+ * Internal helper for the wizard summary operation.
+ */
+async function wizardSummary(config) {
+    clearConsole();
+    printSapLogo();
+    printHeader('Configuration Summary', 'Review before saving');
+    printLead('Review the profile before it becomes active for MCP clients. Values marked redacted are intentionally not displayed.');
+    console.log('');
+    // Pretty print with colors
+    const summary = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (key.includes('Key') || key.includes('Secret')) {
+            summary[key] = '[REDACTED]';
+        }
+        else {
+            summary[key] = value;
+        }
+    }
+    console.log(JSON.stringify(summary, null, 2));
+    console.log('');
+    printLabel('Operational impact');
+    printBullet(`Active profile will be set to: ${config.profileName}`);
+    printBullet('MCP clients should omit SAP_MCP_PROFILE to follow the active profile manager.');
+    printBullet('Wallet secret bytes are never printed in this wizard output.');
+    if (config.mode === 'local-dev-keypair') {
+        printBullet('This profile can sign transactions; preview and policy checks still apply.');
+    }
+    if (config.mode === 'hosted-api') {
+        printBullet('Remote deployments require TLS termination, rate limits, and deliberate auth/payment settings.');
+    }
+    console.log('');
+    const confirmed = await askConfirm('Save this configuration?', true, [
+        'Choose yes to write the profile config and update .active-profile.',
+        'Choose no or type /exit to leave without saving.',
+    ]);
+    if (!confirmed) {
+        console.log('');
+        printError('Configuration cancelled. Run wizard again to retry.');
+        return false;
+    }
+    return true;
+}
+// ============================================================================
+// Main Wizard Function
+// ============================================================================
+/**
+ * Executes the run wizard operation.
+ */
+export async function runWizard() {
+    try {
+        // Welcome
+        await wizardWelcome();
+        // Step 1: Profile
+        const profileName = await wizardProfile();
+        // Step 2: Mode
+        const mode = await wizardMode();
+        // Step 3: RPC
+        const rpcUrl = await wizardRpcUrl(mode);
+        // Step 4: Signer (pass profileName for wallet path)
+        const signerConfig = await wizardSignerConfig(mode, profileName);
+        // Step 5: Security
+        const securityLimits = await wizardSecurityLimits(mode);
+        // Step 6: Bento Integration (optional)
+        const bentoConfig = await wizardBentoIntegration();
+        // Step 7: HTTP (if hosted-api)
+        const httpConfig = await wizardHttpTransport(mode);
+        // Step 8: Logging
+        const loggingConfig = await wizardLogging();
+        // Build final config
+        const config = {
+            mode,
+            rpcUrl,
+            profileName, // Include profile name for wallet path generation
+            ...signerConfig,
+            ...securityLimits,
+            ...httpConfig,
+            ...loggingConfig,
+            enableBento: bentoConfig.enableBento,
+            bentoApiKey: bentoConfig.bentoApiKey,
+            bentoAgentId: bentoConfig.bentoAgentId,
+        };
+        // Summary and confirmation
+        const confirmed = await wizardSummary(config);
+        if (!confirmed) {
+            rl.close();
+            return;
+        }
+        // Save configuration
+        clearConsole();
+        printSapLogo();
+        printHeader('Saving Configuration', 'Please wait...');
+        const result = await saveWizardSetup(config);
+        printSuccess(`Configuration saved to ${result.configPath}`);
+        if (result.walletPath) {
+            printSuccess(`${result.walletCreated ? 'Wallet created' : 'Wallet configured'} at ${result.walletPath}`);
+            if (result.config.agentPubkey) {
+                console.log('');
+                printField('Agent public key', result.config.agentPubkey);
+                printInfo('Use this public key for SAP agent registration, SNS linking, and operator identity.');
+            }
+        }
+        await wizardMcpClientInjection(result);
+        console.log('\n');
+        printSuccess('Configuration complete!');
+        console.log('');
+        printLabel('Start local stdio MCP');
+        printBullet(paint('npx sap-mcp-server', 'aqua'));
+        console.log('');
+        printLabel('Recommended MCP client environment');
+        printBullet(`${paint('SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE=false', 'aqua')} keeps clients pointed at the active profile manager.`);
+        printBullet(`${paint('SAP_LOG_LEVEL=info', 'aqua')} keeps logs useful without debug noise.`);
+        console.log('');
+        printLabel('Manage this setup later');
+        printBullet(paint('npx sap-mcp-config show', 'aqua'));
+        printBullet(paint('npx sap-mcp-config profiles', 'aqua'));
+        printBullet(paint('npx sap-mcp-config profile <name>', 'aqua'));
+        printBullet(paint('npx sap-mcp-config set <field> <value>', 'aqua'));
+        console.log('');
+        rl.close();
+    }
+    catch (error) {
+        if (error instanceof WizardCancelled) {
+            console.log('');
+            printWarning('Wizard cancelled. No configuration was saved.');
+            rl.close();
+            return;
+        }
+        console.error('');
+        printError(`Error during wizard: ${error instanceof Error ? error.message : String(error)}`);
+        rl.close();
+        process.exit(1);
+    }
+}
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+if (process.argv[1]?.endsWith('wizard.ts') || process.argv[1]?.endsWith('wizard.js')) {
+    runWizard();
+}
+//# sourceMappingURL=wizard.js.map