wispy-cli 2.2.1 → 2.3.0

package/bin/wispy.mjs

@@ -18,73 +18,590 @@
 
 import { fileURLToPath } from "node:url";
 import path from "node:path";
+import { readFileSync } from "node:fs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const args = process.argv.slice(2);
 
+// ── Global helpers ─────────────────────────────────────────────────────────────
+
+// Color helpers (reused throughout)
+const _green  = (s) => `\x1b[32m${s}\x1b[0m`;
+const _red    = (s) => `\x1b[31m${s}\x1b[0m`;
+const _yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const _cyan   = (s) => `\x1b[36m${s}\x1b[0m`;
+const _bold   = (s) => `\x1b[1m${s}\x1b[0m`;
+const _dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+
+// Debug mode (--debug flag or WISPY_DEBUG env)
+const DEBUG = args.includes("--debug") || process.env.WISPY_DEBUG === "1";
+if (DEBUG) {
+  process.env.WISPY_DEBUG = "1";
+  // Remove --debug from args so it doesn't confuse subcommands
+  const idx = args.indexOf("--debug");
+  if (idx !== -1) args.splice(idx, 1);
+}
+
+// Friendly error display
+function friendlyError(err, exitCode = 1) {
+  if (DEBUG) {
+    console.error(_red(`\n❌ Error: ${err.message}`));
+    console.error(_dim(err.stack));
+  } else {
+    console.error(_red(`\n❌ Error: ${err.message}`));
+    console.error(_dim("  Run with --debug for more details."));
+  }
+  process.exit(exitCode);
+}
+
+// Read version once
+let _version;
+function getVersion() {
+  if (_version) return _version;
+  try {
+    _version = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
+  } catch { _version = "?.?.?"; }
+  return _version;
+}
+
+// Global SIGINT handler (individual commands may override this)
+process.on("SIGINT", () => {
+  console.log(_dim("\n\nInterrupted."));
+  process.exit(130);
+});
+
+// ── --version / -v / version ───────────────────────────────────────────────────
+if (args[0] === "--version" || args[0] === "-v" || args[0] === "version") {
+  console.log(`wispy-cli v${getVersion()}`);
+  process.exit(0);
+}
+
+// ── --help / -h ────────────────────────────────────────────────────────────────
+if (args[0] === "--help" || args[0] === "-h") {
+  const v = getVersion();
+  console.log(`
+${_bold("🌿 Wispy")} ${_dim(`v${v}`)} — AI workspace assistant
+
+${_bold("Usage:")} wispy [command] [options]
+
+${_bold("AI Interaction:")}
+  ${_cyan("wispy")}                         Start interactive REPL
+  ${_cyan('wispy "message"')}               One-shot message
+  ${_cyan("wispy tui")}                     Workspace TUI
+  ${_cyan("wispy dry <cmd>")}               Run in dry-run mode
+
+${_bold("Workstreams:")}
+  ${_cyan("wispy ws")}                      List workstreams
+  ${_cyan("wispy ws new <name>")}           Create workstream
+  ${_cyan("wispy ws switch <name>")}        Switch workstream
+  ${_cyan("wispy ws archive <name>")}       Archive workstream
+  ${_cyan("wispy ws delete <name>")}        Delete workstream
+
+${_bold("Trust & Security:")}
+  ${_cyan("wispy trust")}                   Show trust level & policies
+  ${_cyan("wispy trust <level>")}           Set trust (careful/balanced/yolo)
+  ${_cyan("wispy audit")}                   View audit log
+
+${_bold("Continuity:")}
+  ${_cyan("wispy where")}                   Show current mode
+  ${_cyan("wispy handoff")}                 Generate handoff summary
+
+${_bold("Skills:")}
+  ${_cyan("wispy skill list")}              List skills
+  ${_cyan("wispy skill show <name>")}       Show skill details
+  ${_cyan("wispy teach <name>")}            Create skill from conversation
+  ${_cyan("wispy improve <name> [notes]")}  Improve a skill
+
+${_bold("Channels & Bots:")}
+  ${_cyan("wispy channel setup <name>")}    Setup channel (telegram/discord/slack/…)
+  ${_cyan("wispy channel list")}            List configured channels
+  ${_cyan("wispy channel test <name>")}     Test channel connection
+  ${_cyan("wispy --serve")}                 Start all channel bots
+
+${_bold("Server & Deploy:")}
+  ${_cyan("wispy server")}                  Start API server
+  ${_cyan("wispy deploy")}                  Deploy help & config generators
+  ${_cyan("wispy node")}                    Node (multi-machine) management
+  ${_cyan("wispy sync")}                    Sync with remote server
+
+${_bold("Cron & Automation:")}
+  ${_cyan("wispy cron list")}               List cron jobs
+  ${_cyan("wispy cron add")}                Add a cron job
+  ${_cyan("wispy cron start")}              Start scheduler
+
+${_bold("Config & Maintenance:")}
+  ${_cyan("wispy setup")}                   Configure wispy interactively
+  ${_cyan("wispy update")}                  Update to latest version
+  ${_cyan("wispy migrate")}                 Import from OpenClaw
+  ${_cyan("wispy doctor")}                  Check system health
+  ${_cyan("wispy version")}                 Show version
+
+${_bold("Shell Completions:")}
+  ${_cyan("wispy completion bash")}         Bash completion script
+  ${_cyan("wispy completion zsh")}          Zsh completion script
+
+${_bold("Flags:")}
+  ${_cyan("--help, -h")}                    Show this help
+  ${_cyan("--version, -v")}                 Show version
+  ${_cyan("--debug")}                       Verbose logs & stack traces
+  ${_cyan("WISPY_DEBUG=1")}                 Same as --debug via env
+
+${_dim("Run 'wispy help <command>' for detailed help on a specific command.")}
+`);
+  process.exit(0);
+}
+
+// ── help sub-command (detailed per-command help) ──────────────────────────────
+if (args[0] === "help") {
+  const topic = args[1];
+  const helpTexts = {
+    ws: `
+${_bold("wispy ws")} — Workstream management
+
+${_bold("Usage:")}
+  wispy ws                     List all workstreams
+  wispy ws new <name>          Create a new workstream
+  wispy ws switch <name>       Switch to a workstream
+  wispy ws archive <name>      Archive a workstream (move sessions/memory)
+  wispy ws delete <name>       Permanently delete a workstream
+  wispy ws status              Status overview of all workstreams
+  wispy ws search <query>      Search across all workstreams
+
+${_bold("Examples:")}
+  wispy ws new project-x
+  wispy ws switch project-x
+  wispy ws archive old-project
+`,
+    trust: `
+${_bold("wispy trust")} — Trust levels and security
+
+${_bold("Usage:")}
+  wispy trust                  Show current trust level and policies
+  wispy trust careful          Require approval for everything
+  wispy trust balanced         Approve only risky operations
+  wispy trust yolo             Auto-approve everything
+
+${_bold("Trust levels:")}
+  careful    — Review every tool call before execution
+  balanced   — Auto-approve safe ops, review destructive ones
+  yolo       — Full automation (use with care!)
+`,
+    deploy: `
+${_bold("wispy deploy")} — Deployment helpers
+
+${_bold("Usage:")}
+  wispy deploy init              Generate Dockerfile + compose + .env.example
+  wispy deploy dockerfile        Print Dockerfile
+  wispy deploy compose           Print docker-compose.yml
+  wispy deploy systemd           Print systemd unit
+  wispy deploy railway           Print railway.json
+  wispy deploy fly               Print fly.toml
+  wispy deploy render            Print render.yaml
+  wispy deploy modal             Generate Modal serverless config
+  wispy deploy daytona           Generate Daytona workspace config
+  wispy deploy vps user@host     SSH deploy to VPS
+  wispy deploy status <url>      Check remote server health
+
+${_bold("Examples:")}
+  wispy deploy init
+  wispy deploy vps root@my.vps
+  wispy connect https://my.vps:18790 --token <token>
+`,
+    cron: `
+${_bold("wispy cron")} — Scheduled task management
+
+${_bold("Usage:")}
+  wispy cron list             List all cron jobs
+  wispy cron add              Interactive job creation
+  wispy cron remove <id>      Delete a cron job
+  wispy cron run <id>         Run a job immediately
+  wispy cron history <id>     Show past runs
+  wispy cron start            Start scheduler in foreground
+
+${_bold("Schedule types:")}
+  cron   — standard cron expression (e.g. "0 9 * * *")
+  every  — interval in minutes
+  at     — one-time ISO datetime
+`,
+    channel: `
+${_bold("wispy channel")} — Messaging channel setup
+
+${_bold("Usage:")}
+  wispy channel setup telegram    Telegram bot setup
+  wispy channel setup discord     Discord bot setup
+  wispy channel setup slack       Slack bot setup
+  wispy channel setup whatsapp    WhatsApp setup
+  wispy channel setup email       Email setup
+  wispy channel list              List configured channels
+  wispy channel test <name>       Test channel connection
+
+${_bold("Running bots:")}
+  wispy --serve                   Start all configured bots
+  wispy --telegram                Start Telegram bot only
+  wispy --discord                 Start Discord bot only
+`,
+    sync: `
+${_bold("wispy sync")} — Remote sync
+
+${_bold("Usage:")}
+  wispy sync                          Bidirectional sync
+  wispy sync push                     Push local → remote
+  wispy sync pull                     Pull remote → local
+  wispy sync status                   Show sync status
+  wispy sync auto                     Enable auto-sync
+  wispy sync auto --off               Disable auto-sync
+
+${_bold("Flags:")}
+  --remote <url>              Remote server URL
+  --token <token>             Auth token
+  --strategy newer-wins       Conflict resolution (newer-wins|local-wins|remote-wins)
+  --memory-only               Only sync memory files
+  --sessions-only             Only sync sessions
+`,
+    skill: `
+${_bold("wispy skill")} — Skill management
+
+${_bold("Usage:")}
+  wispy skill list            List all installed skills
+  wispy skill show <name>     Show skill details
+  wispy teach <name>          Create a skill from current conversation
+  wispy improve <name>        Improve an existing skill
+
+${_bold("In REPL:")}
+  /skills                     List skills
+  /teach <name>               Teach from conversation
+  /<skill-name>               Invoke any skill
+`,
+    doctor: `
+${_bold("wispy doctor")} — System health check
+
+Checks Node.js version, config, API keys, directory permissions,
+optional dependencies, and remote server connectivity.
+
+${_bold("Usage:")}
+  wispy doctor
+`,
+    node: `
+${_bold("wispy node")} — Multi-machine node management
+
+${_bold("Usage:")}
+  wispy node pair                     Generate pairing code
+  wispy node connect <code> --url <url>  Connect as a node
+  wispy node list                     Show registered nodes
+  wispy node status                   Ping all nodes
+  wispy node remove <id>              Unregister a node
+`,
+  };
+
+  if (topic && helpTexts[topic]) {
+    console.log(helpTexts[topic]);
+  } else if (topic) {
+    console.log(_yellow(`\n⚠️  No detailed help for '${topic}'. Try 'wispy --help' for the full command list.\n`));
+  } else {
+    // Generic help — same as --help
+    args[0] = "--help";
+    // Re-trigger help by falling through (not possible here, just print it)
+    console.log(`Run ${_cyan("wispy --help")} for the full command list.`);
+    console.log(`Run ${_cyan("wispy help <command>")} for per-command help.`);
+    console.log(`\nAvailable topics: ${Object.keys(helpTexts).map(k => _cyan(k)).join(", ")}`);
+  }
+  process.exit(0);
+}
+
+// ── completion sub-command ────────────────────────────────────────────────────
+if (args[0] === "completion") {
+  const shell = args[1] ?? "bash";
+  const cmds = ["ws", "trust", "where", "handoff", "skill", "teach", "improve", "dry",
+    "deploy", "server", "node", "channel", "cron", "audit", "sync", "setup", "update",
+    "tui", "migrate", "version", "doctor", "help", "completion", "status",
+    "connect", "disconnect", "log"];
+  const flags = ["--help", "--version", "--debug", "--serve", "--telegram", "--discord", "--slack"];
+
+  if (shell === "bash") {
+    console.log(`# wispy bash completion
+# Add to ~/.bashrc: eval "$(wispy completion bash)"
+_wispy_completion() {
+  local cur prev words
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  local commands="${cmds.join(" ")}"
+  local flags="${flags.join(" ")}"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "\${commands} \${flags}" -- "\${cur}") )
+  fi
+}
+complete -F _wispy_completion wispy`);
+  } else if (shell === "zsh") {
+    console.log(`# wispy zsh completion
+# Add to ~/.zshrc: eval "$(wispy completion zsh)"
+_wispy() {
+  local -a commands
+  commands=(
+    ${cmds.map(c => `'${c}'`).join("\n    ")}
+  )
+  local -a flags
+  flags=(${flags.map(f => `'${f}'`).join(" ")})
+  _arguments -C \\
+    '1:command:->cmds' \\
+    '*::arg:->args'
+  case $state in
+    cmds) _describe 'wispy commands' commands ;;
+  esac
+}
+compdef _wispy wispy`);
+  } else if (shell === "fish") {
+    const completions = cmds.map(c => `complete -c wispy -f -n '__fish_use_subcommand' -a '${c}'`).join("\n");
+    console.log(`# wispy fish completion\n# Save to ~/.config/fish/completions/wispy.fish\n${completions}`);
+  } else {
+    console.error(_red(`❌ Unknown shell: ${shell}. Use: bash, zsh, or fish`));
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+// ── doctor sub-command ────────────────────────────────────────────────────────
+if (args[0] === "doctor") {
+  const { access, readFile: rf, stat } = await import("node:fs/promises");
+  const { homedir } = await import("node:os");
+  const wispyDir = path.join(homedir(), ".wispy");
+  const configPath = path.join(wispyDir, "config.json");
+  const memoryDir = path.join(wispyDir, "memory");
+  const sessionsDir = path.join(wispyDir, "sessions");
+
+  console.log(`\n${_bold("🩺 Wispy Doctor")} ${_dim(`v${getVersion()}`)}\n`);
+
+  let allOk = true;
+  const issues = [];
+
+  function check(label, ok, detail = "") {
+    if (ok) {
+      console.log(`  ${_green("✅")} ${label}${detail ? _dim("  " + detail) : ""}`);
+    } else {
+      console.log(`  ${_red("❌")} ${label}${detail ? _dim("  " + detail) : ""}`);
+      allOk = false;
+      issues.push(label);
+    }
+  }
+
+  function info(label, detail) {
+    console.log(`  ${_cyan("ℹ️ ")} ${label}${detail ? _dim("  " + detail) : ""}`);
+  }
+
+  // 1. Node.js version
+  const [major] = process.version.replace("v", "").split(".").map(Number);
+  check("Node.js version", major >= 18, `${process.version} (required: >= 18)`);
+
+  // 2. Config file
+  let config = null;
+  try {
+    const raw = await rf(configPath, "utf8");
+    config = JSON.parse(raw);
+    check("Config file", true, configPath);
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      check("Config file", false, `Not found at ${configPath} — run 'wispy setup'`);
+    } else {
+      check("Config file", false, `Malformed JSON — run 'wispy setup' to reconfigure`);
+    }
+  }
+
+  // 3. API key configured
+  if (config) {
+    const provider = config.provider ?? "unknown";
+    const envMap = {
+      google: "GOOGLE_AI_KEY",
+      anthropic: "ANTHROPIC_API_KEY",
+      openai: "OPENAI_API_KEY",
+      groq: "GROQ_API_KEY",
+      openrouter: "OPENROUTER_API_KEY",
+      deepseek: "DEEPSEEK_API_KEY",
+      ollama: null,
+    };
+    const envKey = envMap[provider];
+    if (envKey === null) {
+      check("AI provider (Ollama)", true, "no key needed");
+    } else if (envKey) {
+      const key = config.apiKey || process.env[envKey];
+      check(`API key (${provider})`, !!key && key.length > 10, key ? "configured" : `run 'wispy setup provider'`);
+    } else {
+      check("AI provider", false, `Unknown provider: ${provider}`);
+    }
+  } else {
+    info("AI provider", "skipped (no config)");
+  }
+
+  // 4. Memory directory writable
+  try {
+    const { mkdir: mkd, writeFile: wf, unlink: unl } = await import("node:fs/promises");
+    await mkd(memoryDir, { recursive: true });
+    const testFile = path.join(memoryDir, ".write-test");
+    await wf(testFile, "test", "utf8");
+    await unl(testFile);
+    check("Memory dir writable", true, memoryDir);
+  } catch (e) {
+    check("Memory dir writable", false, e.message);
+  }
+
+  // 5. Sessions directory writable
+  try {
+    const { mkdir: mkd, writeFile: wf, unlink: unl } = await import("node:fs/promises");
+    await mkd(sessionsDir, { recursive: true });
+    const testFile = path.join(sessionsDir, ".write-test");
+    await wf(testFile, "test", "utf8");
+    await unl(testFile);
+    check("Sessions dir writable", true, sessionsDir);
+  } catch (e) {
+    check("Sessions dir writable", false, e.message);
+  }
+
+  // 6. Optional deps
+  console.log(`\n  ${_bold("Optional dependencies:")}`);
+  const optDeps = [
+    { pkg: "grammy",          label: "Telegram (grammy)" },
+    { pkg: "discord.js",      label: "Discord (discord.js)" },
+    { pkg: "@slack/bolt",     label: "Slack (@slack/bolt)" },
+    { pkg: "whatsapp-web.js", label: "WhatsApp (whatsapp-web.js)" },
+    { pkg: "nodemailer",      label: "Email (nodemailer)" },
+    { pkg: "imapflow",        label: "Email IMAP (imapflow)" },
+  ];
+  for (const dep of optDeps) {
+    try {
+      await import(dep.pkg);
+      check(dep.label, true, "installed");
+    } catch {
+      console.log(`  ${_dim("–")}  ${_dim(dep.label + "  not installed (optional)")}`);
+    }
+  }
+
+  // 7. Remote server (if configured)
+  const remotePath = path.join(wispyDir, "remote.json");
+  try {
+    const remote = JSON.parse(await rf(remotePath, "utf8"));
+    if (remote?.url) {
+      console.log(`\n  ${_bold("Remote server:")}`);
+      process.stdout.write(`  ${_cyan("🔄")} Checking ${remote.url}... `);
+      try {
+        const resp = await fetch(`${remote.url}/api/health`, { signal: AbortSignal.timeout(5000) });
+        if (resp.ok) {
+          console.log(_green("✅ reachable"));
+        } else {
+          console.log(_yellow(`⚠️  HTTP ${resp.status}`));
+          allOk = false;
+        }
+      } catch {
+        console.log(_red("❌ unreachable"));
+        allOk = false;
+        issues.push("Remote server unreachable");
+      }
+    }
+  } catch {}
+
+  console.log("");
+  if (allOk) {
+    console.log(`${_green("✅ All checks passed!")}\n`);
+  } else {
+    console.log(`${_yellow("⚠️  Issues found:")} ${issues.join(", ")}`);
+    console.log(_dim("  Run 'wispy setup' to fix configuration issues.\n"));
+  }
+  process.exit(allOk ? 0 : 1);
+}
+
+// ── config validation helper ───────────────────────────────────────────────────
+async function validateConfigOnStartup() {
+  const { homedir } = await import("node:os");
+  const { readFile: rf } = await import("node:fs/promises");
+  const configPath = path.join(homedir(), ".wispy", "config.json");
+  try {
+    const raw = await rf(configPath, "utf8");
+    JSON.parse(raw);
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      console.error(_red("❌ Config file corrupted. Run 'wispy setup' to reconfigure."));
+      process.exit(1);
+    }
+    // File not found is OK (first run)
+  }
+}
+
 // ── ws sub-command ────────────────────────────────────────────────────────────
 if (args[0] === "ws") {
-  const { handleWsCommand } = await import(
-    path.join(__dirname, "..", "lib", "commands", "ws.mjs")
-  );
-  await handleWsCommand(args);
+  try {
+    const { handleWsCommand } = await import(
+      path.join(__dirname, "..", "lib", "commands", "ws.mjs")
+    );
+    await handleWsCommand(args);
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── trust sub-command ─────────────────────────────────────────────────────────
 if (args[0] === "trust") {
-  const { handleTrustCommand } = await import(
-    path.join(__dirname, "..", "lib", "commands", "trust.mjs")
-  );
-  await handleTrustCommand(args);
+  try {
+    const { handleTrustCommand } = await import(
+      path.join(__dirname, "..", "lib", "commands", "trust.mjs")
+    );
+    await handleTrustCommand(args);
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── where sub-command ─────────────────────────────────────────────────────────
 if (args[0] === "where") {
-  const { cmdWhere } = await import(
-    path.join(__dirname, "..", "lib", "commands", "continuity.mjs")
-  );
-  await cmdWhere();
+  try {
+    const { cmdWhere } = await import(
+      path.join(__dirname, "..", "lib", "commands", "continuity.mjs")
+    );
+    await cmdWhere();
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── handoff sub-command ───────────────────────────────────────────────────────
 if (args[0] === "handoff") {
-  const { handleContinuityCommand } = await import(
-    path.join(__dirname, "..", "lib", "commands", "continuity.mjs")
-  );
-  await handleContinuityCommand(args);
+  try {
+    const { handleContinuityCommand } = await import(
+      path.join(__dirname, "..", "lib", "commands", "continuity.mjs")
+    );
+    await handleContinuityCommand(args);
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── skill sub-command ─────────────────────────────────────────────────────────
 if (args[0] === "skill") {
-  const { handleSkillCommand } = await import(
-    path.join(__dirname, "..", "lib", "commands", "skills-cmd.mjs")
-  );
-  await handleSkillCommand(args);
+  try {
+    const { handleSkillCommand } = await import(
+      path.join(__dirname, "..", "lib", "commands", "skills-cmd.mjs")
+    );
+    await handleSkillCommand(args);
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── teach sub-command ─────────────────────────────────────────────────────────
 if (args[0] === "teach") {
-  const { cmdTeach } = await import(
-    path.join(__dirname, "..", "lib", "commands", "skills-cmd.mjs")
-  );
-  await cmdTeach(args[1]);
+  try {
+    const { cmdTeach } = await import(
+      path.join(__dirname, "..", "lib", "commands", "skills-cmd.mjs")
+    );
+    await cmdTeach(args[1]);
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── improve sub-command ───────────────────────────────────────────────────────
 if (args[0] === "improve") {
-  const { cmdImproveSkill } = await import(
-    path.join(__dirname, "..", "lib", "commands", "skills-cmd.mjs")
-  );
-  const name = args[1];
-  const feedback = args.slice(2).join(" ").replace(/^["']|["']$/g, "");
-  await cmdImproveSkill(name, feedback);
+  try {
+    const { cmdImproveSkill } = await import(
+      path.join(__dirname, "..", "lib", "commands", "skills-cmd.mjs")
+    );
+    const name = args[1];
+    const feedback = args.slice(2).join(" ").replace(/^["']|["']$/g, "");
+    await cmdImproveSkill(name, feedback);
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
@@ -103,38 +620,40 @@ if (args[0] === "dry") {
 
 // ── setup / init sub-command ──────────────────────────────────────────────────
 if (args[0] === "setup" || args[0] === "init") {
-  const { OnboardingWizard } = await import(
-    path.join(__dirname, "..", "core", "onboarding.mjs")
-  );
-  const wizard = new OnboardingWizard();
-  const sub = args[1]; // e.g. "provider", "channels", "security"
-  if (sub && sub !== "wizard") {
-    await wizard.runStep(sub);
-  } else {
-    await wizard.run();
-  }
+  // Handle Ctrl+C gracefully in setup
+  process.removeAllListeners("SIGINT");
+  process.on("SIGINT", () => { console.log(_dim("\nSetup cancelled.")); process.exit(130); });
+  try {
+    const { OnboardingWizard } = await import(
+      path.join(__dirname, "..", "core", "onboarding.mjs")
+    );
+    const wizard = new OnboardingWizard();
+    const sub = args[1]; // e.g. "provider", "channels", "security"
+    if (sub && sub !== "wizard") {
+      await wizard.runStep(sub);
+    } else {
+      await wizard.run();
+    }
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
 // ── update sub-command ────────────────────────────────────────────────────────
 if (args[0] === "update") {
-  const { execSync } = await import("node:child_process");
-  console.log("🌿 Checking for updates...");
   try {
-    const current = JSON.parse(await import("node:fs").then(f => f.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"))).version;
+    const { execSync } = await import("node:child_process");
+    console.log(_cyan("🔄 Checking for updates..."));
+    const current = getVersion();
     const latest = execSync("npm info wispy-cli version", { encoding: "utf8" }).trim();
     if (current === latest) {
-      console.log(`✅ Already on latest version (${current})`);
+      console.log(_green(`✅ Already on latest version (${current})`));
     } else {
-      console.log(`📦 ${current} → ${latest}`);
-      console.log("Updating...");
+      console.log(`📦 ${_dim(current)} → ${_bold(latest)}`);
+      console.log(_cyan("🔄 Updating..."));
       execSync("npm install -g wispy-cli@latest", { stdio: "inherit" });
-      console.log(`\n✅ Updated to ${latest}`);
+      console.log(_green(`\n✅ Updated to ${latest}`));
     }
-  } catch (e) {
-    console.error(`❌ Update failed: ${e.message}`);
-    process.exit(1);
-  }
+  } catch (e) { friendlyError(e); }
   process.exit(0);
 }
 
@@ -147,7 +666,7 @@ if (args[0] === "status") {
     );
     await printStatus();
     process.exit(0);
-  } catch {}
+  } catch (e) { if (DEBUG) console.error(e); }
 
   // Fallback: original status (remote check)
   const { readFile } = await import("node:fs/promises");
@@ -1062,6 +1581,45 @@ if (args[0] === "channel") {
   process.exit(0);
 }
 
+// ── Unknown command detection ─────────────────────────────────────────────────
+// Any non-flag argument that wasn't matched above is an unknown command
+const _KNOWN_COMMANDS = new Set([
+  "ws", "trust", "where", "handoff", "skill", "teach", "improve", "dry",
+  "setup", "init", "update", "status", "connect", "disconnect", "sync",
+  "deploy", "migrate", "cron", "audit", "log", "server", "node", "channel",
+  "tui", "help", "doctor", "completion", "version",
+  // serve flags (handled below)
+  "--serve", "--telegram", "--discord", "--slack", "--server",
+  "--help", "-h", "--version", "-v", "--debug", "--tui",
+  // workstream flags
+  "-w", "--workstream",
+]);
+const _firstArg = args[0];
+if (_firstArg && _firstArg[0] !== "-" && !_KNOWN_COMMANDS.has(_firstArg)) {
+  // Not a known command — but could be a one-shot message (no quotes needed)
+  // Heuristic: if it looks like a real command word (no spaces, short), warn.
+  // If it looks like a natural language sentence, fall through to REPL one-shot mode.
+  const looksLikeCommand = /^[a-z][a-z0-9_-]{0,20}$/.test(_firstArg);
+  if (looksLikeCommand) {
+    // Show unknown command error
+    const suggestions = [
+      { cmd: "setup",   desc: "configure wispy" },
+      { cmd: "tui",     desc: "workspace UI" },
+      { cmd: "ws",      desc: "workstream management" },
+      { cmd: "doctor",  desc: "check system health" },
+      { cmd: "help",    desc: "show detailed help" },
+    ];
+    console.error(`\n${_red(`❌ Unknown command: ${_firstArg}`)}`);
+    console.error(`\n${_bold("Did you mean one of these?")}`);
+    for (const { cmd, desc } of suggestions) {
+      console.error(`  ${_cyan("wispy " + cmd.padEnd(12))}— ${desc}`);
+    }
+    console.error(`\n${_dim("Run wispy --help for all commands.")}\n`);
+    process.exit(2);
+  }
+  // Otherwise fall through to one-shot message mode in REPL
+}
+
 // ── Bot / serve modes ─────────────────────────────────────────────────────────
 const serveMode    = args.includes("--serve");
 const telegramMode = args.includes("--telegram");
@@ -1146,17 +1704,28 @@ if (isInteractiveStart) {
   }
 }
 
+// Validate config before starting interactive modes
+await validateConfigOnStartup();
+
 // ── TUI mode ──────────────────────────────────────────────────────────────────
 // `wispy ui` is the primary way; `--tui` is kept as a hidden backwards-compat alias
 const tuiMode = args[0] === "tui" || args.includes("--tui");
 
 if (tuiMode) {
+  // Override SIGINT for clean TUI exit
+  process.removeAllListeners("SIGINT");
+  process.on("SIGINT", () => { process.exit(130); });
+
   const newArgs = args.filter(a => a !== "--tui" && a !== "tui");
   process.argv = [process.argv[0], process.argv[1], ...newArgs];
   const tuiScript = path.join(__dirname, "..", "lib", "wispy-tui.mjs");
-  await import(tuiScript);
+  try {
+    await import(tuiScript);
+  } catch (e) { friendlyError(e); }
 } else {
   // Default: interactive REPL
   const mainScript = path.join(__dirname, "..", "lib", "wispy-repl.mjs");
-  await import(mainScript);
+  try {
+    await import(mainScript);
+  } catch (e) { friendlyError(e); }
 }

package/lib/commands/ws.mjs

@@ -221,6 +221,16 @@ export async function cmdWsArchive(name) {
     return;
   }
 
+  // Confirmation prompt
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise(r => rl.question(`Archive '${name}'? Sessions and memory will be moved. [Y/n] `, r));
+  rl.close();
+  if (answer.trim().toLowerCase() === "n") {
+    console.log(dim("Cancelled."));
+    return;
+  }
+
   const archiveWsDir = path.join(ARCHIVE_DIR, name);
   await mkdir(archiveWsDir, { recursive: true });
 
@@ -356,6 +366,16 @@ export async function cmdWsDelete(name) {
     return;
   }
 
+  // Confirmation prompt
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise(r => rl.question(`⚠️  Are you sure? This will delete all sessions and memory for '${name}'. [y/N] `, r));
+  rl.close();
+  if (answer.trim().toLowerCase() !== "y") {
+    console.log(dim("Cancelled."));
+    return;
+  }
+
   const wsDir = path.join(WORKSTREAMS_DIR, name);
   const convFile = path.join(CONVERSATIONS_DIR, `${name}.json`);
 

package/lib/wispy-repl.mjs

@@ -1151,10 +1151,13 @@ async function runRepl(engine) {
     } catch (err) {
       if (err.message.includes("429") || err.message.includes("rate")) {
         console.log(yellow("\n\n⏳ Rate limited — wait a moment and try again."));
-      } else if (err.message.includes("401") || err.message.includes("403")) {
-        console.log(red("\n\n🔑 Authentication error — check your API key."));
+      } else if (err.message.includes("401") || err.message.includes("403") || err.message.includes("invalid") || err.message.includes("API key")) {
+        console.log(red("\n\n❌ API key is invalid. Run 'wispy setup provider' to reconfigure."));
+      } else if (err.message.includes("ENOTFOUND") || err.message.includes("ECONNREFUSED") || err.message.includes("fetch")) {
+        console.log(red("\n\n❌ Cannot reach API. Check your connection."));
       } else {
         console.log(red(`\n\n❌ Error: ${err.message.slice(0, 200)}`));
+        if (process.env.WISPY_DEBUG === "1") console.error(dim(err.stack));
       }
     }
 
@@ -1163,7 +1166,7 @@ async function runRepl(engine) {
 
   rl.on("close", () => {
     console.log(dim(`\n🌿 Bye! (${engine.providers.formatCost()})`));
-    engine.destroy();
+    try { engine.destroy(); } catch {}
     process.exit(0);
   });
 }
@@ -1180,15 +1183,21 @@ async function runOneShot(engine, message) {
     console.log("");
     console.log(dim(engine.providers.formatCost()));
   } catch (err) {
-    if (err.message.includes("429")) {
-      console.error(yellow("\n⏳ Rate limited — try again shortly."));
+    if (err.message.includes("429") || err.message.includes("rate")) {
+      console.error(yellow("\n⏳ Rate limited — wait a moment and try again."));
+    } else if (err.message.includes("401") || err.message.includes("403") || err.message.includes("invalid") || err.message.includes("API key")) {
+      console.error(red("\n❌ API key is invalid. Run 'wispy setup provider' to reconfigure."));
+    } else if (err.message.includes("ENOTFOUND") || err.message.includes("ECONNREFUSED") || err.message.includes("fetch")) {
+      console.error(red("\n❌ Cannot reach API. Check your connection."));
     } else {
-      console.error(red(`\n❌ ${err.message.slice(0, 200)}`));
+      console.error(red(`\n❌ Error: ${err.message.slice(0, 200)}`));
+      if (process.env.WISPY_DEBUG === "1") console.error(dim(err.stack));
+      else console.error(dim("  Run with WISPY_DEBUG=1 for details."));
     }
-    engine.destroy();
+    try { engine.destroy(); } catch {}
     process.exit(1);
   }
-  engine.destroy();
+  try { engine.destroy(); } catch {}
   process.exit(0);
 }
 
@@ -1243,6 +1252,8 @@ const engine = new WispyEngine({ workstream: ACTIVE_WORKSTREAM });
 const initResult = await engine.init();
 
 if (!initResult) {
+  // Show friendly message before onboarding
+  console.log(yellow("\n⚠️  No API key configured. Run 'wispy setup' to get started.\n"));
   // Delegate to unified onboarding wizard
   try {
     const { OnboardingWizard } = await import("../core/onboarding.mjs");
@@ -1262,8 +1273,15 @@ if (!initResult) {
 
 // Graceful cleanup
 process.on("exit", () => { try { engine.destroy(); } catch {} });
-process.on("SIGINT", () => { engine.destroy(); process.exit(0); });
-process.on("SIGTERM", () => { engine.destroy(); process.exit(0); });
+process.on("SIGINT", () => {
+  console.log(dim("\n\n🌿 Bye!"));
+  try { engine.destroy(); } catch {}
+  process.exit(130);
+});
+process.on("SIGTERM", () => {
+  try { engine.destroy(); } catch {}
+  process.exit(0);
+});
 
 // Auto-start background server
 const serverStatus = await startServerIfNeeded();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wispy-cli",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "🌿 Wispy — AI workspace assistant with trustworthy execution (harness, receipts, approvals, diffs)",
   "license": "MIT",
   "author": "Minseo & Poropo",