@codyswann/lisa 2.121.1 → 2.123.0

package/plugins/lisa-expo-agy/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-agy/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

package/plugins/lisa-expo-agy/skills/apollo-client/references/mutation-patterns.md

@@ -0,0 +1,360 @@
+# Apollo Client Mutation Patterns
+
+This reference provides comprehensive examples of mutation patterns for Apollo Client 3.10.
+
+## Complete Mutation Hook Pattern
+
+Every custom mutation hook should follow this structure:
+
+```typescript
+import { useCallback } from "react";
+import {
+  useUpdateKanbanCardMutation,
+  KanbanCardFragment,
+  KanbanCardFragmentDoc,
+} from "@/generated/graphql";
+
+/**
+ * Hook for updating kanban card with optimistic UI
+ * @param boardId - The board ID for context
+ * @returns Object containing update function and loading state
+ */
+export const useUpdateCard = (boardId: string) => {
+  const [updateCardMutation, { loading }] = useUpdateKanbanCardMutation({
+    // 1. OPTIMISTIC RESPONSE - Provides instant UI feedback
+    optimisticResponse: variables => ({
+      __typename: "Mutation",
+      updateKanbanCard: {
+        __typename: "KanbanCard",
+        id: variables.id,
+        notes: variables.input.notes ?? null,
+        position: variables.input.position ?? 0,
+        kanbanPhaseId: variables.input.kanbanPhaseId ?? "",
+        kanbanPhase: {
+          __typename: "KanbanPhase",
+          id: variables.input.kanbanPhaseId ?? "",
+          name: "", // Will be updated by server response
+        },
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      },
+    }),
+
+    // 2. CACHE UPDATE - Ensures UI stays in sync
+    update(cache, { data }) {
+      if (!data?.updateKanbanCard) return;
+
+      // For simple field updates, Apollo handles automatically
+      // For complex scenarios, use cache.modify:
+      cache.modify({
+        id: cache.identify({
+          __typename: "KanbanCard",
+          id: data.updateKanbanCard.id,
+        }),
+        fields: {
+          notes: () => data.updateKanbanCard.notes,
+          position: () => data.updateKanbanCard.position,
+        },
+      });
+    },
+
+    // 3. ERROR HANDLING - Never pollutes console
+    onError: () => {
+      // Set error state in UI, don't console.log
+    },
+  });
+
+  // 4. WRAPPED CALLBACK - Proper memoization
+  const updateCard = useCallback(
+    async (cardId: string, notes: string) => {
+      await updateCardMutation({
+        variables: {
+          id: cardId,
+          input: { notes },
+        },
+      });
+    },
+    [updateCardMutation]
+  );
+
+  return { updateCard, isUpdating: loading };
+};
+```
+
+## Adding Items to a List
+
+When creating new items that need to appear in a list:
+
+```typescript
+const [addPlayerMutation] = useAddPlayerToKanbanMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    addPlayerToKanban: {
+      __typename: "KanbanCard",
+      id: crypto.randomUUID(), // Temporary ID for new items
+      position: 0,
+      notes: variables.input.notes ?? null,
+      kanbanPhaseId: variables.input.kanbanPhaseId,
+      kanbanPhase: {
+        __typename: "KanbanPhase",
+        id: variables.input.kanbanPhaseId,
+        name: "", // Will be replaced by server
+      },
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  }),
+
+  update(cache, { data }) {
+    if (!data?.addPlayerToKanban) return;
+
+    cache.modify({
+      fields: {
+        listKanbanCards(existingCards = { edges: [] }) {
+          const newCardRef = cache.writeFragment({
+            data: data.addPlayerToKanban,
+            fragment: KanbanCardFragmentDoc,
+          });
+
+          return {
+            ...existingCards,
+            edges: [
+              ...existingCards.edges,
+              {
+                __typename: "KanbanCardEdge",
+                cursor: "",
+                node: { __ref: newCardRef.__ref },
+              },
+            ],
+          };
+        },
+      },
+    });
+  },
+
+  onError: () => {
+    // Handle error in UI state
+  },
+});
+```
+
+## Removing Items from a List
+
+When deleting items that should disappear from a list:
+
+```typescript
+const [removePlayerMutation] = useRemovePlayerFromKanbanMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    removePlayerFromKanban: {
+      __typename: "KanbanCard",
+      id: variables.cardId,
+      position: 0,
+      notes: null,
+      kanbanPhaseId: "",
+      kanbanPhase: {
+        __typename: "KanbanPhase",
+        id: "",
+        name: "",
+      },
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  }),
+
+  update(cache, { data }) {
+    if (!data?.removePlayerFromKanban) return;
+
+    const removedId = data.removePlayerFromKanban.id;
+
+    cache.modify({
+      fields: {
+        listKanbanCards(existingCards = { edges: [] }, { readField }) {
+          return {
+            ...existingCards,
+            edges: existingCards.edges.filter(
+              (edge: { node: { __ref: string } }) => {
+                const cardRef = edge.node.__ref;
+                return readField("id", { __ref: cardRef }) !== removedId;
+              }
+            ),
+          };
+        },
+      },
+    });
+
+    // Evict the removed item from cache entirely
+    cache.evict({
+      id: cache.identify({
+        __typename: "KanbanCard",
+        id: removedId,
+      }),
+    });
+    cache.gc();
+  },
+
+  onError: () => {
+    // Handle error in UI state
+  },
+});
+```
+
+## Moving Items Between Lists
+
+When an item moves from one parent to another:
+
+```typescript
+const [moveCardMutation] = useMoveKanbanCardMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    moveKanbanCard: {
+      __typename: "KanbanCard",
+      id: variables.input.cardId,
+      position: variables.input.targetPosition,
+      notes: null, // Preserve from existing cache
+      kanbanPhaseId: variables.input.targetPhaseId,
+      kanbanPhase: {
+        __typename: "KanbanPhase",
+        id: variables.input.targetPhaseId,
+        name: "", // Will be updated by server
+      },
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  }),
+
+  // For moves, refetchQueries is often cleaner than manual cache updates
+  refetchQueries: ["ListKanbanCards"],
+  awaitRefetchQueries: false, // Don't block UI
+
+  onError: () => {
+    // Handle error in UI state
+  },
+});
+```
+
+## Batch Updates with Reordering
+
+When updating positions of multiple items:
+
+```typescript
+const [updatePositionsMutation] = useUpdateKanbanPhasePositionsMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    updateKanbanPhasePositions: variables.input.phasePositions.map(pp => ({
+      __typename: "KanbanPhase",
+      id: pp.phaseId,
+      position: pp.position,
+      name: "", // Preserve from cache
+      kanbanBoardId: variables.input.kanbanBoardId,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    })),
+  }),
+
+  refetchQueries: ["ListKanbanPhases"],
+  awaitRefetchQueries: false,
+
+  onError: () => {
+    // Handle error in UI state
+  },
+});
+```
+
+## Conditional Optimistic Updates
+
+Skip optimistic updates when conditions aren't met:
+
+```typescript
+const [updateMutation] = useUpdateMutation({
+  optimisticResponse: (variables, { IGNORE }) => {
+    // Skip optimistic update if we don't have enough data
+    if (!variables.input.name) {
+      return IGNORE;
+    }
+
+    return {
+      __typename: "Mutation",
+      update: {
+        __typename: "Entity",
+        id: variables.id,
+        name: variables.input.name,
+        updatedAt: new Date().toISOString(),
+      },
+    };
+  },
+});
+```
+
+## Cache Update with cache.identify
+
+Use `cache.identify` to get the correct cache key:
+
+```typescript
+update(cache, { data }) {
+  if (!data?.updatePlayer) return;
+
+  const cacheId = cache.identify({
+    __typename: "Player",
+    id: data.updatePlayer.id,
+  });
+  // cacheId = "Player:abc-123"
+
+  cache.modify({
+    id: cacheId,
+    fields: {
+      isActive: () => true,
+      updatedAt: () => new Date().toISOString(),
+    },
+  });
+}
+```
+
+## Using readonly Types for Cache Modifiers
+
+Apollo cache data is readonly. Use proper typing:
+
+```typescript
+cache.modify({
+  fields: {
+    players(existingPlayers: readonly { __ref: string }[] = [], { readField }) {
+      return existingPlayers.filter(ref => readField("id", ref) !== removedId);
+    },
+  },
+});
+```
+
+## Decision Tree: Cache Update Strategy
+
+```
+Mutation creates/updates/deletes entity
+            │
+            ▼
+┌───────────────────────────────┐
+│ Does mutation return entity   │
+│ with id and __typename?       │
+└───────────────────────────────┘
+            │
+     ┌──────┴──────┐
+     │ YES         │ NO
+     ▼             ▼
+┌─────────┐   ┌─────────────────┐
+│Automatic│   │ Use             │
+│ Update  │   │ refetchQueries  │
+└─────────┘   └─────────────────┘
+     │
+     ▼
+┌───────────────────────────────┐
+│ Does entity need to appear    │
+│ in or disappear from a list?  │
+└───────────────────────────────┘
+            │
+     ┌──────┴──────┐
+     │ YES         │ NO
+     ▼             ▼
+┌─────────────┐   ┌─────────────┐
+│cache.modify │   │ Automatic   │
+│ with list   │   │ is enough   │
+│ manipulation│   │             │
+└─────────────┘   └─────────────┘
+```