Add DB-backed Promo Manager, Content Drops, SSHV improvements, admin UI enhancements and tests

RUNEWAGER_FUNCTIONALITY_MAP.md

@@ -77,11 +77,11 @@ Navigation is driven by inline menus plus command aliases. Persistent user/admin
 - Content Drops manager shortcut
 
 ### Admin category menus
-- `admin_cat_giveaway`: start/test/status.
-- `admin_cat_promo`: full promo manager actions + guide.
-- `admin_cat_system`: health/version/verify/setup/backup/admin mode/testall/sshv.
-- `admin_cat_tests`: bug tools + test tools + sshv shortcut.
-- `admin_cat_support`: bug report management shortcuts.
+- `admin_cat_giveaway`: start/test/status + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
+- `admin_cat_promo`: full promo manager actions + guide + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
+- `admin_cat_system`: health/version/verify/setup/backup/admin mode/testall/sshv + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
+- `admin_cat_tests`: bug tools + test tools + sshv shortcut + return navigation controls.
+- `admin_cat_support`: bug report management shortcuts + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
 
 ### Restrictions
 - All above require `requireAdmin(ctx)`.
@@ -157,14 +157,15 @@ Restrictions:
 
 ## 11. User Help Booklet
 
-- Multi-page booklet with pagination callbacks.
+- Multi-page booklet with pagination callbacks (`help_page_<n>`), including safe page-to-page transitions.
 - Covers: overview, account setup, promo/bonus usage, giveaways/community, support.
-- Back/menu buttons included on each page.
+- Navigation exits: back/menu controls on each page; settings submenu now also includes explicit cancel exit (`to_main_menu`).
 
 ## 12. Admin Help Booklet
 
 - Admin page includes admin command references and points operators to dashboard categories.
 - Bugs/tests/system-heavy workflows are now surfaced in dashboard menus (Tests & Bugs / System Tools) to reduce command overload.
+- Admin category submenus explicitly provide `Admin Dashboard` return plus `Main Menu`/`Cancel` safety exits to avoid dead-end navigation.
 
 ## 13. Full Command Index (User + Admin)
 
@@ -321,6 +322,7 @@ Admin starts wizard (gwiz)
 
 - 2026-02-26: Added repo-wide baseline docstrings to named function declarations (runtime, helper, and test modules) and re-verified command/callback coverage.
 - 2026-02-26: Re-verified removal of `/language` command/callback surface, reran smoke/full tests, and synchronized agent-contract wording in `CLAUDE.md` with map-first/update-map/verify requirements.
+- 2026-02-26: Completed a menu-integrity pass by adding explicit `Main Menu` + `Cancel` exits to admin category keyboards and settings submenu, then revalidated smoke/full tests.
 
 ## 25. AI Coder Contract Requirements
 

index.js

@@ -3082,6 +3082,7 @@ function settingsKeyboard(user) {
     [Markup.button.callback(quickLabel, 'settings_toggle_quick_commands')],
     [Markup.button.callback(tooltipLabel, 'settings_toggle_tooltips')],
     [Markup.button.callback('⬅️ Back to Menu', 'to_main_menu')],
+    [Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -3166,6 +3167,7 @@ function adminStatsKeyboard() {
       Markup.button.callback('♾️ Lifetime', 'admin_stats_lifetime'),
     ],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -3195,6 +3197,7 @@ function adminGiveawayToolsKeyboard() {
     [Markup.button.callback('🧪 Test Giveaway', 'admin_cmd_testgiveaway')],
     [Markup.button.callback('📊 Giveaway Status', 'admin_cmd_giveaway_status')],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -3232,6 +3235,7 @@ function adminPromoToolsKeyboard() {
     [Markup.button.callback('📣 Announcements', 'admin_cmd_announce_start')],
     [Markup.button.callback('💡 Content Drops', 'admin_cmd_tips_dashboard')],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -3263,6 +3267,7 @@ function adminUserToolsKeyboard() {
     [Markup.button.callback('♻️ Reset Bonus', 'w30_admin_reset')],
     [Markup.button.callback('📋 Pending Bonuses', 'w30_admin_pending')],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -3298,6 +3303,7 @@ function adminSystemToolsKeyboard(user = null) {
     [Markup.button.callback('💾 Backup State', 'admin_backup_action')],
     [Markup.button.callback(toggleLabel, 'admin_cmd_mode_toggle')],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -3327,6 +3333,7 @@ function adminSupportToolsKeyboard() {
     [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt')],
     [Markup.button.callback('📤 Export Bugs', 'admin_cmd_exportbugs')],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -4211,6 +4218,26 @@ function escapeMarkdownFull(text) {
 
  */
 
+/**
+
+ * ensureDataDir 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 ensureDataDir() {
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
 }
@@ -7802,63 +7829,7 @@ function adminTestsToolsKeyboard() {
     [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt'), Markup.button.callback('🧪 Test Content Drop', 'admin_cmd_tiptest')],
     [Markup.button.callback('📟 Open SSHV Console', 'sshv_open')],
     [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
-  ]);
-}
-
-bot.action('admin_cat_tests', async (ctx) => {
-  if (!requireAdmin(ctx)) return;
-  await ctx.answerCbQuery();
-  await replaceCallbackPanel(ctx,
-    `🧪 *Tests & Bug Tools*
-
-Use this menu for diagnostics, bug workflows, and test sends.
-
-• TestAll = full sanity check
-• Test Giveaway = simulated giveaway flow
-• Test Content Drop = sends one random drop to current target
-• SSHV = VPS console tools`,
-    { parse_mode: 'Markdown', ...adminTestsToolsKeyboard() },
-  );
-});
-
-
-/**
-
-
- * adminTestsToolsKeyboard 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 adminTestsToolsKeyboard() {
-  return Markup.inlineKeyboard([
-    [Markup.button.callback('🧪 Run TestAll', 'admin_cmd_testall'), Markup.button.callback('🎁 Test Giveaway', 'admin_cmd_testgiveaway')],
-    [Markup.button.callback('🐛 View Bug Reports', 'admin_cmd_viewbugs'), Markup.button.callback('📤 Export Bugs', 'admin_cmd_exportbugs')],
-    [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt'), Markup.button.callback('🧪 Test Content Drop', 'admin_cmd_tiptest')],
-    [Markup.button.callback('📟 Open SSHV Console', 'sshv_open')],
-    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
+    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
   ]);
 }
 
@@ -8365,26 +8336,6 @@ bot.action('menu_giveaways', async (ctx) => {
   await sendGiveawayListPage(ctx, 1);
 });
 
-/**
-
- * sendGiveawayListPage 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.
-
- */
-
 /**
 
  * sendGiveawayListPage executes its scoped Runewager logic and participates in menu/command or utility flow composition.