wispy-cli 1.2.2 → 1.3.0

package/core/onboarding.mjs

@@ -0,0 +1,751 @@
+/**
+ * core/onboarding.mjs — Unified first-run wizard for Wispy
+ *
+ * Handles interactive setup from scratch:
+ *   - AI provider + API key
+ *   - Messaging channels (Telegram, Discord, Slack)
+ *   - Workstream
+ *   - Memory / personalization
+ *   - Security level
+ *   - Server / cloud mode
+ *
+ * Usage:
+ *   import { OnboardingWizard } from './onboarding.mjs';
+ *   const wizard = new OnboardingWizard();
+ *   const config = await wizard.run();            // full wizard
+ *   const partial = await wizard.runStep('provider'); // single step
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+
+import {
+  WISPY_DIR,
+  CONFIG_PATH,
+  MEMORY_DIR,
+  PROVIDERS,
+  loadConfig,
+  saveConfig,
+} from "./config.mjs";
+
+// ──────────────────────────────────────────────────────────────────────────────
+// ANSI helpers (no deps)
+// ──────────────────────────────────────────────────────────────────────────────
+
+const bold  = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim   = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const cyan  = (s) => `\x1b[36m${s}\x1b[0m`;
+const yellow= (s) => `\x1b[33m${s}\x1b[0m`;
+const red   = (s) => `\x1b[31m${s}\x1b[0m`;
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Provider registry (display order for wizard)
+// ──────────────────────────────────────────────────────────────────────────────
+
+const PROVIDER_LIST = [
+  { key: "google",     label: "Google AI (Gemini)",        tag: "free tier available ⭐ recommended", signupUrl: "https://aistudio.google.com/apikey",         defaultModel: "gemini-2.5-flash" },
+  { key: "anthropic",  label: "Anthropic (Claude)",         tag: "best quality",                       signupUrl: "https://console.anthropic.com/settings/keys", defaultModel: "claude-sonnet-4-20250514" },
+  { key: "openai",     label: "OpenAI (GPT-4o)",            tag: "",                                   signupUrl: "https://platform.openai.com/api-keys",        defaultModel: "gpt-4o" },
+  { key: "groq",       label: "Groq",                       tag: "fastest inference, free",             signupUrl: "https://console.groq.com/keys",               defaultModel: "llama-3.3-70b-versatile" },
+  { key: "deepseek",   label: "DeepSeek",                   tag: "cheap and good",                     signupUrl: "https://platform.deepseek.com/api_keys",      defaultModel: "deepseek-chat" },
+  { key: "ollama",     label: "Ollama",                     tag: "local, no API key needed",            signupUrl: null,                                          defaultModel: "llama3.2" },
+  { key: "openrouter", label: "OpenRouter",                 tag: "access any model",                   signupUrl: "https://openrouter.ai/keys",                  defaultModel: "anthropic/claude-sonnet-4-20250514" },
+  { key: null,         label: "I'll set this up later",     tag: "",                                   signupUrl: null,                                          defaultModel: null },
+];
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Security level definitions
+// ──────────────────────────────────────────────────────────────────────────────
+
+const SECURITY_LEVELS = {
+  careful: {
+    label: "Careful",
+    desc: "ask before running commands or modifying files (recommended)",
+    permissions: { run_command: "approve", write_file: "approve", git: "approve" },
+  },
+  balanced: {
+    label: "Balanced",
+    desc: "ask for dangerous commands only",
+    permissions: { run_command: "approve", write_file: "notify", git: "approve" },
+  },
+  trust: {
+    label: "Trust me",
+    desc: "auto-approve everything (power users)",
+    permissions: { run_command: "auto", write_file: "auto", git: "auto" },
+  },
+};
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Readline helpers
+// ──────────────────────────────────────────────────────────────────────────────
+
+function makeRl() {
+  return createInterface({ input: process.stdin, output: process.stdout });
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim())));
+}
+
+async function askWithDefault(rl, question, defaultVal) {
+  const answer = await ask(rl, question);
+  return answer === "" ? defaultVal : answer;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// API key validation (basic connectivity check)
+// ──────────────────────────────────────────────────────────────────────────────
+
+async function validateApiKey(provider, key) {
+  if (provider === "ollama") return { ok: true, model: "llama3.2" };
+  try {
+    const info = PROVIDERS[provider];
+    if (!info) return { ok: false, error: "Unknown provider" };
+
+    if (provider === "google") {
+      const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash?key=${key}`;
+      const r = await fetch(url, { signal: AbortSignal.timeout(6000) });
+      if (r.ok) return { ok: true, model: "gemini-2.5-flash" };
+      return { ok: false, error: `HTTP ${r.status}` };
+    }
+
+    if (provider === "anthropic") {
+      const r = await fetch("https://api.anthropic.com/v1/models", {
+        headers: { "x-api-key": key, "anthropic-version": "2023-06-01" },
+        signal: AbortSignal.timeout(6000),
+      });
+      if (r.ok) return { ok: true, model: "claude-sonnet-4-20250514" };
+      return { ok: false, error: `HTTP ${r.status}` };
+    }
+
+    if (provider === "openai") {
+      const r = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${key}` },
+        signal: AbortSignal.timeout(6000),
+      });
+      if (r.ok) return { ok: true, model: "gpt-4o" };
+      return { ok: false, error: `HTTP ${r.status}` };
+    }
+
+    // For other providers just trust the key format
+    return { ok: true, model: info.defaultModel };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Save API key to shell env file
+// ──────────────────────────────────────────────────────────────────────────────
+
+async function saveKeyToEnvFile(provider, key, filePath) {
+  const info = PROVIDERS[provider];
+  if (!info || !info.envKeys?.[0]) return;
+  const envVar = info.envKeys[0];
+  const line = `\nexport ${envVar}="${key}" # wispy-cli\n`;
+  try {
+    const existing = await readFile(filePath, "utf8").catch(() => "");
+    // Remove old entry if present
+    const filtered = existing
+      .split("\n")
+      .filter((l) => !l.includes(`${envVar}=`) || !l.includes("wispy-cli"))
+      .join("\n");
+    await writeFile(filePath, filtered + line, "utf8");
+  } catch (err) {
+    console.error(red(`  Failed to write to ${filePath}: ${err.message}`));
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Channel validation (just ping the token)
+// ──────────────────────────────────────────────────────────────────────────────
+
+async function validateTelegramToken(token) {
+  try {
+    const r = await fetch(`https://api.telegram.org/bot${token}/getMe`, { signal: AbortSignal.timeout(6000) });
+    if (r.ok) {
+      const data = await r.json();
+      return { ok: true, username: data.result?.username };
+    }
+    return { ok: false };
+  } catch { return { ok: false }; }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// OnboardingWizard class
+// ──────────────────────────────────────────────────────────────────────────────
+
+export class OnboardingWizard {
+  constructor() {
+    this._config = {};
+  }
+
+  // ── Step 1: Welcome ────────────────────────────────────────────────────────
+
+  async stepWelcome(rl) {
+    console.log("");
+    console.log(`🌿 ${bold("Welcome to Wispy")} — your personal AI assistant`);
+    console.log("");
+    console.log("Let's get you set up. This takes about 2 minutes.");
+    console.log(dim("Press Enter to start, or Ctrl+C to skip (you can run 'wispy setup' later)."));
+    console.log("");
+    await ask(rl, "");
+  }
+
+  // ── Step 2: AI Provider ────────────────────────────────────────────────────
+
+  async stepProvider(rl) {
+    console.log(`🤖 ${bold("Which AI provider do you want to use?")}\n`);
+    PROVIDER_LIST.forEach((p, i) => {
+      const tag = p.tag ? dim(` — ${p.tag}`) : "";
+      console.log(`  ${i + 1}. ${p.label}${tag}`);
+    });
+    console.log("");
+
+    const choiceStr = await askWithDefault(rl, "Choice [1]: ", "1");
+    const choice = Math.min(Math.max(parseInt(choiceStr) || 1, 1), PROVIDER_LIST.length);
+    const selected = PROVIDER_LIST[choice - 1];
+
+    if (!selected.key) {
+      console.log(dim("\n  OK — run 'wispy setup provider' later to configure.\n"));
+      return {};
+    }
+
+    let apiKey = null;
+
+    if (selected.key === "ollama") {
+      console.log(`\n  ${dim("Checking Ollama at http://localhost:11434...")}`);
+      try {
+        const r = await fetch("http://localhost:11434/api/tags", { signal: AbortSignal.timeout(3000) });
+        if (r.ok) {
+          console.log(green("\n  ✅ Ollama found! Using llama3.2\n"));
+          return { provider: "ollama", model: "llama3.2" };
+        }
+      } catch {}
+      console.log(yellow("\n  ⚠️  Ollama not running. Start it with: ollama serve\n"));
+      return { provider: "ollama", model: "llama3.2" };
+    }
+
+    // Need API key
+    if (selected.signupUrl) {
+      console.log(`\n  Paste your ${selected.label} API key`);
+      console.log(dim(`  (get one at ${selected.signupUrl})`));
+    }
+    console.log("");
+
+    let validated = false;
+    let attempts = 0;
+    while (!validated && attempts < 3) {
+      apiKey = await ask(rl, "  Key: ");
+      if (!apiKey) {
+        console.log(dim("  Skipped. Run 'wispy setup provider' later.\n"));
+        return {};
+      }
+      attempts++;
+
+      process.stdout.write("  Validating...");
+      const result = await validateApiKey(selected.key, apiKey);
+      if (result.ok) {
+        console.log(green(` ✅ Connected! Using ${result.model || selected.defaultModel}`));
+        validated = true;
+      } else {
+        console.log(red(` ✗ ${result.error || "Invalid key"}`));
+        if (attempts < 3) console.log(dim("  Try again, or press Enter to skip."));
+      }
+    }
+
+    if (!validated) {
+      console.log(dim("\n  Skipping provider setup. Run 'wispy setup provider' later.\n"));
+      return {};
+    }
+
+    // Where to save the key
+    console.log(`\n  Save API key to:`);
+    console.log(`  1. ~/.wispy/config.json ${dim("(recommended)")}`);
+    console.log(`  2. ~/.zshenv ${dim("(system-wide)")}`);
+    console.log(`  3. Both`);
+    console.log("");
+    const saveChoice = await askWithDefault(rl, "  Choice [1]: ", "1");
+
+    if (saveChoice === "2" || saveChoice === "3") {
+      const envFile = path.join(os.homedir(), ".zshenv");
+      await saveKeyToEnvFile(selected.key, apiKey, envFile);
+      console.log(green(`  ✅ Saved to ~/.zshenv`));
+    }
+
+    const storeInConfig = saveChoice !== "2"; // save in config unless env-only
+
+    const model = selected.defaultModel;
+    console.log("");
+
+    return {
+      provider: selected.key,
+      model,
+      ...(storeInConfig ? { apiKey } : {}),
+    };
+  }
+
+  // ── Step 3: Channels ───────────────────────────────────────────────────────
+
+  async stepChannels(rl) {
+    console.log(`📱 ${bold("Want to connect messaging channels?")} ${dim("(you can skip and add later)")}\n`);
+    console.log("  1. Telegram bot — chat with your AI on Telegram");
+    console.log("  2. Discord bot — add AI to your Discord server");
+    console.log("  3. Slack bot — integrate with your workspace");
+    console.log("  4. Skip for now");
+    console.log("");
+
+    const input = await askWithDefault(rl, "Choice (comma-separated, e.g. 1,2) [4]: ", "4");
+    const choices = input.split(",").map((s) => parseInt(s.trim())).filter((n) => !isNaN(n));
+
+    const channels = {
+      telegram: { enabled: false },
+      discord: { enabled: false },
+      slack: { enabled: false },
+    };
+
+    if (choices.includes(4) || choices.length === 0) {
+      console.log(dim("\n  Channels skipped. Run 'wispy setup channels' later.\n"));
+      return { channels };
+    }
+
+    if (choices.includes(1)) {
+      console.log(`\n  🤖 ${bold("Telegram Setup")}`);
+      console.log("    1. Open @BotFather on Telegram");
+      console.log("    2. Send /newbot and follow prompts");
+      console.log("    3. Paste the bot token here:");
+      console.log("");
+
+      const token = await ask(rl, "  Token: ");
+      if (token) {
+        process.stdout.write("  Checking...");
+        const result = await validateTelegramToken(token);
+        if (result.ok) {
+          console.log(green(` ✅ Bot connected! @${result.username}`));
+          channels.telegram = { enabled: true, token };
+        } else {
+          console.log(yellow(" ⚠️  Could not verify token — saved anyway"));
+          channels.telegram = { enabled: true, token };
+        }
+      }
+    }
+
+    if (choices.includes(2)) {
+      console.log(`\n  🤖 ${bold("Discord Setup")}`);
+      console.log("    1. Go to https://discord.com/developers/applications");
+      console.log("    2. Create a new application → Bot → Reset Token");
+      console.log("    3. Paste the bot token here:");
+      console.log("");
+
+      const token = await ask(rl, "  Token: ");
+      if (token) {
+        channels.discord = { enabled: true, token };
+        console.log(green("  ✅ Token saved"));
+      }
+    }
+
+    if (choices.includes(3)) {
+      console.log(`\n  🤖 ${bold("Slack Setup")}`);
+      console.log("    1. Go to https://api.slack.com/apps → Create New App");
+      console.log("    2. Add Bot Token Scopes: chat:write, channels:read");
+      console.log("    3. Install to workspace → copy Bot User OAuth Token");
+      console.log("");
+
+      const token = await ask(rl, "  Bot Token (xoxb-...): ");
+      if (token) {
+        const signingSecret = await ask(rl, "  Signing Secret: ");
+        channels.slack = { enabled: true, token, signingSecret };
+        console.log(green("  ✅ Credentials saved"));
+      }
+    }
+
+    console.log("");
+    return { channels };
+  }
+
+  // ── Step 4: Workstream ─────────────────────────────────────────────────────
+
+  async stepWorkstream(rl) {
+    console.log(`📂 ${bold("Set up your first workstream?")}\n`);
+    console.log("  A workstream keeps conversations and context separate per project.\n");
+    console.log("  1. Yes, create one now");
+    console.log("  2. Skip (use default workstream)");
+    console.log("");
+
+    const choice = await askWithDefault(rl, "Choice [2]: ", "2");
+
+    if (choice !== "1") {
+      console.log(dim("  Using default workstream.\n"));
+      return { workstream: "default" };
+    }
+
+    const name = await ask(rl, "  Workstream name (e.g., my-app, backend, homework): ");
+    const clean = (name || "default").replace(/[^a-z0-9_-]/gi, "-").toLowerCase() || "default";
+
+    console.log(green(`  ✅ Workstream "${clean}" set.\n`));
+    return { workstream: clean };
+  }
+
+  // ── Step 5: Memory ─────────────────────────────────────────────────────────
+
+  async stepMemory(rl) {
+    console.log(`🧠 ${bold("Tell Wispy about yourself")} ${dim("(helps personalize responses)")}\n`);
+
+    const name = await ask(rl, "  Your name (optional): ");
+    const role = await askWithDefault(rl, "  Your role (e.g., developer, student, designer) [skip]: ", "");
+    const lang = await askWithDefault(rl, "  Preferred language (e.g., Korean, English) [auto-detect]: ", "");
+
+    // Build user.md
+    const lines = ["# About Me", ""];
+    if (name) lines.push(`**Name:** ${name}`, "");
+    if (role) lines.push(`**Role:** ${role}`, "");
+    if (lang) lines.push(`**Language:** ${lang}`, "");
+    lines.push(`_Generated by wispy setup on ${new Date().toISOString().slice(0, 10)}_`, "");
+
+    try {
+      await mkdir(path.join(WISPY_DIR, "memory"), { recursive: true });
+      await writeFile(path.join(WISPY_DIR, "memory", "user.md"), lines.join("\n"), "utf8");
+      console.log(green(`\n  Saved to ~/.wispy/memory/user.md ✅\n`));
+    } catch (err) {
+      console.log(yellow(`\n  Could not save memory file: ${err.message}\n`));
+    }
+
+    return { _memoryName: name, _memoryRole: role };
+  }
+
+  // ── Step 6: Security ───────────────────────────────────────────────────────
+
+  async stepSecurity(rl) {
+    console.log(`🔒 ${bold("Security level for tool execution?")}\n`);
+    console.log(`  1. Careful   — ${dim("ask before running commands or modifying files (recommended)")}`);
+    console.log(`  2. Balanced  — ${dim("ask for dangerous commands only")}`);
+    console.log(`  3. Trust me  — ${dim("auto-approve everything (power users)")}`);
+    console.log("");
+
+    const choice = await askWithDefault(rl, "Choice [1]: ", "1");
+    const levelMap = { "1": "careful", "2": "balanced", "3": "trust" };
+    const security = levelMap[choice] || "careful";
+    const levelInfo = SECURITY_LEVELS[security];
+
+    console.log(green(`\n  ✅ Security: ${levelInfo.label}\n`));
+    return { security, permissions: levelInfo.permissions };
+  }
+
+  // ── Step 7: Server / Cloud ─────────────────────────────────────────────────
+
+  async stepServer(rl) {
+    console.log(`☁️  ${bold("Want to run Wispy as a server?")} ${dim("(access from anywhere)")}\n`);
+    console.log("  1. Yes, set up server mode");
+    console.log("  2. Generate deployment files (Docker/Railway/Fly)");
+    console.log("  3. Connect to existing Wispy server");
+    console.log("  4. Skip for now");
+    console.log("");
+
+    const choice = await askWithDefault(rl, "Choice [4]: ", "4");
+
+    if (choice === "4" || choice === "") {
+      console.log(dim("  Skipped. Run 'wispy deploy init' or 'wispy server' later.\n"));
+      return { server: { enabled: false } };
+    }
+
+    if (choice === "1") {
+      const portStr = await askWithDefault(rl, "  Port [18790]: ", "18790");
+      const port = parseInt(portStr) || 18790;
+      const host = await askWithDefault(rl, "  Host [0.0.0.0]: ", "0.0.0.0");
+
+      // Generate token
+      const { randomBytes } = await import("node:crypto");
+      const token = randomBytes(24).toString("hex");
+
+      console.log(green(`\n  ✅ Server mode: ${host}:${port}`));
+      console.log(dim(`  Token: ${token}`));
+      console.log(dim("  Start with: wispy server\n"));
+
+      return { server: { enabled: true, port, host, token } };
+    }
+
+    if (choice === "2") {
+      console.log(dim("\n  Running deploy init...\n"));
+      try {
+        const { DeployManager } = await import("./deploy.mjs");
+        const dm = new DeployManager();
+        const created = await dm.init(process.cwd());
+        for (const f of created) console.log(`  ✅ ${f}`);
+      } catch (err) {
+        console.log(yellow(`  Could not run deploy init: ${err.message}`));
+      }
+      console.log("");
+      return { server: { enabled: false } };
+    }
+
+    if (choice === "3") {
+      const url = await ask(rl, "  Wispy server URL (e.g. https://my.server:18790): ");
+      const token = await ask(rl, "  Token (optional): ");
+      if (url) {
+        try {
+          const { mkdir: mkdirNode, writeFile: wfNode } = await import("node:fs/promises");
+          await mkdirNode(WISPY_DIR, { recursive: true });
+          await wfNode(
+            path.join(WISPY_DIR, "remote.json"),
+            JSON.stringify({ url: url.replace(/\/$/, ""), token, connectedAt: new Date().toISOString() }, null, 2),
+            "utf8"
+          );
+          console.log(green(`\n  ✅ Connected to ${url}\n`));
+        } catch (err) {
+          console.log(yellow(`\n  Warning: ${err.message}\n`));
+        }
+      }
+      return { server: { enabled: false, remote: url } };
+    }
+
+    return { server: { enabled: false } };
+  }
+
+  // ── Step 8: Summary ────────────────────────────────────────────────────────
+
+  printSummary(config) {
+    const providerKey = config.provider;
+    const providerInfo = PROVIDER_LIST.find((p) => p.key === providerKey);
+    const providerLabel = providerInfo ? providerInfo.label : providerKey ?? dim("none");
+
+    const model = config.model ?? dim("not set");
+    const workstream = config.workstream ?? "default";
+    const security = SECURITY_LEVELS[config.security ?? "careful"]?.label ?? "Careful";
+
+    const tg = config.channels?.telegram?.enabled
+      ? green(`Telegram (@${config.channels.telegram.token?.slice(0, 4) ?? "..."}...)`)
+      : null;
+    const dc = config.channels?.discord?.enabled ? green("Discord") : null;
+    const sl = config.channels?.slack?.enabled ? green("Slack") : null;
+    const channelsStr = [tg, dc, sl].filter(Boolean).join(", ") || dim("none");
+
+    console.log(`✅ ${bold("Wispy is ready!")}\n`);
+    console.log(`  Provider:    ${cyan(providerLabel)} ${dim(`(${model})`)}`);
+    console.log(`  Channels:    ${channelsStr}`);
+    console.log(`  Workstream:  ${workstream}`);
+    console.log(`  Security:    ${security}`);
+    console.log(`  Memory:      ${dim("user.md saved")}`);
+    console.log(`  Config:      ${dim("~/.wispy/config.json")}`);
+    console.log("");
+    console.log("Getting started:");
+    console.log(`  ${cyan("wispy")}                    Interactive chat`);
+    console.log(`  ${cyan("wispy --tui")}              Full terminal UI`);
+    console.log(`  ${cyan("wispy --serve")}            Start channels + cron`);
+    console.log(`  ${cyan('wispy "hello"')}            Quick one-shot`);
+    console.log("");
+    console.log("Happy building! 🌿");
+    console.log("");
+  }
+
+  // ── Public: run full wizard ────────────────────────────────────────────────
+
+  async run() {
+    const rl = makeRl();
+
+    // Trap Ctrl+C gracefully
+    rl.on("SIGINT", () => {
+      console.log(dim("\n\n  Setup skipped. Run 'wispy setup' anytime.\n"));
+      process.exit(0);
+    });
+
+    try {
+      await this.stepWelcome(rl);
+
+      const providerResult   = await this.stepProvider(rl);
+      const channelsResult   = await this.stepChannels(rl);
+      const workstreamResult = await this.stepWorkstream(rl);
+      const memoryResult     = await this.stepMemory(rl);
+      const securityResult   = await this.stepSecurity(rl);
+      const serverResult     = await this.stepServer(rl);
+
+      rl.close();
+
+      // Merge everything into config
+      const existingConfig = await loadConfig();
+      const config = {
+        ...existingConfig,
+        ...providerResult,
+        ...channelsResult,
+        ...workstreamResult,
+        ...securityResult,
+        ...serverResult,
+        onboarded: true,
+        onboardedAt: new Date().toISOString(),
+      };
+
+      // Remove internal step fields
+      delete config._memoryName;
+      delete config._memoryRole;
+
+      await saveConfig(config);
+      console.log("");
+      this.printSummary(config);
+
+      return config;
+    } catch (err) {
+      rl.close();
+      throw err;
+    }
+  }
+
+  // ── Public: run individual step ────────────────────────────────────────────
+
+  async runStep(step) {
+    const rl = makeRl();
+    rl.on("SIGINT", () => {
+      console.log(dim("\n  Cancelled.\n"));
+      rl.close();
+      process.exit(0);
+    });
+
+    let partial = {};
+    try {
+      const stepMap = {
+        welcome:    () => this.stepWelcome(rl),
+        provider:   () => this.stepProvider(rl),
+        channels:   () => this.stepChannels(rl),
+        workstream: () => this.stepWorkstream(rl),
+        memory:     () => this.stepMemory(rl),
+        security:   () => this.stepSecurity(rl),
+        server:     () => this.stepServer(rl),
+      };
+
+      if (!stepMap[step]) {
+        console.log(red(`  Unknown step: ${step}`));
+        console.log(dim("  Valid steps: provider, channels, workstream, memory, security, server"));
+        rl.close();
+        return {};
+      }
+
+      partial = await stepMap[step]();
+
+      // Merge with existing config and save
+      if (Object.keys(partial).length > 0) {
+        const existing = await loadConfig();
+        const updated = { ...existing, ...partial };
+        delete updated._memoryName;
+        delete updated._memoryRole;
+        await saveConfig(updated);
+        console.log(green("  ✅ Config saved.\n"));
+      }
+    } finally {
+      rl.close();
+    }
+
+    return partial;
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Convenience helpers
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if this is a first run (config missing or onboarded !== true)
+ */
+export async function isFirstRun() {
+  try {
+    const config = await loadConfig();
+    return !config.onboarded;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Print `wispy status` output — comprehensive current config view
+ */
+export async function printStatus() {
+  const { readdir, stat } = await import("node:fs/promises");
+  const { existsSync } = await import("node:fs");
+  const { SESSIONS_DIR, MEMORY_DIR: MEM_DIR } = await import("./config.mjs");
+
+  const config = await loadConfig();
+
+  // Remote mode?
+  let remote = null;
+  try {
+    const rp = path.join(WISPY_DIR, "remote.json");
+    remote = JSON.parse(await readFile(rp, "utf8"));
+  } catch {}
+
+  // Count memory files
+  let memCount = 0;
+  let memFiles = [];
+  try {
+    const mFiles = await readdir(path.join(WISPY_DIR, "memory"));
+    memFiles = mFiles.filter((f) => f.endsWith(".md") || f.endsWith(".txt"));
+    memCount = memFiles.length;
+    // Count daily files
+    try {
+      const dailyFiles = await readdir(path.join(WISPY_DIR, "memory", "daily"));
+      memCount += dailyFiles.length;
+      memFiles.push(...dailyFiles.map((f) => `daily/${f}`));
+    } catch {}
+  } catch {}
+
+  // Count sessions
+  let sessionCount = 0;
+  try {
+    const sFiles = await readdir(path.join(WISPY_DIR, "sessions"));
+    sessionCount = sFiles.filter((f) => f.endsWith(".json")).length;
+  } catch {}
+
+  // Count cron jobs
+  let cronCount = 0;
+  try {
+    const cronData = JSON.parse(await readFile(path.join(WISPY_DIR, "cron.json"), "utf8"));
+    cronCount = (cronData.jobs ?? []).filter((j) => j.enabled).length;
+  } catch {}
+
+  // Count nodes
+  let nodeCount = 0;
+  try {
+    const nodeData = JSON.parse(await readFile(path.join(WISPY_DIR, "nodes.json"), "utf8"));
+    nodeCount = (nodeData.nodes ?? []).length;
+  } catch {}
+
+  // Provider info
+  const providerKey = config.provider;
+  const providerInfo = PROVIDER_LIST.find((p) => p.key === providerKey);
+  const providerLabel = providerInfo ? providerInfo.label : providerKey ?? dim("not set");
+  const hasApiKey = !!(config.apiKey || (providerKey === "ollama"));
+  const providerDisplay = providerKey
+    ? `${cyan(providerLabel)} ${dim(`(${config.model ?? providerInfo?.defaultModel ?? "?"})`)}`
+      + (hasApiKey ? ` ${green("✅")}` : ` ${yellow("⚠️  no key")}`)
+    : red("not configured");
+
+  // Channels
+  const tgOk  = config.channels?.telegram?.enabled;
+  const dcOk  = config.channels?.discord?.enabled;
+  const slOk  = config.channels?.slack?.enabled;
+  const chanStr = [
+    `Telegram ${tgOk ? green("✅") : red("❌")}`,
+    `Discord ${dcOk  ? green("✅") : red("❌")}`,
+    `Slack ${slOk    ? green("✅") : red("❌")}`,
+  ].join(dim(" | "));
+
+  const mode = remote?.url ? yellow("remote") : green("local");
+  const security = SECURITY_LEVELS[config.security ?? "careful"]?.label ?? "Careful";
+
+  console.log(`\n🌿 ${bold("Wispy Status")}\n`);
+  console.log(`  Mode:        ${mode}`);
+  if (remote?.url) console.log(`  Server:      ${cyan(remote.url)}`);
+  console.log(`  Provider:    ${providerDisplay}`);
+  console.log(`  Channels:    ${chanStr}`);
+  console.log(`  Workstream:  ${config.workstream ?? "default"}`);
+  console.log(`  Security:    ${security}`);
+  console.log(`  Memory:      ${memCount} file${memCount !== 1 ? "s" : ""}`
+    + (memFiles.length > 0 ? dim(` (${memFiles.slice(0, 3).join(", ")}${memFiles.length > 3 ? "..." : ""})`) : ""));
+  console.log(`  Sessions:    ${sessionCount} total`);
+  console.log(`  Cron jobs:   ${cronCount} active`);
+  console.log(`  Nodes:       ${nodeCount} connected`);
+  console.log(`  Server:      ${config.server?.enabled ? green("On :"+config.server.port) : "Off"}`);
+  console.log("");
+  console.log(`  ${dim("Config:")} ${dim(CONFIG_PATH)}`);
+  console.log(`  ${dim("Data:  ")} ${dim(WISPY_DIR + "/")}`);
+  console.log("");
+}