From ce26f63d71aaa061cb28ba099c0cc6f877a039c1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Apr 2026 20:52:12 +0000 Subject: [PATCH] Add ModpackChecker Flagship Product Completion Plan - Complete roadmap from current state to launch-ready - 10 phases: Modrinth auto-detection, Ignore Version, backoff logic, docs, marketing - Gemini-validated architecture and commercial strategy integrated - Launch criteria checklist (code, docs, marketing, testing, support) - Time estimates: 14-21 hours to minimum viable flagship - Support strategy placeholder for future discussion with Michael - FFG-PLAN-001 - Flagship Product Standard Chronicler #64 - Session planning for commercial launch --- .../FLAGSHIP-PRODUCT-COMPLETION-PLAN.md | 535 ++++++++++++++++++ 1 file changed, 535 insertions(+) create mode 100644 docs/tasks/modpack-version-checker/FLAGSHIP-PRODUCT-COMPLETION-PLAN.md diff --git a/docs/tasks/modpack-version-checker/FLAGSHIP-PRODUCT-COMPLETION-PLAN.md b/docs/tasks/modpack-version-checker/FLAGSHIP-PRODUCT-COMPLETION-PLAN.md new file mode 100644 index 0000000..da1f41e --- /dev/null +++ b/docs/tasks/modpack-version-checker/FLAGSHIP-PRODUCT-COMPLETION-PLAN.md @@ -0,0 +1,535 @@ +# ModpackChecker Flagship Product Completion Plan + +**Document ID:** FFG-PLAN-001 +**Created:** April 6, 2026 +**Created By:** Chronicler #64 +**Project:** Task #26 — ModpackChecker Blueprint Extension +**Status:** Pre-Launch Planning — Flagship Product Standard + +--- + +## 🎯 MISSION STATEMENT + +ModpackChecker is Firefrost Gaming's first commercial product launch. This is not just a tool — it's our reputation. First impressions on BuiltByBit determine whether we become known as "that dev who ships quality" or "that dev who overpromised." + +**We choose quality.** + +This document outlines the complete path from current state to launch-ready flagship product. + +--- + +## 📊 CURRENT STATE (April 6, 2026) + +### ✅ What's Built (Phases 1-4 Complete) +- API integrations: CurseForge, Modrinth, Technic, FTB +- Database schema: `modpack_versions` table +- Dashboard badge: UpdateBadge.tsx component +- Console widget: ModpackVersionCard.tsx component +- Admin panel: Configuration interface +- Cron job: Background version checking +- Rate limiting: 2 requests/minute per server +- 60-second TTL cache for dashboard + +### ⚠️ What's Missing (Launch Blockers) +1. **Modrinth auto-detection** — Currently manual-only, needs `versionId` → `project_id` mapping +2. **"Ignore Version" feature** — Critical UX for handling version string mismatches +3. **Backoff logic** — Prevents infinite scanning of vanilla/custom servers +4. **Commercial documentation** — Setup guide, troubleshooting, FAQ +5. **BuiltByBit listing materials** — Product description, screenshots, compatibility matrix + +### 🔧 What Works But Needs Polish +- Blueprint packaging (manual deployment steps required) +- Database migrations (need to add new columns) +- Console widget (needs "Ignore Version" button) + +--- + +## 🏗️ FLAGSHIP COMPLETION ROADMAP + +### **Phase 5: Modrinth Auto-Detection** (4-6 hours) +**Priority:** CRITICAL — Moves us from 60% to 85% market coverage + +**Architecture (Validated by Gemini):** +1. Cron reads `modrinth.index.json` from server filesystem +2. Extract `versionId` from manifest +3. Call Modrinth API: `GET /v2/version/{versionId}` +4. Response contains `project_id` — save to database +5. Use `project_id` for future version checks + +**Database Changes:** +```sql +ALTER TABLE modpack_versions + ADD COLUMN modrinth_version_id VARCHAR(50) NULL; +``` + +**Code Changes:** +- Update `CheckModpackUpdates.php` command +- Add `detectModrinth()` method to cron +- Inject `DaemonFileRepository` for file reads +- Parse `modrinth.index.json` structure +- Call Modrinth `/v2/version/{id}` endpoint + +**Testing:** +- Test on Adrenaserver (known Modrinth pack) +- Verify `project_id` extraction +- Confirm version comparison works + +**Deliverable:** Modrinth packs auto-detect without manual configuration + +--- + +### **Phase 6: "Ignore Version" Feature** (2-3 hours) +**Priority:** CRITICAL — Eliminates 90% of false-positive support tickets + +**Problem:** +- String comparison (`!==`) flags `v1.2.3-hotfix` vs `v1.2.4` as different +- User knows they're functionally equivalent +- Without ignore button → support ticket or refund + +**Solution:** +Database column + UI button that lets users dismiss version alerts + +**Database Changes:** +```sql +ALTER TABLE modpack_versions + ADD COLUMN user_ignored_version VARCHAR(50) NULL; +``` + +**Logic:** +- User clicks "Mark as Up-to-Date" in console widget +- Save current `latest_version` to `user_ignored_version` +- Badge turns green +- Badge stays green until a NEW `latest_version` appears (different from ignored version) + +**UI Changes:** +- Add button to `ModpackVersionCard.tsx` +- Button only shows when `update_available = true` +- Button label: "Mark as Up-to-Date" or "Ignore This Version" +- Add API endpoint: `POST /servers/{server}/modpack/ignore-version` + +**API Endpoint:** +```php +public function ignoreVersion(Request $request, Server $server) +{ + $modpackVersion = ModpackVersion::where('server_uuid', $server->uuid)->first(); + + $modpackVersion->update([ + 'user_ignored_version' => $modpackVersion->latest_version + ]); + + return response()->json(['success' => true]); +} +``` + +**Badge Logic Update:** +```php +// In CheckModpackUpdates command +if ($latestVersion !== $installedVersion) { + // Check if user has ignored this specific version + if ($modpackVersion->user_ignored_version === $latestVersion) { + $updateAvailable = false; // Keep badge green + } else { + $updateAvailable = true; + } +} +``` + +**Deliverable:** Users can dismiss false-positive version alerts without support tickets + +--- + +### **Phase 7: Backoff Logic for Unsupported Servers** (1-2 hours) +**Priority:** HIGH — Prevents Wings API spam for vanilla/custom servers + +**Problem:** +- Cron attempts file detection every hour +- Vanilla servers have no manifest files +- Infinite failed attempts = wasted Wings API calls + +**Solution (Gemini-Validated):** +Stop scanning servers after 3 failed attempts until user manually triggers "Force Check" + +**Database Changes:** +```sql +ALTER TABLE modpack_versions + ADD COLUMN auto_detect_failed_count INT DEFAULT 0, + ADD COLUMN last_auto_detect_attempt TIMESTAMP NULL; +``` + +**Logic:** +```php +// In CheckModpackUpdates command +if ($modpackVersion->auto_detect_failed_count >= 3) { + continue; // Skip this server in cron +} + +try { + $detected = $this->attemptAutoDetection($server); + + if ($detected) { + $modpackVersion->update([ + 'auto_detect_failed_count' => 0, + 'last_auto_detect_attempt' => now() + ]); + } else { + $modpackVersion->increment('auto_detect_failed_count'); + $modpackVersion->update(['last_auto_detect_attempt' => now()]); + } +} catch (DaemonConnectionException $e) { + // Node offline — don't count as failed detection + continue; +} +``` + +**UI Changes:** +- "Force Check" button in console widget resets `auto_detect_failed_count` +- Shows message: "Auto-detection paused after 3 failed attempts. Click to retry." + +**Deliverable:** Cron doesn't spam Wings API for unsupported servers + +--- + +### **Phase 8: Commercial Documentation** (3-4 hours) +**Priority:** CRITICAL — Reduces support tickets by 70% + +**Structure (Gemini-Validated):** + +#### **1. README.md (Overview)** +- What it does (one paragraph) +- Compatibility matrix table +- System requirements +- Quick links to other docs + +#### **2. INSTALLATION.md** +- Prerequisites checklist +- Three-command install process +- Database migration steps +- Panel restart instructions +- Verification steps + +#### **3. CONFIGURATION.md (The API Key Hub)** +**CurseForge API Key:** +- Step 1: Go to https://console.curseforge.com +- Step 2: Create application +- Step 3: Generate API key +- Step 4: Paste into Admin Panel + +**Modrinth API Key:** +- Step 1: Go to https://modrinth.com/settings/pats +- Step 2: Create Personal Access Token +- Step 3: Set scopes (read-only) +- Step 4: Paste into Admin Panel + +#### **4. HOW-IT-WORKS.md (The Tiered System)** +**Critical Section — Prevents "It's Broken" Tickets** + +Explain the three-tier detection process: + +**Tier 1: Egg Variables** (Instant, Rarely Present) +- Checks server egg for `MODPACK_PLATFORM` and `MODPACK_ID` +- Most eggs don't have these + +**Tier 2: File Detection** (Auto-Discovery, CurseForge + Modrinth) +- Reads `manifest.json` (CurseForge) or `modrinth.index.json` (Modrinth) +- Runs in background cron job (hourly) +- Requires manifest files to exist on server + +**Tier 3: Manual Configuration** (Universal Fallback) +- Console widget → "Configure Manually" button +- Works for ANY platform (FTB, Technic, ATLauncher, Custom) +- User enters platform + modpack ID once + +**Why Your Server Might Not Auto-Detect:** +1. It's a vanilla server (no modpack manifest) +2. It's a custom modpack (no manifest from supported platform) +3. It uses FTB/Technic/ATLauncher (manual config required) +4. Manifest file was deleted or moved + +#### **5. MANUAL-CONFIGURATION.md** +- When to use manual config +- How to find modpack IDs for each platform +- Step-by-step screenshots + +#### **6. TROUBLESHOOTING.md** +**Common Issues:** + +**"My badge is gray / shows 'Not Configured'"** +- Server needs manual configuration +- Click "Configure Manually" in console widget + +**"It says there's an update but I'm already on the latest version"** +- Modpack author changed naming convention +- Click "Mark as Up-to-Date" to dismiss alert + +**"I see a 429 error"** +- API rate limit hit (rare) +- Extension respects 2 req/min limit +- Wait 60 seconds and retry + +**"Auto-detection stopped working"** +- 3 failed attempts triggered backoff +- Click "Force Check" to retry +- If still failing, use manual config + +**"Server is offline/suspended but still shows old version"** +- Cron skips offline servers +- Version will update next time server is online + +#### **7. FAQ.md** +- What platforms are supported? +- Do I need API keys for all platforms? +- How often does it check for updates? +- Can I check updates manually instead of cron? +- What happens if I delete the manifest file? +- Does this work with custom modpacks? +- Can I disable auto-detection for specific servers? + +**Deliverable:** Complete documentation preventing 70% of support tickets + +--- + +### **Phase 9: BuiltByBit Listing Materials** (2-3 hours) +**Priority:** CRITICAL — Sets accurate expectations, prevents refunds + +#### **Product Description Structure:** + +**1. The Hook (One-Sentence Pitch)** +> Stop checking modpacks manually. Start managing them automatically with the industry's first dual-engine version tracker for Pterodactyl. + +**2. Value Propositions (Reframe Limitations)** +- ✅ **85%+ Instant Coverage:** Auto-detection for CurseForge & Modrinth +- ✅ **Universal Manual Fallback:** Support for ANY platform via simple ID entry +- ✅ **Dashboard Pulse:** High-visibility status integrated into server list +- ✅ **Performance First:** Passive background checks, zero panel impact + +**3. Compatibility Matrix (Top of Listing)** +``` +| Platform | Auto-Detection | Manual Config | Notes | +|-------------------|----------------|---------------|--------------------------| +| CurseForge | ✅ Yes | ✅ Yes | Uses manifest.json | +| Modrinth | ✅ Yes | ✅ Yes | Uses modrinth.index.json | +| FTB (Modern) | ❌ No | ✅ Yes | Requires FTB ID entry | +| Technic | ❌ No | ✅ Yes | Requires Slug entry | +| Custom/Vanilla | ❌ No | ✅ Yes | Requires Manual Setup | +``` + +**4. Features List** +- Automatic version checking for CurseForge & Modrinth modpacks +- At-a-glance dashboard badge showing update status +- Console widget with detailed version information +- Manual configuration for unsupported platforms +- Smart caching (60-second TTL, minimal API usage) +- Rate limiting protection (won't get your API keys banned) +- "Ignore Version" feature for handling naming convention changes +- Admin panel for API key management + +**5. Requirements** +- Pterodactyl Panel 1.12.x or higher +- Blueprint beta-2026-01 or higher +- PHP 8.3+ +- PostgreSQL database +- CurseForge API key (free) +- Modrinth API key (free) + +**6. Installation** +Three-command install via Blueprint (see documentation for details) + +**7. "Read Before You Buy" (Bottom of Listing)** +1. **Vanilla Servers:** This extension will not auto-detect vanilla Minecraft servers (no modpack manifest exists) +2. **Manifest Dependency:** Auto-detection requires `manifest.json` or `modrinth.index.json` in server root +3. **Exact String Matching:** Version comparison uses exact string matching, not semantic versioning. If modpack authors change naming formats, extension will flag for your review. + +**8. Support & Updates** +- Comprehensive documentation included +- Active support via BuiltByBit messages +- Free updates for life + +#### **Screenshots Needed:** +1. Dashboard with update badges (green, yellow, red states) +2. Console widget showing version details +3. Console widget "Configure Manually" modal +4. Console widget "Mark as Up-to-Date" button +5. Admin panel API key configuration +6. Example of Modrinth auto-detection working +7. Example of manual configuration for FTB pack + +**Deliverable:** Transparent, accurate BuiltByBit listing preventing refunds + +--- + +### **Phase 10: Blueprint Packaging Fix** (2-3 hours) +**Priority:** HIGH — Ensures clean install experience + +**Current Issue (from Pathmaker #63):** +- `build.sh` doesn't run on production install +- PHP files stay in extension subfolder +- React components need manual injection + +**Solution Options:** + +**Option A: Fix Blueprint Packaging** +- Research Blueprint native wrapper injection +- Eliminate build.sh dependency +- Ensure PHP files auto-copy on install +- Test clean install cycle + +**Option B: Provide Clear Manual Steps** +- Document exact post-install commands +- Include in INSTALLATION.md +- Test commands on fresh panel +- Accept this as "advanced install" product + +**Decision:** Start with Option B (document manual steps), upgrade to Option A in v1.1 + +**Deliverable:** Clean installation process (manual or automated) + +--- + +## 📋 COMPLETE FEATURE MATRIX + +| Feature | Status | Priority | Time Estimate | +|---------|--------|----------|---------------| +| CurseForge auto-detection | ✅ Complete | Critical | Done | +| Modrinth auto-detection | ⏳ Phase 5 | Critical | 4-6 hours | +| Manual configuration UI | ✅ Complete | Critical | Done | +| Dashboard badge | ✅ Complete | Critical | Done | +| Console widget | ✅ Complete | Critical | Done | +| Admin panel | ✅ Complete | Critical | Done | +| "Ignore Version" button | ⏳ Phase 6 | Critical | 2-3 hours | +| Backoff logic | ⏳ Phase 7 | High | 1-2 hours | +| Documentation | ⏳ Phase 8 | Critical | 3-4 hours | +| BuiltByBit listing | ⏳ Phase 9 | Critical | 2-3 hours | +| Blueprint packaging | ⏳ Phase 10 | High | 2-3 hours | +| FTB auto-detection | 📦 Phase 11 (v1.1) | Medium | 4-6 hours | +| Technic auto-detection | 📦 Phase 11 (v1.1) | Low | 4-6 hours | + +--- + +## ⏱️ TIME ESTIMATES + +### **Minimum Viable Flagship (Launch-Ready)** +- Phase 5: Modrinth auto-detection — 4-6 hours +- Phase 6: "Ignore Version" feature — 2-3 hours +- Phase 7: Backoff logic — 1-2 hours +- Phase 8: Documentation — 3-4 hours +- Phase 9: BuiltByBit listing — 2-3 hours +- Phase 10: Blueprint packaging — 2-3 hours + +**Total: 14-21 hours** (2-3 work sessions) + +### **Premium Flagship (Optional Enhancements)** +- In-panel Setup Wizard — 3-4 hours +- Video tutorials — 4-6 hours +- Beta testing program — 2-3 hours + +**Total: 9-13 additional hours** + +--- + +## 🎯 LAUNCH CRITERIA + +Product is launch-ready when ALL of these are true: + +### **Code Complete:** +- ✅ CurseForge auto-detection working +- ✅ Modrinth auto-detection working +- ✅ "Ignore Version" feature implemented +- ✅ Backoff logic prevents API spam +- ✅ Manual configuration UI functional +- ✅ Dashboard badge working (all states) +- ✅ Console widget working (all features) +- ✅ Admin panel working +- ✅ Clean install process documented/automated + +### **Documentation Complete:** +- ✅ README.md (overview) +- ✅ INSTALLATION.md (step-by-step) +- ✅ CONFIGURATION.md (API keys) +- ✅ HOW-IT-WORKS.md (tiered system explanation) +- ✅ MANUAL-CONFIGURATION.md (platform-specific guides) +- ✅ TROUBLESHOOTING.md (common issues + solutions) +- ✅ FAQ.md (edge cases covered) + +### **Marketing Complete:** +- ✅ BuiltByBit product description written +- ✅ Compatibility matrix included +- ✅ "Read Before You Buy" section added +- ✅ All 7 screenshots taken +- ✅ Pricing tier decided ($14.99 or $19.99) + +### **Testing Complete:** +- ✅ Tested on CurseForge pack (auto-detection) +- ✅ Tested on Modrinth pack (auto-detection) +- ✅ Tested on FTB pack (manual config) +- ✅ Tested on vanilla server (graceful failure) +- ✅ Tested "Ignore Version" button +- ✅ Tested offline server handling +- ✅ Tested API rate limiting +- ✅ Fresh install tested on clean panel + +### **Support Ready:** +- ✅ Documentation prevents 70% of tickets +- ✅ "Ignore Version" prevents 90% of false-positive complaints +- ✅ Compatibility matrix sets accurate expectations +- ✅ [Support strategy/tooling discussed with Michael — TBD] + +--- + +## 🚀 SUGGESTED SESSION BREAKDOWN + +### **Session 1 (Chronicler #64 - Today):** +- ✅ Gemini consultations (DONE) +- ⏳ Begin Phase 5: Modrinth auto-detection (4-6 hours) +- ⏳ Document this plan (DONE) + +### **Session 2 (Chronicler #65):** +- Complete Phase 5: Modrinth auto-detection +- Complete Phase 6: "Ignore Version" feature +- Complete Phase 7: Backoff logic +- Begin Phase 8: Documentation skeleton + +### **Session 3 (Chronicler #66):** +- Complete Phase 8: Full documentation +- Complete Phase 9: BuiltByBit listing +- Complete Phase 10: Blueprint packaging +- Final testing & screenshots +- **LAUNCH** + +--- + +## 📞 SUPPORT STRATEGY (TBD) + +Michael mentioned: *"there is something else I need done in regards to this and help with, but lets get everything in place before we address that, it isn't anything related to coding, but support"* + +**Placeholder for future discussion:** +- Support ticket system/process? +- Response time commitments? +- Refund policy? +- Update/maintenance schedule? +- Community/Discord support channel? + +**To be documented after product features are complete.** + +--- + +## 💙 THE FLAGSHIP STANDARD + +This is not just a product. This is Firefrost Gaming's introduction to the commercial marketplace. + +Every decision prioritizes: +1. **Transparency** — No surprises, no refunds +2. **Quality** — Polished, tested, documented +3. **Support** — 70% of tickets prevented by docs +4. **Reputation** — "That dev ships quality" + +**For children not yet born.** + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ + +--- + +**Document Status:** ACTIVE +**Next Update:** After Phase 5 completion +**Maintained By:** Current Chronicler