@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-expo-devin/skills/add-app-clip/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: add-app-clip
+description: Add an iOS App Clip target to an Expo app. Use when the user mentions App Clip, AASA, apple-app-site-association, appclips, smart app banner, or wants to ship a lightweight iOS Clip invoked from a URL alongside their parent app.
+---
+
+# Add an App Clip to an Expo App
+
+Adds an iOS App Clip target to an Expo project. The Clip lives in `targets/clip/`, ships alongside the parent app, and is invoked from a URL on the app's domain via an Apple App Site Association (AASA) file.
+
+The parent app's bundle ID becomes `com.<username>.<app-name>` and the Clip's is automatically derived as `<parent>.clip` (e.g. `com.bacon.may20.clip`).
+
+## 1. Set `bundleIdentifier` and `appleTeamId`
+
+`bun create target` warns if these are missing. Add to `app.json`:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "bundleIdentifier": "com.<username>.<app-name>",
+      "appleTeamId": "XX57RJ5UTD"
+    }
+  }
+}
+```
+
+## 2. Add the App Clip target
+
+```sh
+bun create target clip
+```
+
+This installs [`@bacons/apple-targets`](https://github.com/EvanBacon/expo-apple-targets), adds it to the `plugins` array in `app.json`, and writes:
+
+- `targets/clip/expo-target.config.js` — the target's config plugin
+- `targets/clip/Info.plist` — Clip Info.plist
+- `targets/clip/AppDelegate.swift`, `Assets.xcassets`, etc.
+
+Pick a good icon or reuse the existing one defined in the app — check it with `bunx expo config` under the `icon` or `ios.icon` key.
+
+## 3. Wire up associated domains
+
+The parent app and the Clip each need the Associated Domains entitlement pointing at the domain that hosts the AASA file.
+
+In `app.json`, add both `applinks:` (parent) and `appclips:` (Clip invocation) entries:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "associatedDomains": [
+        "applinks:may20.expo.app",
+        "appclips:may20.expo.app"
+      ]
+    }
+  }
+}
+```
+
+In `targets/clip/expo-target.config.js`, declare the Clip's entitlement:
+
+```js
+/** @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} */
+module.exports = (config) => ({
+  type: "clip",
+  icon: "https://github.com/expo.png",
+  entitlements: {
+    "com.apple.developer.associated-domains": ["appclips:may20.expo.app"],
+  },
+});
+```
+
+> If you skip this, `expo prebuild` will print: `Apple App Clip may require the associated domains entitlement but none were found`.
+
+## 4. Register bundle IDs and create the App Store entry
+
+```sh
+bunx setup-safari
+```
+
+This logs in to the Apple Developer account, registers `com.bacon.may20`, creates the App Store Connect entry, and prints:
+
+- A starter `apple-app-site-association` JSON
+- A `<meta name="apple-itunes-app">` tag with the iTunes app id
+- Team ID, iTunes ID, and Bundle ID
+
+## 5. Host the AASA file
+
+App Clips are invoked when iOS fetches `https://<your-domain>/.well-known/apple-app-site-association` and finds a matching `appclips` entry.
+
+```sh
+mkdir -p public/.well-known
+touch public/.well-known/apple-app-site-association
+```
+
+Paste the JSON `setup-safari` printed, but **add an `appclips` block** for the Clip's full app ID (`<TeamID>.<ClipBundleID>`). The output of `setup-safari` only covers the parent app:
+
+```json
+{
+  "applinks": {
+    "details": [
+      {
+        "appIDs": ["XX57RJ5UTD.com.bacon.may20"],
+        "components": [{ "/": "*", "comment": "Matches all routes" }]
+      }
+    ]
+  },
+  "appclips": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20.clip"]
+  },
+  "activitycontinuation": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20"]
+  },
+  "webcredentials": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20"]
+  }
+}
+```
+
+Notes:
+
+- The file has **no extension** and **no `Content-Type` requirements** beyond being served as-is. Expo Router static export serves files in `public/` verbatim.
+- The `appclips` block is what lets a URL on the domain launch the Clip.
+- `webcredentials` is used for sharing credentials between the website, parent app, and the App Clip.
+- `activitycontinuation` is optional and used for sharing the link between mobile and desktop. Must be used with `Head` from expo-router — see https://docs.expo.dev/router/advanced/apple-handoff/
+- Notation and route-disabling details: https://sosumi.ai/documentation/xcode/supporting-associated-domains
+
+## 6. Add the Smart App Banner meta tag
+
+Create `src/app/+html.tsx` (Expo Router's HTML shell) and add the tag from `setup-safari`. Create the versioned template if it doesn't exist:
+
+```sh
+bunx expo customize src/app/+html.tsx
+```
+
+Add the meta tag to the `<head>`:
+
+```tsx
+import { ScrollViewStyleReset } from "expo-router/html";
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="apple-itunes-app" content="app-id=6771566491" />
+        <ScrollViewStyleReset />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+To make the website show the App Clip card instead of the install card, use:
+
+```html
+<meta
+  name="apple-itunes-app"
+  content="app-id=6771566491, app-clip-bundle-id=com.bacon.may20.clip, app-clip-display=card"
+/>
+```
+
+## 7. Deploy the website
+
+The AASA file must be live before iOS will trust the association. Use [EAS Hosting](https://docs.expo.dev/eas/hosting/):
+
+```sh
+bunx expo export -p web
+eas deploy --prod
+```
+
+This publishes the site (including `/.well-known/apple-app-site-association`) at `https://<slug>.expo.app`. Verify:
+
+```sh
+curl https://may20.expo.app/.well-known/apple-app-site-association
+```
+
+## 8. Mirror permissions
+
+Inspect the parent app's permissions after prebuild:
+
+```sh
+npx expo config --type introspect
+```
+
+Look at the `infoPlist` object — mirror the permission keys in the App Clip's `Info.plist` so matching APIs can be used from the Clip.
+
+Set `deploymentTarget: "17.6"` in the Clip's target config — App Clips have a higher minimum size limit in iOS 17.6.
+
+If the app uses push notifications or location services, add to the App Clip's `Info.plist` to request the necessary permissions:
+
+```xml
+<key>NSAppClip</key>
+<dict>
+  <key>NSAppClipRequestEphemeralUserNotification</key>
+  <false/>
+  <key>NSAppClipRequestLocationConfirmation</key>
+  <true/>
+</dict>
+```
+
+## 9. Build and submit to TestFlight
+
+```sh
+bunx testflight
+```
+
+This will:
+
+1. Generate an `eas.json` if missing.
+2. Set up credentials for **both** targets (parent + Clip). Each gets its own provisioning profile but can share a single Distribution Certificate.
+3. Sync capabilities — note `Enabled: Associated Domains` for the Clip target.
+4. Build, upload, and schedule a TestFlight submission.
+
+## 10. Configure App Clip metadata
+
+Pull existing App Store metadata to local:
+
+```sh
+eas metadata:pull
+```
+
+Add `apple.appClip` to `store.config.json`. Up to 3 invocation URLs can launch the Clip from a web page:
+
+```json
+{
+  "configVersion": 0,
+  "apple": {
+    "appClip": {
+      "defaultExperience": {
+        "action": "PLAY",
+        "releaseWithAppStoreVersion": true,
+        "reviewDetail": {
+          "invocationUrls": ["https://may20.expo.app/", null, null]
+        },
+        "info": {
+          "en-US": {
+            "subtitle": "Instantly native with Expo",
+            "headerImage": "store/apple/app-clip/en-US/asc-app-clip.png"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `headerImage` must be a 1800x1200 PNG with no opacity.
+
+Push back to the store:
+
+```sh
+eas metadata:push
+```
+
+Apple's recommended App Clip metadata guidelines: https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip
+
+## What you get
+
+- Parent app target: `com.bacon.may20`
+- App Clip target: `com.bacon.may20.clip`, lives in `targets/clip/`
+- AASA hosted at `https://may20.expo.app/.well-known/apple-app-site-association`
+- Smart App Banner meta tag on every web route
+- Every route linked to its native counterpart
+- TestFlight build of the parent app with the Clip embedded
+
+Once Apple invokes the Clip from a URL on the domain, iOS opens `targets/clip/`'s entry point which loads the React Native app.
+
+## Native detection (optional)
+
+To let JS detect when it's running inside an App Clip and present an install prompt for the full app, create a local Expo module (`bunx create-expo-module --local`) that exposes `navigator.appClip.prompt()`.
+
+See [./references/native-module.md](./references/native-module.md) for the Swift module, TypeScript interface, and usage.
+
+## References
+
+- ./references/native-module.md — Local Expo module to detect App Clip context and present the SKOverlay install prompt

package/plugins/lisa-expo-devin/skills/add-app-clip/references/native-module.md

@@ -0,0 +1,96 @@
+# Native App Clip detection
+
+Create a local Expo module so JS can detect when the app is running inside an App Clip and present the install prompt for the full app.
+
+```sh
+bunx create-expo-module --local
+```
+
+## Swift module
+
+```swift
+import ExpoModulesCore
+import StoreKit
+
+internal class MissingCurrentWindowSceneException: Exception {
+  override var reason: String {
+    "Cannot determine the current window scene in which to present the App Clip install overlay."
+  }
+}
+
+internal class MissingContainerURLException: Exception {
+  override var reason: String {
+    "Cannot determine the container URL."
+  }
+}
+
+public class AppClipModule: Module {
+  private static let isAppClip: Bool = {
+    if let infoPlist = Bundle.main.infoDictionary, let _ = infoPlist["NSAppClip"] as? [String: Any] {
+      return true
+    }
+    return false
+  }()
+
+  public func definition() -> ModuleDefinition {
+    Name("AppClip")
+
+    Constant("isAppClip") {
+      AppClipModule.isAppClip
+    }
+
+    // Display overlay to advertise full app.
+    // https://developer.apple.com/documentation/app_clips/recommending_your_app_to_app_clip_users
+    AsyncFunction("prompt") {
+      if #available(iOS 16, *) {
+        guard let currentScene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
+          throw MissingCurrentWindowSceneException()
+        }
+
+        let config = SKOverlay.AppClipConfiguration(position: .bottom)
+        let overlay = SKOverlay(configuration: config)
+        overlay.present(in: currentScene)
+      }
+    }.runOnQueue(DispatchQueue.main)
+  }
+}
+```
+
+## TypeScript interface
+
+```ts
+import { NativeModule, requireOptionalNativeModule } from "expo";
+
+declare class AppClipModule extends NativeModule<{}> {
+  prompt(): void;
+  isAppClip?: boolean;
+}
+
+const AppClipNative = requireOptionalNativeModule<AppClipModule>("AppClip");
+
+if (AppClipNative?.isAppClip) {
+  navigator.appClip = {
+    prompt: AppClipNative.prompt,
+  };
+}
+
+declare global {
+  interface Navigator {
+    /**
+     * Only available in an App Clip context.
+     * @expo
+     */
+    appClip?: {
+      /** Open the SKOverlay */
+      prompt: () => void;
+    };
+  }
+}
+
+export {};
+```
+
+## Usage
+
+- Detect App Clip context: `if (navigator.appClip) { ... }`
+- Prompt to install the full app: `navigator.appClip?.prompt()`

package/plugins/lisa-expo-devin/skills/apollo-client/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: apollo-client
+description: This skill should be used when writing or modifying GraphQL operations, hooks, or mutations using Apollo Client 3.10. It enforces best practices for optimistic responses, cache updates, and TypeScript type generation. Use this skill when creating new queries/mutations, reviewing Apollo code, or troubleshooting cache issues.
+---
+
+# Apollo Client 3.10
+
+## Overview
+
+This skill provides best practices for Apollo Client 3.10 in this codebase, ensuring consistent patterns for GraphQL operations, optimistic UI updates, cache management, and TypeScript type safety.
+
+## Quick Reference
+
+### Generator Commands
+
+After modifying any `operations.graphql` file, run the appropriate generator:
+
+```bash
+bun run generate:types:dev        # Development environment
+bun run generate:types:staging    # Staging environment
+bun run generate:types:production # Production environment
+```
+
+> **Note:** Replace `bun` with your project's package manager (`npm`, `yarn`, `pnpm`) as needed.
+
+### Import Pattern
+
+All GraphQL types, hooks, and documents must come from generated types:
+
+```typescript
+import {
+  useGetPlayerQuery,
+  useUpdatePlayerMutation,
+  GetPlayerQuery,
+  PlayerFragment,
+  ListPlayersDocument,
+} from "@/generated/graphql";
+```
+
+## Core Rules
+
+### 1. Only Use Generated Types
+
+Import all GraphQL-related types from `@/generated/graphql`. Never define manual TypeScript types for GraphQL entities.
+
+```typescript
+// CORRECT
+import { PlayerFragment, useUpdatePlayerMutation } from "@/generated/graphql";
+
+// INCORRECT - Never do this
+type Player = { id: string; name: string };
+```
+
+### 2. Never Modify Generated Files
+
+The `generated/graphql.ts` file is auto-generated by codegen. To change types:
+
+1. Edit the appropriate `operations.graphql` file in the feature directory
+2. Run `bun run generate:types:dev`
+3. Import the newly generated types
+
+### 3. Always Run Generator After Schema Changes
+
+After modifying any `operations.graphql` file, immediately run the generator before committing. Verify changes compile with `bun run typecheck`.
+
+### 4. Always Include Optimistic Response
+
+Every mutation must include an `optimisticResponse` for instant UI feedback:
+
+```typescript
+const [updatePlayer] = useUpdatePlayerMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    updatePlayer: {
+      __typename: "Player",
+      id: variables.id,
+      name: variables.input.name,
+      updatedAt: new Date().toISOString(),
+    },
+  }),
+});
+```
+
+Key requirements:
+
+- Always include `__typename` for every object in the response
+- Always include `id` for cache normalization
+- Use temporary IDs for new objects (e.g., `crypto.randomUUID()`)
+- Include all fields that the mutation returns
+
+### 5. Always Update Cache
+
+Every mutation must handle cache updates using one of these strategies:
+
+**Automatic Updates** - When mutation returns the full entity with `id` and `__typename`, Apollo updates automatically. No extra code needed.
+
+**cache.modify** - For adding/removing items from lists:
+
+```typescript
+const [addPlayer] = useAddPlayerMutation({
+  optimisticResponse: {
+    /* ... */
+  },
+  update(cache, { data }) {
+    cache.modify({
+      fields: {
+        players(existingPlayers = [], { readField }) {
+          const newRef = cache.writeFragment({
+            data: data.addPlayer,
+            fragment: PlayerFragmentDoc,
+          });
+          return [...existingPlayers, newRef];
+        },
+      },
+    });
+  },
+});
+```
+
+**refetchQueries** - Fallback for complex scenarios:
+
+```typescript
+const [complexMutation] = useComplexMutation({
+  refetchQueries: ["ListPlayers"],
+  awaitRefetchQueries: true,
+});
+```
+
+## Operations.graphql Structure
+
+### Fragment-First Pattern
+
+Define fragments before queries/mutations that use them:
+
+```graphql
+# 1. Fragments first
+fragment PlayerFragment on Player {
+  id
+  knownName
+  firstName
+  lastName
+  team {
+    id
+    name
+  }
+}
+
+# 2. Queries second
+query GetPlayer($id: ID!) {
+  player(id: $id) {
+    ...PlayerFragment
+  }
+}
+
+# 3. Mutations last
+mutation UpdatePlayer($id: ID!, $input: UpdatePlayerInput!) {
+  updatePlayer(id: $id, input: $input) {
+    ...PlayerFragment
+  }
+}
+```
+
+### Include Required Fields
+
+Mutations must return all fields needed for cache updates:
+
+```graphql
+mutation AddPlayerToKanban($input: AddPlayerToKanbanInput!) {
+  addPlayerToKanban(input: $input) {
+    id # Required for cache normalization
+    position
+    notes
+    kanbanPhaseId
+    kanbanPhase {
+      # Include related objects
+      id
+      name
+    }
+    createdAt
+    updatedAt
+  }
+}
+```
+
+## Query Best Practices
+
+### Fetch Policies
+
+```typescript
+// Frequently changing data - balance speed and freshness
+fetchPolicy: "cache-and-network";
+
+// Stable reference data - prioritize cache
+fetchPolicy: "cache-first";
+
+// Always-fresh data - skip cache
+fetchPolicy: "network-only";
+```
+
+### Skip When Variables Undefined
+
+```typescript
+const { data } = useGetPlayerQuery({
+  variables: { id: playerId! },
+  skip: !playerId,
+});
+```
+
+### Error Handling
+
+Use `onError` callback instead of try/catch with console.log:
+
+```typescript
+const [mutation] = useMutation(MUTATION, {
+  onError: error => {
+    setErrorState("Failed to update. Please try again.");
+  },
+});
+```
+
+## Complete Mutation Pattern
+
+Reference `references/mutation-patterns.md` for comprehensive examples of the complete mutation pattern including optimistic responses, cache updates, and error handling.
+
+## Validation Checklist
+
+When writing or reviewing Apollo code, verify:
+
+- [ ] All types imported from `@/generated/graphql`
+- [ ] No manual type definitions for GraphQL entities
+- [ ] Every mutation has `optimisticResponse`
+- [ ] Every mutation has cache update strategy
+- [ ] `__typename` included in all optimistic response objects
+- [ ] `id` included in all optimistic response objects
+- [ ] Queries use appropriate `fetchPolicy`
+- [ ] Queries use `skip` when variables may be undefined
+- [ ] Error handling via `onError` callback
+- [ ] Generator was run after operations.graphql changes