@darksol/terminal 0.2.2 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
   "scripts": {
     "start": "node bin/darksol.js",
     "dev": "node bin/darksol.js dashboard",
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "postinstall": "echo \"\n🌑 DARKSOL Terminal installed. Run 'darksol setup' to configure your AI provider.\n\""
   },
   "keywords": [
     "darksol",
@@ -25,20 +26,21 @@
   "author": "DARKSOL <chris00claw@gmail.com>",
   "license": "MIT",
   "dependencies": {
+    "blessed": "^0.1.81",
+    "blessed-contrib": "^4.11.0",
+    "boxen": "^8.0.1",
     "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
+    "conf": "^13.0.1",
     "ethers": "^6.13.0",
-    "boxen": "^8.0.1",
-    "ora": "^8.1.0",
-    "cli-table3": "^0.6.5",
-    "inquirer": "^12.0.0",
     "figlet": "^1.8.0",
     "gradient-string": "^3.0.0",
-    "conf": "^13.0.1",
+    "inquirer": "^12.0.0",
     "nanospinner": "^1.1.0",
     "node-fetch": "^3.3.2",
-    "blessed": "^0.1.81",
-    "blessed-contrib": "^4.11.0",
+    "open": "^11.0.0",
+    "ora": "^8.1.0",
     "terminal-link": "^3.0.0",
     "update-notifier": "^7.3.1"
   },

package/src/cli.js

@@ -19,6 +19,7 @@ import { addKey, removeKey, listKeys } from './config/keys.js';
 import { parseIntent, startChat, adviseStrategy, analyzeToken, executeIntent } from './llm/intent.js';
 import { startAgentSigner, showAgentDocs } from './wallet/agent-signer.js';
 import { listSkills, installSkill, skillInfo, uninstallSkill } from './services/skills.js';
+import { runSetupWizard, checkFirstRun } from './setup/wizard.js';
 
 export function cli(argv) {
   const program = new Command();
@@ -293,6 +294,15 @@ export function cli(argv) {
     .description('Settle payment on-chain')
     .action((payment) => facilitatorSettle(payment));
 
+  // ═══════════════════════════════════════
+  // SETUP COMMAND
+  // ═══════════════════════════════════════
+  program
+    .command('setup')
+    .description('First-run setup wizard — configure AI provider, chain, wallet')
+    .option('-f, --force', 'Re-run even if already configured')
+    .action((opts) => runSetupWizard({ force: opts.force }));
+
   // ═══════════════════════════════════════
   // AI / LLM COMMANDS
   // ═══════════════════════════════════════
@@ -581,57 +591,221 @@ export function cli(argv) {
     });
 
   // ═══════════════════════════════════════
-  // DASHBOARD (default)
+  // DASHBOARD (default) — CHAT-FIRST
   // ═══════════════════════════════════════
   program
     .command('dashboard', { isDefault: true })
-    .description('Show DARKSOL Terminal dashboard')
+    .description('Show DARKSOL Terminal — chat-first interface')
     .action(async () => {
       showBanner();
 
+      // First-run detection — force setup
+      const ranSetup = await checkFirstRun();
+      if (ranSetup) return;
+
       const cfg = getAllConfig();
       const wallet = cfg.activeWallet;
+      const { hasKey } = await import('./config/keys.js');
+      const hasLLM = ['openai', 'anthropic', 'openrouter', 'ollama'].some(s => hasKey(s));
+
+      // ── Status bar (compact) ──
+      const statusParts = [
+        wallet ? theme.success(`● ${wallet}`) : theme.dim('○ no wallet'),
+        theme.dim(`${cfg.chain}`),
+        theme.dim(`${cfg.slippage}% slip`),
+        hasLLM ? theme.success('● AI ready') : theme.accent('○ no AI'),
+      ];
+      console.log(`  ${statusParts.join(theme.dim('  │  '))}`);
+      console.log('');
 
-      showSection('STATUS');
+      // ── CHAT INTERFACE (primary) ──
+      if (hasLLM) {
+        // AI is connected — drop straight into chat
+        console.log(theme.gold('  ╔══════════════════════════════════════════════════════════╗'));
+        console.log(theme.gold('  ║') + theme.label('  DARKSOL AI — ready. Ask anything.                      ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('  "swap 0.1 ETH for USDC" • "what\'s AERO at?" • "help"   ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('  Type "commands" to see all tools. Type "exit" to quit.   ') + theme.gold('║'));
+        console.log(theme.gold('  ╚══════════════════════════════════════════════════════════╝'));
+        console.log('');
+
+        // Start interactive chat loop
+        await startChatLoop(cfg);
+      } else {
+        // No AI — show connect prompt
+        console.log(theme.gold('  ╔══════════════════════════════════════════════════════════╗'));
+        console.log(theme.gold('  ║') + theme.accent('  ⚠  No AI provider connected                            ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('  The DARKSOL AI needs an LLM to work.                    ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('                                                          ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('  Run: ') + theme.label('darksol setup') + theme.dim('          to connect OpenAI/Anthropic  ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('  Run: ') + theme.label('darksol keys add openai') + theme.dim(' to add an API key       ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('                                                          ') + theme.gold('║'));
+        console.log(theme.gold('  ║') + theme.dim('  Or use Ollama for free local AI — no key needed.        ') + theme.gold('║'));
+        console.log(theme.gold('  ╚══════════════════════════════════════════════════════════╝'));
+        console.log('');
+        showCommandList();
+      }
+    });
+
+  program.parse(argv);
+}
+
+// ═══════════════════════════════════════
+// CHAT-FIRST LOOP (default experience)
+// ═══════════════════════════════════════
+
+async function startChatLoop(cfg) {
+  const { createLLM } = await import('./llm/engine.js');
+  const { quickPrice } = await import('./utils/helpers.js');
+  const { executeIntent, parseIntent, INTENT_SYSTEM_PROMPT } = await import('./llm/intent.js');
+
+  let llm;
+  try {
+    llm = await createLLM({});
+    const chain = cfg.chain || 'base';
+    const wallet = cfg.activeWallet || '(not set)';
+    const slippage = cfg.slippage || 0.5;
+
+    const systemPrompt = INTENT_SYSTEM_PROMPT
+      .replace('{{chain}}', chain)
+      .replace('{{wallet}}', wallet)
+      .replace('{{slippage}}', slippage);
+
+    llm.setSystemPrompt(systemPrompt);
+  } catch (err) {
+    error(`AI init failed: ${err.message}`);
+    info('Run: darksol setup');
+    return;
+  }
+
+  const inquirerMod = await import('inquirer');
+  const inquirerDefault = inquirerMod.default;
+
+  while (true) {
+    const { input } = await inquirerDefault.prompt([{
+      type: 'input',
+      name: 'input',
+      message: theme.gold('🌑'),
+      validate: (v) => v.length > 0 || ' ',
+    }]);
+
+    const trimmed = input.trim().toLowerCase();
+
+    // Meta-commands within chat
+    if (['exit', 'quit', 'q'].includes(trimmed)) {
+      const usage = llm.getUsage();
+      info(`Session: ${usage.calls} calls, ${usage.totalTokens} tokens`);
+      break;
+    }
+
+    if (['commands', 'help', 'cmds', '?'].includes(trimmed)) {
+      showCommandList();
+      continue;
+    }
+
+    if (trimmed === 'status') {
       kvDisplay([
-        ['Wallet', wallet || theme.dim('Not set — run: darksol wallet create')],
+        ['Wallet', cfg.activeWallet || theme.dim('(none)')],
         ['Chain', cfg.chain],
+        ['Provider', `${llm.provider}/${llm.model}`],
         ['Slippage', `${cfg.slippage}%`],
       ]);
+      continue;
+    }
 
-      console.log('');
-      showSection('COMMANDS');
-      const commands = [
-        ['wallet', 'Create, import, manage wallets'],
-        ['trade', 'Swap tokens, snipe, trading'],
-        ['dca', 'Dollar-cost averaging orders'],
-        ['ai', 'AI trading assistant & analysis'],
-        ['agent', 'Secure agent signer (PK-isolated)'],
-        ['keys', 'API key vault (LLMs, data, RPCs)'],
-        ['script', 'Execution scripts & strategies'],
-        ['market', 'Market intel & token data'],
-        ['oracle', 'On-chain random oracle'],
-        ['casino', 'The Clawsino — betting'],
-        ['cards', 'Prepaid Visa/MC cards'],
-        ['builders', 'ERC-8021 builder index'],
-        ['facilitator', 'x402 payment facilitator'],
-        ['skills', 'Agent skill directory & install'],
-        ['config', 'Terminal configuration'],
-        ['tips', 'Trading & scripting tips'],
-        ['networks', 'Chain reference & explorers'],
-        ['quickstart', 'Getting started guide'],
-        ['lookup', 'Look up any address on-chain'],
-      ];
+    // Check if it looks like a trade intent
+    const tradeWords = ['buy', 'sell', 'swap', 'snipe', 'transfer', 'send', 'trade'];
+    const isTradeIntent = tradeWords.some(w => trimmed.startsWith(w));
+
+    if (isTradeIntent) {
+      // Parse as trade intent with confirmation
+      const intent = await parseIntent(input, {});
+      if (intent.action !== 'error' && intent.action !== 'unknown') {
+        showSection('PARSED INTENT');
+        kvDisplay(Object.entries(intent)
+          .filter(([k]) => !['raw', 'model', 'reasoning'].includes(k))
+          .map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : String(v)])
+        );
+        if (intent.warnings?.length) intent.warnings.forEach(w => warn(w));
+        if (intent.command) info(`Command: ${theme.gold(intent.command)}`);
+        console.log('');
+      } else {
+        // Fall through to regular chat
+        await chatResponse(llm, input);
+      }
+      continue;
+    }
 
-      commands.forEach(([cmd, desc]) => {
-        console.log(`  ${theme.gold(cmd.padEnd(16))} ${theme.dim(desc)}`);
-      });
+    // Regular chat
+    await chatResponse(llm, input);
+  }
+}
 
-      console.log('');
-      console.log(theme.dim('  Run any command with --help for details'));
-      console.log(theme.dim('  Example: darksol trade swap --help'));
-      console.log('');
-    });
+async function chatResponse(llm, input) {
+  const { quickPrice } = await import('./utils/helpers.js');
+  const { spinner: spin } = await import('./ui/components.js');
+  const s = spin('Thinking...').start();
+
+  try {
+    // Enrich with live price data
+    let enriched = input;
+    const tokenPattern = /\b([A-Z]{2,10})\b/g;
+    const tokens = [...new Set(input.toUpperCase().match(tokenPattern) || [])];
+    const skipTokens = ['ETH', 'THE', 'FOR', 'AND', 'BUY', 'SELL', 'DCA', 'SWAP', 'WHAT', 'PRICE', 'HOW', 'MUCH', 'NOT', 'CAN', 'YOU', 'HELP'];
+
+    const priceData = [];
+    for (const t of tokens.filter(t => !skipTokens.includes(t)).slice(0, 3)) {
+      const p = await quickPrice(t);
+      if (p) priceData.push(`${p.symbol}: $${p.price} (liq: $${p.liquidity})`);
+    }
+
+    if (priceData.length > 0) {
+      enriched += `\n\n[Live data: ${priceData.join(', ')}]`;
+    }
+
+    const result = await llm.chat(enriched);
+    s.succeed('');
+
+    // Display response
+    console.log('');
+    const lines = result.content.split('\n');
+    for (const line of lines) {
+      console.log(theme.dim('  ') + line);
+    }
+    console.log('');
+  } catch (err) {
+    s.fail('Error');
+    error(err.message);
+  }
+}
 
-  program.parse(argv);
+function showCommandList() {
+  console.log('');
+  showSection('COMMANDS');
+  const commands = [
+    ['wallet', 'Create, import, manage wallets'],
+    ['trade', 'Swap tokens, snipe, trading'],
+    ['dca', 'Dollar-cost averaging orders'],
+    ['ai chat', 'Standalone AI chat session'],
+    ['ai execute', 'Parse + execute a trade via AI'],
+    ['agent start', 'Start secure agent signer'],
+    ['keys', 'API key vault'],
+    ['script', 'Execution scripts & strategies'],
+    ['market', 'Market intel & token data'],
+    ['oracle', 'On-chain random oracle'],
+    ['casino', 'The Clawsino — betting'],
+    ['cards', 'Prepaid Visa/MC cards'],
+    ['builders', 'ERC-8021 builder index'],
+    ['facilitator', 'x402 payment facilitator'],
+    ['skills', 'Agent skill directory'],
+    ['setup', 'Re-run setup wizard'],
+    ['config', 'Terminal configuration'],
+  ];
+
+  commands.forEach(([cmd, desc]) => {
+    console.log(`  ${theme.gold(cmd.padEnd(16))} ${theme.dim(desc)}`);
+  });
+
+  console.log('');
+  console.log(theme.dim('  Run any command: darksol <command> --help'));
+  console.log('');
 }

package/src/config/keys.js

@@ -1,7 +1,7 @@
 import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'crypto';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
+import { homedir, hostname, userInfo } from 'os';
 import { theme } from '../ui/theme.js';
 import { kvDisplay, success, error, warn, info } from '../ui/components.js';
 import { showSection } from '../ui/banner.js';
@@ -317,4 +317,56 @@ export function listKeys() {
   info('Services: ' + Object.keys(SERVICES).join(', '));
 }
 
+/**
+ * Add a key directly (non-interactive, for setup wizard / OAuth)
+ * Uses a machine-derived vault password for seamless storage
+ */
+export function addKeyDirect(service, apiKey) {
+  const vaultPass = getMachineVaultPass();
+  const vault = loadVault();
+  const svc = SERVICES[service];
+  vault.keys[service] = {
+    encrypted: encrypt(apiKey, vaultPass),
+    service: svc?.name || service,
+    category: svc?.category || 'custom',
+    addedAt: new Date().toISOString(),
+    autoStored: true,  // flag: stored via wizard, not manual password
+  };
+  saveVault(vault);
+}
+
+/**
+ * Get a key stored via addKeyDirect (auto-stored, machine password)
+ */
+export function getKeyAuto(service) {
+  const vault = loadVault();
+  const entry = vault.keys[service];
+  if (!entry) return getKeyFromEnv(service);
+  if (!entry.autoStored) return getKeyFromEnv(service);  // manual entries need password
+  try {
+    return decrypt(entry.encrypted, getMachineVaultPass());
+  } catch {
+    return getKeyFromEnv(service);
+  }
+}
+
+/**
+ * Check if any key exists for a service (stored or env)
+ */
+export function hasKey(service) {
+  const vault = loadVault();
+  if (vault.keys[service]) return true;
+  const svc = SERVICES[service];
+  if (svc?.envVar && process.env[svc.envVar]) return true;
+  return false;
+}
+
+/**
+ * Machine-derived vault password for auto-stored keys
+ * (derived from hostname + username — not high security, but protects at rest)
+ */
+function getMachineVaultPass() {
+  return `darksol-vault-${hostname()}-${userInfo().username}`;
+}
+
 export { KEYS_DIR, KEYS_FILE };

package/src/setup/wizard.js

@@ -0,0 +1,505 @@
+import inquirer from 'inquirer';
+import { theme } from '../ui/theme.js';
+import { showSection, showDivider } from '../ui/banner.js';
+import { success, error, warn, info, kvDisplay } from '../ui/components.js';
+import { getConfig, setConfig } from '../config/store.js';
+import { addKeyDirect, hasKey, SERVICES } from '../config/keys.js';
+import { createServer } from 'http';
+import open from 'open';
+import crypto from 'crypto';
+
+// ══════════════════════════════════════════════════
+// FIRST-RUN SETUP WIZARD
+// ══════════════════════════════════════════════════
+
+/**
+ * Check if this is a first run (no LLM keys configured)
+ */
+export function isFirstRun() {
+  const hasAnyLLM = ['openai', 'anthropic', 'openrouter', 'ollama'].some(s => hasKey(s));
+  const setupDone = getConfig('setupComplete');
+  return !hasAnyLLM && !setupDone;
+}
+
+/**
+ * Run the setup wizard
+ */
+export async function runSetupWizard(opts = {}) {
+  const force = opts.force || false;
+
+  if (!force && !isFirstRun()) {
+    info('Setup already complete. Use --force to re-run.');
+    return;
+  }
+
+  console.log('');
+  showSection('🌑 DARKSOL TERMINAL — FIRST RUN SETUP');
+  console.log('');
+  console.log(theme.dim('  Welcome to DARKSOL Terminal. Let\'s get you set up.'));
+  console.log(theme.dim('  You need an LLM provider to use the AI trading assistant.'));
+  console.log(theme.dim('  Everything else works without one.'));
+  console.log('');
+
+  showDivider();
+
+  // Step 1: Choose LLM provider
+  const { provider } = await inquirer.prompt([{
+    type: 'list',
+    name: 'provider',
+    message: theme.gold('Choose your AI provider:'),
+    choices: [
+      { name: '🤖 OpenAI (GPT-4o, GPT-5) — API key or OAuth', value: 'openai' },
+      { name: '🧠 Anthropic (Claude Opus, Sonnet) — API key or OAuth', value: 'anthropic' },
+      { name: '🔀 OpenRouter (any model, one key) — API key', value: 'openrouter' },
+      { name: '🏠 Ollama (local models, free, private) — no key needed', value: 'ollama' },
+      { name: '⏭️  Skip for now', value: 'skip' },
+    ],
+  }]);
+
+  if (provider === 'skip') {
+    warn('Skipped LLM setup. You can set up later with: darksol setup');
+    setConfig('setupComplete', true);
+    showPostSetup();
+    return;
+  }
+
+  if (provider === 'ollama') {
+    await setupOllama();
+  } else {
+    await setupCloudProvider(provider);
+  }
+
+  // Step 2: Chain selection
+  console.log('');
+  const { chain } = await inquirer.prompt([{
+    type: 'list',
+    name: 'chain',
+    message: theme.gold('Default chain:'),
+    choices: [
+      { name: 'Base (recommended — low fees, fast)', value: 'base' },
+      { name: 'Ethereum (mainnet)', value: 'ethereum' },
+      { name: 'Arbitrum', value: 'arbitrum' },
+      { name: 'Optimism', value: 'optimism' },
+      { name: 'Polygon', value: 'polygon' },
+    ],
+    default: 'base',
+  }]);
+  setConfig('chain', chain);
+  success(`Chain set to ${chain}`);
+
+  // Step 3: Wallet
+  console.log('');
+  const { createWallet } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'createWallet',
+    message: theme.gold('Create a wallet now?'),
+    default: true,
+  }]);
+
+  if (createWallet) {
+    const { createNewWallet } = await import('../wallet/manager.js');
+    await createNewWallet();
+  } else {
+    info('Create one later: darksol wallet create <name>');
+  }
+
+  setConfig('setupComplete', true);
+  showPostSetup();
+}
+
+/**
+ * Setup a cloud provider (OpenAI, Anthropic, OpenRouter)
+ */
+async function setupCloudProvider(provider) {
+  const supportsOAuth = ['openai', 'anthropic'].includes(provider);
+  const providerName = {
+    openai: 'OpenAI',
+    anthropic: 'Anthropic',
+    openrouter: 'OpenRouter',
+  }[provider];
+
+  if (supportsOAuth) {
+    const { method } = await inquirer.prompt([{
+      type: 'list',
+      name: 'method',
+      message: theme.gold(`How do you want to connect ${providerName}?`),
+      choices: [
+        { name: `🔑 API Key — paste your ${providerName} API key`, value: 'apikey' },
+        { name: `🌐 OAuth — sign in with your ${providerName} account`, value: 'oauth' },
+        { name: `📋 Instructions — show me how to get a key`, value: 'help' },
+      ],
+    }]);
+
+    if (method === 'apikey') {
+      await setupAPIKey(provider);
+    } else if (method === 'oauth') {
+      await startOAuth(provider);
+    } else {
+      showKeyInstructions(provider);
+      // After showing instructions, ask for key
+      await setupAPIKey(provider);
+    }
+  } else {
+    await setupAPIKey(provider);
+  }
+}
+
+/**
+ * Setup via API key entry
+ */
+async function setupAPIKey(provider) {
+  const providerName = {
+    openai: 'OpenAI',
+    anthropic: 'Anthropic',
+    openrouter: 'OpenRouter',
+  }[provider];
+
+  const { key } = await inquirer.prompt([{
+    type: 'password',
+    name: 'key',
+    message: theme.gold(`${providerName} API key:`),
+    mask: '●',
+    validate: (v) => {
+      if (!v || v.length < 10) return 'Key seems too short';
+      return true;
+    },
+  }]);
+
+  addKeyDirect(provider, key);
+  success(`${providerName} key saved (encrypted)`);
+
+  // Set as default provider
+  setConfig('llmProvider', provider);
+  info(`Default AI provider set to ${provider}`);
+}
+
+/**
+ * Setup Ollama (local)
+ */
+async function setupOllama() {
+  console.log('');
+  console.log(theme.gold('  OLLAMA SETUP'));
+  console.log(theme.dim('  Ollama runs models locally — free, private, no API key needed.'));
+  console.log('');
+
+  const { host } = await inquirer.prompt([{
+    type: 'input',
+    name: 'host',
+    message: theme.gold('Ollama host:'),
+    default: 'http://localhost:11434',
+  }]);
+
+  setConfig('ollamaHost', host);
+
+  const { model } = await inquirer.prompt([{
+    type: 'input',
+    name: 'model',
+    message: theme.gold('Default model:'),
+    default: 'llama3',
+  }]);
+
+  setConfig('ollamaModel', model);
+  setConfig('llmProvider', 'ollama');
+
+  success(`Ollama configured: ${host} / ${model}`);
+  info('Make sure Ollama is running: ollama serve');
+}
+
+/**
+ * Show instructions for getting API keys
+ */
+function showKeyInstructions(provider) {
+  console.log('');
+
+  if (provider === 'openai') {
+    showSection('GET AN OPENAI API KEY');
+    console.log(theme.dim('  1. Go to https://platform.openai.com/api-keys'));
+    console.log(theme.dim('  2. Click "Create new secret key"'));
+    console.log(theme.dim('  3. Copy the key (starts with sk-)'));
+    console.log(theme.dim('  4. Paste it below'));
+    console.log('');
+    console.log(theme.dim('  💡 If you have a ChatGPT Plus/Pro subscription,'));
+    console.log(theme.dim('     you can use OAuth instead (sign in with your account).'));
+  } else if (provider === 'anthropic') {
+    showSection('GET AN ANTHROPIC API KEY');
+    console.log(theme.dim('  1. Go to https://console.anthropic.com/settings/keys'));
+    console.log(theme.dim('  2. Click "Create Key"'));
+    console.log(theme.dim('  3. Copy the key (starts with sk-ant-)'));
+    console.log(theme.dim('  4. Paste it below'));
+    console.log('');
+    console.log(theme.dim('  💡 If you have a Claude Pro/Team subscription,'));
+    console.log(theme.dim('     you can use OAuth instead.'));
+  }
+
+  console.log('');
+}
+
+// ══════════════════════════════════════════════════
+// OAuth FLOWS
+// ══════════════════════════════════════════════════
+
+// OAuth configurations
+const OAUTH_CONFIGS = {
+  openai: {
+    name: 'OpenAI',
+    authUrl: 'https://auth.openai.com/authorize',
+    tokenUrl: 'https://auth.openai.com/oauth/token',
+    // These are placeholder client IDs — users need to register their own app
+    // or use the direct API key flow
+    clientId: null,
+    scopes: ['openid', 'profile'],
+    helpUrl: 'https://platform.openai.com/docs/guides/authentication',
+  },
+  anthropic: {
+    name: 'Anthropic',
+    authUrl: 'https://console.anthropic.com/oauth/authorize',
+    tokenUrl: 'https://console.anthropic.com/oauth/token',
+    clientId: null,
+    scopes: ['api'],
+    helpUrl: 'https://docs.anthropic.com/en/docs/authentication',
+  },
+};
+
+/**
+ * Start OAuth flow for a provider
+ */
+async function startOAuth(provider) {
+  const config = OAUTH_CONFIGS[provider];
+
+  // Check if provider has public OAuth available
+  // As of 2026, OpenAI and Anthropic have limited OAuth — API keys are more common
+  console.log('');
+  showSection(`${config.name} OAuth`);
+  console.log('');
+  console.log(theme.dim('  OAuth lets you sign in with your existing subscription'));
+  console.log(theme.dim('  without creating a separate API key.'));
+  console.log('');
+
+  // Check for custom client ID (user may have registered an OAuth app)
+  const storedClientId = getConfig(`oauth_${provider}_clientId`);
+
+  if (!storedClientId && !config.clientId) {
+    // No OAuth app registered — offer alternatives
+    console.log(theme.accent('  ⚠️  OAuth requires a registered application.'));
+    console.log('');
+    console.log(theme.dim('  Options:'));
+    console.log(theme.dim(`  1. Register an OAuth app at ${config.helpUrl}`));
+    console.log(theme.dim('  2. Use an API key instead (faster, simpler)'));
+    console.log('');
+
+    const { oauthChoice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'oauthChoice',
+      message: theme.gold('How to proceed?'),
+      choices: [
+        { name: '🔑 Use API key instead (recommended)', value: 'apikey' },
+        { name: '📝 Enter my OAuth client ID', value: 'clientid' },
+        { name: '🌐 Open registration page in browser', value: 'register' },
+      ],
+    }]);
+
+    if (oauthChoice === 'apikey') {
+      await setupAPIKey(provider);
+      return;
+    }
+
+    if (oauthChoice === 'register') {
+      try {
+        await open(config.helpUrl);
+        info(`Opened ${config.helpUrl} in your browser`);
+      } catch {
+        info(`Go to: ${config.helpUrl}`);
+      }
+      console.log('');
+      const { hasClientId } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'hasClientId',
+        message: theme.gold('Do you have a client ID now?'),
+        default: false,
+      }]);
+      if (!hasClientId) {
+        info('No problem — use an API key for now.');
+        await setupAPIKey(provider);
+        return;
+      }
+    }
+
+    // Get client ID from user
+    const { clientId } = await inquirer.prompt([{
+      type: 'input',
+      name: 'clientId',
+      message: theme.gold('OAuth Client ID:'),
+      validate: (v) => v.length > 5 || 'Client ID seems too short',
+    }]);
+
+    const { clientSecret } = await inquirer.prompt([{
+      type: 'password',
+      name: 'clientSecret',
+      message: theme.gold('OAuth Client Secret:'),
+      mask: '●',
+    }]);
+
+    setConfig(`oauth_${provider}_clientId`, clientId);
+    if (clientSecret) {
+      addKeyDirect(`${provider}_oauth_secret`, clientSecret);
+    }
+
+    await executeOAuthFlow(provider, clientId, clientSecret);
+  } else {
+    const clientId = storedClientId || config.clientId;
+    const clientSecret = getKey(`${provider}_oauth_secret`);
+    await executeOAuthFlow(provider, clientId, clientSecret);
+  }
+}
+
+/**
+ * Execute the OAuth authorization code flow
+ */
+async function executeOAuthFlow(provider, clientId, clientSecret) {
+  const config = OAUTH_CONFIGS[provider];
+  const port = 19876; // Local callback port
+  const redirectUri = `http://localhost:${port}/callback`;
+  const state = crypto.randomBytes(16).toString('hex');
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+
+  // Build auth URL
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    scope: config.scopes.join(' '),
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+  });
+
+  const authUrl = `${config.authUrl}?${params}`;
+
+  // Start local server to receive callback
+  return new Promise(async (resolve) => {
+    const server = createServer(async (req, res) => {
+      const url = new URL(req.url, `http://localhost:${port}`);
+
+      if (url.pathname === '/callback') {
+        const code = url.searchParams.get('code');
+        const returnedState = url.searchParams.get('state');
+        const err = url.searchParams.get('error');
+
+        if (err) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>❌ Authorization failed</h2><p>You can close this window.</p></body></html>');
+          error(`OAuth error: ${err}`);
+          server.close();
+          resolve(false);
+          return;
+        }
+
+        if (returnedState !== state) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>❌ State mismatch</h2><p>Possible CSRF. You can close this window.</p></body></html>');
+          error('OAuth state mismatch — possible security issue');
+          server.close();
+          resolve(false);
+          return;
+        }
+
+        // Exchange code for token
+        try {
+          const fetch = (await import('node-fetch')).default;
+          const tokenResp = await fetch(config.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+              grant_type: 'authorization_code',
+              code,
+              redirect_uri: redirectUri,
+              client_id: clientId,
+              ...(clientSecret ? { client_secret: clientSecret } : {}),
+              code_verifier: codeVerifier,
+            }),
+          });
+
+          const tokenData = await tokenResp.json();
+
+          if (tokenData.access_token) {
+            // Store the token as the API key
+            addKeyDirect(provider, tokenData.access_token);
+            if (tokenData.refresh_token) {
+              addKeyDirect(`${provider}_refresh`, tokenData.refresh_token);
+            }
+            setConfig('llmProvider', provider);
+
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(`<html><body style="background:#1a1a2e;color:#d4a574;font-family:monospace;text-align:center;padding:60px"><h2>✅ DARKSOL Terminal — Connected to ${config.name}</h2><p>You can close this window.</p></body></html>`);
+
+            success(`${config.name} connected via OAuth`);
+            info(`Token stored (encrypted). Provider set to ${provider}.`);
+          } else {
+            throw new Error(tokenData.error || 'No access token in response');
+          }
+        } catch (tokenErr) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>❌ Token exchange failed</h2><p>You can close this window.</p></body></html>');
+          error(`Token exchange failed: ${tokenErr.message}`);
+          info('Try using an API key instead: darksol keys add ' + provider);
+        }
+
+        server.close();
+        resolve(true);
+      }
+    });
+
+    server.listen(port, '127.0.0.1', async () => {
+      console.log('');
+      info(`Opening ${config.name} authorization page...`);
+      console.log(theme.dim(`  If browser doesn't open, go to:`));
+      console.log(theme.accent(`  ${authUrl}`));
+      console.log('');
+      info('Waiting for authorization...');
+
+      try {
+        await open(authUrl);
+      } catch {
+        warn('Could not open browser automatically');
+      }
+    });
+
+    // Timeout after 5 minutes
+    setTimeout(() => {
+      warn('OAuth timed out (5 minutes)');
+      server.close();
+      resolve(false);
+    }, 300000);
+  });
+}
+
+// ══════════════════════════════════════════════════
+// POST-SETUP & HELPERS
+// ══════════════════════════════════════════════════
+
+function showPostSetup() {
+  console.log('');
+  showSection('🌑 YOU\'RE READY');
+  console.log('');
+  console.log(theme.gold('  Next steps:'));
+  console.log(theme.dim('  • darksol ai chat          Start the AI trading assistant'));
+  console.log(theme.dim('  • darksol market top        See what\'s moving'));
+  console.log(theme.dim('  • darksol wallet create     Create an encrypted wallet'));
+  console.log(theme.dim('  • darksol tips              Trading tips & tricks'));
+  console.log(theme.dim('  • darksol quickstart        Full getting started guide'));
+  console.log('');
+  console.log(theme.dim('  Re-run setup anytime: darksol setup --force'));
+  console.log('');
+}
+
+/**
+ * Quick check on startup — if first run, FORCE setup (no prompt)
+ */
+export async function checkFirstRun() {
+  if (isFirstRun()) {
+    await runSetupWizard();
+    return true;
+  }
+  return false;
+}

package/src/ui/banner.js

@@ -26,7 +26,7 @@ export function showBanner(opts = {}) {
   );
   console.log(
     theme.dim('  ║ ') +
-    theme.subtle(' v0.2.2') +
+    theme.subtle(' v0.3.1') +
     theme.dim('                                                ') +
     theme.gold('🌑') +
     theme.dim(' ║')
@@ -44,7 +44,7 @@ export function showBanner(opts = {}) {
 
 export function showMiniBanner() {
   console.log('');
-  console.log(theme.gold.bold('  🌑 DARKSOL TERMINAL') + theme.dim(' v0.2.2'));
+  console.log(theme.gold.bold('  🌑 DARKSOL TERMINAL') + theme.dim(' v0.3.1'));
   console.log(theme.dim('  ─────────────────────────────'));
   console.log('');
 }
@@ -62,3 +62,5 @@ export function showDivider() {
 
 
 
+
+