alvin-bot 4.22.3 → 4.23.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.23.0] — 2026-05-12
+
+### Installer: bootstrap Node automatically + optional capability tools
+
+The first-time install path no longer assumes Node (or Homebrew, or anything beyond a normal Mac/Linux shell) is already in place, and the setup wizard now offers to install a curated set of universally useful CLIs in one step.
+
+- **`install.sh` — auto-bootstraps Node.** New `ensure_brew()` + `ensure_node()` helpers replace the old "fail with manual install instructions" behaviour. On macOS, if Homebrew is missing, the installer offers to install it via the official `curl|bash` (with `NONINTERACTIVE=1` so it doesn't pause for ENTER). On Debian/Ubuntu, offers Node 22 via the NodeSource repo (with sudo confirmation). Non-interactive shells fall back to clear manual-install messages. Skipping the prompts is always an option. `eval "$(brew shellenv)"` is invoked after a fresh brew install so the rest of the script sees brew on PATH.
+
+- **`alvin-bot setup` — optional tools step.** After Telegram + AI provider config, the wizard now lists eight commonly useful tools and lets the user install just the ones they want with a comma-separated picklist (or `a` for all missing, `n` to skip). Already-installed tools are marked `✓` and skipped automatically. Install failures don't block bot setup — the user gets a working bot regardless.
+
+- **New `alvin-bot tools` command.** Re-runnable later: `alvin-bot tools list` shows what's installed, `alvin-bot tools install` opens the same interactive menu the setup wizard uses.
+
+Tools offered (curated, all generic — none require maintainer-specific creds or workflows):
+
+| Tool | What it unlocks |
+|---|---|
+| Playwright + Chromium | Tier 1 stealth browser automation (web-research, social-fetch, browser-manager) |
+| agent-browser CLI | Tier 1.5 token-efficient web automation (Vercel Labs) |
+| ffmpeg | Audio/video processing for media-transcribe, video-generate, voice features |
+| ImageMagick | Image conversion & manipulation for image-generate and visual skills |
+| Pandoc | Markdown ↔ PDF/DOCX/HTML conversion for document-creation skill |
+| ripgrep | Fast file/code search (`alvin-bot search`, code-aware skills) |
+| jq | JSON parsing for helper scripts |
+| himalaya | Multi-account IMAP/SMTP email CLI (configure after install) |
+
 ## [4.22.3] — 2026-05-12
 
 ### Fixed

package/bin/cli.js

@@ -128,6 +128,237 @@ const PROVIDERS = [
   },
 ];
 
+// ── Optional capability tools ───────────────────────────────────────────────
+//
+// Curated, universally useful CLIs that significantly expand what skills can
+// do. All optional, all opt-in. The list is intentionally short and generic —
+// no maintainer-specific credentials or workflows are required to make any of
+// these useful to a public user; auth/config is per-user and out of scope here.
+//
+// Each entry has:
+//   id           machine-readable key
+//   name         shown to the user
+//   desc         one-liner explaining what skills/features it unlocks
+//   check()      returns boolean — is it already installed?
+//   install      either a shell-command string (single platform) or an object
+//                { macos, linux } with platform-specific shell commands, or a
+//                function that does whatever it takes
+//   skipOnLinuxIf  optional: skip the Linux install if this command is missing
+//                  (e.g. himalaya on Linux needs cargo)
+const OPTIONAL_TOOLS = [
+  {
+    id: "playwright",
+    name: "Playwright + Chromium",
+    desc: "Browser automation (Tier 1 stealth) — used by web-research, social-fetch, browser-manager",
+    check: () => hasCommand("playwright") || hasCommand("npx") && tryNpx("playwright --version"),
+    install: () => {
+      execSync("npm install -g playwright", { stdio: "inherit" });
+      execSync("npx playwright install chromium", { stdio: "inherit" });
+    },
+  },
+  {
+    id: "agent-browser",
+    name: "agent-browser CLI (Vercel Labs)",
+    desc: "Tier 1.5 token-efficient web automation — ~90% cheaper than raw Playwright for AI-driven tasks",
+    check: () => hasCommand("agent-browser"),
+    install: () => {
+      execSync("npm install -g agent-browser", { stdio: "inherit" });
+      // Best-effort: ignore failure if the install subcommand isn't there
+      try { execSync("agent-browser install", { stdio: "inherit" }); } catch {}
+    },
+  },
+  {
+    id: "ffmpeg",
+    name: "ffmpeg",
+    desc: "Audio/video processing — required by media-transcribe, video-generate, voice features",
+    check: () => hasCommand("ffmpeg"),
+    install: { macos: "brew install ffmpeg", linux: "sudo apt-get install -y ffmpeg" },
+  },
+  {
+    id: "imagemagick",
+    name: "ImageMagick",
+    desc: "Image conversion & manipulation — used by image-generate and visual skills",
+    check: () => hasCommand("magick") || hasCommand("convert"),
+    install: { macos: "brew install imagemagick", linux: "sudo apt-get install -y imagemagick" },
+  },
+  {
+    id: "pandoc",
+    name: "Pandoc",
+    desc: "Document conversion (Markdown ↔ PDF/DOCX/HTML) — used by document-creation skill",
+    check: () => hasCommand("pandoc"),
+    install: { macos: "brew install pandoc", linux: "sudo apt-get install -y pandoc" },
+  },
+  {
+    id: "ripgrep",
+    name: "ripgrep (rg)",
+    desc: "Fast file & code search — used by `alvin-bot search` and code-aware skills",
+    check: () => hasCommand("rg"),
+    install: { macos: "brew install ripgrep", linux: "sudo apt-get install -y ripgrep" },
+  },
+  {
+    id: "jq",
+    name: "jq",
+    desc: "JSON parsing for shell scripts — used by many helper scripts and integrations",
+    check: () => hasCommand("jq"),
+    install: { macos: "brew install jq", linux: "sudo apt-get install -y jq" },
+  },
+  {
+    id: "himalaya",
+    name: "himalaya (email CLI)",
+    desc: "Multi-account IMAP/SMTP email CLI — bring your own email accounts, configure after install",
+    check: () => hasCommand("himalaya"),
+    install: { macos: "brew install himalaya", linux: "cargo install himalaya" },
+    skipOnLinuxIf: "cargo",
+  },
+];
+
+function hasCommand(name) {
+  try {
+    execSync(`command -v ${name}`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryNpx(args) {
+  try {
+    execSync(`npx --no-install ${args}`, { stdio: "pipe", timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Make sure `brew` is reachable in the current process. The setup wizard
+ * may be running in a fresh shell right after `install.sh` installed brew
+ * for the first time — in that case `/opt/homebrew/bin` may not be in
+ * PATH yet. Side-loads it if we find the binary.
+ */
+function ensureBrewOnPath() {
+  if (hasCommand("brew")) return true;
+  for (const candidate of ["/opt/homebrew/bin", "/usr/local/bin"]) {
+    if (existsSync(join(candidate, "brew"))) {
+      process.env.PATH = `${candidate}:${process.env.PATH || ""}`;
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Print the status of optional tools without prompting. Used by
+ * `alvin-bot tools list` for inspection and scripting.
+ */
+function listOptionalTools() {
+  const platform = process.platform === "darwin" ? "macos"
+                 : process.platform === "linux" ? "linux"
+                 : null;
+  console.log(`\n📦 Optional capability tools — ${platform || process.platform}\n`);
+  const states = OPTIONAL_TOOLS.map(t => ({ ...t, installed: t.check() }));
+  states.forEach((t, i) => {
+    const mark = t.installed ? "✓" : "·";
+    console.log(`  [${String(i + 1).padStart(2)}] ${mark} ${t.name}`);
+    console.log(`         ${t.desc}`);
+  });
+  const missing = states.filter(t => !t.installed).length;
+  console.log(`\n  ${states.length - missing} installed, ${missing} missing.`);
+  if (missing > 0) {
+    console.log(`  Install missing with:  alvin-bot tools install\n`);
+  } else {
+    console.log("");
+  }
+}
+
+async function runOptionalToolsStep() {
+  // Skip on platforms we don't have install commands for.
+  const platform = process.platform === "darwin" ? "macos"
+                 : process.platform === "linux" ? "linux"
+                 : null;
+  if (!platform) {
+    return;
+  }
+
+  // On macOS, anything that uses brew needs brew on PATH.
+  if (platform === "macos") {
+    if (!ensureBrewOnPath()) {
+      console.log("\n  ℹ️  Skipping optional tools step — Homebrew not found.");
+      console.log("     Install brew from https://brew.sh and re-run 'alvin-bot setup' to revisit.");
+      return;
+    }
+  }
+
+  console.log(`\n━━━ Optional capability tools ━━━\n`);
+  console.log("These CLIs significantly expand what skills can do. All optional — skip");
+  console.log("now and run 'alvin-bot setup' later to revisit. Already-installed tools");
+  console.log("are skipped automatically.\n");
+
+  const states = OPTIONAL_TOOLS.map(t => ({ ...t, installed: t.check() }));
+  states.forEach((t, i) => {
+    const mark = t.installed ? "✓" : " ";
+    console.log(`  [${String(i + 1).padStart(2)}] ${mark} ${t.name}`);
+    console.log(`         ${t.desc}`);
+  });
+  console.log(`\n  ✓ = already installed (will be skipped)\n`);
+
+  const ans = (await ask("  Install which? Comma-separated numbers, [a]ll missing, [n]one [n]: ")).trim().toLowerCase();
+
+  let selected = [];
+  if (ans === "" || ans === "n" || ans === "none") {
+    console.log("  Skipped — no tools installed this round.\n");
+    return;
+  } else if (ans === "a" || ans === "all") {
+    selected = states.filter(t => !t.installed);
+  } else {
+    const indices = ans.split(",").map(s => parseInt(s.trim(), 10)).filter(n => Number.isFinite(n));
+    selected = indices.map(n => states[n - 1]).filter(t => t && !t.installed);
+  }
+
+  if (selected.length === 0) {
+    console.log("  Nothing to install — every pick was either invalid or already present.\n");
+    return;
+  }
+
+  const installed = [];
+  const failed = [];
+  for (const tool of selected) {
+    // Linux-only fallbacks: skip if a hard prereq is missing.
+    if (platform === "linux" && tool.skipOnLinuxIf && !hasCommand(tool.skipOnLinuxIf)) {
+      console.log(`\n  ⚠️  Skipping ${tool.name} — needs '${tool.skipOnLinuxIf}' which isn't installed.`);
+      failed.push({ tool, reason: `missing prerequisite: ${tool.skipOnLinuxIf}` });
+      continue;
+    }
+    console.log(`\n📦 Installing ${tool.name}...`);
+    try {
+      if (typeof tool.install === "function") {
+        tool.install();
+      } else if (typeof tool.install === "object" && tool.install[platform]) {
+        execSync(tool.install[platform], { stdio: "inherit" });
+      } else {
+        console.log(`  ⚠️  No install command for ${platform}. Skipping.`);
+        failed.push({ tool, reason: `no install method for ${platform}` });
+        continue;
+      }
+      installed.push(tool);
+      console.log(`  ✅ ${tool.name} installed.`);
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.log(`  ❌ ${tool.name} install failed: ${msg.split("\n")[0]}`);
+      console.log(`     Bot setup will continue — retry this tool later with its native install command.`);
+      failed.push({ tool, reason: "install command failed" });
+    }
+  }
+
+  console.log("");
+  if (installed.length) {
+    console.log(`  ✅ Installed: ${installed.map(t => t.name).join(", ")}`);
+  }
+  if (failed.length) {
+    console.log(`  ⚠️  Skipped/failed: ${failed.map(f => f.tool.name).join(", ")}`);
+  }
+}
+
 // ── Offline mode: Ollama + Gemma 4 E4B ─────────────────────────────────────
 
 /**
@@ -1197,6 +1428,11 @@ async function setup() {
     console.log("  ✅ CLAUDE.md initialized from example");
   }
 
+  // ── Optional capability tools (curated list of useful CLIs) ──────────────
+  // Offered after the core setup (Telegram + AI provider) is complete so the
+  // user always gets a working bot first — tool installs are pure upside.
+  await runOptionalToolsStep();
+
   // ── Build (only for local/dev installs — global npm installs already have dist/)
   const isGlobalInstall = !existsSync(resolve(process.cwd(), "tsconfig.json"));
   if (!isGlobalInstall) {
@@ -1926,6 +2162,23 @@ switch (cmd) {
   case "doctor":
     doctor().catch(console.error);
     break;
+  case "tools": {
+    const sub = process.argv[3] || "list";
+    if (sub === "list" || sub === "ls" || sub === "status") {
+      listOptionalTools();
+    } else if (sub === "install") {
+      runOptionalToolsStep().then(() => closeRL()).catch(err => {
+        console.error(err);
+        closeRL();
+      });
+    } else {
+      console.log("Usage: alvin-bot tools <list|install>");
+      console.log("");
+      console.log("  list     — Show installed / missing optional tools.");
+      console.log("  install  — Interactive menu to install missing tools.");
+    }
+    break;
+  }
   case "update":
     update().catch(console.error);
     break;
@@ -2288,6 +2541,7 @@ ${t("cli.commands")}
   doctor    ${t("cli.doctorDesc")}
   audit     Security health check (permissions, secrets, config)
   search    Search your assets, memories, and skills
+  tools     List / install optional capability tools (ffmpeg, pandoc, …)
   browser   Manage bot-owned Chromium (start/stop/goto/shot/doctor)
   update    ${t("cli.updateDesc")}
   start     ${t("cli.startDesc")} (background via PM2)

package/install.sh

@@ -54,22 +54,111 @@ check_git() {
   ok "Git found: $(git --version)"
 }
 
-check_node() {
-  if ! command -v node &>/dev/null; then
-    fail "Node.js is not installed (>= $MIN_NODE_VERSION required).
-    Install via: https://nodejs.org or
-    macOS:  brew install node@22
-    Linux:  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs"
+# Is this shell interactive enough to prompt the user?
+is_interactive() {
+  [ -t 0 ] && [ -t 1 ]
+}
+
+# Ensure Homebrew is available on macOS. Offers to auto-install via the
+# official curl|bash sequence. A no-op on non-macOS systems.
+ensure_brew() {
+  [ "$OS" = "macOS" ] || return 0
+  if command -v brew &>/dev/null; then
+    ok "Homebrew found: $(brew --version | head -1)"
+    return 0
+  fi
+  warn "Homebrew is not installed."
+  if ! is_interactive; then
+    fail "Non-interactive shell — cannot prompt. Install Homebrew manually: https://brew.sh"
   fi
+  echo ""
+  read -r -p "  Install Homebrew automatically? [Y/n] " ans
+  case "${ans:-Y}" in
+    [Yy]*)
+      info "Installing Homebrew (the official installer may prompt for sudo)..."
+      # NONINTERACTIVE=1 tells brew's installer to skip the ENTER-to-confirm
+      # pause — the user already opted in here.
+      NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" \
+        || fail "Homebrew install failed. See https://brew.sh for manual instructions."
+      # Add brew to PATH for the remainder of this script.
+      if [ -x /opt/homebrew/bin/brew ]; then
+        eval "$(/opt/homebrew/bin/brew shellenv)"
+      elif [ -x /usr/local/bin/brew ]; then
+        eval "$(/usr/local/bin/brew shellenv)"
+      fi
+      ok "Homebrew installed."
+      ;;
+    *)
+      fail "Cannot continue without Homebrew. Install manually: https://brew.sh"
+      ;;
+  esac
+}
 
-  local node_ver
-  node_ver=$(node -v | sed 's/^v//' | cut -d. -f1)
-  if [ "$node_ver" -lt "$MIN_NODE_VERSION" ]; then
-    fail "Node.js >= $MIN_NODE_VERSION required, but found v$(node -v). Please upgrade."
+# Ensure Node.js >= MIN_NODE_VERSION. Offers to install via brew (macOS) or
+# NodeSource (Debian/Ubuntu) if missing or too old. Falls back to a clear
+# manual-install message on unsupported platforms.
+ensure_node() {
+  if command -v node &>/dev/null; then
+    local node_ver
+    node_ver=$(node -v | sed 's/^v//' | cut -d. -f1)
+    if [ "$node_ver" -ge "$MIN_NODE_VERSION" ]; then
+      ok "Node.js found: $(node -v)"
+      return 0
+    fi
+    warn "Node.js v$node_ver is too old (need >= $MIN_NODE_VERSION)."
+  else
+    warn "Node.js is not installed."
   fi
-  ok "Node.js found: $(node -v)"
+
+  if ! is_interactive; then
+    fail "Non-interactive shell — install Node >= $MIN_NODE_VERSION manually: https://nodejs.org"
+  fi
+
+  case "$OS" in
+    macOS)
+      ensure_brew
+      echo ""
+      read -r -p "  Install Node via Homebrew? [Y/n] " ans
+      case "${ans:-Y}" in
+        [Yy]*)
+          info "Installing Node (latest LTS via brew)..."
+          brew install node || fail "brew install node failed."
+          ok "Node installed: $(node -v)"
+          ;;
+        *)
+          fail "Cannot continue without Node. Install manually: https://nodejs.org"
+          ;;
+      esac
+      ;;
+    Linux|WSL)
+      if command -v apt-get &>/dev/null; then
+        echo ""
+        warn "About to install Node 22 from the official NodeSource repo. This needs sudo."
+        read -r -p "  Continue? [Y/n] " ans
+        case "${ans:-Y}" in
+          [Yy]*)
+            info "Adding NodeSource repo..."
+            curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - \
+              || fail "NodeSource setup failed."
+            info "Installing nodejs..."
+            sudo apt-get install -y nodejs || fail "apt-get install nodejs failed."
+            ok "Node installed: $(node -v)"
+            ;;
+          *)
+            fail "Cannot continue without Node. Install manually: https://nodejs.org"
+            ;;
+        esac
+      else
+        fail "Auto-install on Linux only supports apt-based distros. Install Node manually: https://nodejs.org"
+      fi
+      ;;
+    *)
+      fail "Cannot bootstrap Node on $OS — install manually."
+      ;;
+  esac
 }
 
+# npm comes bundled with node, but verify just in case.
 check_npm() {
   if ! command -v npm &>/dev/null; then
     fail "npm is not installed. It should come with Node.js — please reinstall Node."
@@ -136,7 +225,7 @@ main() {
 
   detect_os
   check_git
-  check_node
+  ensure_node
   check_npm
 
   echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.22.3",
+  "version": "4.23.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",