shopify-ai-backup/windows-app/README.md

Plugin Compass Desktop (Electron)

This folder contains the desktop app build for Plugin Compass. The desktop app reuses the existing web UI and wraps it with a native Electron shell that can run OpenCode locally, save output on the user's machine, and sync finished plugins to the backend.

Features

• Reuses the existing web UI with minimal divergence.
• Self-updating via electron-updater (no manual downloads required).
• Run OpenCode locally with API keys pulled securely from the backend.
• Persist work on the user's device and sync results back to the backend.
• Build via GitHub Actions.

Self-Update System

The app includes an automatic update system using electron-updater:

1. Automatic Check: On startup, the app checks for updates from GitHub Releases.
2. Background Download: Updates download in the background without interrupting the user.
3. User Notification: When an update is ready, the user is notified via the UI.
4. One-Click Install: User can restart the app to apply the update.

How Updates Work

• Updates are published to GitHub Releases by the CI workflow.
• electron-updater downloads the new version from GitHub.
• The update is verified before installation.
• Users can choose when to restart and apply the update.

Developer Notes

• Updates require code-signing for production (not needed for testing).
• The update server is GitHub Releases (configured in package.json).
• Update events are exposed via window.windowsAppBridge:
  • checkForUpdates() - Manually check for updates
  • downloadUpdate() - Download available update
  • installUpdate() - Restart and install
  • onUpdateAvailable(callback) - Listen for update available
  • onUpdateDownloaded(callback) - Listen for update ready
  • onDownloadProgress(callback) - Track download progress

Setup

1. Install prerequisites (Node 18+).
2. From this folder: npm install.
3. Pull UI assets: npm run prepare-ui.

Development

• npm run dev starts Electron using the copied UI in ui-dist.
• Commands are exposed via window.windowsAppBridge.

CI build

• GitHub Actions workflow: .github/workflows/build-electron-app.yml.
• The action runs on windows-latest, builds the app, and publishes to GitHub Releases.

Security notes

• No command exposes the stored API key to the web layer.
• OpenCode is only invoked from the main process with the key set via environment variables.
• File system access is restricted to the app data directory.