4.1 KiB
4.1 KiB
Plugin development instructions
Instructions for opencode agents working on the Paarrot plugin system in this repo.
Architecture
- Plugin host:
overlay/src/app/utils/pluginHost.ts. Electron useswindow.electron.plugins, Android uses the CapacitorPluginStorageplugin, web returns null. - Native Android host:
android/app/src/main/java/com/paarrot/app/PluginStoragePlugin.kt(download zip, unzip with zip-slip guard, list, uninstall, readPluginCode). Registered inMainActivity.java. - Loader:
cinny/src/app/features/settings/plugins/PluginLoader.tsx, mounted inClientRoot.tsx. It evaluatesindex.jswithnew Functionfor CommonJS and falls back to a data-URL import for ESM. - Registry and marketplace:
PluginAPI.tspersists both tolocalStorage. Enabled state survives restarts. Plugins load at app start, so enabling a plugin requires an app restart.
Plugin context contract
createPluginContextfrom@paarrot/plugin-managerprovides:commands,messages,ui,settings,themes,events,timers,log,warn,error.PluginLoaderadds compat fields on top:matrixClient,matrix,React,lucide. Plugins destructure these directly (for exampleconst { Link } = ctx.lucide), so a missing field throws atonLoadand the plugin never runs. Keep the compat fields in sync betweencinnyandoverlay. A missinglucidecaused silent plugin failure on mobile, fixed in commit1f16f5d.
UI locations
- Valid
UILocationvalues:room-header,message-actions,user-menu,room-menu,composer-actions,channel-list,direct-messages,home-section,search-notification-section,text-composer-toolbar,sidebar-actions. - Button slots render at all screen sizes. Nav-only locations (
channel-list,direct-messages,home-section,sidebar-actions) have no surface in the single-column mobile UI, so plugins that only register there are invisible on phones.
Mobile quirks
- Capacitor injects plugins on
Capacitor.Pluginsafter the bridge is ready, andregisterPluginis often missing on Android. ThewaitForBridgefallback pattern inoverlay/src/app/utils/backgroundSync.tsis the reference. - No CSP is configured in
capacitor.config.json, sonew Functionand data-URL imports work. Adding CSP would break plugin evaluation. - WebView console logs reach logcat under the tag
Capacitor/Console.
Debugging on device
- Wireless adb:
adb connect <ip>:<port>. Theadb tcpipport persists until reboot, then resets to 5555. Android 11+ wireless debugging randomizes the port per reboot by design. Pinning needs root (persist.adb.tcp.port). - Plugin files:
adb shell run-as com.paarrot.app cat files/plugins/<id>/index.jsworks on debuggable builds. - Enabled state: localStorage lives in
app_webview/Local Storage/leveldb. Search forplugin-manager:installed-plugins. - Live eval: the WebView devtools socket is
@webview_devtools_remote_<pid>. Forward withadb forward tcp:9222 localsocket:webview_devtools_remote_<pid>. The socket may refuse HTTP and WebSocket requests from non-localhost hosts. - To trigger plugin load logs: force-stop, start, then
logcat -d | grep PluginLoader. - Hotpatching the installed copy with
run-asplus an app restart tests plugin changes without reinstalling.
Marketplace
- Directory:
Paarrot/Plugin-Directory. Entries are static JSON files. Theversionfield is a manual snapshot and is never synced from the plugin repo. - Updates go through PRs.
validate-pr.ymlvalidates and auto-merges.update-index.ymlregeneratesindex.jsonfrom committed entries only. - A plugin repo needs
index.jsandplugin-metadata.json. The directorydownloadUrlis the GitHub archive zip. - Bump the version in both the plugin repo metadata and the directory entry when shipping changes.
Repo conventions
- Edit
overlay/files, notcinnydirectly.scripts/apply-overlay.mjslayers the overlay onto the cinny submodule before every Android build. android/gradlewis not executable. Run it assh gradlew.- Use
scripts/push.shfor commits. It skips the cinny submodule pointer andgradlew.