From 9b86a50c38bee757ef9603dcddcbb055732786c0 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Fri, 17 Oct 2025 10:20:55 +0000 Subject: [PATCH] docs(test-app): add comprehensive plugin detection and build documentation - Add PLUGIN_DETECTION_GUIDE.md with complete troubleshooting guide - Add BUILD_QUICK_REFERENCE.md for streamlined build process - Document critical fix-capacitor-plugins.js requirement after npx cap sync - Include verification checklists and common issue solutions - Provide automated build script and debugging tools - Cover Vue 3 compatibility issues and click event troubleshooting These docs ensure reliable plugin detection and prevent the common issue where npx cap sync overwrites capacitor.plugins.json. --- .../docs/BUILD_QUICK_REFERENCE.md | 95 +++++ .../docs/PLUGIN_DETECTION_GUIDE.md | 324 ++++++++++++++++++ 2 files changed, 419 insertions(+) create mode 100644 test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md create mode 100644 test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md diff --git a/test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md b/test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md new file mode 100644 index 0000000..741ecb1 --- /dev/null +++ b/test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md @@ -0,0 +1,95 @@ +# Build Process Quick Reference + +**Author**: Matthew Raymer +**Date**: October 17, 2025 + +## 🚨 Critical Build Steps + +```bash +# 1. Build web assets +npm run build + +# 2. Sync with native projects +npx cap sync android + +# 3. 🔧 FIX PLUGIN REGISTRY (REQUIRED!) +node scripts/fix-capacitor-plugins.js + +# 4. Build and deploy Android +cd android +./gradlew :app:assembleDebug +adb install -r app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification.test/.MainActivity +``` + +## ⚠️ Why Step 3 is Critical + +**Problem**: `npx cap sync` overwrites `capacitor.plugins.json` and removes custom plugins. + +**Solution**: The fix script restores the DailyNotification plugin entry. + +**Without Step 3**: Plugin detection fails, "simplified dialog" appears. + +## 🔍 Verification Checklist + +After build, verify: + +- [ ] `capacitor.plugins.json` contains DailyNotification entry +- [ ] System Status shows "Plugin: Available" (green) +- [ ] Plugin Diagnostics shows all 4 plugins +- [ ] Click events work on ActionCard components +- [ ] No "simplified dialog" appears + +## 🛠️ Automated Build Script + +Create `scripts/build-and-deploy.sh`: + +```bash +#!/bin/bash +set -e + +echo "🔨 Building web assets..." +npm run build + +echo "🔄 Syncing with native projects..." +npx cap sync android + +echo "🔧 Fixing plugin registry..." +node scripts/fix-capacitor-plugins.js + +echo "🏗️ Building Android app..." +cd android +./gradlew :app:assembleDebug + +echo "📱 Installing and launching..." +adb install -r app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification.test/.MainActivity + +echo "✅ Build and deploy complete!" +``` + +## 🐛 Common Issues + +| Issue | Symptom | Solution | +|-------|---------|----------| +| Empty plugin registry | `capacitor.plugins.json` is `[]` | Run `node scripts/fix-capacitor-plugins.js` | +| Plugin not detected | "Plugin: Not Available" (red) | Check plugin registry, rebuild | +| Click events not working | Buttons don't respond | Check Vue 3 compatibility, router config | +| Inconsistent status | Different status in different cards | Use consistent detection logic | + +## 📱 Testing Commands + +```bash +# Check plugin registry +cat android/app/src/main/assets/capacitor.plugins.json + +# Monitor native logs +adb logcat | grep -i "dailynotification\|capacitor\|plugin" + +# Check app installation +adb shell pm list packages | grep dailynotification +``` + +--- + +**Remember**: Always run the fix script after `npx cap sync`! diff --git a/test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md b/test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md new file mode 100644 index 0000000..0dab23f --- /dev/null +++ b/test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md @@ -0,0 +1,324 @@ +# DailyNotification Plugin Detection Guide + +**Author**: Matthew Raymer +**Date**: October 17, 2025 +**Version**: 1.0.0 + +## Overview + +This guide documents the plugin detection system for the DailyNotification Capacitor plugin, including troubleshooting steps and build process requirements. + +## Table of Contents + +1. [Plugin Detection Architecture](#plugin-detection-architecture) +2. [Build Process Requirements](#build-process-requirements) +3. [Troubleshooting Guide](#troubleshooting-guide) +4. [Development Workflow](#development-workflow) +5. [Common Issues and Solutions](#common-issues-and-solutions) + +## Plugin Detection Architecture + +### Native Side (Android) + +The DailyNotification plugin is registered on the native Android side through: + +1. **Automatic Discovery**: Using Capacitor's annotation processor +2. **Manual Registration**: Fallback in `MainActivity.onCreate()` +3. **Plugin Class**: `com.timesafari.dailynotification.DailyNotificationPlugin` + +### JavaScript Side (WebView) + +The JavaScript layer detects plugins through: + +1. **`capacitor.plugins.json`**: Bridge file that lists available plugins +2. **Capacitor.Plugins Object**: Runtime plugin registry +3. **Plugin Detection Logic**: Checks both sources for availability + +### Key Files + +``` +android/ +├── app/src/main/assets/capacitor.plugins.json # Plugin registry +├── app/src/main/java/.../MainActivity.java # Plugin registration +└── dailynotification/build.gradle # Annotation processor + +src/ +├── views/HomeView.vue # Plugin detection UI +└── components/cards/ActionCard.vue # Interactive components +``` + +## Build Process Requirements + +### Prerequisites + +1. **Annotation Processor**: Must be configured in both app and plugin modules +2. **Post-Sync Script**: Required to maintain `capacitor.plugins.json` +3. **Proper Dependencies**: Capacitor Android and plugin modules + +### Required Build Steps + +```bash +# 1. Build web assets +npm run build + +# 2. Sync with native projects +npx cap sync android + +# 3. Fix plugin registry (CRITICAL) +node scripts/fix-capacitor-plugins.js + +# 4. Build and deploy Android app +cd android +./gradlew :app:assembleDebug +adb install -r app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification.test/.MainActivity +``` + +### Why the Fix Script is Required + +**Problem**: `npx cap sync android` overwrites `capacitor.plugins.json` and doesn't include custom plugins. + +**Solution**: Post-sync script automatically restores the DailyNotification plugin entry. + +**File**: `scripts/fix-capacitor-plugins.js` + +```javascript +const PLUGIN_ENTRY = { + name: "DailyNotification", + classpath: "com.timesafari.dailynotification.DailyNotificationPlugin" +}; +``` + +## Troubleshooting Guide + +### Issue: "Plugin: Not Available" in System Status + +**Symptoms**: +- System Status card shows red "Not Available" indicator +- Plugin Diagnostics shows "Plugin Available: No" + +**Diagnosis Steps**: +1. Check `capacitor.plugins.json` content +2. Verify native plugin registration logs +3. Test JavaScript detection logic + +**Solutions**: +```bash +# Check plugin registry +cat android/app/src/main/assets/capacitor.plugins.json + +# Should contain: +[ + { + "name": "DailyNotification", + "classpath": "com.timesafari.dailynotification.DailyNotificationPlugin" + } +] + +# If empty or missing, run fix script +node scripts/fix-capacitor-plugins.js +``` + +### Issue: Click Events Not Working + +**Symptoms**: +- ActionCard buttons don't respond to clicks +- No console logs from click handlers + +**Common Causes**: +1. **Wrong View Component**: Router pointing to simplified view +2. **Vue 3 Compatibility**: Using deprecated `@click.native` +3. **Component Registration**: Missing component imports + +**Solutions**: +```vue + + + + + +``` + +### Issue: Empty capacitor.plugins.json After Build + +**Symptoms**: +- File contains only `[]` +- Plugin detection fails +- "Simplified dialog" appears + +**Root Cause**: `npx cap sync` overwrites the file + +**Solution**: Always run fix script after sync +```bash +npx cap sync android && node scripts/fix-capacitor-plugins.js +``` + +## Development Workflow + +### Daily Development Cycle + +1. **Make Changes**: Edit Vue components, native code, or plugin logic +2. **Build Web**: `npm run build` +3. **Sync Native**: `npx cap sync android` +4. **Fix Plugins**: `node scripts/fix-capacitor-plugins.js` +5. **Build Android**: `cd android && ./gradlew :app:assembleDebug` +6. **Deploy**: `adb install -r app/build/outputs/apk/debug/app-debug.apk` +7. **Test**: Launch app and verify plugin detection + +### Automated Build Script + +Create `scripts/build-and-deploy.sh`: + +```bash +#!/bin/bash +set -e + +echo "🔨 Building web assets..." +npm run build + +echo "🔄 Syncing with native projects..." +npx cap sync android + +echo "🔧 Fixing plugin registry..." +node scripts/fix-capacitor-plugins.js + +echo "🏗️ Building Android app..." +cd android +./gradlew :app:assembleDebug + +echo "📱 Installing and launching..." +adb install -r app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification.test/.MainActivity + +echo "✅ Build and deploy complete!" +``` + +### Verification Checklist + +After each build, verify: + +- [ ] `capacitor.plugins.json` contains DailyNotification entry +- [ ] System Status shows "Plugin: Available" (green) +- [ ] Plugin Diagnostics shows all 4 plugins +- [ ] Click events work on ActionCard components +- [ ] No "simplified dialog" appears +- [ ] Console logs show plugin detection success + +## Common Issues and Solutions + +### Issue: Annotation Processor Not Working + +**Symptoms**: Plugin not auto-discovered, manual registration required + +**Solution**: Ensure annotation processor is configured in both modules + +```gradle +// app/build.gradle +dependencies { + annotationProcessor project(':capacitor-android') +} + +// dailynotification/build.gradle +dependencies { + annotationProcessor project(':capacitor-android') +} +``` + +### Issue: Plugin Loads But Methods Fail + +**Symptoms**: Plugin detected but `checkStatus()` throws errors + +**Diagnosis**: Check native plugin implementation and permissions + +**Solution**: Verify plugin class methods and Android permissions + +### Issue: Inconsistent Status Between Cards + +**Symptoms**: System Status shows "Not Available" but Plugin Diagnostics shows "Available" + +**Root Cause**: Different detection logic between functions + +**Solution**: Use consistent detection method (see `checkSystemStatus` in HomeView.vue) + +### Issue: Build Failures After Changes + +**Symptoms**: Gradle build errors, TypeScript compilation failures + +**Common Causes**: +1. Missing imports after refactoring +2. TypeScript errors in Vue components +3. Gradle dependency conflicts + +**Solution**: Check build logs and fix compilation errors + +## Debugging Tools + +### Console Logging + +The app includes comprehensive logging for plugin detection: + +```javascript +// Plugin detection logs +console.log('🔍 Plugin detection debug:') +console.log(' - window.DailyNotification:', (window as any).DailyNotification) +console.log(' - Capacitor.Plugins:', (window as any).Capacitor?.Plugins) +console.log(' - Available plugins:', Object.keys((window as any).Capacitor?.Plugins || {})) +``` + +### ADB Logging + +Monitor native Android logs: + +```bash +adb logcat | grep -i "dailynotification\|capacitor\|plugin\|error" +``` + +### Plugin Diagnostics + +Use the built-in Plugin Diagnostics feature to get comprehensive system information: + +1. Click "Plugin Diagnostics" button +2. Review detailed plugin report +3. Check all available plugins list +4. Verify plugin status and capabilities + +## Best Practices + +### Development + +1. **Always run fix script** after `npx cap sync` +2. **Test plugin detection** after each build +3. **Use consistent detection logic** across components +4. **Monitor console logs** for debugging information +5. **Verify both native and JavaScript sides** work correctly + +### Maintenance + +1. **Keep fix script updated** if plugin classpath changes +2. **Document any new plugin dependencies** +3. **Update this guide** when architecture changes +4. **Test on multiple devices** and Android versions +5. **Monitor Capacitor updates** for breaking changes + +## Related Files + +- `scripts/fix-capacitor-plugins.js` - Post-sync plugin registry fix +- `src/views/HomeView.vue` - Main plugin detection UI +- `src/components/cards/ActionCard.vue` - Interactive components +- `android/app/src/main/assets/capacitor.plugins.json` - Plugin registry +- `android/app/src/main/java/.../MainActivity.java` - Native registration + +## Support + +For issues not covered in this guide: + +1. Check Capacitor documentation +2. Review Android plugin development guides +3. Examine console logs and ADB output +4. Test with minimal reproduction case +5. Consult development team + +--- + +**Last Updated**: October 17, 2025 +**Next Review**: After major Capacitor updates or architecture changes