Claude/plan v3 deployment vp mpw

RUNEWAGER_FUNCTIONALITY_MAP.md

@@ -1,6 +1,6 @@
 # RUNEWAGER_FUNCTIONALITY_MAP.md
 
-_Last audited: 2026-02-28 (v3.1 pass)_
+_Last audited: 2026-03-04 (/runewager-audit pass — 0 critical, 0 warnings after fix)_
 _Source of truth files: `index.js`, `test/*.test.js`, scripts under `scripts/`, deployment/runtime docs in repo root._
 
 ---
@@ -288,10 +288,14 @@ Pending-action timeout handling is enforced in the text input router: each pendi
 ## 22. Internal Utilities & Shared Modules
 
 Repo modules:
-- `index.js` main app.
+- `index.js` main app (15,148 lines after v3.1 merge).
+- `telegramSafe.js` — rate-limited Telegram API wrapper; patches `bot.telegram` on init.
+- `rateLimiter.js` — global (~28 req/sec) + per-chat (1 msg/sec) queue enforcer.
+- `backend.js` — companion HTTP service on port 3001: autofix webhook, admin bridge, `/health/full`.
 - `promo-message.js` promo copy helper.
-- `scripts/*.sh` deployment/runtime ops (backup, restore, smoke, rollback, diagnostics).
+- `scripts/*.sh` deployment/runtime ops (backup, restore, smoke, rollback, diagnostics, redeploy, cpu-guard).
 - `test/*.test.js` smoke/unit/runtime tests.
+- `runewager-endpoint.service` — systemd unit for `backend.js` (separate from `runewager.service`).
 
 Key shared helper families in `index.js`:
 - Markdown escape helpers.
@@ -402,6 +406,8 @@ Mandatory rules for any AI agent touching this repo:
 - 2026-02-27: Added QA tester scaffolding (`qa/context/bot_capabilities.json`, `qa/context/repo_info.json`, `qa/state/provider_status.json`, `qa/README_QA.md`), with runtime refresh via `/qa_*` commands and 10-minute provider cooldown reset.
 - 2026-02-27: Hardened SSHV Run prompt flow so admin text in private DM executes against active SSHV sessions if pending state desynchronizes.
 - 2026-02-28: v3.1 — added group command guard middleware (`GROUP_PASSTHROUGH_COMMANDS` + `bot.use` interceptor); added `onboardingProgressBar()` and progress header on each onboarding step prompt (auto-deletes after 8s); added one-time onboarding completion card (tracked via `user.onboarding.completionCardShown`); added `🔗 Group Linking` to Admin System Tools keyboard (`admin_sys_group_linking` callback with back-to-system-tools navigation).
+- 2026-03-04: Merged main branch additions — `telegramSafe.js` (global rate-limit patch via `telegramSafe.init(bot)`), `rateLimiter.js` (per-chat + global Telegram API rate limiter), `backend.js` (companion HTTP service on port 3001, `runewager-endpoint.service` systemd unit), updated `prod-run.sh`, `scripts/runewager_redeploy.sh`, `scripts/rw_cpu_guard.sh`.
+- 2026-03-04: /runewager-audit — 17-phase full audit. Findings: 0 critical, 1 warning resolved (dead `adminKeyboard()` function removed — legacy promo keyboard with no callers). Auto-fix applied. 60/60 tests pass post-fix.
 - 2026-03-01: Created `docs/` feature documentation system — 15 per-feature `.md` files, central `docs/INDEX.md` with full callback + pending-action cross-reference, and `docs/TODO_FUNCTIONALITY_UPGRADE.md` tracking 14 open upgrade/stale-menu items. Future Claude sessions must consult `docs/INDEX.md` first, then the relevant feature `.md`, before reading `index.js`.
 - 2026-03-01: Phase implementation — resolved T-01/T-02/T-03/T-15 from TODO list. (1) Walkthrough: `sendWalkthroughStep()` upgraded with `clearOldMenus()`, Back disabled on step 1, Finish on last step, `walk_done` on last step returns to main menu. New doc: `16-walkthrough.md`. (2) Menu stacking: `clearOldMenus()` added to `sendOnboardingReferralPrompt`, `renderSshvConsole`, `renderGroupLinkingTools`, `tips_cmd_edit`, `tips_cmd_remove`. (3) Tooltip view: `tips_cmd_view` selector + `tip_view_{id}` handler with Prev/Next/Edit/Toggle/Delete/Back/AdminMenu — "👁 View Tooltip" button added to dashboard. (4) Broadcast failures: 500-item cap removed; all failures logged via `adminLog()`; `/broadcast_failed` shows chunks of 30 with overflow note; >20% failure rate triggers admin DM warnings. PR comments fixed: `add_tooltip.sh` array validation hardened; `docs/12-group-linking.md` entry-point callback corrected to `admin_sys_group_linking`; merge conflicts (PRs #112-114) resolved keeping SIGTERM→SIGKILL safety improvements. 60/60 tests pass.
 - 2026-02-28: PR #112 review + audit pass — fixed 10 issues: (R1) `await_tip_import_batch` dedicated pending type with JSON-array router; (R2) `generate_tooltips.sh` command-substitution pollution fixed via `RUNEWAGER_APP` env var; (R3) `add_tooltip.sh` shell-injection fixed via `TOOLTIP_TEXT_ENV`/`TOOLTIP_TMP_FILE` env vars and `<<'EOF'`; (R4) `catchAllCases` test extended with multiline patterns + `CATCH_ALL_CORES` updated; (R5) `extractCommandHandlerNames` test extended with `let`/`var`/no-semicolon fixtures; (R6) typo "auto-deletes 8s" → "auto-deletes after 8s"; (A1) dead `buildGiveawayAnnouncementText(giveaway,remainingStr)` removed; (A2) simplified `buildGiveawayAnnouncementKeyboard` with wrong callback removed; (A3+A4) duplicate `bot.action('admin_cat_system')` and `bot.action('admin_cat_support')` first registrations removed. All 60 tests pass.

index.js

@@ -2944,38 +2944,6 @@ function linkPrefKeyboard() {
   ]);
 }
 
-/**
-
- * adminKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.
-
- * Parameters: See the function signature for exact argument names and accepted values.
-
- * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
-
- * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
-
- * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
-
- * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
-
- * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
-
- * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
-
- */
-
-function adminKeyboard() {
-  return Markup.inlineKeyboard([
-    [Markup.button.callback('📄 View Promo', 'admin_view')],
-    [Markup.button.callback('✏️ Edit Promo Code', 'admin_edit_code')],
-    [Markup.button.callback('💰 Edit SC Amount', 'admin_edit_amount')],
-    [Markup.button.callback('🔢 Edit Claim Limit', 'admin_edit_limit')],
-    [Markup.button.callback('⏸ Pause Promo', 'admin_pause')],
-    [Markup.button.callback('▶️ Unpause Promo', 'admin_unpause')],
-    [Markup.button.callback('🗑 Remove Promo', 'admin_remove')],
-    [Markup.button.callback('📢 Push Update to Users', 'admin_broadcast')],
-  ]);
-}
 
 /**
 

prod-run.sh

@@ -499,11 +499,18 @@ if [[ -n "$PID" ]]; then
     say "Safe restart of running bot (PID: $PID)"
 fi
 if command -v systemctl >/dev/null 2>&1 && [[ -f "$SERVICE_FILE" ]]; then
-    systemctl restart "${APP_NAME}.service" 2>/dev/null || true
+    if ! systemctl restart "${APP_NAME}.service" 2>/dev/null; then
+        warn "systemctl restart failed — falling back to manual kill+nohup"
+        [[ -n "$PID" ]] && kill "$PID" 2>/dev/null || true
+        sleep 1
+        nohup node "$PROJECT_DIR/index.js" >> "$MAIN_LOG" 2>> "$ERROR_LOG" < /dev/null &
+        disown || true
+        say "Bot started via nohup fallback"
+    fi
 else
     [[ -n "$PID" ]] && kill "$PID" 2>/dev/null || true
     nohup node "$PROJECT_DIR/index.js" >> "$MAIN_LOG" 2>> "$ERROR_LOG" < /dev/null &
-    disown
+    disown || true
 fi
 # Always refresh PID after restart so step 11 knows the live process
 sleep 3
@@ -546,17 +553,18 @@ fi
 
 is_port_listening "$HEALTH_PORT" && PORT_STATUS="listening"
 
-# Telegram admin notification
+# Telegram admin notification (plain text — no parse_mode to avoid Markdown rendering issues
+# with unescaped log content or special chars in env values)
 _ADMIN_IDS="$(read_env_value ADMIN_IDS || true)"
 _BOT_TOKEN="$(read_env_value TELEGRAM_BOT_TOKEN || true)"
 if [[ -n "$_BOT_TOKEN" && -n "$_ADMIN_IDS" ]]; then
-    _REPORT="$(( tail -n 30 "$MAIN_LOG"; tail -n 20 "$ERROR_LOG" ) 2>/dev/null \
-        | sed 's/"/\\"/g' | head -c 3500)"
+    _HEALTH_LABEL="$( [[ "$HEALTH_STATUS" == healthy ]] && echo OK || echo FAILED )"
+    _MSG="Deploy complete: Health ${_HEALTH_LABEL} | Port: ${HEALTH_PORT} | PID: ${PID:-none} | Systemd: ${SYSTEMD_ACTIVE}"
     for _AID in ${_ADMIN_IDS//,/ }; do
         curl -s -X POST "https://api.telegram.org/bot${_BOT_TOKEN}/sendMessage" \
-            -d chat_id="$_AID" \
-            -d parse_mode="Markdown" \
-            -d text="Deploy complete: Health $( [[ "$HEALTH_STATUS" == healthy ]] && echo OK || echo FAILED) Port: $HEALTH_PORT PID: ${PID:-none}" >/dev/null 2>&1 || true
+            --data-urlencode "chat_id=${_AID}" \
+            --data-urlencode "text=${_MSG}" \
+            >/dev/null 2>&1 || true
     done
 fi
 

todolist.md

@@ -1,6 +1,6 @@
 # Runewager Bot — Improvement Task Board
 
-_Last updated: 2026-02-28 — PR #112 review fixes + codebase audit pass_
+_Last updated: 2026-03-04 — /runewager-audit pass + merge main (backend.js, rateLimiter.js, telegramSafe.js, prod-run.sh, scripts)_
 
 ---
 
@@ -11,6 +11,9 @@ _Last updated: 2026-02-28 — PR #112 review fixes + codebase audit pass_
 
 ## BUGS (confirmed code defects)
 
+- [x] **Dead code: `adminKeyboard()` function** `index.js`
+  - Fixed: 2026-03-04. Legacy promo keyboard function with no callers (belonged to removed `/admin_menu` command). Deleted entire block (JSDoc + function body). All 60 tests pass.
+
 - [x] **`gw.endsAt` / `endTime` field inconsistency** `index.js`
   - Fixed: all three occurrences replaced with `gw.endTime`; extend action now calls `resetGiveawayTimer(gw)` to re-arm the timer.
   - Also fixed `gw.winnersCount` → `gw.maxWinners` in the admin panel display.