alvin-bot 4.24.0 → 4.25.1

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.25.1] — 2026-05-13
+
+### Fixed: `alvin-bot launchd install` now persists the PM2 cleanup
+
+The launchd installer correctly called `pm2 delete alvin-bot` when migrating a previously-PM2-managed bot to launchd — but `pm2 delete` only mutates the live process list, **not** the persisted `~/.pm2/dump.pm2`. On the next login, PM2's startup script would call `pm2 resurrect`, see alvin-bot in the stale dump, and re-spawn it. The resurrected pm2-managed instance and the new launchd-managed instance then both polled Telegram with the same `BOT_TOKEN`, racking up `409 Conflict: terminated by other getUpdates request` errors until one of them crashed.
+
+The fix adds `pm2 save --force` immediately after `pm2 delete`, so the dump file reflects reality. `--force` is needed because plain `pm2 save` refuses to persist an empty list with a warning. Other PM2-managed processes (e.g. unrelated projects in the user's PM2) are preserved correctly — the save only mutates entries for alvin-bot.
+
+### How it surfaced
+
+A maintainer's local Mac that had been running alvin-bot under PM2 *before* the v4.x migration to launchd hit `409 Conflict` errors out of nowhere — turns out PM2 had been silently resurrecting alvin-bot on every reboot for months (106,000+ restart counter), invocations without args printed help and exited, PM2 restarted it instantly, the cycle continued. Today the cycle accidentally aligned with a Telegram getUpdates call, causing the conflict. Cleanup steps:
+
+```bash
+pm2 delete polyseus                      # any other PM2 entries
+pm2 save --force                         # empty dump
+launchctl unload ~/Library/LaunchAgents/pm2.alvin_de.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/pm2.alvin_de.plist
+pm2 kill
+npm uninstall -g pm2
+rm -rf ~/.pm2
+```
+
+After this patch, future users migrating from PM2 to launchd via `alvin-bot launchd install` won't accumulate the stale-dump time bomb — the cleanup is persistent immediately.
+
+### End-to-end verified on a real Apple Silicon Mac (.75)
+
+1. Reproduced the broken pre-condition: install PM2, add alvin-bot to its dump via `pm2 start … && pm2 save`. `grep -c alvin-bot ~/.pm2/dump.pm2` → 7 hits.
+2. Ran `alvin-bot launchd install` with the fix applied.
+3. Verified `grep -c alvin-bot ~/.pm2/dump.pm2` → **0 hits**. PM2 live list is also empty.
+
+The installer's output now ends with `🧹 Removed alvin-bot from pm2 and persisted (other pm2 projects left intact).` and includes a `💡 pm2 now has zero managed processes. You can remove it entirely:` hint when no other pm2 projects remain.
+
+## [4.25.0] — 2026-05-13
+
+### Auto-bootstrap media tools (yt-dlp + ffmpeg) on every setup and update
+
+`yt-dlp` and `ffmpeg` are now installed (or upgraded) automatically whenever the user runs `alvin-bot setup` or `alvin-bot update` — silently, one line of status per tool, non-fatal on failure. These are the two foundational media tools used by the transcribe / download / video-generate / voice skills and they break or need patches often enough that "whatever brew shipped last week" is materially worse than "current latest" for ordinary users.
+
+**No bundling. No redistribution.** alvin-bot shells out to the user's own system package manager (Homebrew on macOS, `pipx`/`apt` on Linux). The user remains the licensee under each tool's upstream license. License notes are recorded in `BOOTSTRAP_TOOLS` for transparency:
+
+- **yt-dlp** — Unlicense (public-domain equivalent)
+- **ffmpeg** — LGPL-2.1+ (Brew default build; no GPL-only codecs are pulled in by the default formula)
+
+### Behaviour
+
+| User action | What happens |
+|---|---|
+| `alvin-bot setup` (interactive) | At the very start, before any prompt: tries `brew install yt-dlp` + `brew install ffmpeg` (or `pipx`/`apt` on Linux) if missing, runs `brew upgrade` if already installed. One status line per tool. |
+| `alvin-bot update` | After `npm install -g` / `git pull` completes, the same bootstrap step runs — so an update of the bot also refreshes media tools. |
+| `alvin-bot setup --no-bootstrap-tools` | Skips the bootstrap step entirely. For users who want full manual control. |
+| Failure (no brew, no network, etc.) | Setup/update continues; user sees a `⚠` warning line; bot still works for everything that doesn't need media tools. |
+
+### Implementation detail that matters
+
+On macOS, `brew upgrade <pkg>` does **not** automatically refresh the formula database before checking versions — meaning a user on stale brew (haven't run `brew update` in weeks) would see "already at latest" even when newer versions exist. The bootstrap step runs `brew update --quiet` **once per session** before any brew upgrade, memoized so multiple tools share the refresh cost. Cost: 5-30 s on first invocation, zero on subsequent calls.
+
+### End-to-end verified on a real Apple Silicon Mac
+
+Two scenarios run manually after the code change:
+
+1. **Both tools present, brew formulas stale.** Bootstrap ran `brew update --quiet` + `brew upgrade yt-dlp/ffmpeg`. yt-dlp's brew-listed and upstream latest both confirmed at `2026.03.17` (verified via `brew info yt-dlp` and `yt-dlp -U`'s self-check) — code correctly reported "up-to-date". ffmpeg's pre-existing dylib-link failure (`libx265.215.dylib not found`) was incidentally fixed by `brew upgrade ffmpeg`, which is the exact kind of bit-rot the bootstrap is meant to catch.
+
+2. **yt-dlp deliberately uninstalled, run `alvin-bot update` again.** Bootstrap correctly detected `command -v yt-dlp` → not found, ran `brew install yt-dlp`, reported "installed (2026.03.17)" (note the differentiated wording vs "up-to-date" — same versioning convention as `npm install` vs `npm update`). Post-state: `/opt/homebrew/bin/yt-dlp` back and working.
+
 ## [4.24.0] — 2026-05-12
 
 ### Switch AI providers cleanly after install — new `alvin-bot provider` command

package/bin/cli.js

@@ -235,6 +235,165 @@ function hasCommand(name) {
   }
 }
 
+// ─── Auto-bootstrap media tools ───────────────────────────────────────────
+//
+// These two are universally useful for the media-related skills (transcribe,
+// download, video-generate, voice) and they break or need patches often enough
+// (yt-dlp especially — YouTube changes its extractors weekly) that "always
+// latest" is materially better than "whatever brew shipped last week".
+//
+// The installer here is NOT redistribution: we shell out to the user's own
+// system package manager (brew/apt) to install or upgrade. The user remains
+// the licensee under the tool's upstream license. License notes per tool are
+// in BOOTSTRAP_TOOLS for transparency — and `--no-bootstrap-tools` lets users
+// opt out entirely.
+//
+// Output is intentionally quiet: a single status line per tool, install output
+// only surfaces on failure. Setup-flow is never blocked by a bootstrap-tool
+// failure — the user gets a warning, the wizard continues.
+
+const BOOTSTRAP_TOOLS = [
+  {
+    cmd: "yt-dlp",
+    name: "yt-dlp",
+    license: "Unlicense (public domain equivalent)",
+    install: { macos: "brew install yt-dlp", linux: "pipx install yt-dlp" },
+    // yt-dlp ships its own `-U` self-updater but it bails out for binaries
+    // installed via brew (can't write to /opt/homebrew/). Always go through
+    // the package manager that originally installed it.
+    upgrade: { macos: "brew upgrade yt-dlp", linux: "pipx upgrade yt-dlp" },
+    // Linux fallback if pipx isn't available
+    linuxSkipIf: "pipx",
+  },
+  {
+    cmd: "ffmpeg",
+    name: "ffmpeg",
+    license: "LGPL-2.1+ (brew default; auto-install via your package manager — you remain the licensee)",
+    install: { macos: "brew install ffmpeg", linux: "sudo apt-get install -y ffmpeg" },
+    upgrade: { macos: "brew upgrade ffmpeg", linux: "sudo apt-get install --only-upgrade -y ffmpeg" },
+  },
+];
+
+// Memoized: `brew update` is slow (5-30s) but needs to run at least once
+// per session before `brew upgrade` so we get the latest formula info,
+// not whatever was cached locally weeks ago. Without this we hit the
+// "brew thinks yt-dlp is at 2026-03-17 because formula DB is stale" trap.
+let brewFormulasRefreshed = false;
+function refreshBrewFormulas() {
+  if (brewFormulasRefreshed) return;
+  if (!hasCommand("brew")) return;
+  try {
+    execSync("brew update --quiet", { stdio: "pipe", timeout: 90_000 });
+  } catch {
+    // brew update can fail transiently (rate limits, network). Non-fatal:
+    // we'll fall through with whatever cached formulas brew has.
+  }
+  brewFormulasRefreshed = true;
+}
+
+/**
+ * Detect the major package manager available for non-interactive installs.
+ * Returns "macos" (homebrew), "linux" (apt-based), or null.
+ */
+function detectPlatformPm() {
+  if (process.platform === "darwin") return "macos";
+  if (process.platform === "linux") return "linux";
+  return null;
+}
+
+/**
+ * Quietly install or upgrade a single bootstrap tool. Returns a brief status
+ * string for the caller to print. Never throws — failures are reported as
+ * { ok: false, message } so the calling step keeps going.
+ */
+function bootstrapOneTool(tool, platform) {
+  const cmdAvailable = hasCommand(tool.cmd);
+
+  // Linux-only prerequisite check (e.g. pipx for yt-dlp).
+  if (platform === "linux" && tool.linuxSkipIf && !hasCommand(tool.linuxSkipIf)) {
+    return { ok: false, message: `${tool.name} skipped — needs '${tool.linuxSkipIf}' on Linux` };
+  }
+
+  // Decide whether the install/upgrade command goes through brew on macOS.
+  // If so, refresh the formula DB once before any upgrade attempts so we
+  // don't end up running `brew upgrade` against weeks-old formula info.
+  const installCmd = tool.install[platform];
+  const upgradeCmd = tool.upgrade && tool.upgrade[platform];
+  if (platform === "macos" && (String(installCmd).startsWith("brew") || String(upgradeCmd).startsWith("brew"))) {
+    refreshBrewFormulas();
+  }
+
+  // ── Upgrade path: tool is already installed ────────────────────────────
+  if (cmdAvailable) {
+    if (!upgradeCmd) {
+      return { ok: true, message: `${tool.name} (already installed, no upgrade path on ${platform})` };
+    }
+    let beforeVersion = "";
+    try {
+      beforeVersion = execSync(`${tool.cmd} --version 2>&1 | head -1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+    } catch {}
+    try {
+      execSync(upgradeCmd, { stdio: "pipe", timeout: 120_000, encoding: "utf-8" });
+      let afterVersion = "";
+      try {
+        afterVersion = execSync(`${tool.cmd} --version 2>&1 | head -1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+      } catch {}
+      const upgraded = beforeVersion && afterVersion && beforeVersion !== afterVersion;
+      const verbInfix = upgraded ? "upgraded" : "up-to-date";
+      const versionTag = afterVersion ? ` (${afterVersion})` : "";
+      return { ok: true, message: `${tool.name} ${verbInfix}${versionTag}` };
+    } catch (err) {
+      const msg = String(err.stderr || err.message || err).split("\n")[0].slice(0, 120);
+      return { ok: true, message: `${tool.name} present (upgrade attempt failed: ${msg})` };
+    }
+  }
+
+  // ── Fresh install ──────────────────────────────────────────────────────
+  if (!installCmd) {
+    return { ok: false, message: `${tool.name} skipped — no install command for ${platform}` };
+  }
+  try {
+    execSync(installCmd, { stdio: "pipe", timeout: 240_000, encoding: "utf-8" });
+    let version = "";
+    try {
+      version = execSync(`${tool.cmd} --version 2>&1 | head -1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+    } catch {}
+    return { ok: true, message: `${tool.name} installed${version ? ` (${version})` : ""}` };
+  } catch (err) {
+    const msg = String(err.stderr || err.message || err).split("\n")[0].slice(0, 120);
+    return { ok: false, message: `${tool.name} install failed (${msg})` };
+  }
+}
+
+/**
+ * Run all bootstrap tools quietly. Used at the start of `alvin-bot setup` and
+ * in `alvin-bot update`. Skipped entirely if the caller passes
+ * `--no-bootstrap-tools`. On unsupported platforms (Windows etc.) this is a
+ * silent no-op — the user can install manually.
+ */
+async function ensureBootstrapTools(opts = {}) {
+  if (opts.skip) return;
+  const platform = detectPlatformPm();
+  if (!platform) return;
+
+  console.log("\n🎬 Setting up media tools (yt-dlp + ffmpeg)...");
+
+  // macOS needs brew on PATH — same trick as ensureBrewOnPath() uses.
+  if (platform === "macos" && !hasCommand("brew")) {
+    if (!ensureBrewOnPath()) {
+      console.log("  ⚠️  Skipping media-tool bootstrap — Homebrew not installed.");
+      console.log("      To enable: install brew from https://brew.sh and re-run setup.");
+      return;
+    }
+  }
+
+  for (const tool of BOOTSTRAP_TOOLS) {
+    const result = bootstrapOneTool(tool, platform);
+    console.log(`  ${result.ok ? "✓" : "⚠"} ${result.message}`);
+  }
+  console.log("");
+}
+
 function tryNpx(args) {
   try {
     execSync(`npx --no-install ${args}`, { stdio: "pipe", timeout: 5000 });
@@ -1405,7 +1564,7 @@ async function runPostSetupValidation(providerKey, apiKey, botToken, webPort) {
  */
 function parseSetupArgs(argv) {
   const args = {};
-  const flags = new Set(["--non-interactive", "-y", "--yes", "--skip-validation"]);
+  const flags = new Set(["--non-interactive", "-y", "--yes", "--skip-validation", "--no-bootstrap-tools"]);
   const valueFlags = [
     "--bot-token", "--allowed-users", "--primary-provider",
     "--groq-key", "--google-key", "--openai-key", "--nvidia-key",
@@ -1558,6 +1717,11 @@ async function setup() {
     return;
   }
 
+  // ── Auto-bootstrap media tools (yt-dlp + ffmpeg) ───────────────────────
+  // Runs before any prompts so the user doesn't have to wait at the end.
+  // Single-line status per tool. Failure is non-fatal — setup continues.
+  await ensureBootstrapTools({ skip: !!args["no-bootstrap-tools"] });
+
   // ── Step 1: Telegram Bot
   console.log(`\n━━━ ${t("setup.step1")} ━━━`);
   console.log(t("setup.step1.intro"));
@@ -2360,6 +2524,8 @@ async function doctor() {
 async function update() {
   console.log(`${t("update.title")}\n`);
 
+  const skipBootstrap = process.argv.includes("--no-bootstrap-tools");
+
   try {
     const isGit = existsSync(resolve(process.cwd(), ".git"));
 
@@ -2376,6 +2542,10 @@ async function update() {
       execSync("npm update alvin-bot", { stdio: "inherit" });
       console.log(`\n  ✅ ${t("update.done")}`);
     }
+
+    // Refresh bootstrap media tools (yt-dlp / ffmpeg) — keeps them in sync
+    // with the alvin-bot version that just got installed.
+    await ensureBootstrapTools({ skip: skipBootstrap });
   } catch (err) {
     console.error(`\n  ❌ ${t("update.failed")} ${err.message}`);
   }
@@ -2573,7 +2743,19 @@ async function launchdInstall() {
     if (pm2HadAlvinBot) {
       try {
         execSync("pm2 delete alvin-bot", { stdio: "pipe" });
-        console.log("🧹 Removed alvin-bot from pm2 (other pm2 projects left intact).");
+        // CRITICAL: `pm2 delete` only mutates the live process list; the
+        // persisted dump (~/.pm2/dump.pm2) keeps a stale copy. Without
+        // `pm2 save --force` here, the next time PM2 resurrects on
+        // login it will re-spawn alvin-bot from the dump — fighting with
+        // the new launchd-managed bot for the same BOT_TOKEN and racking
+        // up Telegram getUpdates 409 conflicts (six-figure restart counts
+        // in extreme cases). `--force` ensures the save runs even when
+        // the resulting list is empty (default `pm2 save` warns and
+        // skips the write on an empty list).
+        try {
+          execSync("pm2 save --force", { stdio: "pipe" });
+        } catch { /* save failed — non-fatal, user has clean live list either way */ }
+        console.log("🧹 Removed alvin-bot from pm2 and persisted (other pm2 projects left intact).");
       } catch { /* already gone */ }
     }
   } catch { /* pm2 not installed — nothing to clean up */ }

package/package.json

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