@lehaotech/walmart-mcp 0.5.4

package/build/scripts/diagnose.js

@@ -0,0 +1,320 @@
+/**
+ * walmart-mcp diagnose
+ * ------------------------------------------------------------
+ * Self-check script. Run via `npm run diagnose`.
+ *
+ * Reports environment readiness, credential validity, and MCP-client config
+ * presence without revealing credential values. Use `--export` to dump a
+ * JSON report suitable for attaching to bug reports.
+ *
+ * Exit codes:
+ *   0  all checks passed (or only warnings)
+ *   1  one or more errors — configuration must be fixed before the MCP works
+ *   2  fatal (script itself crashed)
+ */
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import * as dotenv from 'dotenv';
+import { getBaseUrl } from '../config/environment.js';
+// ---------- Tiny tty helpers — no chalk dep on purpose ----------
+const isTty = process.stdout.isTTY === true;
+const c = {
+    red: (s) => (isTty ? `\x1b[31m${s}\x1b[0m` : s),
+    green: (s) => (isTty ? `\x1b[32m${s}\x1b[0m` : s),
+    yellow: (s) => (isTty ? `\x1b[33m${s}\x1b[0m` : s),
+    dim: (s) => (isTty ? `\x1b[2m${s}\x1b[0m` : s),
+    bold: (s) => (isTty ? `\x1b[1m${s}\x1b[0m` : s),
+};
+const results = [];
+function record(section, severity, message) {
+    results.push({ section, severity, message });
+    const icon = severity === 'ok' ? c.green('OK  ') :
+        severity === 'warn' ? c.yellow('WARN') :
+            severity === 'error' ? c.red('ERR ') :
+                c.dim('..  ');
+    console.log(`   ${icon} ${message}`);
+}
+function section(num, total, title) {
+    console.log('');
+    console.log(c.bold(`[${num}/${total}] ${title}`));
+}
+// ---------- Placeholder & secret-safe rendering ----------
+const PLACEHOLDER_PATTERNS = [
+    /^REPLACE_WITH_/i,
+    /^YOUR_/i,
+    /^xxx+$/i,
+    /^<.*>$/,
+    /^\$\{.*\}$/,
+];
+function isPlaceholder(value) {
+    if (!value)
+        return false;
+    return PLACEHOLDER_PATTERNS.some((re) => re.test(value));
+}
+function safeRender(value, label) {
+    if (!value)
+        return `${label} not set`;
+    if (isPlaceholder(value))
+        return `${label} is a placeholder ("${value}")`;
+    const masked = value.length > 12
+        ? `${value.slice(0, 4)}...${value.slice(-4)}`
+        : '***';
+    return `${label} = ${masked} (${value.length} chars)`;
+}
+// ===================================================================
+// Step 1: Node runtime
+// ===================================================================
+function checkNode() {
+    section('1', '7', 'Node runtime');
+    const v = process.versions.node;
+    const major = parseInt(v.split('.')[0] ?? '0', 10);
+    if (major >= 22) {
+        record('node', 'ok', `Node v${v} (>= 22 required)`);
+    }
+    else if (major >= 20) {
+        record('node', 'warn', `Node v${v} works but >= 22 recommended`);
+    }
+    else {
+        record('node', 'error', `Node v${v} too old — install Node 22+ from https://nodejs.org/`);
+    }
+}
+// ===================================================================
+// Step 2: env file presence
+// ===================================================================
+function checkEnvFile() {
+    section('2', '7', 'Environment file');
+    const cwd = process.cwd();
+    const envPath = join(cwd, '.env');
+    if (!existsSync(envPath)) {
+        record('env-file', 'warn', `No .env at ${envPath} — relying on env vars from MCP client config`);
+        return;
+    }
+    dotenv.config({ path: envPath });
+    record('env-file', 'ok', `Found .env at ${envPath}`);
+}
+// ===================================================================
+// Step 3: Required env vars
+// ===================================================================
+function checkRequiredEnv() {
+    section('3', '7', 'Required env vars');
+    const clientId = process.env.WALMART_CLIENT_ID;
+    if (!clientId) {
+        record('env', 'error', 'WALMART_CLIENT_ID not set');
+    }
+    else if (isPlaceholder(clientId)) {
+        record('env', 'error', `WALMART_CLIENT_ID is a placeholder ("${clientId}")`);
+    }
+    else {
+        record('env', 'ok', safeRender(clientId, 'WALMART_CLIENT_ID'));
+    }
+    const secret = process.env.WALMART_CLIENT_SECRET;
+    if (!secret) {
+        record('env', 'error', 'WALMART_CLIENT_SECRET not set');
+    }
+    else if (isPlaceholder(secret)) {
+        record('env', 'error', 'WALMART_CLIENT_SECRET is a placeholder');
+    }
+    else {
+        record('env', 'ok', safeRender(secret, 'WALMART_CLIENT_SECRET'));
+    }
+    const env = process.env.WALMART_ENVIRONMENT || 'sandbox';
+    if (env !== 'sandbox' && env !== 'production') {
+        record('env', 'error', `WALMART_ENVIRONMENT="${env}" — must be "sandbox" or "production"`);
+    }
+    else {
+        record('env', 'ok', `WALMART_ENVIRONMENT = "${env}"`);
+    }
+    const market = (process.env.WALMART_MARKET || 'us').toLowerCase();
+    if (!['us', 'mx', 'ca', 'cl'].includes(market)) {
+        record('env', 'error', `WALMART_MARKET="${market}" — must be us|mx|ca|cl`);
+    }
+    else {
+        record('env', 'ok', `WALMART_MARKET = "${market}"`);
+    }
+}
+// ===================================================================
+// Step 4: Optional env vars (advertising)
+// ===================================================================
+function checkOptionalEnv() {
+    section('4', '7', 'Optional env vars (Walmart Connect advertising)');
+    const adId = process.env.WALMART_AD_CONSUMER_ID;
+    const adKey = process.env.WALMART_AD_PRIVATE_KEY;
+    if (!adId && !adKey) {
+        record('ads', 'info', 'WALMART_AD_CONSUMER_ID + WALMART_AD_PRIVATE_KEY not set');
+        record('ads', 'info', '25 walmart_ad_* tools will return a friendly "credentials not configured" error');
+    }
+    else if (adId && adKey) {
+        record('ads', 'ok', safeRender(adId, 'WALMART_AD_CONSUMER_ID'));
+        record('ads', 'ok', safeRender(adKey, 'WALMART_AD_PRIVATE_KEY'));
+    }
+    else {
+        record('ads', 'warn', 'Only one of AD_CONSUMER_ID / AD_PRIVATE_KEY is set — both required');
+    }
+}
+// ===================================================================
+// Step 5: Walmart token exchange
+// ===================================================================
+async function checkTokenExchange() {
+    section('5', '7', 'Walmart token exchange');
+    const id = process.env.WALMART_CLIENT_ID;
+    const secret = process.env.WALMART_CLIENT_SECRET;
+    if (!id || !secret || isPlaceholder(id) || isPlaceholder(secret)) {
+        record('token', 'info', 'Skipped (credentials missing or placeholder — fix step [3] first)');
+        return false;
+    }
+    const env = (process.env.WALMART_ENVIRONMENT === 'production' ? 'production' : 'sandbox');
+    const tokenUrl = `${getBaseUrl(env)}/v3/token`;
+    try {
+        const basicAuth = Buffer.from(`${id}:${secret}`).toString('base64');
+        const resp = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Basic ${basicAuth}`,
+                'WM_QOS.CORRELATION_ID': 'diagnose-' + Date.now(),
+                'WM_SVC.NAME': process.env.WALMART_SVC_NAME || 'Walmart Marketplace',
+                Accept: 'application/json',
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: 'grant_type=client_credentials',
+        });
+        if (resp.ok) {
+            const body = (await resp.json());
+            record('token', 'ok', `Token exchange OK (type=${body.token_type}, expires_in=${body.expires_in}s)`);
+            return true;
+        }
+        const bodyText = await resp.text();
+        record('token', 'error', `Token exchange failed: ${resp.status} ${resp.statusText}`);
+        if (bodyText) {
+            record('token', 'error', `  Body: ${bodyText.slice(0, 300)}`);
+        }
+        if (resp.status === 400) {
+            record('token', 'info', '  Hint: 400 usually means wrong Client ID/Secret, or sandbox creds against production endpoint (or vice versa)');
+        }
+        return false;
+    }
+    catch (err) {
+        record('token', 'error', `Network error: ${err instanceof Error ? err.message : String(err)}`);
+        record('token', 'info', '  Hint: check HTTPS_PROXY / firewall / DNS to marketplace.walmartapis.com');
+        return false;
+    }
+}
+// ===================================================================
+// Step 6: Walmart API connectivity sanity
+// ===================================================================
+function checkApiCall(hadToken) {
+    section('6', '7', 'Walmart API connectivity');
+    if (!hadToken) {
+        record('api', 'info', 'Skipped (no token from step [5])');
+        return;
+    }
+    record('api', 'ok', 'Token endpoint reachable — same host as all other APIs');
+}
+// ===================================================================
+// Step 7: MCP client config (best effort, read-only)
+// ===================================================================
+function checkMcpClientConfig() {
+    section('7', '7', 'MCP client config (best effort)');
+    const home = homedir();
+    const plat = platform();
+    const candidates = [];
+    if (plat === 'darwin') {
+        candidates.push({
+            name: 'Claude Desktop',
+            path: join(home, 'Library/Application Support/Claude/claude_desktop_config.json'),
+        });
+    }
+    else if (plat === 'win32') {
+        const appdata = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+        candidates.push({
+            name: 'Claude Desktop',
+            path: join(appdata, 'Claude', 'claude_desktop_config.json'),
+        });
+    }
+    else {
+        candidates.push({
+            name: 'Claude Desktop',
+            path: join(home, '.config/Claude/claude_desktop_config.json'),
+        });
+    }
+    candidates.push({ name: 'Claude Code CLI', path: join(home, '.claude.json') });
+    candidates.push({ name: 'Cursor', path: join(home, '.cursor', 'mcp.json') });
+    let foundAny = false;
+    for (const cand of candidates) {
+        if (!existsSync(cand.path))
+            continue;
+        foundAny = true;
+        record('mcp-config', 'ok', `${cand.name} config found at ${cand.path}`);
+        try {
+            const raw = readFileSync(cand.path, 'utf8');
+            const json = JSON.parse(raw);
+            const servers = json.mcpServers ?? json.servers;
+            if (!servers) {
+                record('mcp-config', 'warn', `  No mcpServers section in ${cand.name}`);
+                continue;
+            }
+            const walmartKey = Object.keys(servers).find((k) => k.toLowerCase().startsWith('walmart'));
+            if (!walmartKey) {
+                record('mcp-config', 'warn', '  No "walmart*" entry in mcpServers — server not registered');
+                continue;
+            }
+            record('mcp-config', 'ok', `  "${walmartKey}" entry present in mcpServers`);
+            const entry = servers[walmartKey];
+            const envBlock = entry?.env ?? {};
+            const idInBlock = envBlock.WALMART_CLIENT_ID;
+            const secretInBlock = envBlock.WALMART_CLIENT_SECRET;
+            if (isPlaceholder(idInBlock) || isPlaceholder(secretInBlock)) {
+                record('mcp-config', 'warn', `  env block in ${cand.name} still has placeholder credentials`);
+            }
+        }
+        catch (err) {
+            record('mcp-config', 'error', `  Failed to parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!foundAny) {
+        record('mcp-config', 'warn', 'No supported MCP client config found in expected paths');
+        record('mcp-config', 'info', '  walmart-mcp will still work via direct stdio, but no client knows about it yet');
+    }
+}
+// ===================================================================
+// Overall + export
+// ===================================================================
+async function main() {
+    console.log(c.bold('=== walmart-mcp diagnose ==='));
+    checkNode();
+    checkEnvFile();
+    checkRequiredEnv();
+    checkOptionalEnv();
+    const hadToken = await checkTokenExchange();
+    checkApiCall(hadToken);
+    checkMcpClientConfig();
+    console.log('');
+    const errors = results.filter((r) => r.severity === 'error').length;
+    const warnings = results.filter((r) => r.severity === 'warn').length;
+    const summary = errors > 0
+        ? c.red(`Overall: ${errors} errors, ${warnings} warnings`)
+        : warnings > 0
+            ? c.yellow(`Overall: ${warnings} warnings`)
+            : c.green('Overall: all checks passed');
+    console.log(summary);
+    if (process.argv.includes('--export')) {
+        const reportPath = join(process.cwd(), 'walmart-mcp-diagnose.json');
+        writeFileSync(reportPath, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            node: process.versions.node,
+            platform: process.platform,
+            cwd: process.cwd(),
+            environment: process.env.WALMART_ENVIRONMENT || 'sandbox',
+            market: process.env.WALMART_MARKET || 'us',
+            results,
+            summary: { errors, warnings },
+        }, null, 2));
+        console.log(c.dim(`Report exported to ${reportPath}`));
+    }
+    if (errors > 0)
+        process.exit(1);
+}
+main().catch((err) => {
+    console.error(c.red('Fatal:'), err);
+    process.exit(2);
+});

package/build/scripts/setup.d.ts

@@ -0,0 +1,17 @@
+/**
+ * walmart-mcp setup
+ * ------------------------------------------------------------
+ * Interactive wizard. Run via `npm run setup` (or `npx walmart-mcp setup`).
+ *
+ * What it does:
+ *   1. Ask for environment + market (sandbox/production, us/mx/ca/cl)
+ *   2. Ask for WALMART_CLIENT_ID and WALMART_CLIENT_SECRET (masked input)
+ *   3. Live-validate credentials via OAuth token exchange
+ *   4. Optionally ask for Walmart Connect advertising credentials
+ *   5. Detect installed MCP clients (Claude Desktop, Claude Code CLI,
+ *      Cursor, Cline, Continue, Windsurf, Zed) and offer multi-select
+ *      write — backs up each client's config before modifying it.
+ *
+ * Zero new runtime deps. Uses node:readline/promises.
+ */
+export {};

package/build/scripts/setup.js

@@ -0,0 +1,276 @@
+/**
+ * walmart-mcp setup
+ * ------------------------------------------------------------
+ * Interactive wizard. Run via `npm run setup` (or `npx walmart-mcp setup`).
+ *
+ * What it does:
+ *   1. Ask for environment + market (sandbox/production, us/mx/ca/cl)
+ *   2. Ask for WALMART_CLIENT_ID and WALMART_CLIENT_SECRET (masked input)
+ *   3. Live-validate credentials via OAuth token exchange
+ *   4. Optionally ask for Walmart Connect advertising credentials
+ *   5. Detect installed MCP clients (Claude Desktop, Claude Code CLI,
+ *      Cursor, Cline, Continue, Windsurf, Zed) and offer multi-select
+ *      write — backs up each client's config before modifying it.
+ *
+ * Zero new runtime deps. Uses node:readline/promises.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import * as readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { getBaseUrl } from '../config/environment.js';
+import { CLIENT_SPECS, writeWalmartEntry, } from './client-configs.js';
+// ---------- Tty helpers — no chalk dep ----------
+const isTty = stdout.isTTY === true;
+const c = {
+    red: (s) => (isTty ? `\x1b[31m${s}\x1b[0m` : s),
+    green: (s) => (isTty ? `\x1b[32m${s}\x1b[0m` : s),
+    yellow: (s) => (isTty ? `\x1b[33m${s}\x1b[0m` : s),
+    cyan: (s) => (isTty ? `\x1b[36m${s}\x1b[0m` : s),
+    dim: (s) => (isTty ? `\x1b[2m${s}\x1b[0m` : s),
+    bold: (s) => (isTty ? `\x1b[1m${s}\x1b[0m` : s),
+};
+const rl = readline.createInterface({ input: stdin, output: stdout });
+function logBanner() {
+    console.log('');
+    console.log(c.bold('======================================'));
+    console.log(c.bold('   walmart-mcp setup wizard'));
+    console.log(c.bold('======================================'));
+    console.log(c.dim('   Press Ctrl+C to abort at any time'));
+    console.log('');
+}
+function logStep(label) {
+    console.log('');
+    console.log(c.cyan(`>> ${label}`));
+}
+// ---------- Masked input ----------
+async function askMasked(prompt) {
+    process.stdout.write(prompt);
+    let value = '';
+    await new Promise((resolve) => {
+        const onData = (chunk) => {
+            const s = chunk.toString('utf8');
+            for (const ch of s) {
+                if (ch === '\n' || ch === '\r') {
+                    stdin.removeListener('data', onData);
+                    stdin.setRawMode(false);
+                    process.stdout.write('\n');
+                    resolve();
+                    return;
+                }
+                if (ch === '') {
+                    process.stdout.write('\n');
+                    process.exit(130);
+                }
+                if (ch === '' || ch === '\b') {
+                    if (value.length > 0) {
+                        value = value.slice(0, -1);
+                        process.stdout.write('\b \b');
+                    }
+                    continue;
+                }
+                value += ch;
+                process.stdout.write('*');
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+    });
+    return value.trim();
+}
+async function chooseFromList(label, options, defaultIdx = 0) {
+    console.log(label);
+    options.forEach((opt, i) => {
+        const marker = i === defaultIdx ? c.green(' (default)') : '';
+        console.log(`  ${i + 1}) ${opt.value}${opt.description ? c.dim(' - ' + opt.description) : ''}${marker}`);
+    });
+    const answer = (await rl.question(`Pick [1-${options.length}] (default ${defaultIdx + 1}): `)).trim();
+    if (!answer)
+        return options[defaultIdx].value;
+    const idx = parseInt(answer, 10) - 1;
+    if (Number.isNaN(idx) || idx < 0 || idx >= options.length) {
+        console.log(c.yellow(`  Not a valid choice, using default ${options[defaultIdx].value}`));
+        return options[defaultIdx].value;
+    }
+    return options[idx].value;
+}
+/**
+ * Parse a comma-separated list of 1-based indices into a deduped set.
+ * "1,3,4" -> Set{0,2,3}. Out-of-range entries are dropped silently.
+ */
+function parseMultiSelect(answer, maxIdx) {
+    const out = new Set();
+    for (const part of answer.split(/[,\s]+/)) {
+        if (!part)
+            continue;
+        const n = parseInt(part, 10);
+        if (!Number.isNaN(n) && n >= 1 && n <= maxIdx)
+            out.add(n - 1);
+    }
+    return out;
+}
+async function validateCredentials(clientId, clientSecret, env) {
+    const url = `${getBaseUrl(env)}/v3/token`;
+    try {
+        const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+        const resp = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Basic ${auth}`,
+                'WM_QOS.CORRELATION_ID': 'setup-' + Date.now(),
+                'WM_SVC.NAME': 'Walmart Marketplace',
+                Accept: 'application/json',
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: 'grant_type=client_credentials',
+        });
+        if (resp.ok) {
+            const body = (await resp.json());
+            return { ok: true, expiresIn: body.expires_in ?? 0 };
+        }
+        const bodyText = await resp.text();
+        return {
+            ok: false,
+            reason: `HTTP ${resp.status} ${resp.statusText}${bodyText ? ': ' + bodyText.slice(0, 200) : ''}`,
+        };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function main() {
+    logBanner();
+    logStep('1/5 Choose Walmart environment');
+    const environment = await chooseFromList('   Which environment will you use?', [
+        { value: 'sandbox', description: 'testing, mock data, no real listings' },
+        { value: 'production', description: 'real store, real money' },
+    ], 0);
+    logStep('2/5 Choose marketplace');
+    const market = await chooseFromList('   Walmart marketplace:', [
+        { value: 'us', description: 'United States' },
+        { value: 'mx', description: 'Mexico' },
+        { value: 'ca', description: 'Canada' },
+        { value: 'cl', description: 'Chile' },
+    ], 0);
+    logStep('3/5 Walmart credentials');
+    let clientId = '';
+    let clientSecret = '';
+    while (true) {
+        clientId = (await rl.question('   WALMART_CLIENT_ID: ')).trim();
+        clientSecret = await askMasked('   WALMART_CLIENT_SECRET (hidden): ');
+        if (!clientId || !clientSecret) {
+            console.log(c.red('   Both fields required.'));
+            continue;
+        }
+        process.stdout.write(c.dim('   Validating against Walmart... '));
+        const result = await validateCredentials(clientId, clientSecret, environment);
+        if (result.ok) {
+            console.log(c.green(`OK (token expires in ${result.expiresIn}s)`));
+            break;
+        }
+        console.log(c.red('FAIL'));
+        console.log(c.red('   ' + result.reason));
+        const retry = (await rl.question('   Try again? [Y/n]: ')).trim().toLowerCase();
+        if (retry === 'n') {
+            console.log(c.yellow('   Aborting. Fix credentials at https://developer.walmart.com/ and re-run.'));
+            process.exit(1);
+        }
+    }
+    logStep('4/5 Walmart Connect advertising (optional)');
+    const wantsAds = (await rl.question('   Configure now? [y/N]: ')).trim().toLowerCase() === 'y';
+    let adConsumerId;
+    let adPrivateKey;
+    if (wantsAds) {
+        adConsumerId = (await rl.question('   WALMART_AD_CONSUMER_ID: ')).trim() || undefined;
+        if (adConsumerId)
+            adPrivateKey = (await askMasked('   WALMART_AD_PRIVATE_KEY (hidden): ')) || undefined;
+    }
+    else {
+        console.log(c.dim('   Skipped. 25 walmart_ad_* tools will return a friendly error until configured.'));
+    }
+    logStep('5/5 Register MCP server in your AI clients');
+    const buildPath = join(process.cwd(), 'build', 'index.js');
+    if (!existsSync(buildPath)) {
+        console.log(c.yellow(`   WARN: ${buildPath} does not exist yet. Run 'npm run build' first.`));
+        console.log(c.yellow('         Continuing anyway — config will point to that path once you build.'));
+    }
+    // Detect installed clients.
+    const installed = [];
+    const notInstalled = [];
+    for (const spec of CLIENT_SPECS) {
+        const p = spec.resolvePath();
+        if (p && existsSync(p))
+            installed.push({ ...spec, path: p });
+        else
+            notInstalled.push(spec);
+    }
+    if (installed.length === 0) {
+        console.log(c.yellow('   No supported MCP client config files found in expected paths.'));
+        console.log(c.dim('   Looked for:'));
+        for (const spec of CLIENT_SPECS)
+            console.log(c.dim(`     - ${spec.name}: ${spec.resolvePath()}`));
+        console.log(c.yellow('   Skipping write — install at least one MCP client and re-run.'));
+        process.exit(0);
+    }
+    console.log('   Detected MCP clients:');
+    installed.forEach((spec, i) => console.log(`     ${i + 1}) ${spec.name}  ${c.dim('(' + spec.path + ')')}`));
+    console.log('');
+    const answer = (await rl.question('   Select which to configure (comma-separated, e.g. "1,3"; empty = all): ')).trim();
+    const picked = answer === ''
+        ? new Set(installed.map((_, i) => i))
+        : parseMultiSelect(answer, installed.length);
+    if (picked.size === 0) {
+        console.log(c.yellow('   Nothing selected, aborting.'));
+        process.exit(0);
+    }
+    const walmartEntry = {
+        type: 'stdio',
+        command: 'node',
+        args: [buildPath],
+        env: {
+            WALMART_CLIENT_ID: clientId,
+            WALMART_CLIENT_SECRET: clientSecret,
+            WALMART_ENVIRONMENT: environment,
+            WALMART_MARKET: market,
+            ...(adConsumerId ? { WALMART_AD_CONSUMER_ID: adConsumerId } : {}),
+            ...(adPrivateKey ? { WALMART_AD_PRIVATE_KEY: adPrivateKey } : {}),
+        },
+    };
+    let okCount = 0;
+    let failCount = 0;
+    for (const idx of picked) {
+        const target = installed[idx];
+        process.stdout.write(c.dim(`   Writing ${target.name}... `));
+        try {
+            const r = writeWalmartEntry(target, target.path, walmartEntry);
+            const tag = r.overwrote ? c.yellow('updated') : c.green('added');
+            const backupTag = r.backedUp ? c.dim(' (backup at .before-walmart-setup.bak)') : '';
+            console.log(`${tag}${backupTag}`);
+            okCount += 1;
+        }
+        catch (err) {
+            console.log(c.red(`FAIL: ${err instanceof Error ? err.message : String(err)}`));
+            failCount += 1;
+        }
+    }
+    console.log('');
+    console.log(c.bold('================= Done ================='));
+    if (failCount === 0)
+        console.log(c.green(`Configured ${okCount} client(s).`));
+    else
+        console.log(c.yellow(`Configured ${okCount} client(s), ${failCount} failed.`));
+    console.log('');
+    console.log('Next:');
+    console.log('  1. If you have not built yet:   ' + c.cyan('npm run build'));
+    console.log('  2. Restart each configured AI client');
+    console.log('  3. Try in chat: ' + c.cyan('"Show me my recent Walmart orders"'));
+    console.log('');
+    console.log(c.dim('If anything fails, run ' + c.cyan('npm run diagnose') + c.dim(' for a self-check.')));
+    rl.close();
+}
+main().catch((err) => {
+    console.error(c.red('Setup failed:'), err);
+    rl.close();
+    process.exit(2);
+});