alvin-bot 4.22.2 → 4.23.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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
+
+- **Codex CLI provider:** close stdin after spawn so `codex exec` returns immediately. The provider opened stdin as a pipe but never sent EOF — `codex exec` then printed `Reading additional input from stdin...` and blocked until the 120 s spawn timeout, which surfaced on the chat side as "no reply" / empty Telegram messages whenever a user picked Codex CLI as their AI provider. Single-line fix (`proc.stdin.end()`) plus an explanatory comment. ([#1](https://github.com/alvbln/Alvin-Bot/pull/1))
+
+### macOS UX: surface Full Disk Access gaps under launchd ([#2](https://github.com/alvbln/Alvin-Bot/pull/2))
+
+When the bot runs as a LaunchAgent, macOS TCC binds permissions to the `node` binary's real Cellar path. Anything the bot spawns (Codex CLI, file-reading skills, plugins touching `~/Documents`/`~/Desktop`) inherits that identity, and without Full Disk Access on `node` those reads silently fail — no dialog appears under launchd. Fresh public users were hitting this without knowing what was going on; the failure mode (spawned tools producing empty output) looked like a bot bug.
+
+- **`alvin-bot launchd install`** now detects FDA after a successful install and either confirms it's granted or prints a prominent warning with: the exact Cellar path to add (resolved via `realpathSync`), the `open "x-apple.systempreferences:..."` command for the right pane, the `launchctl kickstart` command to apply the grant, and a heads-up that `brew upgrade node` invalidates the grant (TCC binds to the versioned Cellar path).
+- **`alvin-bot doctor`** gains a "macOS permissions" section that shows FDA status and how to fix — useful after `brew upgrade node` rolls forward to a new Cellar path and the old grant becomes stale.
+- **README** "A note on permission prompts" is extended with the launchd/FDA caveat, linking to the macOS Setup Guide PDF.
+
 ## [4.22.2] — 2026-05-11
 
 ### Docs

package/README.md

@@ -68,6 +68,8 @@ Free AI providers available — no credit card needed. **Privacy-first?** Pick t
 
 The first time Alvin reaches for a new tool — a shell command, a file read, a web fetch — you may see a permission prompt from the underlying agent runtime asking whether to allow it. Those prompts come from Alvin himself, not from a third party. Approving one expands what he can do for you autonomously; denying keeps the scope narrow. The more you allow, the more capable and hands-off he becomes — you stay in control either way, and you can always revoke a permission later.
 
+**macOS only — one extra step under launchd.** If you install Alvin as a background service (`alvin-bot launchd install`), macOS won't be able to show you those permission dialogs interactively anymore. To let the bot and anything it spawns (Codex CLI, file-reading skills) actually read your files, grant **Full Disk Access** to `node` once: System Settings → Privacy & Security → Full Disk Access → **+** → add `/opt/homebrew/Cellar/node/<version>/bin/node` (find the exact path with `readlink -f "$(which node)"`). `alvin-bot launchd install` and `alvin-bot doctor` will both detect and remind you with the exact path. After `brew upgrade node` you'll need to re-grant, because TCC binds to the versioned Cellar path. The printable [macOS Setup Guide PDF](https://github.com/alvbln/Alvin-Bot/releases/latest/download/Alvin-Bot-macOS-Setup-Guide.pdf) covers this end-to-end.
+
 ### 📘 First-time setup walkthroughs
 
 Step-by-step printable PDF guides:

package/bin/cli.js

@@ -17,7 +17,7 @@
  */
 
 import { createInterface } from "readline";
-import { existsSync, writeFileSync, readFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "fs";
+import { existsSync, writeFileSync, readFileSync, mkdirSync, copyFileSync, readdirSync, statSync, accessSync, realpathSync, constants as fsConstants } from "fs";
 import { resolve, join } from "path";
 import { homedir } from "os";
 import { execSync } from "child_process";
@@ -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) {
@@ -1515,6 +1751,21 @@ async function doctor() {
     console.log(`  ${hasChrome ? "✅" : "⚠️ "} WhatsApp (Chrome: ${hasChrome ? "found" : "not found"})`);
   }
 
+  // ── macOS permissions (TCC) ────────────────────────────────────────────
+  if (process.platform === "darwin") {
+    console.log("\n  macOS permissions:");
+    const fda = checkMacosFullDiskAccess(process.execPath);
+    if (fda.hasFDA) {
+      console.log(`  ✅ Full Disk Access — granted to ${fda.realNodePath}`);
+    } else {
+      console.log(`  ⚠️  Full Disk Access NOT granted to node (${fda.realNodePath})`);
+      console.log(`     Spawned tools (codex CLI, file-reading skills) may silently fail`);
+      console.log(`     to read protected directories under launchd. To fix:`);
+      console.log(`       open "${fda.paneUrl}"`);
+      console.log(`     and add the path above with the "+" button.`);
+    }
+  }
+
   console.log("");
 }
 
@@ -1557,6 +1808,57 @@ async function version() {
 
 // ── LaunchAgent helpers (macOS only) ────────────────────────────────────────
 
+/**
+ * Inspect the macOS Full Disk Access (TCC) state for the node binary that
+ * the bot will run under.
+ *
+ * Background: macOS TCC grants permissions to specific binary paths, not to
+ * user accounts. When `alvin-bot` runs under launchd, the bot process is
+ * `node` from Homebrew (e.g. /opt/homebrew/Cellar/node/<version>/bin/node).
+ * Any child process the bot spawns — `codex`, `ripgrep`, plugins reading
+ * ~/Documents, the file-manager skill — inherits the parent's TCC identity.
+ * If `node` doesn't have Full Disk Access, those children silently fail to
+ * read protected directories (no dialog appears under launchd).
+ *
+ * Heuristic for "FDA granted": try to read `~/Library/Mail`, which lives in
+ * the TCC-protected user-data quarantine. Successful read ⇒ FDA is on.
+ * This matches `src/services/sudo.ts:getSudoStatus()`.
+ *
+ * Returns { realNodePath, hasFDA, panEUrl, settingsCommand } so callers can
+ * print actionable guidance.
+ */
+function checkMacosFullDiskAccess(nodePath) {
+  if (process.platform !== "darwin") {
+    return { skipped: true };
+  }
+
+  // Resolve symlinks — TCC tracks the real binary path, not the symlink.
+  // /opt/homebrew/bin/node is typically a symlink into the Cellar.
+  let realNodePath = nodePath;
+  try {
+    realNodePath = realpathSync(nodePath);
+  } catch {
+    // Fall back to the symlink path if resolution fails.
+  }
+
+  let hasFDA = false;
+  try {
+    accessSync(resolve(homedir(), "Library", "Mail"), fsConstants.R_OK);
+    hasFDA = true;
+  } catch {
+    // Either Mail isn't there (very rare) or FDA is missing. Default to
+    // "missing" — false negatives just trigger a warning the user can ignore.
+    hasFDA = false;
+  }
+
+  return {
+    skipped: false,
+    realNodePath,
+    hasFDA,
+    paneUrl: "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles",
+  };
+}
+
 /**
  * Render the launchd plist that runs `node dist/index.js` as a per-user
  * agent. Inherits the GUI login session so the macOS Keychain is
@@ -1726,6 +2028,40 @@ async function launchdInstall() {
     console.log("");
     console.log("💡 pm2 still has other projects running — leaving it installed.");
   }
+
+  // ── Full Disk Access reminder ────────────────────────────────────────────
+  //
+  // Under launchd, the bot has no foreground Terminal to inherit TCC from.
+  // Anything it spawns (codex CLI, file-reading skills, etc.) needs `node`
+  // itself to have Full Disk Access — otherwise reads silently fail.
+  const fda = checkMacosFullDiskAccess(nodePath);
+  if (!fda.skipped && !fda.hasFDA) {
+    console.log("");
+    console.log("⚠️  Full Disk Access not granted to node.");
+    console.log("");
+    console.log("   Under launchd, the bot can't ask for permission dialogs interactively.");
+    console.log("   Without FDA, anything the bot spawns (codex CLI, file-reading skills,");
+    console.log("   ~/Documents access, …) will silently fail to read protected files.");
+    console.log("");
+    console.log("   Grant once: System Settings → Privacy & Security → Full Disk Access → +");
+    console.log("   Then add this exact path (⌘⇧G to paste it):");
+    console.log("");
+    console.log(`      ${fda.realNodePath}`);
+    console.log("");
+    console.log("   Open the right pane now:");
+    console.log(`      open "${fda.paneUrl}"`);
+    console.log("");
+    console.log("   After granting, restart the bot to pick up the new permission:");
+    console.log(`      launchctl kickstart -k gui/$UID/${label}`);
+    console.log("");
+    console.log("   Note: re-grant is required after `brew upgrade node` — TCC binds to");
+    console.log("   the Cellar version path, which changes when node is upgraded.");
+  } else if (!fda.skipped && fda.hasFDA) {
+    console.log("");
+    console.log("✅ Full Disk Access already granted to node — spawned tools can read");
+    console.log(`   protected files. (Granted path: ${fda.realNodePath})`);
+  }
+
   process.exit(0);
 }
 
@@ -1826,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;
@@ -2188,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/dist/providers/codex-cli-provider.js

@@ -91,6 +91,12 @@ export class CodexCLIProvider {
                 timeout: 120_000,
                 env: { ...process.env, NO_COLOR: "1" },
             });
+            // Close stdin so `codex exec` doesn't wait for additional input — the
+            // prompt is passed as a positional arg, no stdin payload follows.
+            // Without this, codex prints "Reading additional input from stdin..."
+            // and blocks until the 120s timeout, causing the bot to return
+            // "keine Antwort" / empty replies on the chat side.
+            proc.stdin.end();
             let stdout = "";
             let stderr = "";
             proc.stdout.on("data", (data) => {

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.2",
+  "version": "4.23.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",