daily-notification-plugin/test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md

# 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
<!-- ❌ Wrong: Vue 3 doesn't support .native -->
<ActionCard @click.native="handler" />

<!-- ✅ Correct: Standard event binding -->
<ActionCard @click="handler" />
```

### 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
npm run cap:sync
# Or manually:
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**: `npm run cap:sync` (automatically fixes plugin paths)
4. **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