@rune-kit/rune 2.1.1 → 2.2.1

package/extensions/mobile/skills/flutter.md

@@ -0,0 +1,60 @@
+---
+name: "flutter"
+pack: "@rune/mobile"
+description: "Flutter patterns — widget composition, state management (Riverpod, BLoC), platform channels, adaptive layouts."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# flutter
+
+Flutter patterns — widget composition, state management (Riverpod, BLoC), platform channels, adaptive layouts.
+
+#### Workflow
+
+**Step 1 — Detect Flutter architecture**
+Use Grep to find state management (`riverpod`, `flutter_bloc`, `provider`, `get_it`), routing (`go_router`, `auto_route`), and platform channel usage. Read `pubspec.yaml` for dependencies and `lib/` structure for architecture pattern (feature-first, layer-first).
+
+**Step 2 — Audit widget tree and state**
+Check for: `setState` in complex widgets (should use state management), deeply nested widget trees (extract widgets), `BuildContext` passed through many layers (use InheritedWidget or Riverpod), missing `const` constructors (unnecessary rebuilds), platform-specific code without adaptive checks.
+
+**Step 3 — Emit refactored patterns**
+For each issue, emit: extracted widget with const constructor, Riverpod provider for state, proper error handling with `AsyncValue`, and adaptive layout using `LayoutBuilder` + breakpoints.
+
+#### Example
+
+```dart
+// BEFORE: setState in complex widget, no separation
+class HomeScreen extends StatefulWidget { ... }
+class _HomeScreenState extends State<HomeScreen> {
+  List<Item> items = [];
+  bool loading = true;
+
+  @override
+  void initState() {
+    super.initState();
+    fetchItems().then((data) => setState(() { items = data; loading = false; }));
+  }
+}
+
+// AFTER: Riverpod with AsyncValue, separated concerns
+@riverpod
+Future<List<Item>> items(Ref ref) async {
+  final repo = ref.watch(itemRepositoryProvider);
+  return repo.fetchAll();
+}
+
+class HomeScreen extends ConsumerWidget {
+  const HomeScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final itemsAsync = ref.watch(itemsProvider);
+    return itemsAsync.when(
+      data: (items) => ItemList(items: items),
+      loading: () => const ShimmerList(),
+      error: (err, stack) => ErrorView(message: err.toString(), onRetry: () => ref.invalidate(itemsProvider)),
+    );
+  }
+}
+```

package/extensions/mobile/skills/ios-build-pipeline.md

@@ -0,0 +1,142 @@
+---
+name: "ios-build-pipeline"
+pack: "@rune/mobile"
+description: "End-to-end iOS build pipeline — certificate generation, provisioning profiles, Xcode archive, IPA export, TestFlight upload, build polling."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ios-build-pipeline
+
+End-to-end iOS build pipeline — certificate generation, provisioning profiles, Xcode archive, IPA export, TestFlight upload, build polling. Covers both React Native and native Swift projects.
+
+#### Workflow
+
+**Step 1 — Detect project type and signing state**
+Use Glob to find: `.xcworkspace` or `.xcodeproj` (check `ios/`, `macos/`, `apple/` for RN projects), `Podfile` (needs `pod install` if workspace missing), `project.pbxproj` for current signing config (`DEVELOPMENT_TEAM`, `CODE_SIGN_STYLE`, `PRODUCT_BUNDLE_IDENTIFIER`). Check for existing signing state file (`.rune/signing-state.json`) from previous pipeline runs — if exists, skip completed steps (idempotent pipeline).
+
+**Step 2 — Bundle ID registration**
+Check if bundle ID exists on Apple Developer portal. If not:
+- Register via App Store Connect API: `POST /v1/bundleIds` with `identifier`, `name`, `platform: IOS`
+- Common failure: bundle ID already taken by another team → suggest alternative namespace
+- Store `bundleIdResourceId` in signing state for later use
+
+**Step 3 — Distribution certificate**
+Generate Apple Distribution certificate:
+```bash
+# Generate RSA 2048-bit CSR via OpenSSL
+openssl req -new -newkey rsa:2048 -nodes \
+  -keyout distribution.key \
+  -out distribution.csr \
+  -subj "/CN=Apple Distribution/O=YourTeam"
+
+# Upload CSR to App Store Connect API
+# Download signed certificate (.cer)
+
+# Create .p12 bundle — OpenSSL 3.x requires -legacy flag
+openssl pkcs12 -export -legacy \
+  -inkey distribution.key \
+  -in distribution.cer \
+  -out distribution.p12 \
+  -passout pass:""
+
+# Import to login keychain
+security import distribution.p12 -k ~/Library/Keychains/login.keychain-db -T /usr/bin/codesign
+```
+
+Sharp edges:
+- OpenSSL 3.x (macOS 14+) changed default encryption — `.p12` without `-legacy` flag silently fails import
+- Must import to `login.keychain-db` specifically, not `System.keychain`
+- `codesign` needs explicit trust via `-T /usr/bin/codesign` flag
+
+**Step 4 — Provisioning profile**
+Create App Store distribution profile via ASC API → download → install:
+```bash
+# Decode base64 profile content from API response
+base64 -d profile_content.b64 > profile.mobileprovision
+
+# Install to standard location
+cp profile.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/<UUID>.mobileprovision
+```
+
+**Step 5 — Patch project.pbxproj**
+Update Xcode project build settings:
+- `DEVELOPMENT_TEAM` = team ID from ASC
+- `CODE_SIGN_STYLE` = `Automatic` for dev, `Manual` for distribution
+- `PRODUCT_BUNDLE_IDENTIFIER` = registered bundle ID
+- For React Native: detect workspace in `ios/`, run `pod install` if Podfile exists without workspace
+
+**Step 6 — Archive and export**
+```bash
+# Archive
+xcodebuild archive \
+  -workspace App.xcworkspace \
+  -scheme App \
+  -archivePath build/App.xcarchive \
+  -destination "generic/platform=iOS" \
+  CODE_SIGN_STYLE=Manual \
+  CODE_SIGN_IDENTITY="Apple Distribution" \
+  PROVISIONING_PROFILE_SPECIFIER="<profile-name>"
+
+# Export IPA
+xcodebuild -exportArchive \
+  -archivePath build/App.xcarchive \
+  -exportPath build/export \
+  -exportOptionsPlist ExportOptions.plist
+```
+
+Sharp edges:
+- Archive fails silently if CocoaPods not installed → check for `Pods/` directory
+- Export failure diagnostics hidden in `IDEDistribution.standard-log.txt` inside archive — always check this file on failure
+- `ExportOptions.plist` must specify `method: app-store`, `teamID`, `signingStyle: manual`, `provisioningProfiles` dict
+
+**Step 7 — Upload to TestFlight**
+```bash
+# Upload via xcrun altool with API key auth (.p8 file)
+xcrun altool --upload-app \
+  -f build/export/App.ipa \
+  --type ios \
+  --apiKey <key-id> \
+  --apiIssuer <issuer-id>
+```
+
+**Step 8 — Poll build processing**
+After upload, poll ASC API every 30s (up to 30 min) for build to transition from `PROCESSING` → `VALID` or `INVALID`. On `VALID`: auto-attach build to pending App Store version. On `INVALID`: fetch `betaBuildLocalizations` for error details.
+
+#### Example
+
+```json
+// .rune/signing-state.json — idempotent pipeline state
+{
+  "bundleId": "com.example.myapp",
+  "bundleIdResourceId": "ABC123",
+  "certificateId": "DEF456",
+  "provisioningProfileUUID": "GHI-789-...",
+  "provisioningProfileName": "MyApp Distribution",
+  "teamId": "TEAM123",
+  "lastArchivePath": "build/App.xcarchive",
+  "lastUploadBuildNumber": "42",
+  "completedSteps": ["bundleId", "certificate", "profile", "patch"]
+}
+```
+
+```xml
+<!-- ExportOptions.plist -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>method</key>
+  <string>app-store</string>
+  <key>teamID</key>
+  <string>TEAM123</string>
+  <key>signingStyle</key>
+  <string>manual</string>
+  <key>provisioningProfiles</key>
+  <dict>
+    <key>com.example.myapp</key>
+    <string>MyApp Distribution</string>
+  </dict>
+</dict>
+</plist>
+```

package/extensions/mobile/skills/native-bridge.md

@@ -0,0 +1,66 @@
+---
+name: "native-bridge"
+pack: "@rune/mobile"
+description: "Native bridge patterns — platform-specific code, Expo Modules API, TurboModules, Swift/Kotlin interop, background tasks."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# native-bridge
+
+Native bridge patterns — platform-specific code, Expo Modules API, TurboModules, Swift/Kotlin interop, background tasks.
+
+#### Workflow
+
+**Step 1 — Detect bridge requirements**
+Use Grep to find platform-specific code: `Platform.OS`, `Platform.select`, `NativeModules` (legacy), `TurboModuleRegistry` (new), `MethodChannel` (Flutter), Expo modules (`expo-modules-core`). Read existing native code in `ios/` and `android/` directories.
+
+**Step 2 — Audit bridge safety**
+Check for:
+- `NativeModules.X` direct access: returns `undefined` silently in bridgeless mode (New Architecture). Must use TurboModule codegen or Expo Modules API instead
+- Type mismatches between JS/Dart and native (string expected, int sent): crashes app instead of returning error
+- Synchronous bridge calls blocking UI thread
+- Missing null checks on platform-specific returns
+- Mixing old Bridge modules + new TurboModules: possible during migration but causes subtle memory leaks
+- Missing codegen step (`generateCodegenArtifacts`): intermittent "module not found" errors only in release builds
+
+**Step 3 — Emit type-safe bridge**
+For React Native: emit Expo Module with TypeScript interface (preferred) or TurboModule with codegen types. For Flutter: emit MethodChannel with proper error handling, type-safe serialization, and platform-specific implementations for both iOS (Swift) and Android (Kotlin).
+
+#### Example
+
+```typescript
+// React Native — Expo Module (type-safe, New Architecture compatible)
+// modules/haptics/index.ts
+import { NativeModule, requireNativeModule } from 'expo-modules-core';
+
+interface HapticsModule extends NativeModule {
+  impact(style: 'light' | 'medium' | 'heavy'): void;
+  notification(type: 'success' | 'warning' | 'error'): void;
+}
+
+const HapticsNative = requireNativeModule<HapticsModule>('Haptics');
+
+export function impact(style: 'light' | 'medium' | 'heavy' = 'medium') {
+  HapticsNative.impact(style);
+}
+
+// modules/haptics/ios/HapticsModule.swift
+import ExpoModulesCore
+import UIKit
+
+public class HapticsModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("Haptics")
+    Function("impact") { (style: String) in
+      let generator: UIImpactFeedbackGenerator
+      switch style {
+      case "light": generator = UIImpactFeedbackGenerator(style: .light)
+      case "heavy": generator = UIImpactFeedbackGenerator(style: .heavy)
+      default: generator = UIImpactFeedbackGenerator(style: .medium)
+      }
+      generator.impactOccurred()
+    }
+  }
+}
+```

package/extensions/mobile/skills/ota-updates.md

@@ -0,0 +1,97 @@
+---
+name: "ota-updates"
+pack: "@rune/mobile"
+description: "OTA update strategy — EAS Update, runtime version management, rollback, staged rollouts, bytecode compatibility."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ota-updates
+
+OTA update strategy — EAS Update, runtime version management, rollback, staged rollouts, bytecode compatibility.
+
+#### Workflow
+
+**Step 1 — Detect OTA setup**
+Use Grep to find: `expo-updates`, `Updates.checkForUpdateAsync`, `runtimeVersion` in `app.json`/`app.config.js`, `eas.json` update channel configuration, custom `UpdatesProvider`.
+
+**Step 2 — Audit OTA safety**
+Check for:
+- **Runtime version match**: OTA update only applies to builds with exactly matching `runtimeVersion`. A native dependency change bumps runtime version and invalidates all pending OTA updates. Verify `runtimeVersion` strategy (semver auto vs manual)
+- **Hermes bytecode compatibility**: Each RN version compiles to specific bytecode version. OTA built against RN 0.79 crashes on binary built with RN 0.78. NEVER OTA across RN version boundaries
+- **Update timing**: Updates apply on next cold start, NOT instantly. Users with app in background don't receive updates. For emergency fixes, need custom `UpdatesProvider` with in-session check
+- **Rollback gaps**: `eas update:rollback` has syntax bugs with specific flag combinations. Use branch-based rollback: republish previous update to same channel
+- **Rollout math**: 10% rollout = 10% of cold-start checks, NOT 10% of users. If 80% of users never cold-start in a week, actual reach is ~2%
+- **Native code limitation**: OTA ships JS bundle only. Bugs requiring native changes need full App Store submission
+
+**Step 3 — Emit OTA strategy**
+Emit: channel-based configuration (production/staging/preview), runtime version strategy, update check implementation with error handling, and rollback procedure.
+
+#### Example
+
+```json
+// eas.json — channel-based OTA configuration
+{
+  "build": {
+    "production": {
+      "channel": "production",
+      "distribution": "store",
+      "autoIncrement": true
+    },
+    "preview": {
+      "channel": "preview",
+      "distribution": "internal"
+    }
+  }
+}
+```
+
+```typescript
+// app.config.ts — runtime version strategy
+export default {
+  expo: {
+    runtimeVersion: {
+      policy: 'fingerprintExperimental', // Auto-bumps when native deps change
+    },
+    updates: {
+      url: 'https://u.expo.dev/your-project-id',
+      fallbackToCacheTimeout: 3000, // Don't block startup > 3s
+    },
+  },
+};
+```
+
+```typescript
+// Custom update check with error handling and staged rollout
+import * as Updates from 'expo-updates';
+
+async function checkForUpdate() {
+  if (__DEV__) return; // Skip in development
+
+  try {
+    const update = await Updates.checkForUpdateAsync();
+    if (!update.isAvailable) return;
+
+    // Download in background — don't block user
+    const result = await Updates.fetchUpdateAsync();
+    if (!result.isNew) return;
+
+    // Option A: Apply on next cold start (default, safe)
+    // User gets update automatically next time they fully close + reopen
+
+    // Option B: Prompt user to restart (for important fixes)
+    Alert.alert(
+      'Update Available',
+      'A new version is ready. Restart to apply?',
+      [
+        { text: 'Later', style: 'cancel' },
+        { text: 'Restart', onPress: () => Updates.reloadAsync() },
+      ]
+    );
+  } catch (error) {
+    // OTA failures should NEVER crash the app
+    // Log to error tracking, don't show to user
+    console.error('OTA check failed:', error);
+  }
+}
+```

package/extensions/mobile/skills/push-notifications.md

@@ -0,0 +1,111 @@
+---
+name: "push-notifications"
+pack: "@rune/mobile"
+description: "Push notification setup — FCM v1, APNs, Expo Notifications, permission handling, scheduling, debugging delivery failures."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# push-notifications
+
+Push notification setup — FCM v1, APNs, Expo Notifications, permission handling, scheduling, debugging delivery failures.
+
+#### Workflow
+
+**Step 1 — Detect notification setup**
+Use Grep to find: `expo-notifications`, `@react-native-firebase/messaging`, `firebase.messaging`, push token registration, notification listeners. Check `app.json` plugins for `expo-notifications` config. Check for `google-services.json` (Android) and `GoogleService-Info.plist` (iOS).
+
+**Step 2 — Audit FCM v1 migration**
+Check for:
+- FCM Legacy API usage (server key string instead of service account JSON): Legacy API is fully shut down since June 2024
+- `google-services.json` must be FCM v1 version — old files from Legacy API still circulate in repos
+- `MismatchSenderId` error: FCM server key and `google-services.json` project_number must match same Firebase project
+- Multiple Firebase environments: dev/staging/prod need separate `google-services.json` files with environment-specific project numbers
+
+**Step 3 — Audit iOS-specific gotchas**
+Check for:
+- `aps-environment` entitlement: works in dev builds but fails in production if `expo-notifications` not in `app.json` plugins array
+- `getDevicePushTokenAsync()` race condition: silently never resolves on SDK 53+ for some users (GitHub #37516). Must call after app is fully initialized, not in root layout mount
+- iOS requires paid Apple Developer account ($99/yr) for APNs — no way to test push on Simulator or free account
+- iOS 18: explicit permission prompt required before scheduling local notifications — call `requestPermissionsAsync()` first
+- Push notifications removed from Expo Go on Android (SDK 53+). Must use development build
+
+**Step 4 — Audit permission handling**
+Check that permission is requested at contextual moment (not app launch), fallback UI shown when denied, and `Settings.openURL` offered for re-enabling from Settings.
+
+**Step 5 — Emit notification pipeline**
+Emit: server-side push via FCM v1 HTTP API with service account auth, client-side token registration with retry, notification listener setup with cleanup, and scheduled notification with proper permission check.
+
+#### Example
+
+```typescript
+// Server — FCM v1 push (NOT legacy). Requires service account JSON
+import { GoogleAuth } from 'google-auth-library';
+
+const auth = new GoogleAuth({
+  keyFile: 'service-account.json', // NOT a server key string
+  scopes: ['https://www.googleapis.com/auth/firebase.messaging'],
+});
+
+async function sendPush(token: string, title: string, body: string, data?: Record<string, string>) {
+  const client = await auth.getClient();
+  const projectId = 'your-project-id';
+
+  const response = await client.request({
+    url: `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`,
+    method: 'POST',
+    data: {
+      message: {
+        token,
+        notification: { title, body },
+        data: data ?? {},
+        android: { priority: 'high' },
+        apns: {
+          payload: { aps: { sound: 'default', badge: 1 } },
+          headers: { 'apns-priority': '10' },
+        },
+      },
+    },
+  });
+  return response.data;
+}
+```
+
+```typescript
+// Client — Expo Notifications with proper lifecycle
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+
+// Configure BEFORE any notification arrives
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldShowAlert: true,
+    shouldPlaySound: true,
+    shouldSetBadge: true,
+  }),
+});
+
+async function registerForPush(): Promise<string | null> {
+  if (!Device.isDevice) {
+    console.warn('Push notifications require a physical device');
+    return null;
+  }
+
+  const { status: existing } = await Notifications.getPermissionsAsync();
+  let finalStatus = existing;
+
+  if (existing !== 'granted') {
+    // Request at contextual moment, NOT app launch
+    const { status } = await Notifications.requestPermissionsAsync();
+    finalStatus = status;
+  }
+
+  if (finalStatus !== 'granted') return null;
+
+  // Must be called AFTER app is fully initialized (not in root layout mount)
+  const { data: token } = await Notifications.getExpoPushTokenAsync({
+    projectId: 'your-expo-project-id', // Required for EAS
+  });
+  return token;
+}
+```

package/extensions/mobile/skills/react-native.md

@@ -0,0 +1,82 @@
+---
+name: "react-native"
+pack: "@rune/mobile"
+description: "React Native patterns — New Architecture migration, navigation, state management, native modules, performance optimization, Expo vs bare workflow decisions."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# react-native
+
+React Native patterns — New Architecture migration, navigation, state management, native modules, performance optimization, Expo vs bare workflow decisions.
+
+#### Workflow
+
+**Step 1 — Detect React Native setup**
+Use Grep to find framework markers: `react-native` in package.json (extract version — 0.82+ = New Architecture mandatory), `expo` config (extract SDK version — 53+ = New Arch default), navigation library (`@react-navigation/native` v6 vs v7, `expo-router` v3 vs v4), state management (`zustand`, `redux`, `jotai`), and native module usage. Read `app.json`/`app.config.js` for Expo configuration.
+
+**Step 2 — Audit New Architecture readiness**
+Check for:
+- `react-native` >= 0.82 or Expo SDK >= 55: New Architecture is mandatory, no opt-out
+- `setNativeProps` usage: incompatible with New Architecture, must migrate to Reanimated or Animated API
+- Third-party libraries using legacy Bridge (`NativeModules.X` directly instead of TurboModules): check each against `reactnative.directory` compatibility list
+- `react-native-reanimated` version: must be >= 3.8 to avoid Android animation stutter on New Architecture (GitHub #7435)
+- Kotlin version in `android/build.gradle`: Reanimated + Kotlin 1.9.25 fails EAS Build (GitHub #7674)
+- State batching: New Architecture enables React 18 concurrent batching — components relying on intermediate state between updates silently break
+
+**Step 3 — Audit performance patterns**
+Check for: FlatList without `keyExtractor` or with inline `renderItem` (re-renders), images using `react-native-fast-image` (not compatible with New Architecture — migrate to `expo-image`), heavy re-renders from context (missing `useMemo`/`useCallback`), navigation listeners not cleaned up, large JS bundle without lazy loading (`React.lazy` + `Suspense`), `removeClippedSubviews` causing blank cells on fast scroll.
+
+**Step 4 — Audit navigation patterns (React Navigation v7 / Expo Router v4)**
+Check for:
+- `navigate()` calls: v7 changed semantics — now pushes new screen even if route exists in stack (v6 navigated to existing instance). Audit all `navigation.navigate()` calls
+- `useNavigation()` hook: causes re-renders on every route change in Expo Router v4, not just current route (GitHub #35383). Replace with `useRouter()` for navigation-only usage
+- Non-unique navigator names: deep links silently fail to resolve (GitHub #9267)
+- Authentication + deep link race condition: `NavigationContainer` not ready when initial URL received. Must capture URL, wait for auth, then navigate
+
+**Step 5 — Emit optimized patterns**
+For each issue, emit the fix: memoized FlatList item components, `expo-image` migration, proper navigation with typed routes, optimized state selectors, and Hermes engine configuration. For New Architecture migration, emit a phased plan: audit → update libraries → enable → test → fix regressions.
+
+#### Example
+
+```tsx
+// BEFORE: FlatList anti-patterns + legacy image library
+import FastImage from 'react-native-fast-image'; // ❌ Not New Arch compatible
+<FlatList
+  data={items}
+  renderItem={({ item }) => (
+    <View>
+      <FastImage source={{ uri: item.image }} />
+      <Text>{item.name}</Text>
+    </View>
+  )}
+/>
+
+// AFTER: New Architecture compatible, memoized, proper image caching
+import { Image } from 'expo-image'; // ✅ New Arch compatible
+import { FlashList } from '@shopify/flash-list'; // ✅ Better than FlatList
+
+const ItemCard = React.memo<{ item: Item; onPress: () => void }>(({ item, onPress }) => (
+  <Pressable onPress={onPress}>
+    <Image
+      source={item.image}
+      style={styles.image}
+      contentFit="cover"
+      placeholder={item.blurhash}
+      transition={200}
+    />
+    <Text>{item.name}</Text>
+  </Pressable>
+));
+
+const renderItem = useCallback(({ item }: { item: Item }) => (
+  <ItemCard item={item} onPress={() => router.push(`/product/${item.id}`)} />
+), [router]);
+
+<FlashList
+  data={items}
+  renderItem={renderItem}
+  estimatedItemSize={88} // Required — measure actual item height
+  keyExtractor={item => item.id}
+/>
+```