packwise-skills 1.0.0

package/sub-skills/plugins/browser-extension.md

@@ -0,0 +1,308 @@
+# Browser Extension Build Sub-Skill
+
+Build and publish browser extensions for Chrome, Edge, Firefox, and Safari.
+
+**Current version**: Manifest V3 (MV3) / Chrome 130+ / Firefox 130+ / Safari 18+ (2025-2026)
+
+## When to Use
+
+- Browser productivity tools (ad blockers, password managers, note-taking)
+- Developer tools (API inspectors, debug panels)
+- Content enhancement (readers, translators, UI overlays)
+- Web scraping / data extraction tools
+- AI-powered browser assistants
+
+## Manifest V3 (Required for Chrome/Edge)
+
+### Project Structure
+
+```
+my-extension/
+├── manifest.json           ← Core configuration (MV3)
+├── background.js           ← Service Worker (replaces background page)
+├── content.js              ← Content script (injected into pages)
+├── popup/
+│   ├── popup.html          ← Popup page
+│   └── popup.js
+├── options/
+│   ├── options.html        ← Settings page
+│   └── options.js
+├── icons/
+│   ├── icon16.png
+│   ├── icon48.png
+│   └── icon128.png
+└── sidepanel/              ← Chrome Side Panel (optional)
+    ├── panel.html
+    └── panel.js
+```
+
+### manifest.json Template (MV3)
+
+```json
+{
+  "manifest_version": 3,
+  "name": "My Extension",
+  "version": "1.0.0",
+  "description": "Extension description",
+  "permissions": [
+    "activeTab",
+    "storage",
+    "scripting",
+    "sidePanel"
+  ],
+  "host_permissions": ["https://*/*"],
+  "background": {
+    "service_worker": "background.js"
+  },
+  "content_scripts": [{
+    "matches": ["https://*/*"],
+    "js": ["content.js"],
+    "css": ["content.css"],
+    "run_at": "document_idle"
+  }],
+  "action": {
+    "default_popup": "popup/popup.html",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "48": "icons/icon48.png",
+      "128": "icons/icon128.png"
+    }
+  },
+  "side_panel": {
+    "default_path": "sidepanel/panel.html"
+  },
+  "icons": {
+    "16": "icons/icon16.png",
+    "48": "icons/icon48.png",
+    "128": "icons/icon128.png"
+  },
+  "minimum_chrome_version": "116"
+}
+```
+
+### Background Service Worker (MV3)
+
+```javascript
+// background.js — runs as Service Worker (NOT persistent)
+chrome.runtime.onInstalled.addListener(() => {
+  console.log('Extension installed');
+});
+
+// Listen for messages from content script or popup
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.action === 'getData') {
+    chrome.storage.local.get(['data'], (result) => {
+      sendResponse(result.data);
+    });
+    return true; // Keep message channel open for async response
+  }
+});
+
+// Side Panel API
+chrome.sidePanel.setOptions({ path: 'sidepanel/panel.html', enabled: true });
+```
+
+### Content Script
+
+```javascript
+// content.js — runs in the context of web pages
+// Can access DOM but NOT Chrome APIs directly
+// Communicate with background via chrome.runtime.sendMessage
+
+const data = document.title;
+chrome.runtime.sendMessage({ action: 'pageTitle', data });
+```
+
+### Build Tools (Bundling with Vite/Webpack)
+
+```bash
+npm install -D @crxjs/vite-plugin  # For Vite projects
+```
+
+```javascript
+// vite.config.js
+import { crx } from '@crxjs/vite-plugin';
+import manifest from './manifest.json';
+
+export default {
+  plugins: [crx({ manifest })],
+  build: {
+    rollupOptions: {
+      input: { background: 'background.js' },
+    },
+  },
+};
+```
+
+---
+
+## Firefox Extension (Manifest V3 Support)
+
+Firefox now supports MV3. Add `browser_specific_settings` to manifest.json:
+
+```json
+{
+  "manifest_version": 3,
+  "browser_specific_settings": {
+    "gecko": {
+      "id": "my-extension@example.com",
+      "strict_min_version": "109.0"
+    }
+  }
+}
+```
+
+### Firefox-Specific Differences
+
+| Feature | Chrome MV3 | Firefox MV3 |
+|---------|-----------|-------------|
+| Background | Service Worker (ephemeral) | Event pages (can be persistent) |
+| `browser` API | `chrome.*` | `browser.*` (promise-based) + `chrome.*` (compat) |
+| Storage | `chrome.storage` | `browser.storage` |
+| Side Panel | Supported | Not supported |
+| `webRequest` blocking | Removed (use `declarativeNetRequest`) | Still supported |
+
+### Cross-Browser Build (WXT Framework)
+
+```bash
+npm install -D wxt
+```
+
+```bash
+# Development
+npx wxt dev
+
+# Build for Chrome
+npx wxt build --browser chrome
+# Output: .output/chrome-mv3/
+
+# Build for Firefox
+npx wxt build --browser firefox
+# Output: .output/firefox-mv2/
+
+# Build for all browsers
+npx wxt zip        # Creates .zip for store upload
+```
+
+---
+
+## Safari Extension
+
+### Option 1: Web Extension (Recommended — share code with Chrome/Firefox)
+
+```bash
+# In Xcode:
+# File → New → Target → Safari Web Extension
+# Import your Chrome MV3 extension
+# Xcode converts it to Safari format
+
+# Build
+xcodebuild -scheme MyApp-Extension -configuration Release archive
+```
+
+### Option 2: Safari App Extension (Native Swift)
+
+```swift
+import SafariServices
+
+class SafariExtensionHandler: SFSafariExtensionHandler {
+    override func messageReceived(withName messageName: String, from page: SFSafariPage, userInfo: [String: Any]?) {
+        page.dispatchMessageToScript(withName: "response", userInfo: ["data": "Hello from native!"])
+    }
+}
+```
+
+### Safari-Specific Notes
+
+- Safari uses Web Extension format (similar to MV3 but with limitations)
+- Requires macOS + Xcode
+- Distributed via App Store ($99/year developer account)
+- Some Chrome APIs not available in Safari
+
+---
+
+## Packaging & Publishing
+
+### Chrome Web Store
+
+```bash
+# 1. Build production version
+npm run build
+
+# 2. Zip the extension
+zip -r my-extension.zip manifest.json *.js *.css popup/ options/ icons/
+
+# 3. Upload to Chrome Web Store
+# chrome.google.com/webstore/devconsole
+# - Pay $5 one-time registration fee
+# - Upload .zip
+# - Fill: description, screenshots (1280x800), privacy policy URL
+# - Submit for review (1–7 days)
+
+# Or: automated with GitHub Action
+# wxtjs/wxt-builder-action
+```
+
+### Edge Add-ons
+
+```bash
+# Same .zip works for Edge
+# partner.microsoft.com/dashboard
+# Upload .zip → Submit for review (1–3 days)
+```
+
+### Firefox Add-ons
+
+```bash
+# addons.mozilla.org/developers/
+# Upload .zip → Submit for review (1–7 days, sometimes longer)
+# No registration fee
+```
+
+### Safari Extensions
+
+```bash
+# App Store Connect → New App → macOS
+# Upload .xcarchive via Xcode
+# Requires Apple Developer account ($99/year)
+# Review: 1–3 days
+```
+
+---
+
+## Store Comparison
+
+| Store | Fee | Review Time | User Base | Auto-Update |
+|-------|-----|-------------|-----------|-------------|
+| Chrome Web Store | $5 one-time | 1–7 days | 3B+ users | Yes |
+| Edge Add-ons | Free | 1–3 days | 300M+ users | Yes |
+| Firefox Add-ons | Free | 1–7 days | 200M+ users | Yes |
+| Safari Extensions | $99/year | 1–3 days | 1B+ devices | Yes (via App Store) |
+
+---
+
+## MV3 Migration Checklist (from MV2)
+
+| MV2 Feature | MV3 Replacement |
+|-------------|----------------|
+| Background page | Service Worker |
+| `chrome.browserAction` | `chrome.action` |
+| `webRequest` blocking | `declarativeNetRequest` |
+| Remote code execution | Bundled code only |
+| `eval()` | Not allowed |
+| Persistent background | Event-driven (non-persistent) |
+| `chrome.extension.getURL` | `chrome.runtime.getURL` |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| V2 deprecated | Migrate to V3 (Service Worker replaces Background Page) |
+| CSP restriction in MV3 | No remote code; bundle all dependencies |
+| Too many permissions rejected | Minimize permissions; use `activeTab` instead of `<all_urls>` |
+| Review rejected | Ensure privacy policy URL is valid; minimize data collection |
+| Service Worker dies | MV3 Service Workers are ephemeral; use `chrome.alarms` for periodic tasks |
+| Content script not injecting | Check `matches` pattern; verify `run_at` setting |
+| `chrome.storage` not persisting | Use `chrome.storage.sync` for cross-device; `local` for device-only |
+| Cross-browser compatibility | Use WXT or webextension-polyfill for unified API |
+| Popup not showing | Check popup.html exists; verify `default_popup` in manifest |

package/sub-skills/plugins/jetbrains-plugin.md

@@ -0,0 +1,226 @@
+# JetBrains Plugin Build Sub-Skill
+
+Develop and publish plugins for IntelliJ-based IDEs (IntelliJ IDEA, PyCharm, WebStorm, Android Studio, etc.).
+
+**Current version**: Gradle IntelliJ Plugin 2.x / IntelliJ Platform 2024.3+ (2025-2026)
+
+## When to Use
+
+- Building plugins for IntelliJ IDEA, PyCharm, WebStorm, CLion, Android Studio, etc.
+- Need deep IDE integration (refactoring, code analysis, tool windows)
+- Want to distribute via JetBrains Marketplace
+
+## Key Features
+
+- **Gradle IntelliJ Plugin** — standard build tooling (replaced legacy Plugin DevKit)
+- **Kotlin/Java** — both supported; Kotlin recommended for new plugins
+- **Plugin Verifier** — automated compatibility checking across IDE versions
+- **Dynamic plugins** — hot-reload without restarting IDE (since Platform 2020.1)
+
+## Prerequisites
+
+```bash
+# JDK 17+ (JBR — JetBrains Runtime recommended)
+# Gradle 8.x (wrapper included in template)
+# IntelliJ IDEA (for development and testing)
+```
+
+## Project Setup
+
+```bash
+# Option 1: IntelliJ Plugin Template (recommended)
+# File → New → Project → IntelliJ Platform Plugin
+# Or clone from GitHub:
+git clone https://github.com/JetBrains/intellij-platform-plugin-template.git my-plugin
+cd my-plugin
+
+# Option 2: Gradle init
+# Use IntelliJ Plugin Generator: https://plugins.jetbrains.com/docs/intellij/generating-plugin.html
+```
+
+## Build Configuration
+
+```kotlin
+// build.gradle.kts
+plugins {
+    id("java")
+    id("org.jetbrains.kotlin.jvm") version "2.0.21"
+    id("org.jetbrains.intellij.platform") version "2.2.1"
+}
+
+intellijPlatform {
+    pluginConfiguration {
+        id = "com.example.myplugin"
+        name = "My Plugin"
+        version = "1.0.0"
+        description = "Plugin description"
+        ideaVersion {
+            sinceBuild = "243"
+            untilBuild = "253.*"
+        }
+    }
+
+    // Target IDE(s)
+    intellijIdeaCommunity = "2024.3"
+
+    // Plugin dependencies
+    plugins = listOf(
+        "com.intellij.java",       // Java support
+        "org.intellij.plugins.markdown:243.22562.64" // Markdown plugin
+    )
+
+    // Plugin Verifier
+    pluginVerifier {
+        ides = listOf(
+            intellijIdeaCommunity("2024.3"),
+            intellijIdeaCommunity("2025.1"),
+        )
+    }
+}
+
+// Required dependencies for IntelliJ Platform development
+dependencies {
+    intellijPlatform {
+        intellijIdeaCommunity("2024.3")
+        instrumentationTools()
+        pluginVerifier()
+        zipSigner()
+    }
+}
+```
+
+## Build & Test
+
+```bash
+# Build plugin ZIP
+./gradlew buildPlugin
+# Output: build/distributions/my-plugin-1.0.0.zip
+
+# Run IDE with plugin installed (for testing)
+./gradlew runIde
+
+# Run unit tests
+./gradlew test
+
+# Run Plugin Verifier (compatibility check)
+./gradlew runPluginVerifier
+
+# Check for IntelliJ-specific lint issues
+./gradlew verifyPlugin
+```
+
+## Publishing
+
+```bash
+# 1. Get token from JetBrains Marketplace
+#    https://plugins.jetbrains.com/author/me → Upload Token
+
+# 2. Publish
+./gradlew publishPlugin
+# Requires plugin signing (automatic with zipSigner)
+
+# With token via environment variable:
+export PUBLISH_TOKEN=your-token-here
+./gradlew publishPlugin
+
+# Or specify channel (beta/alpha):
+./gradlew publishPlugin -Pchannel=beta
+```
+
+## Plugin Structure
+
+```
+my-plugin/
+├── src/main/kotlin/com/example/myplugin/
+│   ├── MyToolWindowFactory.kt    # Tool window
+│   ├── MyAction.kt               # Menu/toolbar action
+│   └── services/
+│       └── MyService.kt          # Application-level service
+├── src/main/resources/
+│   └── META-INF/
+│       └── plugin.xml            # Plugin descriptor (required)
+├── build.gradle.kts
+└── gradle.properties
+```
+
+```xml
+<!-- src/main/resources/META-INF/plugin.xml -->
+<idea-plugin>
+    <id>com.example.myplugin</id>
+    <name>My Plugin</name>
+    <vendor email="me@example.com">My Company</vendor>
+
+    <description><![CDATA[
+        Plugin description with <b>HTML</b> support.
+    ]]></description>
+
+    <depends>com.intellij.modules.platform</depends>
+    <depends optional="true" config-file="my-java-ext.xml">com.intellij.java</depends>
+
+    <extensions defaultExtensionNs="com.intellij">
+        <toolWindow id="My Tool" factoryClass="com.example.myplugin.MyToolWindowFactory"/>
+    </extensions>
+
+    <actions>
+        <action id="MyPlugin.MyAction"
+                class="com.example.myplugin.MyAction"
+                text="My Action"
+                description="Does something useful">
+            <add-to-group group-id="ToolsMenu" anchor="last"/>
+        </action>
+    </actions>
+</idea-plugin>
+```
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Plugin rejected on Marketplace | Ensure `plugin.xml` has all required fields (id, name, vendor, description, depends) |
+| IDE version mismatch | Set `sinceBuild`/`untilBuild` carefully; test with Plugin Verifier |
+| Build fails with SDK error | Clear Gradle cache (`~/.gradle/caches/modules-2`); verify JDK 17+ |
+| Plugin not loaded in dev IDE | Check `plugin.xml` for syntax errors; check IDE log (`Help → Diagnostic Tools → Debug Log Settings`) |
+| Tests fail with `NoClassDefFoundError` | Add required platform dependencies to `testImplementation` |
+| Slow `runIde` startup | Use `buildSearchableOptions = false` for faster iteration |
+| API deprecation warnings | Check IntelliJ Platform SDK changelog; migrate to new APIs |
+| Memory issues in large projects | Use `ReadAction.runReadAction()` for thread-safe file access |
+
+## CI/CD — GitHub Actions
+
+```yaml
+name: Build Plugin
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - run: ./gradlew buildPlugin
+      - run: ./gradlew runPluginVerifier
+      - uses: actions/upload-artifact@v4
+        with:
+          name: plugin
+          path: build/distributions/*.zip
+
+  publish:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - run: ./gradlew publishPlugin
+        env:
+          PUBLISH_TOKEN: ${{ secrets.JETBRAINS_TOKEN }}
+```