@rune-kit/rune 2.2.0 → 2.2.2

package/extensions/chrome-ext/skills/ext-storage.md

@@ -0,0 +1,133 @@
+---
+name: "ext-storage"
+pack: "@rune/chrome-ext"
+description: "Typed Chrome storage patterns — choose the right storage tier, define schema, implement typed helpers, handle schema migrations, and monitor quota."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ext-storage
+
+Typed Chrome storage patterns — choose the right storage tier, define schema, implement typed helpers, handle schema migrations, and monitor quota. Prevents the #3 MV3 failure: storing state in service worker JS variables that reset on termination.
+
+#### Workflow
+
+**Step 1 — Choose storage type**
+| Type | Capacity | Persistence | Sync | Use For |
+|------|----------|-------------|------|---------|
+| `chrome.storage.local` | 10 MB | Until uninstall | No | User data, large payloads, cached content |
+| `chrome.storage.sync` | 100 KB / 8 KB per item | Cross-device | Yes | Settings, small preferences |
+| `chrome.storage.session` | 10 MB | Until browser closes | No | Ephemeral state that service worker needs across terminations |
+| `chrome.storage.managed` | Read-only | Admin-controlled | No | Enterprise policy |
+
+CRITICAL: `chrome.storage.session` is the correct replacement for service worker JS variables. If you need state to survive a 30-second termination but clear on browser close, use session storage.
+
+**Step 2 — Define TypeScript storage schema**
+Create `src/types/storage.ts` with versioned schema interface. Include a `version` field for migration tracking.
+
+**Step 3 — Implement typed get/set helpers**
+Create `src/lib/storage.ts` with typed wrappers that preserve the schema type. Avoid `chrome.storage.*.get(null)` which returns `any` — always specify keys.
+
+**Step 4 — Add migration logic**
+On `chrome.runtime.onInstalled` with `reason === 'update'`, check stored schema version and run incremental migrations. Each migration transforms data from version N to N+1.
+
+**Step 5 — Implement quota monitoring**
+Chrome storage has hard limits that throw `QUOTA_BYTES_PER_ITEM` and `QUOTA_BYTES` errors on write. Wrap all writes with error handling and warn the user or prune old data when approaching 80% capacity.
+
+#### Example
+
+```typescript
+// src/types/storage.ts — versioned storage schema
+export const STORAGE_VERSION = 2;
+
+export interface StorageSchema {
+  version: number;
+  settings: {
+    useBuiltinAI: boolean;
+    externalApiKey: string;
+    maxLength: number;
+    theme: 'light' | 'dark' | 'system';
+  };
+  cache: {
+    lastSummary: string;
+    lastUrl: string;
+    timestamp: number;
+  } | null;
+}
+
+export const STORAGE_DEFAULTS: StorageSchema = {
+  version: STORAGE_VERSION,
+  settings: {
+    useBuiltinAI: true,
+    externalApiKey: '',
+    maxLength: 500,
+    theme: 'system',
+  },
+  cache: null,
+};
+```
+
+```typescript
+// src/lib/storage.ts — typed get/set helpers with quota monitoring
+
+import type { StorageSchema } from '../types/storage';
+import { STORAGE_DEFAULTS, STORAGE_VERSION } from '../types/storage';
+
+type StorageKey = keyof StorageSchema;
+
+export async function storageGet<K extends StorageKey>(
+  key: K
+): Promise<StorageSchema[K]> {
+  const result = await chrome.storage.local.get(key);
+  return (result[key] as StorageSchema[K]) ?? STORAGE_DEFAULTS[key];
+}
+
+export async function storageSet<K extends StorageKey>(
+  key: K,
+  value: StorageSchema[K]
+): Promise<void> {
+  try {
+    await chrome.storage.local.set({ [key]: value });
+  } catch (err) {
+    const error = err as Error;
+    if (error.message.includes('QUOTA_BYTES')) {
+      console.warn('[Storage] Quota exceeded — clearing cache');
+      await chrome.storage.local.remove('cache');
+      // retry once after clearing cache
+      await chrome.storage.local.set({ [key]: value });
+    } else {
+      throw err;
+    }
+  }
+}
+
+// Quota monitoring — warn at 80% capacity
+export async function checkStorageQuota(): Promise<void> {
+  const bytesUsed = await chrome.storage.local.getBytesInUse(null);
+  const quota = chrome.storage.local.QUOTA_BYTES; // 10 MB = 10,485,760 bytes
+  const pct = (bytesUsed / quota) * 100;
+  if (pct > 80) {
+    console.warn(`[Storage] ${pct.toFixed(1)}% of local storage used (${bytesUsed} / ${quota} bytes)`);
+  }
+}
+
+// Migration runner — call on onInstalled with reason='update'
+export async function runMigrations(): Promise<void> {
+  const stored = await chrome.storage.local.get('version');
+  const currentVersion = (stored['version'] as number | undefined) ?? 1;
+
+  if (currentVersion < 2) {
+    // v1 → v2: renamed 'apiKey' to 'externalApiKey'
+    const legacy = await chrome.storage.local.get('settings');
+    const legacySettings = legacy['settings'] as Record<string, unknown> | undefined;
+    if (legacySettings?.['apiKey']) {
+      await chrome.storage.local.set({
+        settings: { ...legacySettings, externalApiKey: legacySettings['apiKey'], apiKey: undefined },
+        version: 2,
+      });
+    }
+  }
+
+  await chrome.storage.local.set({ version: STORAGE_VERSION });
+}
+```

package/extensions/chrome-ext/skills/mv3-scaffold.md

@@ -0,0 +1,164 @@
+---
+name: "mv3-scaffold"
+pack: "@rune/chrome-ext"
+description: "Manifest V3 project scaffolding — detect extension type, generate minimal-permission manifest, scaffold service worker with correct lifecycle patterns, scaffold content script, and generate build config."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# mv3-scaffold
+
+Manifest V3 project scaffolding — detect extension type, generate minimal-permission manifest, scaffold service worker with correct lifecycle patterns, scaffold content script, and generate build config. Prevents the #1 MV3 mistake: carrying MV2 mental models (background pages, remote scripts, setTimeout for keepalive) into an MV3 project.
+
+#### Workflow
+
+**Step 1 — Detect or clarify extension type**
+Use `Read` on any existing `manifest.json` or project description to classify the extension type:
+- **popup**: user-triggered UI (toolbar button → popup.html)
+- **sidebar**: persistent panel (chrome.sidePanel API, Chrome 114+)
+- **content-injector**: modifies host pages (content scripts + optional popup)
+- **background-only**: no visible UI, reacts to events (alarms, network, tabs)
+- **devtools**: extends Chrome DevTools panel
+
+If undetectable from files, ask the user. Extension type determines which APIs, permissions, and scaffold components are generated.
+
+**Step 2 — Generate minimal-permission manifest.json**
+Emit `manifest.json` with only the permissions required for the detected type. Flag over-permissioning immediately — requesting `<all_urls>` when only `activeTab` is needed is the #1 CWS rejection cause.
+
+Key MV3 manifest rules:
+- `"manifest_version": 3` — mandatory, MV2 deprecated Jan 2023
+- `"background"` uses `{ "service_worker": "background.js" }` — NOT `"scripts"` array
+- `"action"` replaces `"browser_action"` and `"page_action"`
+- No `"content_security_policy"` that relaxes `script-src` (blocks CWS review)
+- No `"web_accessible_resources"` with `matches: ["<all_urls>"]` unless justified
+- External URLs in `"host_permissions"` require justification in CWS dashboard
+
+**Step 3 — Scaffold service worker (CRITICAL lifecycle patterns)**
+Generate `background.ts` / `background.js` with the following non-negotiable patterns:
+
+CRITICAL: service workers terminate after 30 seconds of idle. Every assumption that breaks because of this:
+- JS variables reset on termination — use `chrome.storage.session` for ephemeral state
+- `setTimeout` / `setInterval` — NOT reliable across terminations, use `chrome.alarms`
+- Pending async operations mid-flight get killed — use alarm + storage to resume
+- `fetch()` initiated in a response to a non-event call may not complete
+
+All event listeners MUST be registered at the top level synchronously — NOT inside `async` functions, Promises, or conditionals. Chrome only registers listeners present during the initial synchronous execution of the service worker.
+
+**Step 4 — Scaffold content script**
+Generate `content.ts` with correct isolation model:
+- Runs in an **isolated world** — own JS context, cannot access page's JS variables
+- Has access to the DOM but NOT to `chrome.storage`, `chrome.tabs`, most `chrome.*` APIs (exceptions: `chrome.runtime`, `chrome.storage`, `chrome.i18n`)
+- Must message the service worker for privileged operations
+- Inject only when needed — prefer `"run_at": "document_idle"` over `"document_start"`
+
+**Step 5 — Scaffold popup/sidebar UI**
+For popup and sidebar types, generate `popup.html` + `popup.ts`:
+- Popup HTML MUST NOT load remote scripts (`<script src="https://...">`) — blocked by CSP
+- All scripts must be local and listed in `web_accessible_resources` if loaded from content scripts
+- Popup closes when user clicks away — don't depend on popup state for background operations
+- For sidebar: register `chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true })`
+
+**Step 6 — Generate build config**
+Emit a build configuration based on detected tooling:
+- If `vite` in `package.json` → emit `vite.config.ts` using `@crxjs/vite-plugin` (hot-reload for extension dev)
+- Otherwise → emit vanilla TypeScript config with `tsc` + file copy script
+- Include `web-ext` config for local loading and reload
+
+#### Example
+
+```json
+// manifest.json — content-injector type, minimal permissions
+{
+  "manifest_version": 3,
+  "name": "Page Summarizer",
+  "version": "1.0.0",
+  "description": "Summarize any page using built-in AI or an external API.",
+  "permissions": ["activeTab", "storage", "sidePanel"],
+  "host_permissions": [],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["content.js"],
+      "run_at": "document_idle"
+    }
+  ],
+  "action": {
+    "default_title": "Summarize this page",
+    "default_icon": { "128": "icons/icon128.png" }
+  },
+  "side_panel": {
+    "default_path": "sidebar.html"
+  },
+  "icons": { "128": "icons/icon128.png" },
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'"
+  }
+}
+```
+
+```typescript
+// background.ts — correct MV3 service worker patterns
+// CRITICAL: all listeners registered synchronously at top level
+
+chrome.runtime.onInstalled.addListener(({ reason }) => {
+  if (reason === 'install') {
+    console.log('[SW] Extension installed');
+  }
+});
+
+// Use chrome.alarms — NOT setTimeout (alarms survive service worker termination)
+chrome.runtime.onInstalled.addListener(() => {
+  chrome.alarms.create('heartbeat', { periodInMinutes: 1 });
+});
+
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === 'heartbeat') {
+    // periodic work here — service worker woke up for this
+  }
+});
+
+// Message handler — registered synchronously, NOT inside async function
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.type === 'SUMMARIZE_PAGE') {
+    // Return true to keep the message channel open for async response
+    handleSummarize(message.payload).then(sendResponse);
+    return true;
+  }
+});
+
+async function handleSummarize(payload: { text: string }): Promise<{ summary: string }> {
+  // Service worker is alive for the duration of this message handler
+  const summary = await callExternalApi(payload.text);
+  return { summary };
+}
+```
+
+```typescript
+// content.ts — isolated world, limited chrome.* access
+const selectedText = window.getSelection()?.toString() ?? '';
+
+if (selectedText.length > 0) {
+  // Content scripts can message service worker
+  chrome.runtime.sendMessage(
+    { type: 'SUMMARIZE_PAGE', payload: { text: selectedText } },
+    (response: { summary: string }) => {
+      if (chrome.runtime.lastError) {
+        console.error('[Content] Message failed:', chrome.runtime.lastError.message);
+        return;
+      }
+      displaySummary(response.summary);
+    }
+  );
+}
+
+function displaySummary(summary: string): void {
+  const panel = document.createElement('div');
+  panel.id = 'rune-summarizer-panel';
+  panel.textContent = summary;
+  document.body.appendChild(panel);
+}
+```